org.ocap.media
Class VBIFilterGroup

java.lang.Object
  extended by org.ocap.media.VBIFilterGroup
All Implemented Interfaces:
ResourceProxy, ResourceServer

public class VBIFilterGroup
extends java.lang.Object
implements ResourceProxy, ResourceServer

This class represents a group of VBI data filters. The VBI filters in a group are attached to a ServiceContext. Current video played back on the ServiceContext is the target of filtering. If the current video is analog, the filters retrieve specific data in a specified VBI line of the video. The data format is defined in each VBI data specification. If the current video is MPEG video, the filters retrieve specific data in the user_data found in the MPEG picture headers of the video. Data format in user_data is defined in ANSI/SCTE 20 and ANSI/SCTE 21.

When a new VBIFilterGroup is constructed, an application specifies the total number of VBIFilters held by it. The application can create a specified number of new VBIFilter instances via a newVBIFilter(int[], int, int, int, int) method. VBI lines and data format for filtering are specified in this method. After configuring all filters, the VBIFilterGroup is attached to a specific ServiceContext. Current video on the ServiceContext is the target of filtering. If the startFiltering() method of a VBI filter is called, the filter starts filtering immediately. The application can retrieve VBI data via a VBIFilter.getVBIData() method. The host may be able to filter VBI data by using separated fields (specify either field 1 or field 2 and retrieve data in only the specified field) or by using mixed fields (retrieve data in both field 1 and 2 in arrival order).

The data unit is defined as follows.

XDS (VBI_DATA_FORMAT_XDS)
XDS packets in line 21 field 2 is defined in EIA-608-B. It has a start/continue/end code and is interleaved with CC3, CC4, T3 and T4 service. One XDS packet is a single data unit of this data format.

Text service (VBI_DATA_FORMAT_T1/T2/T3/T4)
Text service data in line 21 field 1 or 2 is defined in EIA-608-B. It has start/end codes and is interleaved with the other closed captioning service and Text service according to Section 7 of EIA-608-B. A single data unit of Text service is a character sequence between a text mode in code (RTD or TR) and a text mode out code (EOC, RCL, RDC, RU2, RU3 or RU4). Note that Text service data unit returned from the VBIFilter doesn't contain these text mode in/out codes, but contains another control code like EDM etc.

Generic EIA-608-B service (VBI_DATA_FORMAT_EIA608B)
Generic EIA-608-B service represents a character stream that consists of Character One and Character Two in a field of line 21. Character One and Character Two are defined in Figure 1 of EIA-608-B. Note that the VBIFilter only supports separated field filtering since Character One and Character Two make a separate data stream in each field. A single data unit of this format is a set of Character One and Character Two in one VBI line and field (i.e., only two characters).

NABTS (VBI_DATA_FORMAT_NABTS)
NABTS is defined in EIA-516. It is a 33 byte fixed length packet and consists of 5 byte prefix and 28 byte data block. Note that the filter retrieves only the "Data packet" part. I.e., one NABTS packet is a single data unit. The VBIFilter retrieves multiple NABTS packets in arrival order for all specified lines and fields.

AMOL I/II (VBI_DATA_FORMAT_AMOL_I/II)
AMOL I and II is defined in ACN 403-1218-024. It specifies header bits and the number of bits in a VBI line. The bits in one VBI line/field is a single data unit for this data format, i.e., the header bits are included in the data unit.

UNKNOWN (VBI_DATA_FORMAT_UNKNOWN)
UNKNOWN represents a VBI waveform that is unknown. To retrieve UNKNOWN data unit, the OCAP implementation needs to synchronize to the VBI's bit rate automatically. Filtering success is not guaranteed even if the OCAP implementation supports the UNKNOWN format, since an analog waveform is not standardized. The bits in one VBI line and field is a data unit for UNKNOWN format.

Support of the other VBI lines is optional. And support of the ANSI/SCTE 20 and ANSI/SCTE 21 is also optional. An application can check the supported filtering lines, data format and filtering techniques (field separated or field mixed) via capability methods.


Field Summary
static int FIELD_1
          Represents filtering of VBI data in field 1 only.
static int FIELD_2
          Represents filtering of VBI data in field 2 only.
static int FIELD_MIXED
          Represents filtering of VBI data in both field 1 and field 2 in arrival order.
static int VBI_DATA_FORMAT_AMOL_I
          Represents an AMOL I data format defined by ACN 403-1218-024.
static int VBI_DATA_FORMAT_AMOL_II
          Represents an AMOL II data format defined by ACN 403-1218-024.
