com.sun.dtv.filtering
Class DataSectionFilterCollection

java.lang.Object
  com.sun.dtv.filtering.DataSectionFilterCollection

All Implemented Interfaces:

ScarceResource

public class DataSectionFilterCollection

extends Object

implements ScarceResource

This class represents a collection of data section filters to be activated and de-activated as an atomic operation. The purpose of this class is to minimize the potential for resource deadlock between independent pieces of application(s).

Due to the particular purpose of this class and although it is inheriting from ScarceResource, it does not provide any getInstances() or reserveAny() methods.

Code Sample

Create a filter collection with one circular XOR filter and start filtering

 CircularFilter circularFilter;

 void demo() 
      throws IllegalArgumentException, 
             TimeoutException, 
             IllegalStateException, 
             IncompatibleSourceException, 
	           TuningException,
             InvalidFilterException {
     com.sun.dtv.transport.TransportStream transportStream = null;

     // create a filter collection with 3 filters
     DataSectionFilterCollection collection = new DataSectionFilterCollection(1);

     collection.reserve(true, 10000, new ScarceResourceListener() {

         public boolean releaseRequested(ScarceResource resource) {
             return true;
         }

         public void releaseForced(ScarceResource resource) {
         }

         public void released(ScarceResource resource) {
         }
     });

     // now create a XOR circular filter
     circularFilter = collection.newCircularFilter(1);
     byte[] xorData = { 0x01, 0x02, 0x03, 0x04 };
     byte[] xorZeroMask = { (byte) 0xFF, (byte) 0x00, (byte) 0xFF, (byte) 0x00};
     byte[] xorOneMask = { (byte) 0x00, (byte) 0xF0, (byte) 0x00, (byte) 0xFF};
     circularFilter.setXorFilter(10, xorData, xorZeroMask, xorOneMask);

     // create a listener for filter events
     circularFilter.addSectionFilterListener(new FilterEventListener() {

         public void dataSectionFilterUpdate(DataSectionFilterEvent event) {
             if (event instanceof DataSectionAvailableEvent) {
                   DataSection section = circularFilter.getSections()[0];
                   // do something with the filtered section
               }
           }
     });

     // connect to transport stream and start filtering
     // (transportStream could be retrieved from tuner or application)
     collection.connect(transportStream, this);
     circularFilter.startFiltering(this);
 }
 

See Also:

DataSection, DataSectionFilter

Constructor Summary

DataSectionFilterCollection(int numberOfFilters)
Creates a section filter collection object with an associated number of data section filters needed to be reserved when the object is to be connected to an active source of section data.

DataSectionFilterCollection(int numberOfFilters, boolean highPriority)
Creates a section filter collection object with an associated number of section filters needed to be reserved when the object is to be connected to an active source of data sections.

Method Summary

static void	addResourceTypeListener(ResourceTypeListener listener) Adds a ResourceTypeListener to the implementation.
void	connect(TransportStream stream, Object requestData) Connects a DataSectionFilterCollection to a transport stream.
void	disconnect() Returns a DataSectionFilterCollection to the disconnected state.
TransportStream	getSource() Returns the transport stream to which a DataSectionFilterCollection is currently connected.
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.
CircularFilter	newCircularFilter(int numberOfEntries) Creates a new ring section filter within the parent section filter collection.
CircularFilter	newCircularFilter(int numberOfEntries, int sectionSize) Creates a new ring section filter within the parent section filter collection.
ListFilter	newListFilter() Creates a new table section filter object within the parent section filter collection.
ListFilter	newListFilter(int sectionSize) Creates a new table section filter object within the parent section filter collection.
SingleFilter	newSingleFilter() Creates a new single section filter object within the parent section filter collection.
SingleFilter	newSingleFilter(int sectionSize) Creates a new simple section filter object within the parent section filter collection.
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.
static void	removeResourceTypeListener(ResourceTypeListener listener) Removes a previously attached listener.
void	reserve(boolean force, long timeoutms, ScarceResourceListener listener) 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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DataSectionFilterCollection

public DataSectionFilterCollection(int numberOfFilters)

Creates a section filter collection object with an associated number of data section filters needed to be reserved when the object is to be connected to an active source of section data.

The object will have a default high resource priority should the number of section filters available to the package become insufficient.

Parameters:

numberOfFilters - the number of section filters needed for the object.

DataSectionFilterCollection

public DataSectionFilterCollection(int numberOfFilters,
                                   boolean highPriority)

Creates a section filter collection object with an associated number of section filters needed to be reserved when the object is to be connected to an active source of data sections.

Parameters:

numberOfFilters - the number of section filters needed for the object.

highPriority - the resource priority of the object should the number of section filters available to the package become insufficient. High priority is indicated by true and low priority by false.

Method Detail

