001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: *
017: * $Header:$
018: */
019: package org.apache.beehive.controls.api.context;
020:
021: import org.apache.beehive.controls.api.events.EventSet;
022:
023: /**
024: * The ResourceContext interface defines a basic contextual service for coordinating the
025: * resource utilization of a control implementation within a resource scope defined external
026: * to the control. This contextual service that provides assistance to a Control in managing
027: * any external resources (connections, sesssions, etc) that may be relatively expensive to
028: * obtain and/or can only be held for a relatively short duration.
029: * <p>
030: * A ResourceContext implementation may be provided by an external container of Controls, such
031: * as a servlet engine or EJB container, that coordinates the resource lifecycle of controls with
032: * the activities of the external container. For example, the resource scope for a
033: * ResourceContext provider associated with the web tier might enable control resources to be
034: * used for the duration of a single http request; for the EJB tier it might mean for the
035: * lifetime of the current EJB invocation or active transaction.
036: * <p>
037: * A control implementation participates in this resource management contract by declaring a
038: * ResourceContext instance annotated with the
039: * <sp>@Context annotation, the standard service provider model of the Control runtime will
040: * associate the control instance with a ResourceControl provider implementation that is
041: * associated with the current execution context. This is demonstrated by the following
042: * code excerpt from a ControlImplementation class:
043: * <p>
044: * <pre><code>
045: * <sp>@org.apache.beehive.controls.api.bean.ControlImplementation
046: * public class MyControlImpl
047: * {
048: * ...
049: * // Declare need for resource mgmt support via the ResourceContext service
050: * <sp>@org.apache.beehive.controls.api.context.Context
051: * ResourceContext resourceContext;
052: * ...
053: * </code></pre>
054: * <p>
055: * Once the control has been associated with a ResourceContext provider, the provider will
056: * deliver events to the Control Implementation instance according to the following basic
057: * contract:
058: * <p>
059: * <ul>
060: * <li>the ResourceContext provider notifies a control implementation when it should acquire its
061: * resources using the onAcquire event.
062: * <li>the ResourceContext provider notifies a control implementation when it should release its
063: * resources using the onRelease event.
064: * </ul>
065: * <p>
066: * The following code fragment shows how to receive resource events from within a Control
067: * implementation:
068: * <p>
069: * <pre><code>
070: * import org.apache.beehive.controls.api.events.EventHandler;
071: *
072: * ...
073: *
074: * <sp>@EventHandler(field="resourceContext",
075: * eventSet=ResourceContext.ResourceEvents.class,
076: * eventName="onAcquire")
077: * public void onAcquire()
078: * {
079: * // code to obtain connections/sessions/...
080: * }
081: *
082: * <sp>@EventHandler(field="resourceContext",
083: * eventSet=ResourceContext.ResourceEvents.class,
084: * eventName="onRelease")
085: * public void onRelease()
086: * {
087: * // code to release connections/sessions/...
088: * }
089: * </code></pre>
090: * <p>
091: * The onAcquire resource event is guaranteed to be delivered once before any operation declared
092: * on a public or extension interface associated with the control. This event will be delivered
093: * once, and only once, within a particular resource scope associated with the ResourceContext.
094: *
095: * If a control needs to utilize its resources in another context (such as in response to a
096: * PropertyChange notification), the ResourceContext also provides support for manually
097: * acquiring and releasing resources.
098: *
099: * @see org.apache.beehive.controls.api.context.ResourceContext.ResourceEvents
100: * @see org.apache.beehive.controls.api.context.Context
101: * @see org.apache.beehive.controls.api.events.EventHandler
102: */
103: public interface ResourceContext {
104: /**
105: * The acquire method allows a Control implementation to manually request acquisition.
106: * This is useful in contexts where the control needs access to associated resources
107: * from outside the scope of an operation. If invoked when the control has not currently
108: * acquired resources, the onAcquire event will be delivered to the control and it will
109: * be registered in the current resource scope as holding resources. If the control has
110: * previously acquired resources in the current resource scope, then calling acquire()
111: * will have no effect.
112: */
113: public void acquire();
114:
115: /**
116: * The release method allows a Control implement to manually release resources immediately,
117: * instead of waiting until the end of the current resource scope. If invoked when the
118: * control has currently acquired resources, the onRelease event will be delivered immediately
119: * and the control will no longer be in the list of controls holding resources in the current
120: * resource scope. If the control has not previously acquired resources, then calling
121: * release() will have no effect.
122: */
123: public void release();
124:
125: /**
126: * The hasResources method returns true if the control has currently acquired resources,
127: * false otherwise.
128: */
129: public boolean hasResources();
130:
131: /**
132: * The ResourceEvents interface defines the resource events delivered by a ResourceContext
133: * provider.
134: */
135: @EventSet
136: public interface ResourceEvents {
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(
160: ResourceEvents resourceListener);
161:
162: /**
163: * Unregisters a listener that implements the ResourceEvents interface for the ResourceContext.
164: */
165: public void removeResourceEventsListener(
166: ResourceEvents resourceListener);
167: }
|