|
Java DTV API 1.3 18-Nov-2009 |
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object com.sun.dtv.filtering.DataSectionFilterCollection
public class DataSectionFilterCollection
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).
Please note that due to the particular purpose of this class and
although it is inheriting from ScarceResource
, it does not
provide any getInstances()
or reserveOne()
methods as described in the ScarceResource
interface
description.
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); }
DataSection
,
DataSectionFilter
Constructor Summary | |
---|---|
DataSectionFilterCollection(TransportStream stream,
int numberOfFilters)
Creates a section filter collection object with an associated number of data section filters on the specified transport stream needed to be reserved when the object is to be connected to an active source of section data. |
|
DataSectionFilterCollection(TransportStream stream,
int numberOfFilters,
boolean highPriority)
Creates a section filter collection object with an associated number of section filters on the specified transport stream 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(Object requestData)
Connects a DataSectionFilterCollection to the transport stream. |
void |
disconnect()
Returns a DataSectionFilterCollection to the disconnected
state. |
TransportStream |
getSource()
Returns the transport stream on which a DataSectionFilterCollection is used to
filter. |
boolean |
isAvailable()
Checks whether the given resource is currently available for reservation. |
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. |
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. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
public DataSectionFilterCollection(TransportStream stream, int numberOfFilters)
The object will have a default high resource priority should the number of section filters available to the package become insufficient.
stream
- specifies the source of data sections for filteringnumberOfFilters
- the number of section filters needed for the object.public DataSectionFilterCollection(TransportStream stream, int numberOfFilters, boolean highPriority)
stream
- specifies the source of data sections for filteringnumberOfFilters
- 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 |
---|
public SingleFilter newSingleFilter()
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
SingleFilter
object.public SingleFilter newSingleFilter(int sectionSize)
startFiltering
) the SingleFilter
object will use section filters from the total specified when the parent
DataSectionFilterCollection
was created.
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.
SingleFilter
object.public CircularFilter newCircularFilter(int numberOfEntries)
startFiltering
) the new CircularFilter
object will use section filters from the total specified when the parent
DataSectionFilterCollection
was created.
numberOfEntries
- The number of DataSection
objects to be created for use
in the circular buffer.
CircularFilter
object.public CircularFilter newCircularFilter(int numberOfEntries, int sectionSize)
startFiltering
) the new CircularFilter
object will use section filters from the total specified when the parent
DataSectionFilterCollection
was created.
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.
CircularFilter
object.public ListFilter newListFilter()
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.
ListFilter
object.public ListFilter newListFilter(int sectionSize)
startFiltering
) the new ListFilter
object will use section filters from the total specified when the parent
DataSectionFilterCollection
was created.
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.
ListFilter
object.public void connect(Object requestData) throws IllegalStateException, IncompatibleSourceException, TuningException
DataSectionFilterCollection
has to reserve the number of section filters on the transport stream 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.
requestData
- application specific data for use by the resource notification API
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 topublic void disconnect() throws IllegalStateException
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
DataSectionFilterCollection
s already in the
disconnected state.
IllegalStateException
- if the DataSectionFilterCollection
has not been connected before.public TransportStream getSource()
DataSectionFilterCollection
is used to
filter.
public void reserve(boolean force, long timeoutms, ScarceResourceListener listener) throws IllegalArgumentException, TimeoutException, SecurityException
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:
ScarceResourceListener.releaseRequested()
if
force
is false
,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.
reserve
in interface ScarceResource
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.
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.
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.public void release()
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.
release
in interface ScarceResource
public boolean isAvailable()
isAvailable
in interface ScarceResource
true
if the given resource is
currently available for reservation.public static void addResourceTypeListener(ResourceTypeListener listener) throws NullPointerException
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.
listener
- The listener that is triggered for events on resources
of the same type.
NullPointerException
- If listener
is
null
.removeResourceTypeListener(com.sun.dtv.resources.ResourceTypeListener)
public static void removeResourceTypeListener(ResourceTypeListener listener) throws NullPointerException
listener
- The listener that is triggered for events on resources
of the same type.
NullPointerException
- If listener
is
null
.addResourceTypeListener(com.sun.dtv.resources.ResourceTypeListener)
|
Java DTV API 1.3 18-Nov-2009 |
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |