org.apache.beehive.controls.api.context
Interface ResourceContext
- All Known Implementing Classes:
- ResourceContextImpl
public interface ResourceContext
The ResourceContext interface defines a basic contextual service for coordinating the
resource utilization of a control implementation within a resource scope defined external
to the control. This contextual service that provides assistance to a Control in managing
any external resources (connections, sesssions, etc) that may be relatively expensive to
obtain and/or can only be held for a relatively short duration.
A ResourceContext implementation may be provided by an external container of Controls, such
as a servlet engine or EJB container, that coordinates the resource lifecycle of controls with
the activities of the external container. For example, the resource scope for a
ResourceContext provider associated with the web tier might enable control resources to be
used for the duration of a single http request; for the EJB tier it might mean for the
lifetime of the current EJB invocation or active transaction.
A control implementation participates in this resource management contract by declaring a
ResourceContext instance annotated with the
@Context annotation, the standard service provider model of the Control runtime will
associate the control instance with a ResourceControl provider implementation that is
associated with the current execution context. This is demonstrated by the following
code excerpt from a ControlImplementation class:
@org.apache.beehive.controls.api.bean.ControlImplementation
public class MyControlImpl
{
...
// Declare need for resource mgmt support via the ResourceContext service
@org.apache.beehive.controls.api.context.Context
ResourceContext resourceContext;
...
Once the control has been associated with a ResourceContext provider, the provider will
deliver events to the Control Implementation instance according to the following basic
contract:
- the ResourceContext provider notifies a control implementation when it should acquire its
resources using the onAcquire event.
- the ResourceContext provider notifies a control implementation when it should release its
resources using the onRelease event.
The following code fragment shows how to receive resource events from within a Control
implementation:
import org.apache.beehive.controls.api.events.EventHandler;
...
@EventHandler(field="resourceContext"
eventSet=ResourceContext.Events.class,
eventName="onAcquire")
public void onAcquire()
{
// code to obtain connections/sessions/...
}
@EventHandler(field="resourceContext"
eventSet=ResourceContext.Events.class,
eventName="onRelease")
public void onRelease()
{
// code to release connections/sessions/...
}
The onAcquire resource event is guaranteed to be delivered once before any operation declared
on a public or extension interface associated with the control. This event will be delivered
once, and only once, within a particular resource scope associated with the ResourceContext.
If a control needs to utilize its resources in another context (such as in response to a
PropertyChange notification), the ResourceContext also provides support for manually
acquiring and releasing resources.
- See Also:
org.apache.beehive.controls.api.context.ResourceContext.Events
,
Context
,
EventHandler
Nested Class Summary |
static interface |
ResourceContext.ResourceEvents
The ResourceEvents interface defines the resource events delivered by a ResourceContext
provider. |
Method Summary |
void |
acquire()
The acquire method allows a Control implementation to manually request acquisition. |
void |
addResourceEventsListener(ResourceContext.ResourceEvents resourceListener)
Registers a listener that implements the ResourceEvents interface for the ResourceContext. |
boolean |
hasResources()
The hasResources method returns true if the control has currently acquired resources,
false otherwise. |
void |
release()
The release method allows a Control implement to manually release resources immediately,
instead of waiting until the end of the current resource scope. |
void |
removeResourceEventsListener(ResourceContext.ResourceEvents resourceListener)
Unregisters a listener that implements the ResourceEvents interface for the ResourceContext. |
acquire
void acquire()
- The acquire method allows a Control implementation to manually request acquisition.
This is useful in contexts where the control needs access to associated resources
from outside the scope of an operation. If invoked when the control has not currently
acquired resources, the onAcquire event will be delivered to the control and it will
be registered in the current resource scope as holding resources. If the control has
previously acquired resources in the current resource scope, then calling acquire()
will have no effect.
release
void release()
- The release method allows a Control implement to manually release resources immediately,
instead of waiting until the end of the current resource scope. If invoked when the
control has currently acquired resources, the onRelease event will be delivered immediately
and the control will no longer be in the list of controls holding resources in the current
resource scope. If the control has not previously acquired resources, then calling
release() will have no effect.
hasResources
boolean hasResources()
- The hasResources method returns true if the control has currently acquired resources,
false otherwise.
addResourceEventsListener
void addResourceEventsListener(ResourceContext.ResourceEvents resourceListener)
- Registers a listener that implements the ResourceEvents interface for the ResourceContext.
removeResourceEventsListener
void removeResourceEventsListener(ResourceContext.ResourceEvents resourceListener)
- Unregisters a listener that implements the ResourceEvents interface for the ResourceContext.