org.ocap.resource
Class ResourceContext

java.lang.Object
  extended by org.ocap.resource.ResourceContext

public abstract class ResourceContext
extends Object

An instance of ResourceContext may be used to specify implicit parameters to resource reservation requests, including implicit reservations made on an application's behalf.

The scope of a resource context (that is the scope to which its set attributes apply) SHALL be the execution of a given resource action (ResourceAction or ResourceExceptionAction) up to but not including the introduction of another resource context scope. At most one resource context SHALL be in scope at a time. The resource context that is in scope when an API that explicitly or implicitly (including at some time in the future) reserves one or more resources is invoked by an application SHALL be considered to be an implicit parameter to such reservation operations.

The following example shows how ResourceContext may be used to lower the stated priority of implicit reservations made as part of service selection.

 final boolean[] maybe = { false };
 ResourceContext ctx = ResourceContext.createInstance();
 ctx.setResourcePriority(ResourcePriority.PRIORITY_HIGH);
 ctx.setResourceClient(new org.davic.resource.ResourceClient() {
     public boolean requestRelease(org.davic.resource.ResourceProxy proxy, Object data) {
         return maybe[0];
     }
     public void release(org.davic.resource.ResourceProxy) { /* ... */ }
     public void notifyRelease(org.davic.resource.ResourceProxy proxy) { /* ... */ }
 });
 
 final javax.tv.service.Service service = /* ... */ ;
 final javax.tv.service.selection.ServiceContext sc = /* ...*/ ;
 ctx.doResourceAction(new ResourceAction() {
     public Object executeAction()
     {
         // Select the service... 
         // Specifying the ResourceClient and importance 
         sc.select(service);
     }
 });
 
 // ... 
 // At some later time, lower the priority.
 ctx.setResourcePriority(ResourcePriority.PRIORITY_MEDIUM);
 // Or perhaps avoid contention with other requests altogether
 maybe[0] = true;
 

Author:
Aaron Kamienski
See Also:
ResourcePriority, ResourceAction, ResourceExceptionAction

Method Summary
static ResourceContext createInstance()
          Creates and returns a new instance of ResourceContext.
abstract  Object doResourceAction(ResourceAction action)
          Executes the given ResourceAction within the context of this ResourceContext.
abstract  Object doResourceAction(ResourceExceptionAction action)
          Executes the given ResourceExceptionAction within the context of this ResourceContext.
abstract  void setRequestRetry(RequestRetryCallback callback)
          Enables or disables automatic reservation request retry for this resource context.
abstract  void setResourceClient(ResourceClient rc)
          Sets the ResourceClient for this resource context.
abstract  void setResourcePriority(int priority)
          Sets the resource priority for this resource context.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

createInstance

public static ResourceContext createInstance()
Creates and returns a new instance of ResourceContext. The returned resource context object may subsequently be used to specify additional parameters that should implicitly apply to resource reservation operations executed within the context.

Returns:
A new instance of ResourceContext.

setResourcePriority

public abstract void setResourcePriority(int priority)
Sets the resource priority for this resource context. A default resource priority value of ResourcePriority.PRIORITY_UNKNOWN SHALL be used if this method is never called.

This priority will be exposed to the ResourceContentionHandler in case of resource contention via the ResourceUsage.getResourcePriority() method. If the application that created this ResourceContext is destroyed (including upon reboot of the OCAP environment), then the resource priority value SHALL be frozen as last set by the application.

Parameters:
priority - The new resource priority for this resource context.
Throws:
IllegalArgumentException - if the given value is not a valid resource priority as defined by the ResourcePriority interface
See Also:
ResourcePriority

setResourceClient

public abstract void setResourceClient(ResourceClient rc)
Sets the ResourceClient for this resource context. A default value of null SHALL be assumed if this method is never called.

This method allows an application to explicitly specify a ResourceClient to be used for implicit reservations made on its behalf. This gives the application the opportunity to respond to release requests and be notified of resource loss.

Parameters:
rc - The resource client for this resource context; may be null.

setRequestRetry

public abstract void setRequestRetry(RequestRetryCallback callback)
Enables or disables automatic reservation request retry for this resource context. This method allows an application to request that the implementation queue failed resource reservation requests for later automatic retry.

If the request retry attribute is non-null when a reservation request is made and fails, the implementation SHALL enqueue that request for later consideration. When a successful reservation is made due to an automatic retry, the given RequestRetryCallback SHALL be notified.

If the request retry attribute is null when a reservation request is made and fails, then no enqueuing SHALL occur, even if a non-null value is specified in the future. Setting the request retry attribute to null, if previously non-null, SHALL cancel any retry requests that were previously enqueued while the attribute was non-null.

Parameters:
callback - if null, disables automatic request retry; otherwise, enables automatic request retry, specifying the object to be notified of successful reservation due to automatic request retry.

doResourceAction

public abstract Object doResourceAction(ResourceAction action)
Executes the given ResourceAction within the context of this ResourceContext. The scope of this resource context is the execution of the ResourceAction executeAction method. This ResourceContext is an implicit argument to any resource reservation (explicit or implicit) operations performed by the given ResourceAction.

Parameters:
action - The ResourceAction to execute.
Returns:
The Object reference returned by action.executeAction().
Throws:
RuntimeException - uncaught RuntimeException thrown during the execution of action.executeAction()
Error - uncaught Error thrown during the execution of action.executeAction()

doResourceAction

public abstract Object doResourceAction(ResourceExceptionAction action)
                                 throws InvocationTargetException
Executes the given ResourceExceptionAction within the context of this ResourceContext. The scope of this context is the execution of the ResourceExceptionAction executeAction method. This ResourceContext is an implicit argument to any resource reservation (explicit or implicit) operations performed by the given ResourceExceptionAction.

Parameters:
action - The ResourceExceptionAction to execute.
Returns:
The Object reference returned by action.executeAction().
Throws:
InvocationTargetException - encapsulates an uncaught exception thrown during the execution of action.executeAction()
RuntimeException - uncaught RuntimeException thrown during the execution of action.executeAction()
Error - uncaught Error thrown during the execution of action.executeAction()