Package org.ocap.resource

See:
          Description

Interface Summary
ApplicationResourceUsage This interface represents a ResourceUsage corresponding to a resource explicitly reserved by an application by successfully calling one of the following OCAP calls: org.davic.mpeg.section.SectionFilterGroup.attach(TransportStream, ResourceClient, Object) org.davic.net.tuning.NetworkInterfaceController.reserve(NetworkInterface, Object) org.davic.net.tuning.NetworkInterfaceController.reserveFor(Locator, Object) org.havi.ui.HBackgroundDevice.reserveDevice(ResourceClient) org.havi.ui.HGraphicsDevice.reserveDevice(ResourceClient) org.havi.ui.HVideoDevice.reserveDevice(ResourceClient) org.ocap.media.VBIFilterGroup.attach(ServiceContext serviceContext, ResourceClient client, Object requestData) An object implementing this interface should be used by the implementation to represent the ResourceUsage corresponding to a reserved resource when the ResourceContentionHandler.resolveResourceContention() method is invoked.
RequestRetryCallback An instances of RequestRetryCallback SHALL be provided when enabling automatic reservation request retry via the ResourceContext.
ResourceAction A computation to be performed within a specific resource context.
ResourceContentionHandler A class implementing this interface decides which application shall be allowed to reserve a resource.
ResourceContentionHandler2 A class implementing this interface decides which application(s) shall be allowed to reserve a resource.
ResourceExceptionAction A computation to be performed within a specific resource context.
ResourcePriority An enumeration of priority values that describe the importance of a resource reservation to an application.
ResourceUsage This interface represents a grouping of resources specific to an function performed by an application.
SharedResourceUsage This interface represents a group of resources where one or more resources are shared between multiple resource usages.
 

Class Summary
ResourceContentionManager This class manages a means of resolving a resource contention.
ResourceContext An instance of ResourceContext may be used to specify implicit parameters to resource reservation requests, including implicit reservations made on an application's behalf.
 

Package org.ocap.resource Description

The Resource Management API allows a monitor application to refuse a reservation of limited resources unconditionally and to resolve a resource reservation contention after negotiation. The monitor application can implement a subclass of the org.dvb.application.AppsDatabaseFilter class to refuse a reservation, and a concrete class that implements the org.ocap.resource.ResourceContentionHandler interface to resolve a contention. See Section 19 Resource Management for more details.

Example of Monitor Application

This sample code shows how the monitor application implements this package. The class ResourceHandler is one of the classes of the monitor application. It prevents an application that has an organization ID of REJECTED_ORGANIZATION from reserving a section filter resource and assigns priority based upon expressed need, allowing higher priority for resource reservation to an application that has an organization ID of PRIORITIZED_ORGANIZATION.

 
import org.ocap.resource.*;
import org.dvb.application.*;
 
public class ResourceHandler extends AppsDatabaseFilter
    implements ResourceContentionHandler, ResourceContentionHandler2 
{
    
    private static final int REJECTED_ORGANIZATION = 0xABCD;
    private static final int PRIORITIZED_ORGANIZATION = 0x1234;
    
    /*
     * This is Constructor. 
     * Set a ResourceFilter and a ResourceContentionManager for a resource 
     * handling when constructing. 
     */
    public ResourceHandler() {
        ResourceContentionManager rcManager = ResourceContentionManager.getInstance();
        rcManager.setResourceFilter(this, "org.davic.mpeg.sections.SectionFilterGroup");
        rcManager.setResourceContentionHandler(this);
    }
    
    /*
     * Check if the application is allowed to reserve a resource or not. 
     */
    public boolean accept(AppID appid) {
        return appid.getOID() != REJECTED_ORGANIZATION;
    }
    
    /*
     * Resolve a resource contention.
     */
    public ResourceUsage[] resolveResourceContention(
            ResourceUsage[] newRequests,
            ResourceUsage[] currentReservations)
    {
        // Copy new requests and current reservations into single array
        ResourceUsage[] result = 
            new ResourceUsage[newRequests.length + currentReservations.length];
        System.arraycopy(newRequests, 0, 
                         result, 0, 
                         newRequests.length);
        System.arraycopy(currentReservations, 0, 
                         result, newRequests.length, 
                         currentReservations.length);
        
        // Use bubble sort to order all requests by priority descending
        for(int i = 0; i < result.length; i++)
        {
            for(int j = 0; j < result.length - 1; i++)
            {
                if (mapPriority(result[j]) < mapPriority(result[j+1]))
                {
                    ResourceUsage temp = result[j];
                    result[j] = result[j+1];
                    result[j+1] = temp;
                }
            }
        }
        // Return array contain all new requests and current reservations
        // ordered by priority descending.
        return result;
    }
    
    /*
     * Resolve a resource contention.
     */
    public ResourceUsage[] resolveResourceContention(
            ResourceUsage newRequest,
            ResourceUsage[] currentReservations)
    {
        return resolveResourceContention(new ResourceUsage[] { newRequest },
                                         currentReservations);
    }
    
    /*
     * Map given ResourceUsage to desired priority. 
     */
    private static int mapPriority(ResourceUsage ru) {
        if ( ru == null )
            return -1;
        int p = ru.getResourcePriority();
        if (ru.getAppID().getOID() == PRIORITIZED_ORGANIZATION)
            return p;
        if (p >= ResourcePriority.PRIORITY_UNKNOWN
            && p < ResourcePriority.PRIORITY_MSO_FIRST)
            return p;
        return ResourcePriority.PRIORITY_UNKNOWN;
    }
    
    public void resourceContentionWarning(ResourceUsage newRequest, ResourceUsage[] currentReservations)
    {
        // Ignored for this example
    }
}