|
JSR-927 (Maintenance Release) | ||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object javax.tv.service.SIManager
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.
Service
,
SIElement
Constructor Summary | |
protected |
SIManager()
Constructs an SIManager object. |
Method Summary | |
static SIManager |
createInstance()
Creates a new instance of SIManager . |
abstract ServiceList |
filterServices(ServiceFilter filter)
Filters the available services using the ServiceFilter provided to generate a
ServiceList containing the matching services. |
abstract java.lang.String |
getPreferredLanguage()
Reports the preferred language for this SIManager . |
abstract RatingDimension |
getRatingDimension(java.lang.String name)
Reports the RatingDimension corresponding to the
specified string name. |
abstract Service |
getService(Locator locator)
Provides the Service identified by a given
Locator . |
abstract java.lang.String[] |
getSupportedDimensions()
Provides the names of available rating dimensions in the local rating region. |
abstract Transport[] |
getTransports()
Reports the various content delivery mechanisms currently available on this platform. |
abstract void |
registerInterest(Locator locator,
boolean active)
Provides a hint to the SI database that the application desires SI information as complete as possible about the specified SIElement . |
abstract SIRequest |
retrieveProgramEvent(Locator locator,
SIRequestor requestor)
Retrieves the ProgramEvent corresponding to the
given Locator . |
abstract SIRequest |
retrieveServiceDetails(Locator locator,
SIRequestor requestor)
Retrieves the ServiceDetails object corresponding to
the given Locator . |
abstract SIRequest |
retrieveSIElement(Locator locator,
SIRequestor requestor)
Retrieves the SIElement corresponding to the
specified Locator . |
abstract void |
setPreferredLanguage(java.lang.String language)
Overrides the system-level preferred language for objects obtained through this SIManager . |
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
protected SIManager()
SIManager
object.
Method Detail |
public static SIManager createInstance()
SIManager
.
SIManager
.public abstract void setPreferredLanguage(java.lang.String language)
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.
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 java.lang.String getPreferredLanguage()
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.
null
is returned.public abstract void registerInterest(Locator locator, boolean active) throws InvalidLocatorException, java.lang.SecurityException
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.
locator
- A locator referencing the SIElement
for which complete information is desired.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
.
InvalidLocatorException
- If locator
does not
reference a valid SIElement
.
java.lang.SecurityException
- If the caller does not have
javax.tv.service.ReadPermission(locator)
.ReadPermission
public abstract java.lang.String[] getSupportedDimensions()
RatingDimension
public abstract RatingDimension getRatingDimension(java.lang.String name) throws SIException
RatingDimension
corresponding to the
specified string name.
name
- The name of the requested rating dimension.
RatingDimension
.
SIException
- If name
is not a supported
rating dimension, as returned by getSupportedDimensions()
.getSupportedDimensions()
public abstract Transport[] getTransports()
Transport
instance.
Transport
objects representing
the content delivery mechanisms currently available on this
platform.public abstract SIRequest retrieveSIElement(Locator locator, SIRequestor requestor) throws InvalidLocatorException, java.lang.SecurityException
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 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.
locator
- A locator referencing one or more SIElements.requestor
- The SIRequestor
to be notified
when this retrieval operation completes.
SIRequest
object identifying this
asynchronous retrieval request.
InvalidLocatorException
- If locator
does not
reference a valid SIElement
.
java.lang.SecurityException
- if the caller does not have
javax.tv.service.ReadPermission(locator)
.SIElement
public abstract Service getService(Locator locator) throws InvalidLocatorException, java.lang.SecurityException
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.
locator
- A locator identifying a service.
Service
object corresponding to the
specified locator.
InvalidLocatorException
- If locator
does not
identify a valid Service
.
java.lang.SecurityException
- If the caller does not have
javax.tv.service.ReadPermission(locator)
.ReadPermission
public abstract SIRequest retrieveServiceDetails(Locator locator, SIRequestor requestor) throws InvalidLocatorException, java.lang.SecurityException
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.
locator
- A locator referencing a Servicerequestor
- The SIRequestor
to be notified
when this retrieval operation completes.
SIRequest
object identifying this
asynchronous retrieval request.
InvalidLocatorException
- If locator
does not
reference a valid Service
.
java.lang.SecurityException
- If the caller does not have
javax.tv.service.ReadPermission(locator)
.Locator
,
ServiceDetails
,
ReadPermission
public abstract SIRequest retrieveProgramEvent(Locator locator, SIRequestor requestor) throws InvalidLocatorException, java.lang.SecurityException
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.
locator
- A locator referencing a ProgramEventrequestor
- The SIRequestor
to be notified
when this retrieval operation completes.
SIRequest
object identifying this
asynchronous retrieval request.
InvalidLocatorException
- If locator
does not
reference a valid ProgramEvent
.
java.lang.SecurityException
- If the caller does not have
javax.tv.service.ReadPermission(locator)
.ProgramEvent
,
ReadPermission
public abstract ServiceList filterServices(ServiceFilter filter)
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.
Note that for each Service
to be filtered, the
accept()
method of the given
ServiceFilter
will be invoked with the same
application thread that invokes this method.
filter
- A ServiceFilter
by which to generate
the requested service list, or null
.
ServiceList
generated according to the
specified filtering rules.ServiceFilter.accept(javax.tv.service.Service)
|
JSR-927 (Maintenance Release) | ||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |