org.dvb.tvanytime.metadata
Interface Database

All Known Subinterfaces:
MonitoredDatabase
All Known Implementing Classes:
DvbDatabase, HTTPDatabase, IPDatabase, MulticastDatabase, StoredContentDatabase

public interface Database

All sources of metadata conform to this interface, whether sourced locally, from a broadcast service or from an IP server. Queries are constructed using a DatabaseQuery object, which is then passed to different database instances depending on the required source. Results are returned inside a DatabaseQueryResult object which is initially empty. An application can receive a sequence of events as each element is added by providing an instance of ResultListener. The scope of the metadata that is returned by a query can be restricted by the use of QueryConstraints

See Also:
DatabaseQuery, ResultListener, QueryConstraints, DatabaseQueryResult, DvbDatabase, IPDatabase, StoredContentDatabase

Method Summary
 Element getDiscoveryRecord()
          If this Database has been located using a BCG Discovery Record this method will return it as an instance of Element.
 DatabaseQueryResult getMetadata(CRID crid, ResultListener listener)
          Get all available metadata on a specific CRID.
 DatabaseQueryResult getMetadata(CRID crid, ResultListener listener, QueryConstraints constraints)
          Get all available metadata on a specific CRID.
 java.lang.String[][] getOptimisedQueryFields()
          Get a list of fieldIDs for fields where an optimised query is possible.
 DatabaseQueryResult query(DatabaseQuery query, ResultListener listener)
          Make a metadata query to the database.
 DatabaseQueryResult query(DatabaseQuery query, ResultListener listener, QueryConstraints constraints)
          Make a metadata query to the database.
 

Method Detail

getMetadata

DatabaseQueryResult getMetadata(CRID crid,
                                ResultListener listener)
                                throws DatabaseException
Get all available metadata on a specific CRID.

Parameters:
crid - The CRID to look up
listener - an instance of ResultListener or null
Returns:
DatabaseQueryResult that contains metadata fragments where the given CRID is the primary key. The document will be in the form of a TV Anytime compliant document (i.e. the top level element will be a TVAMain, followed by all the programme/group/... tables). The DatabaseQueryResult.getAvailableTables() method can be used to see if this contains a ProgramInformation or GroupInformation table, which can be used to decide if this is a group or programme CRID. If the CRID cannot be found, an empty document will be returned.

Implementations can choose whether or not to inline credits information directly, or to reference a fragment in the CreditsInformationTable.

Throws:
DatabaseException - if the CRID is invalid or if there is an error accessing the database.

getMetadata

DatabaseQueryResult getMetadata(CRID crid,
                                ResultListener listener,
                                QueryConstraints constraints)
                                throws DatabaseException
Get all available metadata on a specific CRID.

Parameters:
crid - The CRID to look up
listener - an instance of ResultListener or null
constraints - the constraints to apply to this metadata request
Returns:
DatabaseQueryResult that contains metadata fragments where the given CRID is the primary key. The document will be in the form of a TV Anytime compliant document (i.e. the top level element will be a TVAMain, followed by all the programme/group/... tables). The DatabaseQueryResult.getAvailableTables() method can be used to see if this contains a ProgramInformation or GroupInformation table, which can be used to decide if this is a group or programme CRID. If the CRID cannot be found, an empty document will be returned.

Implementations can choose whether or not to inline credits information directly, or to reference a fragment in the CreditsInformationTable. Specifying the CreditsInformationTable in the QueryConstraints determines if the server returns credits information at all, but does not impact the above choice on how to include the credits information. The implementation will not return credits information if the CreditsInformationTable is not specified in the QueryConstraints.

Throws:
DatabaseException - if the CRID is invalid or if there is an error accessing the database.

getOptimisedQueryFields

java.lang.String[][] getOptimisedQueryFields()
Get a list of fieldIDs for fields where an optimised query is possible. An optimised query is defined as one that uses either a TV Anytime index, a locally indexed field or a field that is supported by an IP metadata service.

Returns:
an array of arrays listing fieldIDs for fields that support optimised searching. Arrays with more than one element represent multifield queries.

query

DatabaseQueryResult query(DatabaseQuery query,
                          ResultListener listener)
                          throws DatabaseException
Make a metadata query to the database.

Parameters:
query - The query to perform on the database
listener - an instance of ResultListener or null
Returns:
DatabaseQueryResult that contains all the metadata that matches the query. The document will be in the form of a TV Anytime compliant document (i.e. the top level element will be a TVAMain, followed by all the programme/group/... tables) If nothing matches the query, an empty document will be returned.

Implementations can choose whether or not to inline credits information directly, or to reference a fragment in the CreditsInformationTable.

A ServiceInformationTable will always be included in the response if a ServiceInformation entry is being referenced (using a serviceIDRef) from a ProgramLocationTable.

Throws:
DatabaseException - if the CRID is invalid or if there is an error accessing the database.

query

DatabaseQueryResult query(DatabaseQuery query,
                          ResultListener listener,
                          QueryConstraints constraints)
                          throws DatabaseException
Make a metadata query to the database.

Parameters:
query - The query to perform on the database
listener - an instance of ResultListener or null
constraints - the constraints to apply to this metadata request
Returns:
DatabaseQueryResult that contains all the metadata that matches the query. The document will be in the form of a TV Anytime compliant document (i.e. the top level element will be a TVAMain, followed by all the programme/group/... tables) If nothing matches the query, an empty document will be returned.

Implementations can choose whether or not to inline credits information directly, or to reference a fragment in the CreditsInformationTable. Specifying the CreditsInformationTable in the QueryConstraints determines if the server returns credits information at all, but does not impact the above choice on how to include the credits information. The implementation will not return credits information if the CreditsInformationTable is not specified in the QueryConstraints.

A ServiceInformationTable will always be included in the response if a ServiceInformation entry is being referenced (using a serviceIDRef) from a ProgramLocationTable. Thus, specifying the ServiceInformationTable in the QueryConstraints will have no effect if a ProgramLocationTable is being returned.

Throws:
DatabaseException - if the CRID is invalid or if there is an error accessing the database.

getDiscoveryRecord

Element getDiscoveryRecord()
If this Database has been located using a BCG Discovery Record this method will return it as an instance of Element. Otherwise this method will return null.

Returns:
an Element carrying the Discovery Record or null.