javax.tv.service.transport.BouquetCollection Maven / Gradle / Ivy
/**
This is not an official specification document, and usage is restricted.
NOTICE
(c) 2005-2008 Sun Microsystems, Inc. All Rights Reserved.
Neither this file nor any files generated from it describe a complete
specification, and they may only be used as described below.
Sun Microsystems Inc. owns the copyright in this file and it is provided
to you for informative use only. For example,
this file and any files generated from it may be used to generate other documentation,
such as a unified set of documents of API signatures for a platform
that includes technologies expressed as Java APIs.
This file may also be used to produce "compilation stubs,"
which allow applications to be compiled and validated for such platforms.
By contrast, no permission is given for you to incorporate this file,
in whole or in part, in an implementation of a Java specification.
Any work generated from this file, such as unified javadocs or compiled
stub files, must be accompanied by this notice in its entirety.
This work corresponds to the API signatures of JSR 927: Java TV API 1.1.1.
In the event of a discrepency between this work and the JSR 927 specification,
which is available at http://www.jcp.org/en/jsr/detail?id=927, the latter takes precedence.
*/
package javax.tv.service.transport;
import javax.tv.service.*;
import javax.tv.locator.*;
/**
* This interface represents a collection of bouquets on a
* Transport. In DVB SI, this information is contained
* in the BAT tables. BouquetCollection may be
* optionally implemented by Transport objects, depending
* on the SI data carried on that transport.
*
* @see Optionally implemented interfaces
*/
public interface BouquetCollection extends Transport
{
/**
* Retrieves the specified Bouquet from the collection.
*
* This method delivers its results asynchronously.
*
* @param locator A Locator referencing the
* Bouquet of interest.
*
* @param requestor The SIRequestor to be notified
* when this retrieval operation completes.
*
* @return An SIRequest object identifying this
* asynchronous retrieval request.
*
* @throws InvalidLocatorException If locator does not
* reference a valid bouquet.
*
* @throws SecurityException If the caller does not have
* javax.tv.service.ReadPermission(locator).
*
* @see Bouquet
* @see javax.tv.service.ReadPermission
*/
public SIRequest retrieveBouquet(Locator locator, SIRequestor requestor)
throws InvalidLocatorException, SecurityException;
/**
* Retrieves an array of all the Bouquet objects in
* this BouquetCollection. This array will only contain
* Bouquet instances b for which the caller has
* javax.tv.service.ReadPermission(b.getLocator()). If
* no Bouquet instances meet this criteria, this method
* will result in an SIRequestFailureType of
* DATA_UNAVAILABLE.
*
* This method delivers its results asynchronously.
*
* @param requestor The SIRequestor to be notified
* when this retrieval operation completes.
*
* @return An SIRequest object identifying this
* asynchronous retrieval request.
*
* @see Bouquet
* @see javax.tv.service.ReadPermission
*/
public SIRequest retrieveBouquets(SIRequestor requestor);
/**
* Registers a BouquetChangeListener to be notified of
* changes to a Bouquet that is part of this
* BouquetCollection. Subsequent notification is made
* via BouquetChangeEvent with this
* BouquetCollection as the event source and an
* SIChangeType of ADD,
* REMOVE or MODIFY. Only changes to
* Bouquet instances b for which the
* caller has
* javax.tv.service.ReadPermission(b.getLocator()) will
* be reported.
*
* This method is only a request for notification. No guarantee is
* provided that the SI database will detect all, or even any, SI
* changes or whether such changes will be detected in a timely
* fashion.
*
* If the specified BouquetChangeListener is
* already registered, no action is performed.
*
* @param listener A BouquetChangeListener to be
* notified about changes related to Bouquet
* carried on this Transport.
*
* @see BouquetChangeEvent
* @see javax.tv.service.ReadPermission
*/
public void addBouquetChangeListener(BouquetChangeListener listener);
/**
* Called to unregister an
* BouquetChangeListener. If the specified
* BouquetChangeListener is not registered, no
* action is performed.
*
* @param listener A previously registered listener.
*/
public void removeBouquetChangeListener(BouquetChangeListener listener);
}