| 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.ResourceEvents.class,
eventName="onAcquire")
public void onAcquire()
{
// code to obtain connections/sessions/...
}
@EventHandler(field="resourceContext",
eventSet=ResourceContext.ResourceEvents.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.ResourceEvents
See Also: org.apache.beehive.controls.api.context.Context
See Also: org.apache.beehive.controls.api.events.EventHandler |