KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > derby > iapi > services > context > Context


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