javax.tv.service.transport.TransportStreamCollection 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 transport streams on a
 * Transport.  TransportStreamCollection may
 * be optionally implemented by Transport objects,
 * depending on the SI data carried on that transport.
 *
 * @see Optionally implemented interfaces
 */
public interface TransportStreamCollection extends Transport
{

    /** 
     * Retrieves the specified TransportStream from the
     * collection.
     *
     * @param locator Locator referencing the
     * TransportStream 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 transport stream.
     *
     * @throws SecurityException If the caller does not have
     * javax.tv.service.ReadPermission(locator).
     *
     * @see TransportStream
     * @see javax.tv.service.ReadPermission
     */
    public SIRequest retrieveTransportStream(Locator locator, SIRequestor
        requestor) throws InvalidLocatorException, SecurityException;

    /** 
     * Retrieves an array of the TransportStream objects in
     * this TransportStreamCollection.  The array will only
     * contain TransportStream instances ts
     * for which the caller has
     * javax.tv.service.ReadPermission(ts.getLocator()). If
     * no TransportStream 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 TransportStream
     * @see javax.tv.service.ReadPermission
     */
    public SIRequest retrieveTransportStreams(SIRequestor requestor);

    /** 
     * Registers a TransportStreamChangeListener to be
     * notified of changes to a TransportStream that is
     * part of this TransportStreamCollection. Subsequent
     * notification is made via TransportStreamChangeEvent
     * with this TransportStreamCollection as the event
     * source and an SIChangeType of ADD,
     * REMOVE or MODIFY.  Only changes to
     * TransportStream instances ts for which
     * the caller has
     * javax.tv.service.ReadPermission(ts.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 TransportStreamChangeListener is
     * already registered, no action is performed.
     *
     * @param listener A TransportStreamChangeListener to be
     * notified about changes related to TransportStream
     * carried on this Transport.
     *
     * @see TransportStreamChangeEvent 
     * @see javax.tv.service.ReadPermission
     */
    public void addTransportStreamChangeListener(TransportStreamChangeListener
        listener);

    /** 
     * Called to unregister an
     * TransportStreamChangeListener.  If the specified
     * TransportStreamChangeListener is not registered, no
     * action is performed.
     *
     * @param listener A previously registered listener.  
     */
    public void
        removeTransportStreamChangeListener(TransportStreamChangeListener
        listener);
}