javax.tv.service.transport.NetworkCollection Maven / Gradle / Ivy
/*
* @(#)NetworkCollection.java 1.31 00/09/27
*
* Copyright 1998-2000 by Sun Microsystems, Inc.,
* 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
* All rights reserved.
*
* This software is the confidential and proprietary information
* of Sun Microsystems, Inc. ("Confidential Information"). You
* shall not disclose such Confidential Information and shall use
* it only in accordance with the terms of the license agreement
* you entered into with Sun.
*/
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 abstract 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 abstract 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 abstract 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 abstract void removeNetworkChangeListener(NetworkChangeListener listener);
}