static int VBI_DATA_FORMAT_EIA608B
          Represents a EIA-608-B generic Character One and Character Two format of line 21 field 1 or 2.
static int VBI_DATA_FORMAT_NABTS
          Represents an NABTS data format defined by EIA-516.
static int VBI_DATA_FORMAT_T1
          Represents a Text service T1 format of line 21 field 1.
static int VBI_DATA_FORMAT_T2
          Represents a Text service T2 format of line 21 field 1.
static int VBI_DATA_FORMAT_T3
          Represents a Text service T3 format of line 21 field 2.
static int VBI_DATA_FORMAT_T4
          Represents a Text service T4 format of line 21 field 2.
static int VBI_DATA_FORMAT_UNKNOWN
          Represents an unknown.
static int VBI_DATA_FORMAT_XDS
          Represents a XDS data format of line 21 field 2.
 
Constructor Summary
VBIFilterGroup(int numberOfFilters)
          Creates a VBIFilterGroup instance that includes the specified number of VBI filters.
 
Method Summary
 void addResourceStatusEventListener(ResourceStatusListener listener)
          Add a listener object to be notified of changes in the status of resources related to VBI filters.
 void attach(javax.tv.service.selection.ServiceContext serviceContext, ResourceClient client, java.lang.Object requestData)
          This method attempts to reserve all VBI filters held by this VBIFilterGroup, and attaches to a specified ServiceContext.
 void detach()
          Releases all filters in this VBIFilterGroup and terminate the connection to the ServiceContext.
 ResourceClient getClient()
          Returns the ResourceClient object specified in the attach() method.
 boolean getMixedFilteringCapability(int[] lineNumber, int dataFormat)
          Returns true if field mixed filtering of the specified VBI line numbers with the specified data format is supported by this VBIFilterGroup.
 boolean getSCTE20Capability()
          Indicates if the host supports line 21 VBI data retrieval from user_data in MPEG picture headers as defined in ANSI/SCTE 20.
 boolean getSCTE21Capability()
          Indicates if the host supports line 21 VBI data retrieval from user_data in MPEG picture headers as defined in ANSI/SCTE 21.
 boolean getSeparatedFilteringCapability(int[] lineNumber, int dataFormat)
          Returns true if field separated filtering of the specified VBI line numbers with the specified data format is supported by this VBIFilterGroup.
 javax.tv.service.selection.ServiceContext getServiceContext()
          Returns a ServiceContext instance specified by a attach(javax.tv.service.selection.ServiceContext, org.davic.resources.ResourceClient, java.lang.Object) method.
 VBIFilter newVBIFilter(int[] lineNumber, int field, int dataFormat, int unitLength, int bufferSize)
          Create a new VBIFilter instance within a VBIFilterGroup instance.
 void removeResourceStatusEventListener(ResourceStatusListener listener)
          Remove a specified listener object from this VBIFilterGroup.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

VBI_DATA_FORMAT_XDS

public static final int VBI_DATA_FORMAT_XDS
Represents a XDS data format of line 21 field 2.

See Also:
Constant Field Values

VBI_DATA_FORMAT_T1

public static final int VBI_DATA_FORMAT_T1
Represents a Text service T1 format of line 21 field 1.

See Also:
Constant Field Values

VBI_DATA_FORMAT_T2

public static final int VBI_DATA_FORMAT_T2
Represents a Text service T2 format of line 21 field 1.

See Also:
Constant Field Values

VBI_DATA_FORMAT_T3

public static final int VBI_DATA_FORMAT_T3
Represents a Text service T3 format of line 21 field 2.

See Also:
Constant Field Values

VBI_DATA_FORMAT_T4

public static final int VBI_DATA_FORMAT_T4
Represents a Text service T4 format of line 21 field 2.

See Also:
Constant Field Values

VBI_DATA_FORMAT_EIA608B

public static final int VBI_DATA_FORMAT_EIA608B
Represents a EIA-608-B generic Character One and Character Two format of line 21 field 1 or 2.

See Also:
Constant Field Values

VBI_DATA_FORMAT_NABTS

public static final int VBI_DATA_FORMAT_NABTS
Represents an NABTS data format defined by EIA-516.

See Also:
Constant Field Values

VBI_DATA_FORMAT_AMOL_I

public static final int VBI_DATA_FORMAT_AMOL_I
Represents an AMOL I data format defined by ACN 403-1218-024.

See Also:
Constant Field Values

