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 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:
ResourceContext.ResourceEvents, 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.
 

Method Detail

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.