com.sun.dtv.resources
Interface ScarceResource

All Known Subinterfaces:

UserInputEvent

All Known Implementing Classes:

DataSectionFilterCollection, KeyEvent, MouseEvent, NetworkDevice, Plane, RemoteControlEvent, Screen, Tuner

public interface ScarceResource

Represents resources that requires special handling for reserving and releasing. This interface allows to set an exclusive lock on any given possibly physical resource. The owner of such a resource is defined at reservation time, to be the instance of the object representing a given scarce resource. The design of scarce resources implies a model where applications are given handler objects whereas the implementation is in control of the actual physical resource.

Application get access to specialized physical resources by selecting one or many out of a list of all resources of a given type and that possibly meet a given filter criteria. Method to retrieve all instances is provided by every resource classes implementing this interface.

The actual management of physical resources including the coordination of locking and unlocking shared resources between the Java Platform and other system components is intentionally left outside the scope of this specification. However, a compliant implementation must insure that the behavior described below is guaranteed for Java applications.

Design

To comply to the design mandated by this specification, instantiable classes representing physical resources should follow the following constraints:

• it must implement this interface,
• it should provide a static getInstances method: this method returns an array of all instances of that given resource type based on a filter criteria that is specific to each resource type class.
• it should provide a static reserveOne method: this method allows to reserve any resource instance of a same type.
• it should provide a static addResourceTypeListener method: this method attaches a listener to reserve and release events related to all resources of same resource type.
• it should provide a static removeResourceTypeListener method: this method removes that listener.

Description for getInstances()

The getInstances method should comply to the following signature and may provide an optional arguments that would define fine grained filter criteria:

public static ResourceClass[] getInstances(filterCriteria);

Returns an array of handlers representing each a physical resource of that given type available on the platform that meet the criteria defined by filterCriteria. Each handler object is unique to both the application and the platform. Each handler object may be different to each other in subsequent calls to the getInstances() method. The list contains all instances whether they are already reserved or not.

The criteria filterCriteria allows the application to focus on a restricted subset of ResourceClass.

If no ResourceClass exists, this method returns a zero-length array.

Returns:

An array of instances of resources of type ResourceClass.

Description for reserveOne()

The reserveOne() method should comply to the following signature and may provide optional arguments that are specific to the specialized scarce resource class:

public static ResourceClass reserveOne(boolean force, long timeoutms, ScarceResourceListener listener, ...)
throws IllegalException,
TimeoutException,
SecurityException;

Returns a reserved instance out of the pool of all instances of type ResourceClass. This may be subject to the optional parameters if any are defined. Please note that this method either returns with the instance that has been reserved or throws an exception according to the situation.

This method behaves exactly as reserve() described in the ScarceResource interface.

Parameters:

force - If true, this method is allowed to withdraw any given resource from its current owner. If false, the implementation will block and wait until a resource is made available (using release()) or until timeoutms milliseconds.

timeoutms - A positive amount of time in millisecond until which this method will wait for any resource to be released by its current owner. The value of -1 indicates that the implementation will wait forever.

listener - The listener to be attached to receive notification about the status of the reserved resource.

Returns:

The instance of type ResourceClass that has been reserved.

Throws:

SecurityException - If the application has no permission for the reserve action for the resource it is about to reserve. Also thrown if force is set to true but the application has no permission for the force action.

IllegalArgumentException - If listener is null or if the value specified in timeoutms is not valid i.e. not either a positive integer or -1.

TimeoutException - If the time specified in timeoutms is over and the resource could not be reserved.

Description for addResourceTypeListener()

public static void addResourceTypeListener(ResourceTypeListener listener)
throws NullPointerException;

Adds a ResourceTypeListener to the implementation. Whenever a reserve() or a release() is called on any resources of the same type, the implementation will call the listener's corresponding methods.

Parameters:

listener - The listener that is triggered for events on resources of the same type.

Throws:

java.lang.NullPointerException - If listener is null.

Description for removeResourceTypeListener()

public static void removeResourceTypeListener(ResourceTypeListener listener)
throws NullPointerException;

Removes a previously attached listener. If the listener was not attached before, this method does nothing.

Parameters:

listener - The listener that is triggered for events on resources of the same type.

Throws:

java.lang.NullPointerException - If listener is null.

Permission

The permission to access the reserve method and its force argument is ruled and controlled by the ScarceResourcePermission.

Code Sample