VBI_DATA_FORMAT_AMOL_II

public static final int VBI_DATA_FORMAT_AMOL_II
Represents an AMOL II data format defined by ACN 403-1218-024.

See Also:
Constant Field Values

VBI_DATA_FORMAT_UNKNOWN

public static final int VBI_DATA_FORMAT_UNKNOWN
Represents an unknown. I.e., all data bits in the VBI line are retrieved.

See Also:
Constant Field Values

FIELD_1

public static final int FIELD_1
Represents filtering of VBI data in field 1 only.

See Also:
Constant Field Values

FIELD_2

public static final int FIELD_2
Represents filtering of VBI data in field 2 only.

See Also:
Constant Field Values

FIELD_MIXED

public static final int FIELD_MIXED
Represents filtering of VBI data in both field 1 and field 2 in arrival order.

See Also:
Constant Field Values
Constructor Detail

VBIFilterGroup

public VBIFilterGroup(int numberOfFilters)
Creates a VBIFilterGroup instance that includes the specified number of VBI filters. The VBI filters are reserved when the attach(javax.tv.service.selection.ServiceContext, org.davic.resources.ResourceClient, java.lang.Object) method is called.

Parameters:
numberOfFilters - the number of requested VBI filters held by a new VBIFilterGroup instance.
Throws:
java.lang.SecurityException - if the caller doesn't have MonitorAppPermission("vbifiltering").
Method Detail

newVBIFilter

public VBIFilter newVBIFilter(int[] lineNumber,
                              int field,
                              int dataFormat,
                              int unitLength,
                              int bufferSize)
Create a new VBIFilter instance within a VBIFilterGroup instance. The VBIFilter filters the specified VBI line/field and retrieves data units of the specified format. The filter has an internal buffer of the specified size to store the filtered data units. If the filtered data size exceeds the buffer size, the oversized part of data will be lost.

Parameters:
lineNumber - an array of VBI line numbers that will be filtered by a returned SimpleVBIFilter. If line 21 is specified, the filter also filters user_data defined in ANSI/SCTE 20 and ANSI/SCTE 21, when a current video is MPEG. Note that filtering of user_data is optional.
field - a field number that will be filtered by a returned VBIFilter. One of the constants that has a FIELD_ prefix.
If FIELD_MIXED is specified, the VBIFilter filters both field 1 and 2 of the specified lineNumber lines. Filtered data is concatenated in arrival order.
If FIELD_1 is specified, the VBIFilter filters only field 1 of the specified lineNumber lines.
If FIELD_2 is specified, the VBIFilter filters only field 2 of the specified lineNumber lines.
dataFormat - one of constants that has a VBI_DATA_FORMAT_ prefix to specify a data format to be filtered.
unitLength - specify the number of bits (not bytes) of a single data unit for the VBI_DATA_FORMAT_UNKNOWN format. This value shall be ignored for the other well known formats.
bufferSize - number of bytes to specify size of an internal buffer used to hold a VBI data unit.
Returns:
a new VBIFilter instance. Total number of filters created by a VBIFilterGroup shall not exceed the number of filters specified by a constructor.
Throws:
java.lang.IllegalStateException - if the total number of filters created by this VBIFilterGroup exceeds the number specified by the constructor.
java.lang.IllegalArgumentException - if this VBIFilterGroup can't create a VBIFilter for specified parameters due to hardware or software restrictions, or the lineNumber is not capable line, or if the field is not defined in constants, or the specified dataFormat is not defined in constants, or if the bufferSize is 0. For example, if this method is called with lineNumber=21, field=FIELD_1 and dataFormat=VBI_DATA_FORMAT_XDS, this exception is thrown and null returns.

attach

public void attach(javax.tv.service.selection.ServiceContext serviceContext,
                   ResourceClient client,
                   java.lang.Object requestData)
This method attempts to reserve all VBI filters held by this VBIFilterGroup, and attaches to a specified ServiceContext. After the method call, the filter starts filtering of VBI data units contained in current selected video on the ServiceContext responding to a VBIFilter.startFiltering(java.lang.Object) call. If the startFiltering method has already been called, the filter starts filtering immediately. Note that the number of filters specified by a constructor shall be created by the newVBIFilter() method before calling this method. (I.e., VBI lines and a data format shall be specified before resource reservation.)