newSingleFilter

public SingleFilter newSingleFilter()

Creates a new single section filter object within the parent section filter collection. On activation (successful startFiltering) the SingleFilter object will use section filters from the total specified when the parent DataSectionFilterCollection was created. The section filter object will have a buffer suitable to hold a default long section. newSimpleSectionFilter

Returns:

the new SingleFilter object.

newSingleFilter

public SingleFilter newSingleFilter(int sectionSize)

Creates a new simple section filter object within the parent section filter collection. On activation (successful startFiltering) the SingleFilter object will use section filters from the total specified when the parent DataSectionFilterCollection was created.

Parameters:

sectionSize - specifies the size in bytes of the buffer to be created to hold data captured by the DataSectionFilter. If sections are filtered which are larger than this then the extra data will be dropped and filtering continue without any notification to the application.

Returns:

the new SingleFilter object.

newCircularFilter

public CircularFilter newCircularFilter(int numberOfEntries)

Creates a new ring section filter within the parent section filter collection. On activation (successful startFiltering) the new CircularFilter object will use section filters from the total specified when the parent DataSectionFilterCollection was created.

Parameters:

numberOfEntries - The number of DataSection objects to be created for use in the circular buffer.

Returns:

the new CircularFilter object.

newCircularFilter

public CircularFilter newCircularFilter(int numberOfEntries,
                                        int sectionSize)

Creates a new ring section filter within the parent section filter collection. On activation (successful startFiltering) the new CircularFilter object will use section filters from the total specified when the parent DataSectionFilterCollection was created.

Parameters:

numberOfEntries - the number of DataSection objects to be created for use in the circular buffer.

sectionSize - the size in bytes of the buffer for each Section object. If sections are filtered which are larger than this then the extra data will be dropped and filtering continue without any notification to the application.

Returns:

the new CircularFilter object.

newListFilter

public ListFilter newListFilter()

Creates a new table section filter object within the parent section filter collection. On activation (successful startFiltering) the new ListFilter object will use section filters from the total specified when the parent DataSectionFilterCollection was created. Each DataSection created for the table section filter object will have a buffer suitable to hold a default long section.

Returns:

the new ListFilter object.

newListFilter

public ListFilter newListFilter(int sectionSize)

Creates a new table section filter object within the parent section filter collection. On activation (successful startFiltering) the new ListFilter object will use section filters from the total specified when the parent DataSectionFilterCollection was created.

Parameters:

sectionSize - specifies the size in bytes of the buffer to be created to hold data captured by the DataSectionFilter. When the first section has been captured and the total number of sections in the table known, each DataSection created will have a buffer of this size. If sections are filtered which are larger than this then the extra data will be dropped and filtering continue without any notification to the application.

Returns:

the new ListFilter object.

connect

public void connect(TransportStream stream,
                    Object requestData)
             throws IllegalStateException,
                    IncompatibleSourceException,
                    TuningException

Connects a DataSectionFilterCollection to a transport stream. The DataSectionFilterCollection has to reserve the number of section filters specified before. Any DataSectionFilter objects which are part of the collection concerned and whose filtering has been started will become active and start filtering the source for sections matching the specified patterns. A call to connect on a connected DataSectionFilterCollection will be treated as a disconnect followed by the new connect.

Parameters:

stream - specifies the source of data sections for filtering

requestData - application specific data for use by the resource notification API

Throws:

IllegalStateException - if the specified collection of section filters has not been reserved before.

IncompatibleSourceException - if the source is not a valid source of data sections.

TuningException - if the source is not currently tuned to

disconnect

public void disconnect()
                throws IllegalStateException

Returns a DataSectionFilterCollection to the disconnected state. When called for a DataSectionFilterCollection in the connected state, it disconnects a DataSectionFilterCollection from a source of data sections. The section filters held by the DataSectionFilterCollection will be not be released back to the environment. Any running filtering operations will be terminated. This method will have no effect for DataSectionFilterCollections already in the disconnected state.

Throws:

IllegalStateException - if the DataSectionFilterCollection has not been connected before.

getSource

public TransportStream getSource()

Returns the transport stream to which a DataSectionFilterCollection is currently connected. If the DataSectionFilterCollection is not connected to a transport stream then the method will return null.

Returns:

the Transport Stream source currently connected

reserve

public 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.

Specified by:

reserve in interface ScarceResource

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

public 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.

Specified by:

release in interface ScarceResource

isAvailable

public 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.

Specified by:

isAvailable in interface ScarceResource

Returns:

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

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:

NullPointerException - If listener is null.

See Also:

removeResourceTypeListener(com.sun.dtv.resources.ResourceTypeListener)

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:

NullPointerException - If listener is null.

See Also:

addResourceTypeListener(com.sun.dtv.resources.ResourceTypeListener)