A resource class would typically follow the following sample of an imaginary built-in 1-liner LCD display.

 import com.sun.dtv.resources.*;

 // This class represents a real physical component
 // and is internal to the implementation
 public class LCDDevice {
     static LCD instances[] = { new LCDDevice(80) };
     boolean isLocked = false;
     int length = 0;
     //...
 }

 // This class represents a handler to the previous LCD device
 // and is made available to applications
 public class LCDHandler implements ScarceResource {

     // Interface : ScarceResource

     public void reserve(boolean force, 
                         long timeoutms, 
                         ScarceResourceListener listener)
         throws IllegalArgumentException,
                TimeoutException { ... }

     public void release() { ... }

     public boolean isAvailable() { ... }

     // Required getInstances
   
     public static LCDHandler[] getInstances() { 
         // generate a new list of LCDHandler
     }

     public static LCDHandler reserveOne(boolean force, 
                                         long timeoutms, 
                                         ScarceResourceListener,
                                         int type)
         throws SecurityException,
                IllegalArgumentException,
                TimeoutException {
         // ...
     }

     public static void addResourceTypeListener(ResourceTypeListener listener)
         throws NullPointerException {
         // ...
     }

    public static void removeResourceTypeListener(ResourceTypeListener listener)
         throws NullPointerException {
         // ...
     }

     // LCD class specific API

     public void display(String text) {
         // Access LCD controller and sets the text
         // ...
     }

     public void clear() {
         display("");
     }
 }
 

Consequently, an application may use the following code:

 LCDHandler lcd = LCDHandler.getInstances()[0]; // you know what you do!
 try {
     lcd.reserve(false, 0, this);

     // LCD is now ours!
     lcd.display("Hello LCD");
 }
 catch(TimeoutException e) {
     // LCD could not be reserved!
 }
 

Another example can be found in the NetworkDevice class description.

See Also:

ScarceResourcePermission, NetworkDevice

Method Summary

boolean	isAvailable() Checks whether the given resource is currently available for reservation.
void	release() Releases this resource.
void	reserve(boolean force, long timeoutms, ScarceResourceListener listener) Requests reservation of the given scarce resource instance.

Method Detail

reserve

void reserve(boolean force,
             long timeoutms,
             ScarceResourceListener listener)
             throws IllegalArgumentException,
                    TimeoutException,
                    SecurityException

Requests reservation of the given scarce resource instance. The method will block until this instance is available. The method returns normally only if the reservation succeeded. All other cases are handled by exceptions.

First, if there is a security manager, its checkPermission method is called with the permission ScarceResourcePermission(name, "reserve"). If force is moreover set to true, then the permission is also checked on ScarceResourcePermission(name, "force").

During the reservation process, if that resource instance is already allocated, the implementation must notify the current owner of that resource about the reservation request via the ScarceResourceListener interface:

• either by ScarceResourceListener.releaseRequested() if force is false,
• or by ScarceResourceListener.releaseForced() in the other case.

The listener will be used for such notification only until this resource is released. After releasing, the implementation must not call any of the listener's interface methods.

After that first event, the implementation will proceed accordingly and release (or not) the requested resource. In case the implementation releases the resource, it will trigger a ScarceResourceListener.released() event to the original listening owner of the resource to inform him that the resource does not belong to him anymore.

The application may control the time to wait for such a resource to be available by setting timeoutms. In case the duration of the reservation exceeds the time expressed in timeoutms, a TimeoutException is thrown.

Under normal operation, resources are released using the release method. However, in the case where the application does not release resources when requested or the application is terminated, the implementation must release all resources allocated to the application to allow other applications to be notified of changes in resource allocation and to be able to reserve them. See the Resource Cleanup section of the application lifecycle.

Parameters:

force - If true, this method will withdraw the resource from the current owner. If false, the implementation will block and wait until the resource is made available (using release()) or until timeoutms.

timeoutms - A positive amount of time in millisecond until which this method will wait for the resource to be released by its current owner. The value of -1 indicates that the implementation will wait forever.

listener - The listener to be attached to receive notification about the status of the resource.

Throws:

SecurityException - If the application has no permission for the reserve action for the resource it is about to reserve. Also thrown if force is set to true but the application has no permission for the force action.

IllegalArgumentException - If listener is null or if the value specified in timeoutms is not valid i.e. not either a positive integer or -1.

TimeoutException - If the time specified in timeoutms is over and the resource could not be reserved.

release

void release()

Releases this resource.

The resource will be made available to another application across the platform. After calling this method, it is no more possible to interact with the given resource: calls to critical methods of that scarce resource must be ignored and may throw IllegalStateException. This assertion is valid and the behavior required for any class implementing the ScarceResource interface. In order to interact again with the given resource, the application must call the reserve() method and become the owner again.

The implementation may dispose any system resources that this object is using. After the implementation must not call any of the methods of the listener that was attached at reservation time.

If the resource was already available (i.e. not reserved), this method does nothing.

isAvailable

boolean isAvailable()

Checks whether the given resource is currently available for reservation. The returned value gives the current situation and does not guarantee that the resource will still be available at a later moment e.g. at reservation time: another application may have taken that resource in the meantime.

Returns:

A boolean set to true if the given resource is currently available for reservation.