javax.tv.service.Service 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;
import javax.tv.locator.Locator;
/**
* The Service interface represents an abstract view on
* what is generally referred to as a television "service" or
* "channel". It may represent an MPEG-2 program, DVB service, an ATSC
* virtual channel, SCTE virtual channel, etc. It represents the basic
* information associated with a service, such as its name or number,
* which is guaranteed to be available on the receiver.
*
* Internal to the receiver, each service is uniquely identified by
* information that may include system type, network ID, transport stream
* ID, service number, service number, or other information. This
* identification is encapsulated by the Locator object.
*
* Note that a Service object may represent multiple
* instances of the same content delivered over different media
* (e.g., the same service may be delivered over a terrestrial and
* cable network). A ServiceDetails object represents a
* specific instance of such content which is bound to a specific
* delivery mechanism.
*
* The information available through this object, i.e., the service name,
* service number, etc., represents information that is stored in
* the receiver and is not necessarily the same as what is broadcast in any
* broadcast service information protocol. For example, a receiver
* implementation may let the end user edit this information according to
* the user's preferences.
*
* A Service object may optionally implement an interface
* that supports service numbers. Each Service object
* must provide either a service name (via the getName method)
* or a service number (via the ServiceNumber interface).
*
* @see #getName
* @see ServiceNumber
* @see javax.tv.service.navigation.ServiceDetails
* @see Optionally implemented interfaces
*/
public interface Service
{
/**
* This method retrieves additional information about the
* Service. This information is retrieved from the
* broadcast service information.
*
* Note that if the content represented by this Service
* is delivered on multiple transport-dependent streams there may be
* multiple ServiceDetails for it. This method
* retrieves one of them based on availability or user
* preferences. If access to all possible
* ServiceDetails is required, the service
* Locator can be transformed to transport-dependent
* Locator instances and ServiceDetails
* can be retrieved for each.
*
* This method returns data asynchronously.
*
* @param requestor The SIRequestor to be notified
* when this retrieval operation completes.
*
* @return An SIRequest object identifying this
* asynchronous retrieval request.
*
* @see javax.tv.locator.Locator
*
* @see javax.tv.service.navigation.ServiceDetails
*/
public SIRequest retrieveDetails(SIRequestor requestor);
/**
* Returns a short service name or acronym. For example, in ATSC
* systems the service name is provided by the the PSIP VCT; in DVB
* systems, this information is provided by the DVB Service
* Descriptor or the Multilingual Service Name Descriptor. The
* service name may also be user-defined.
*
* @return A string representing this service's short name. If the
* short name is unavailable, the string representation of the
* service number is returned.
*/
public String getName();
/**
* This method indicates whether the service represented by this
* Service object is available on multiple
* transports, (e.g., the same content delivered over terrestrial and
* cable network).
*
* @return true if multiple transports carry the same
* content identified by this Service object;
* false if there is only one instance of this service.
*/
public boolean hasMultipleInstances();
/**
* 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();
/**
* Reports the Locator of this Service.
* Note that if the resulting locator is transport-dependent, it
* will also correspond to a ServiceDetails object.
*
* @return A locator referencing this Service.
*
* @see javax.tv.service.navigation.ServiceDetails
*/
public Locator getLocator();
/**
* Tests two Service objects for equality. Returns
* true if and only if:
*
* obj's class is the
* same as the class of this Service, and
*
obj's Locator is equal to
* the Locator of this Service
* (as reported by
* Service.getLocator(), and
*
obj and this object encapsulate identical data.
*
*
* @param obj The object against which to test for equality.
*
* @return true if the two Service objects
* are equal; false otherwise.
*/
public boolean equals(Object obj);
/**
* Reports the hash code value of this Service. Two
* Service objects that are equal will have identical
* hash codes.
*
* @return The hash code value of this Service.
*/
public int hashCode();
}