001: /*
002:
003: Derby - Class org.apache.derby.iapi.services.context.Context
004:
005: Licensed to the Apache Software Foundation (ASF) under one or more
006: contributor license agreements. See the NOTICE file distributed with
007: this work for additional information regarding copyright ownership.
008: The ASF licenses this file to you under the Apache License, Version 2.0
009: (the "License"); you may not use this file except in compliance with
010: the License. You may obtain a copy of the License at
011:
012: http://www.apache.org/licenses/LICENSE-2.0
013:
014: Unless required by applicable law or agreed to in writing, software
015: distributed under the License is distributed on an "AS IS" BASIS,
016: WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: See the License for the specific language governing permissions and
018: limitations under the License.
019:
020: */
021:
022: package org.apache.derby.iapi.services.context;
023:
024: import org.apache.derby.iapi.error.StandardException;
025:
026: /**
027: * Contexts are created and used to manage the execution
028: * environment. They provide a convenient location for
029: * storing globals organized by the module using the
030: * globals.
031: * <p>
032: * A basic context implementation is provided as an abstract
033: * class; this implementation satisfies the interface and
034: * should in general be used as the supertype of all context
035: * types. Otherwise, context classes must satisfy the
036: * semantics of the interface through their own distinct
037: * implementations.
038: * <p>
039: * Contexts assist in cleanup
040: * when errors are caught in the outer block.
041: * <p>
042: * Use of context cleanup is preferred over using try/catch
043: * blocks throughout the code.
044: * <p>
045: * Use of context pushing and popping is preferred over
046: * using many instance or local variables, even when try/catch is present.
047: * when the instance or local variables would be holding resources.
048: <P>
049: Usually Context's have a reference based equality, ie. they do not provide
050: an implementation of equals(). Contexts may implement a value based equality
051: but this usually means there is only one instance of the Context on the stack,
052: This is because the popContext(Context) will remove the most recently pushed
053: Context that matches via the equals method, not by a reference check.
054: Implementing equals is useful for Contexts used in notifyAllThreads() that
055: is not aimed at a single thread.
056: */
057: public interface Context {
058: /**
059: * Returns the context manager that has stored this
060: * context in its stack.
061: */
062: public ContextManager getContextManager();
063:
064: /**
065: * Returns the current id name associated
066: * with this context. Contexts are placed into
067: * stacks by id, in a context manager. Null
068: * if the context is not assigned to an id.
069: * Contexts known by context managers are always
070: * assigned to an id.
071: * <p>
072: * A default Id name should be defined in each
073: * specific context interface as a static final
074: * field with the name CONTEXT_ID. For example,
075: * see org.apache.derby.iapi.sql.compile.CompilerContext.CONTEXT_ID.
076: * @see org.apache.derby.iapi.sql.compile.CompilerContext
077: */
078: public String getIdName();
079:
080: /**
081: * Contexts will be passed errors that are caught
082: * by the outer system when they are serious enough
083: * to require corrective action. They will be told
084: * what the error is, so that they can react appropriately.
085: * Most of the time, the contexts will react by either
086: * doing nothing or by removing themselves from the
087: * context manager. If there are no other references
088: * to the context, removing itself from the manager
089: * equates to freeing it.
090: * <BR>
091: * On an exception that is session severity or greater
092: * the Context must push itself off the stack. This is
093: * to ensure that after a session has been closed there
094: * are no Contexts on the stack that potentially hold
095: * references to objects, thus delaying their garbage
096: * collection.
097: * <p>
098: * Contexts must release all their resources before
099: * removing themselves from their context manager.
100: * <p>
101: * The context manager
102: * will "unwind" the contexts during cleanup in the
103: * reverse order they were placed on its global stack.
104: *
105: * <P>
106: * If error is an instance of StandardException then an implementation
107: * of this method may throw a new exception if and only if the new exception
108: * is an instance of StandardException that is more severe than the original error
109: * or the new exception is a not an instance of StandardException (e.g java.lang.NullPointerException).
110: *
111: * @exception StandardException thrown if cleanup goes awry
112: */
113: public void cleanupOnError(Throwable error)
114: throws StandardException;
115:
116: /**
117: Push myself onto my context stack.
118: */
119: public void pushMe();
120:
121: /**
122: Pop myself of the context stack.
123: */
124: public void popMe();
125:
126: /**
127: * Return whether or not this context is the "last" handler for a
128: * the specified severity level. Previously, the context manager would march
129: * through all of the contexts in cleanupOnError() and call each of
130: * their cleanupOnError() methods. That did not work with server side
131: * JDBC, especially for a StatementException, because outer contexts
132: * could get cleaned up incorrectly. This functionality is specific
133: * to the Language system. Any non-language system contexts should
134: * return ExceptionSeverity.NOT_APPLICABLE_SEVERITY.
135: *
136: * NOTE: Both the LanguageConnectionContext and the JDBC Connection Context are
137: * interested in session level errors because they both have clean up to do.
138: * This method allows both of them to return false so that all such handlers
139: * under them can do their clean up.
140: */
141: public boolean isLastHandler(int severity);
142: }
|