Source code: org/apache/derby/iapi/services/context/Context.java
1 /*
2
3 Derby - Class org.apache.derby.iapi.services.context.Context
4
5 Copyright 1997, 2004 The Apache Software Foundation or its licensors, as applicable.
6
7 Licensed under the Apache License, Version 2.0 (the "License");
8 you may not use this file except in compliance with the License.
9 You may obtain a copy of the License at
10
11 http://www.apache.org/licenses/LICENSE-2.0
12
13 Unless required by applicable law or agreed to in writing, software
14 distributed under the License is distributed on an "AS IS" BASIS,
15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 See the License for the specific language governing permissions and
17 limitations under the License.
18
19 */
20
21 package org.apache.derby.iapi.services.context;
22
23 import org.apache.derby.iapi.error.StandardException;
24
25 /**
26 * Contexts are created and used to manage the execution
27 * environment. They provide a convenient location for
28 * storing globals organized by the module using the
29 * globals.
30 * <p>
31 * A basic context implementation is provided as an abstract
32 * class; this implementation satisfies the interface and
33 * should in general be used as the supertype of all context
34 * types. Otherwise, context classes must satisfy the
35 * semantics of the interface through their own distinct
36 * implementations.
37 * <p>
38 * Contexts assist in cleanup
39 * when errors are caught in the outer block.
40 * <p>
41 * Use of context cleanup is preferred over using try/catch
42 * blocks throughout the code.
43 * <p>
44 * Use of context pushing and popping is preferred over
45 * using many instance or local variables, even when try/catch is present.
46 * when the instance or local variables would be holding resources.
47 <P>
48 Usually Context's have a reference based equality, ie. they do not provide
49 an implementation of equals(). Contexts may implement a value based equality
50 but this usually means there is only one instance of the Context on the stack,
51 This is because the popContext(Context) will remove the most recently pushed
52 Context that matches via the equals method, not by a reference check.
53 Implementing equals is useful for Contexts used in notifyAllThreads() that
54 is not aimed at a single thread.
55 */
56 public interface Context
57 {
58 /**
59 * Returns the context manager that has stored this
60 * context in its stack.
61 */
62 public ContextManager getContextManager();
63
64 /**
65 * Returns the current id name associated
66 * with this context. Contexts are placed into
67 * stacks by id, in a context manager. Null
68 * if the context is not assigned to an id.
69 * Contexts known by context managers are always
70 * assigned to an id.
71 * <p>
72 * A default Id name should be defined in each
73 * specific context interface as a static final
74 * field with the name CONTEXT_ID. For example,
75 * see org.apache.derby.iapi.sql.compile.CompilerContext.CONTEXT_ID.
76 * @see org.apache.derby.iapi.sql.compile.CompilerContext
77 */
78 public String getIdName();
79
80 /**
81 * Contexts will be passed errors that are caught
82 * by the outer system when they are serious enough
83 * to require corrective action. They will be told
84 * what the error is, so that they can react appropriately.
85 * Most of the time, the contexts will react by either
86 * doing nothing or by removing themselves from the
87 * context manager. If there are no other references
88 * to the context, removing itself from the manager
89 * equates to freeing it.
90 * <p>
91 * Contexts must release all their resources before
92 * removing themselves from their context manager.
93 * <p>
94 * The context manager
95 * will "unwind" the contexts during cleanup in the
96 * reverse order they were placed on its global stack.
97 *
98 * <P>
99 * If error is an instance of StandardException then an implementation
100 * of this method may throw a new exception if and only if the new exception
101 * is an instance of StandardException that is more severe than the original error
102 * or the new exception is a not an instance of StandardException (e.g java.lang.NullPointerException).
103 *
104 * @exception StandardException thrown if cleanup goes awry
105 */
106 public void cleanupOnError(Throwable error)
107 throws StandardException;
108
109 /**
110 Push myself onto my context stack.
111 */
112 public void pushMe();
113
114 /**
115 Pop myself of the context stack.
116 */
117 public void popMe();
118
119 /**
120 * Return whether or not this context is the "last" handler for a
121 * the specified severity level. Previously, the context manager would march
122 * through all of the contexts in cleanupOnError() and call each of
123 * their cleanupOnError() methods. That did not work with server side
124 * JDBC, especially for a StatementException, because outer contexts
125 * could get cleaned up incorrectly. This functionality is specific
126 * to the Language system. Any non-language system contexts should
127 * return ExceptionSeverity.NOT_APPLICABLE_SEVERITY.
128 *
129 * NOTE: Both the LanguageConnectionContext and the JDBC Connection Context are
130 * interested in session level errors because they both have clean up to do.
131 * This method allows both of them to return false so that all such handlers
132 * under them can do their clean up.
133 */
134 public boolean isLastHandler(int severity);
135 }