javax.tv.service.navigation.ServiceDetails 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.navigation;
import javax.tv.service.*;
import javax.tv.service.guide.ProgramSchedule;
/**
* This interface provides access to service meta-data. It provides more
* information about a Service object and represents a
* specific instance of a service bound to a transport stream.
*
* A ServiceDetails object may optionally implement the
* ServiceNumber interface to report service numbers as
* assigned by the broadcaster of the service.
*
* A ServiceDetails object may optionally implement the
* ServiceProviderInformation interface to report information
* concerning the service provider.
*
* @see javax.tv.service.Service
*
* @see javax.tv.service.ServiceNumber
*
* @see ServiceProviderInformation
*
* @see Optionally implemented interfaces
*/
public interface ServiceDetails extends SIElement, CAIdentification
{
/**
* Retrieves a textual description of this service if available.
* 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 ServiceDescription
*/
public SIRequest retrieveServiceDescription(SIRequestor requestor);
/**
* Returns the type of this service, for example, "digital
* television", "digital radio", "NVOD", etc. These values can be
* mapped to the ATSC service type in the VCT table and the DVB
* service type in the Service Descriptor.
*
* @return Service type of this service.
*/
public ServiceType getServiceType();
/**
* Retrieves an array of elementary components which are part of
* this service. The array will only contain
* ServiceComponent instances c for which
* the caller has
* javax.tv.service.ReadPermission(c.getLocator()). If
* no ServiceComponent 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 ServiceComponent
* @see javax.tv.service.ReadPermission
*/
public SIRequest retrieveComponents(SIRequestor requestor);
/**
* Returns a schedule of program events associated with this service.
*
* @return The program schedule for this service, or null
* if no schedule is available.
*/
public ProgramSchedule getProgramSchedule();
/**
* Called to obtain a full service name. For example, this
* information may be delivered in the ATSC Extended Channel Name
* Descriptor, the DVB Service Descriptor or the DVB Multilingual
* Service Name Descriptor.
*
* @return A string representing the full service name, or an empty
* string if the name is not available.
*/
public String getLongName();
/**
* Returns the Service this ServiceDetails
* object is associated with.
*
* @return The Service to which this
* ServiceDetails belongs.
*/
public Service getService();
/**
* Registers a ServiceComponentChangeListener to be
* notified of changes to a ServiceComponent that is
* part of this ServiceDetails. Subsequent notification
* is made via ServiceComponentChangeEvent with this
* ServiceDetails instance as the event source and an
* SIChangeType of ADD,
* REMOVE or MODIFY. Only changes to
* ServiceComponent instances c for which
* the caller has
* javax.tv.service.ReadPermission(c.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 ServiceComponentChangeListener is
* already registered, no action is performed.
*
* @param listener A ServiceComponentChangeListener to be
* notified about changes related to a ServiceComponent
* in this ServiceDetails.
*
* @see ServiceComponentChangeEvent
* @see javax.tv.service.ReadPermission
*/
public void addServiceComponentChangeListener(ServiceComponentChangeListener
listener);
/**
* Called to unregister an
* ServiceComponentChangeListener. If the specified
* ServiceComponentChangeListener is not registered, no
* action is performed.
*
* @param listener A previously registered listener.
*/
public void
removeServiceComponentChangeListener(ServiceComponentChangeListener
listener);
/**
* Reports the type of mechanism by which this service was
* delivered.
*
* @return The delivery system type of this service.
*/
public DeliverySystemType getDeliverySystemType();
}