javax.tv.service.transport.NetworkCollection 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 networks on a
* Transport. This information is carried in the DVB SI
* NIT or US Cable SI (A56) NIT tables.
* NetworkCollection may be optionally implemented by
* Transport objects, depending on the SI data carried on
* that transport.
*
* @see Optionally implemented interfaces
*/
public interface NetworkCollection extends Transport
{
/**
* Retrieves the specified Network from the collection.
*
* This method delivers its results asynchronously.
*
* @param locator Locator referencing the Network 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 network.
*
* @throws SecurityException If the caller does not have
* javax.tv.service.ReadPermission(locator).
*
* @see Network
* @see javax.tv.service.ReadPermission
*/
public SIRequest retrieveNetwork(Locator locator, SIRequestor requestor)
throws InvalidLocatorException, SecurityException;
/**
* Retrieves an array of all the Network objects in
* this NetworkCollection. The array will only contain
* Network instances n for which the
* caller has
* javax.tv.service.ReadPermission(n.getLocator()). If
* no Network 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 Network
* @see javax.tv.service.ReadPermission
*/
public SIRequest retrieveNetworks(SIRequestor requestor);
/**
* Registers a NetworkChangeListener to be notified of
* changes to a Network that is part of this
* NetworkCollection. Subsequent notification is made
* via NetworkChangeEvent with this
* NetworkCollection as the event source and an
* SIChangeType of ADD,
* REMOVE or MODIFY. Only changes to
* Network instances n for which the
* caller has
* javax.tv.service.ReadPermission(n.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 NetworkChangeListener is
* already registered, no action is performed.
*
* @param listener A NetworkChangeListener to be
* notified about changes related to Network
* carried on this Transport.
*
* @see NetworkChangeEvent
* @see javax.tv.service.ReadPermission
*/
public void addNetworkChangeListener(NetworkChangeListener listener);
/**
* Called to unregister an
* NetworkChangeListener. If the specified
* NetworkChangeListener is not registered, no
* action is performed.
*
* @param listener A previously registered listener.
*/
public void removeNetworkChangeListener(NetworkChangeListener listener);
}