KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > beehive > controls > api > context > ResourceContext


1 package org.apache.beehive.controls.api.context;
2 /*
3  * Copyright 2004 The Apache Software Foundation.
4  *
5  * Licensed under the Apache License, Version 2.0 (the "License");
6  * you may not use this file except in compliance with the License.
7  * You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  *
17  * $Header:$
18  */
19 import org.apache.beehive.controls.api.events.EventSet;
20
21 /**
22  * The ResourceContext interface defines a basic contextual service for coordinating the
23  * resource utilization of a control implementation within a resource scope defined external
24  * to the control. This contextual service that provides assistance to a Control in managing
25  * any external resources (connections, sesssions, etc) that may be relatively expensive to
26  * obtain and/or can only be held for a relatively short duration.
27  * <p>
28  * A ResourceContext implementation may be provided by an external container of Controls, such
29  * as a servlet engine or EJB container, that coordinates the resource lifecycle of controls with
30  * the activities of the external container. For example, the resource scope for a
31  * ResourceContext provider associated with the web tier might enable control resources to be
32  * used for the duration of a single http request; for the EJB tier it might mean for the
33  * lifetime of the current EJB invocation or active transaction.
34  * <p>
35  * A control implementation participates in this resource management contract by declaring a
36  * ResourceContext instance annotated with the
37  * <sp>@Context annotation, the standard service provider model of the Control runtime will
38  * associate the control instance with a ResourceControl provider implementation that is
39  * associated with the current execution context. This is demonstrated by the following
40  * code excerpt from a ControlImplementation class:
41  * <p>
42  * <pre><code>
43  * <sp>@org.apache.beehive.controls.api.bean.ControlImplementation
44  * public class MyControlImpl
45  * {
46  * ...
47  * // Declare need for resource mgmt support via the ResourceContext service
48  * <sp>@org.apache.beehive.controls.api.context.Context
49  * ResourceContext resourceContext;
50  * ...
51  * </code></pre>
52  * <p>
53  * Once the control has been associated with a ResourceContext provider, the provider will
54  * deliver events to the Control Implementation instance according to the following basic
55  * contract:
56  * <p>
57  * <ul>
58  * <li>the ResourceContext provider notifies a control implementation when it should acquire its
59  * resources using the onAcquire event.
60  * <li>the ResourceContext provider notifies a control implementation when it should release its
61  * resources using the onRelease event.
62  * </ul>
63  * <p>
64  * The following code fragment shows how to receive resource events from within a Control
65  * implementation:
66  * <p>
67  * <pre><code>
68  * import org.apache.beehive.controls.api.events.EventHandler;
69  *
70  * ...
71  *
72  * <sp>@EventHandler(field="resourceContext"
73  * eventSet=ResourceContext.Events.class,
74  * eventName="onAcquire")
75  * public void onAcquire()
76  * {
77  * // code to obtain connections/sessions/...
78  * }
79  *
80  * <sp>@EventHandler(field="resourceContext"
81  * eventSet=ResourceContext.Events.class,
82  * eventName="onRelease")
83  * public void onRelease()
84  * {
85  * // code to release connections/sessions/...
86  * }
87  * </code></pre>
88  * <p>
89  * The onAcquire resource event is guaranteed to be delivered once before any operation declared
90  * on a public or extension interface associated with the control. This event will be delivered
91  * once, and only once, within a particular resource scope associated with the ResourceContext.
92  *
93  * If a control needs to utilize its resources in another context (such as in response to a
94  * PropertyChange notification), the ResourceContext also provides support for manually
95  * acquiring and releasing resources.
96  *
97  * @see org.apache.beehive.controls.api.context.ResourceContext.ResourceEvents
98  * @see org.apache.beehive.controls.api.context.Context
99  * @see org.apache.beehive.controls.api.events.EventHandler
100  */
101 public interface ResourceContext
102 {
103     /**
104      * The acquire method allows a Control implementation to manually request acquisition.
105      * This is useful in contexts where the control needs access to associated resources
106      * from outside the scope of an operation. If invoked when the control has not currently
107      * acquired resources, the onAcquire event will be delivered to the control and it will
108      * be registered in the current resource scope as holding resources. If the control has
109      * previously acquired resources in the current resource scope, then calling acquire()
110      * will have no effect.
111      */
112     public void acquire();
113
114     /**
115      * The release method allows a Control implement to manually release resources immediately,
116      * instead of waiting until the end of the current resource scope. If invoked when the
117      * control has currently acquired resources, the onRelease event will be delivered immediately
118      * and the control will no longer be in the list of controls holding resources in the current
119      * resource scope. If the control has not previously acquired resources, then calling
120      * release() will have no effect.
121      */
122     public void release();
123
124     /**
125      * The hasResources method returns true if the control has currently acquired resources,
126      * false otherwise.
127      */
128     public boolean hasResources();
129
130     /**
131      * The ResourceEvents interface defines the resource events delivered by a ResourceContext
132      * provider.
133      */
134     @EventSet
135     public interface ResourceEvents
136     {
137         /**
138          * The onAcquire event will be delivered by a ResourceContext provider to the
139          * Control implementation <b>before</b> any operation on the control is invoked within
140          * the resource scope associated with the provider and its associated container. This
141          * provides the opportunity for the implementation instance to obtain any resource it
142          * uses to provide its services.
143          */
144         public void onAcquire();
145
146         /**
147          * The onRelease event will be delivered by a ResourceContext provider to the
148          * Control implementation <b>immediately before</b> before the end of the resource
149          * scope associated with the provider and its associated container. This provides
150          * the opportunity for the implementation instance to relinquish any resources it
151          * obtained during <i>onAcquire</i> event handling.
152          */
153         public void onRelease();
154     }
155
156     /**
157      * Registers a listener that implements the ResourceEvents interface for the ResourceContext.
158      */
159     public void addResourceEventsListener(ResourceEvents resourceListener);
160
161     /**
162      * Unregisters a listener that implements the ResourceEvents interface for the ResourceContext.
163      */
164     public void removeResourceEventsListener(ResourceEvents resourceListener);
165 }
166
Popular Tags