javax.tv.service.SIManager Maven / Gradle / Ivy

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.*; import javax.tv.service.navigation.*; import javax.tv.service.transport.Transport; /** * An SIManager represents a managing entity which has * knowledge of all the broadcast resources available to a receiver. An * SIManager can be used to retrieve any * SIElement or create a collection of * Service objects according to filtering rules.

* * An SIManager may also be used to set parameters such * as the preferred language for multilingual text information. * Normally an application will create a single instance of * SIManager and use that instance to access all SI * information. If an application creates more than one instance of * SIManager it may experience degraded caching * performance, particularly if the SIManager instances * use different preferred languages. * * @see Service * @see SIElement * */ public abstract class SIManager { /** * Constructs an SIManager object. */ protected SIManager() { } /** * Creates a new instance of SIManager. * * @return A new instance of SIManager. */ public static SIManager createInstance() { return null; } /** * Overrides the system-level preferred language for objects * obtained through this SIManager. The specified * language will be used by the textual information obtained from * the SIElement objects obtained through this * SIManager, if such information is available in the * specified language. If the specified language is not available * the system-level preferred language is used. If the system-level * preferred language is not available either, the first available * language will be used.

* * The preferred language is indicated using a language code. * This is typically a three-character language code as specified by * ISO 639.2/B, but the code may be system-dependent. * * @param language A string representing the desired language code. * If the input parameter is null, any language * preference previously set using this method is canceled. */ public abstract void setPreferredLanguage(String language); /** * Reports the preferred language for this SIManager. * The resulting string is a language code indicating * the language desired when retrieving multilingual text. This * is typically a three-character code as specified by ISO 639.2/B. * * @return A string representing a language code defining the language * used to retrieve multilingual strings. If no language preference * is in effect, null is returned. */ public abstract String getPreferredLanguage(); /** * Provides a hint to the SI database that the application desires * SI information as complete as possible about the specified * SIElement. As a result, the SI database might tune * to the transport stream delivering the desired information and * begin caching it, depending on resource availability. * *

For example, if the given Locator references a * bouquet, the database might begin caching * ServiceDetails data for services that are part of * the bouquet. If the given Locator * references a service, the database might start caching * ProgramEvent data for the service. * *

Note that this method returns immediately and that there is * no indication of the completion of any resulting SI database * operations. Since it is only a hint for cache optimization, no * specific behavior for this method is guaranteed. * * @param locator A locator referencing the SIElement * for which complete information is desired. * * @param active A flag indicating whether this interest is active * or not. A value of true means that the application * is interested in the SIElement; false * means that the application wants to cancel a previously shown * interest for the SIElement. * * @throws InvalidLocatorException If locator does not * reference a valid SIElement. * * @throws SecurityException If the caller does not have * javax.tv.service.ReadPermission(locator). * * @see javax.tv.service.ReadPermission */ public abstract void registerInterest(Locator locator, boolean active) throws InvalidLocatorException, SecurityException; /** * Provides the names of available rating dimensions in the local * rating region. A zero-length array is returned if no rating * dimensions are available. * * @return An array of strings representing the names of available * rating dimensions in this rating region. * * @see RatingDimension */ public abstract String[] getSupportedDimensions(); /** * Reports the RatingDimension corresponding to the * specified string name. * * @param name The name of the requested rating dimension. * * @return The requested RatingDimension. * * @throws SIException If name is not a supported * rating dimension, as returned by getSupportedDimensions(). * * @see #getSupportedDimensions */ public abstract RatingDimension getRatingDimension(String name) throws SIException; /** * Reports the various content delivery mechanisms currently * available on this platform. The implementation must be capable * of supporting at least one Transport instance. * * @return An array of Transport objects representing * the content delivery mechanisms currently available on this * platform. */ public abstract Transport[] getTransports(); /** * Retrieves the SIElement corresponding to the * specified Locator. If the locator identifies more * than one SIElement, all matching * SIElements are retrieved.

* * For example, multiple SIElement objects are * retrieved when the locator represents identical content delivered * over different media (terrestrial, satellite, cable, etc.) or a * specific program event made available at different times, * possibly on different services.

* * This call retrieves various types of SIElement * instances according to the locator specified. For example, if * the locator is a transport-dependent locator to a service (and * therefore to a ServiceDetails -- see {@link * Service#getLocator} for more information), a * ServiceDetails object is retrieved; if the locator * represents a program event, a ProgramEvent object is * retrieved; if the locator represents a service component, a * ServiceComponent is retrieved.

* *

This method delivers its results asynchronously. * * @param locator A locator referencing one or more SIElements. * * @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 SIElement. * * @throws SecurityException if the caller does not have * javax.tv.service.ReadPermission(locator). * * @see SIElement */ public abstract SIRequest retrieveSIElement(Locator locator, SIRequestor requestor) throws InvalidLocatorException, SecurityException; /** * Provides the Service identified by a given * Locator. An implementation must be capable of * supporting at least one Service instance. *

* If the specified locator references a transport-dependent * SIElement, and the locator data contains * sufficient information to identify the Service which * contains the SIElement, then that Service * will be returned. * * @param locator A locator identifying a service. * * @return The Service object corresponding to the * specified locator. * * @throws InvalidLocatorException If locator does not * identify a valid Service. * * @throws SecurityException If the caller does not have * javax.tv.service.ReadPermission(locator). * * @see javax.tv.service.ReadPermission */ public abstract Service getService(Locator locator) throws InvalidLocatorException, SecurityException; /** * Retrieves the ServiceDetails object corresponding to * the given Locator. * *

Note that the locator may point to an SI element lower in the * hierarchy than a service (such as a program event). In such a * case, the ServiceDetails for the service that the * program event is part of will be returned.

* * If a transport-independent locator is provided, one or more * ServiceDetails objects may be returned. However, it * is permissible in this case for this method to always retrieve * a single ServiceDetails object, as determined * by the implementation, user preferences, or availability. To * obtain all of the corresponding ServiceDetails * objects, the application may transform the transport-independent * locator into multiple transport-dependent locators and retrieve * a ServiceDetails object for each.

* * This method delivers its results asynchronously. * * @param locator A locator referencing a Service * * @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 Service. * * @throws SecurityException If the caller does not have * javax.tv.service.ReadPermission(locator). * * @see Locator * @see ServiceDetails * @see javax.tv.service.ReadPermission */ public abstract SIRequest retrieveServiceDetails(Locator locator, SIRequestor requestor) throws InvalidLocatorException, SecurityException; /** * Retrieves the ProgramEvent corresponding to the * given Locator. If a transport-independent locator * is provided (e.g., one referencing the same movie shown at * different times and/or on different services), this method may * retrieve multiple ProgramEvent objects.

* * This method delivers its results asynchronously. * * @param locator A locator referencing a ProgramEvent * * @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 ProgramEvent. * * @throws SecurityException If the caller does not have * javax.tv.service.ReadPermission(locator). * * @see javax.tv.service.guide.ProgramEvent * @see javax.tv.service.ReadPermission */ public abstract SIRequest retrieveProgramEvent(Locator locator, SIRequestor requestor) throws InvalidLocatorException, SecurityException; /** * Filters the available services using the * ServiceFilter provided to generate a * ServiceList containing the matching services. If * the filter parameter is null, a list of all known * services is generated. Only Service instances for * which the caller has javax.tv.service.ReadPermission * on the underlying locator will be present in the returned * list.