org.dvb.tvanytime.metadata
Interface DatabaseQueryResult


public interface DatabaseQueryResult

Class that holds the result of a database query. When a database query is completed the DatabaseQueryResult will contain 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) The getAvailableTables() method can be used to see what tables (ProgramInformation, GroupInformation, etc) are in the result.

See Also:
Database, DatabaseQuery, ResultListener

Method Summary
 void close()
          Closes the result and releases all system resources, removes all listeners.
 Table[] getAvailableTables()
          Returns a list of the metadata tables present in this result set.
 java.lang.Exception getFailedException()
          Get the exception that caused getStatus() to return REQUEST_FAILED or RESPONSE_INCOMPLETE.
 ListIterator getFragments()
          Get a ListIterator for all of the TV Anytime fragments in this result.
 ListIterator getFragments(java.lang.String[] fragmentNames)
          Get a ListIterator for the specified TV Anytime fragment types that are found in this result.
 Element getRootElement()
          Get the root element of this result.
 int getStatus()
          Returns the status of this DatabaseQueryResult at completion.
 ListIterator getUnknownFragments()
          Get a ListIterator of the unknown fragments that are found in this result.
 ListIterator getUnknownFragments(int DVBContextPath)
          Get a ListIterator of unknown fragments with the specified DVBContextPath that are found in this result.
 boolean isComplete()
          Indicates that the database query has been completed.
 

Method Detail

getAvailableTables

Table[] getAvailableTables()
Returns a list of the metadata tables present in this result set. This method will return null until the database query has been completed and the isComplete() method returns true.

Returns:
an array of type Table, with one element for each table in the result. If there are no tables in the result, an empty array is returned. For each element of the array the methods Table.getSortCriteriaFieldIDs() and Table.getSortCriteriaOrderings() can be used to determine whether the results from a particular table have been sorted.

getRootElement

Element getRootElement()
Get the root element of this result. This method will return null until the database query has been completed and the isComplete() method returns true.

Returns:
an element called "TVAMain", which has one child called "ProgramDescription", or null if the DatabaseQueryResult contains only ContentReferencingTable fragments.

getFragments

ListIterator getFragments()
Get a ListIterator for all of the TV Anytime fragments in this result. This method will return null until the database query has been completed and the isComplete() method returns true. Each fragment is an object that implements the Element interface. For example a fragment for the description of one TV programme would be an element with the name "ProgramInformation". Note that these fragments do not contain TVAMain etc and therefore calling getParent on a fragment will return null.

Returns:
a ListIterator of objects implementing the org.dvb.xml.jdom.Element interface

getFragments

ListIterator getFragments(java.lang.String[] fragmentNames)
Get a ListIterator for the specified TV Anytime fragment types that are found in this result. This method will return null until the database query has been completed and the isComplete() method returns true. Each fragment is an object that implements the Element interface. For example a fragment for the description of one TV programme would be an element with the name "ProgramInformation". Note that these fragments do not contain TVAMain etc and therefore calling getParent on a fragment will return null.

Parameters:
fragmentNames - the list of required fragments. Each item is a String that contains the name of the top level Element of the fragment, for example "ProgramInformation" to request ProgramInformation fragments.
Returns:
a ListIterator of objects implementing the org.dvb.xml.jdom.Element interface

isComplete

boolean isComplete()
Indicates that the database query has been completed. Database queries can take time to be processed. As individual fragments in the results become available they will be signalled by the databaseResultAdded method of ResultListener. The completion of the database query will be signalled by the notifyFinished method of ResultListener after which the isComplete method will return true.

Returns:
true if this DatabaseQueryResult is complete.

getStatus

int getStatus()
Returns the status of this DatabaseQueryResult at completion. The value returned by this method before the database query has been completed and the isComplete() method returns true is unspecified.

Returns:
a value chosen from ResultListener.REQUEST_COMPLETED, ResultListener.REQUEST_FAILED, ResultListener.RESPONSE_INCOMPLETE and ResultListener.RESPONSE_TRUNCATED

close

void close()
Closes the result and releases all system resources, removes all listeners. This function should be called when an application no longer requires this DatabaseQueryResult. Once close() has been called, an application must not call any methods in this object.


getFailedException

java.lang.Exception getFailedException()
                                       throws java.lang.IllegalStateException
Get the exception that caused getStatus() to return REQUEST_FAILED or RESPONSE_INCOMPLETE.

Returns:
The exception that caused the failure. The exception returned will be a DatabaseException.
Throws:
java.lang.IllegalStateException - if getStatus() does not return ResultListener.REQUEST_FAILED or ResultListener.RESPONSE_INCOMPLETE

getUnknownFragments

ListIterator getUnknownFragments()
Get a ListIterator of the unknown fragments that are found in this result. An unknown fragment is one with a DVBContextPath value that is not recognised by the resident decoder. If there are no unknown fragments this method will return null. Each of the returned fragments is represented by an UnknownElementContent object. The UnknownElementContent.readBits(int) method of these objects will access the FragmentUpdatePayload of each fragment.

Returns:
a ListIterator of UnknownElementContent objects or null.

getUnknownFragments

ListIterator getUnknownFragments(int DVBContextPath)
Get a ListIterator of unknown fragments with the specified DVBContextPath that are found in this result. An unknown fragment is one with a DVBContextPath value that is not recognised by the resident decoder. If the specified DVBContextPath value is one supported by the resident decoder this method will return null. If the value is not supported but there are no matching fragments an empty ListIterator will be returned. Each of the returned fragments is represented by an UnknownElementContent object. The UnknownElementContent.readBits(int) method of these objects will access the FragmentUpdatePayload of each fragment.

Parameters:
DVBContextPath - the DVBContextPath of the required fragments.
Returns:
a ListIterator of UnknownElementContent objects.