Parameters:
serviceContext - a ServiceContext that selects the video to be filtered. It is not necessary that a specified ServiceContext is in the presenting state when this method is called.
client - DAVIC ResourceClient to be used for resource management.
requestData - application specific data to be used for resource management. Null is possible.
Throws:
java.lang.IllegalArgumentException - if the serviceContext or the client is null. Note that requestData may be null.
java.lang.IllegalStateException - if this method is called before creating all filters in this VBIFilterGroup.

detach

public void detach()
Releases all filters in this VBIFilterGroup and terminate the connection to the ServiceContext. All filtering by filters in this group terminates immediately.

Throws:
java.lang.IllegalStateException - if this method is called when the filters have already been released and this method does nothing.

getServiceContext

public javax.tv.service.selection.ServiceContext getServiceContext()
Returns a ServiceContext instance specified by a attach(javax.tv.service.selection.ServiceContext, org.davic.resources.ResourceClient, java.lang.Object) method.

Returns:
a ServiceContext instance specified by a attach(javax.tv.service.selection.ServiceContext, org.davic.resources.ResourceClient, java.lang.Object) method. Null if no ServiceContext is attached at the moment.

getSeparatedFilteringCapability

public boolean getSeparatedFilteringCapability(int[] lineNumber,
                                               int dataFormat)
Returns true if field separated filtering of the specified VBI line numbers with the specified data format is supported by this VBIFilterGroup. At a minimum, either this method or the getMixedFilteringCapability(int[], int) method shall return true for the line 21 with CC1, CC2, CC3, CC4, T1, T2, T3, T4 and XDS format.

Parameters:
lineNumber - an array of line numbers used to determine filtering capability.
dataFormat - a data format used to determine filtering capability.
Returns:
true if the host supports field separated filtering of the specified line numbers with the specified data format (i.e., the newVBIFilter() method accepts FIELD_1 or FIELD_2). Otherwise returns false.

getMixedFilteringCapability

public boolean getMixedFilteringCapability(int[] lineNumber,
                                           int dataFormat)
Returns true if field mixed filtering of the specified VBI line numbers with the specified data format is supported by this VBIFilterGroup. At a minimum, either this method or the getSeparatedFilteringCapability(int[], int) method shall return true for the line 21 with CC1, CC2, CC3, CC4, T1, T2, T3, T4 and XDS format.

Parameters:
lineNumber - a line number used to determine filtering capability.
dataFormat - a data format used to determine filtering capability.
Returns:
true if the host supports field mixed filtering of the specified line numbers with the specified data format (i.e., the newVBIFilter() method accepts FIELD_MIXED). Otherwise false returns.

getSCTE20Capability

public boolean getSCTE20Capability()
Indicates if the host supports line 21 VBI data retrieval from user_data in MPEG picture headers as defined in ANSI/SCTE 20. See also a newVBIFilter(int[], int, int, int, int) method.

Returns:
true if the host can retrieve line 21 data from user_data in MPEG picture headers as defined in ANSI/SCTE 20.

getSCTE21Capability

public boolean getSCTE21Capability()
Indicates if the host supports line 21 VBI data retrieval from user_data in MPEG picture headers as defined in ANSI/SCTE 21. See also a newVBIFilter(int[], int, int, int, int) method.

Returns:
true if the host can retrieve line 21 data from user_data in MPEG picture headers as defined in ANSI/SCTE 21.

getClient

public ResourceClient getClient()
Returns the ResourceClient object specified in the attach() method.

Specified by:
getClient in interface ResourceProxy
Returns:
the ResourceClient object specified in the last call of the attach(javax.tv.service.selection.ServiceContext, org.davic.resources.ResourceClient, java.lang.Object) method. If the attach() method has never been called or the detach() method is called to cancel an attach call, this method returns null.

addResourceStatusEventListener

public void addResourceStatusEventListener(ResourceStatusListener listener)
Add a listener object to be notified of changes in the status of resources related to VBI filters.

Specified by:
addResourceStatusEventListener in interface ResourceServer
Parameters:
listener - an object implementing the ResourceStatusListener interface. Multiple calls with a same listener instance is simply ignored with throwing no exception.
Throws:
java.lang.IllegalArgumentException - if the listener is null.

removeResourceStatusEventListener

public void removeResourceStatusEventListener(ResourceStatusListener listener)
Remove a specified listener object from this VBIFilterGroup.

Specified by:
removeResourceStatusEventListener in interface ResourceServer
Parameters:
listener - an object implementing the ResourceStatusListener interface. This method does nothing if the specified ccListener is null, not previously added or already removed.
Throws:
java.lang.IllegalArgumentException - if the listener is null.