ResourceContext

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.ocap.resource
Class ResourceContext

    java.lang.Object
      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()`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD