|
JSR-927 (Maintenance Release) | ||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
A ServiceContext
represents an environment in which
services are presented in a broadcast receiver. Applications may
use ServiceContext
objects to select new services to
be presented. Content associated with a selected service is
presented by one or more ServiceContentHandler
objects
managed by the ServiceContext
.
A ServiceContext
can exist in four states -
presenting, not presenting, presentation
pending and destroyed. The initial state is
not presenting.
The select()
method can be called from any state
except destroyed. Assuming no exception is thrown, the
service context then enters the presentation pending
state. No event is generated on this state transition. If a call to
select()
completes successfully, either a
NormalContentEvent
or an
AlternativeContentEvent
is generated and the
ServiceContext
moves into the presenting
state.
If the selection operation fails, a
SelectionFailedEvent
is generated. If the
select()
method is called during the presentation
pending state, a SelectionFailedEvent
with reason
code INTERRUPTED
is generated, and the
ServiceContext
will proceed in the presentation
pending state for the most recent select()
call.
Otherwise, if the state before the failed select operation was
not presenting, the ServiceContext
will
return to that state and a PresentationTerminatedEvent
be generated.
Likewise, if the state before the failed select operation was
presentation pending, the ServiceContext
will
move to the not presenting state and generate a
PresentationTerminatedEvent
.
If the state before the failed select operation was
presenting, it will attempt to return to that previous
state, which can result in a NormalContentEvent
or
AlternativeContentEvent
if this is possible or a
PresentationTerminatedEvent
if it is not possible.
The not presenting state is entered due to service
presentation being stopped which is reported by a
PresentationTerminatedEvent
. Service
presentation stops when an application calls the
stop()
method or
when continued presentation becomes impossible -- due, for example,
to a a change in the environment or a failed service selection attempt.
The destroyed state is entered by calling the
destroy()
method, and is signaled by a
ServiceContextDestroyedEvent
. Once this state is
entered, the ServiceContext
can no longer be used for
any purpose. A destroyed ServiceContext
will be
eligible for garbage collection once all references to it by any
applications have been removed.
Note that the ability to select a service for presentation does not imply exclusive rights to the resources required for that presentation. Subsequent attempts to select the same service may fail.
Applications may also use this interface to register for events
associated with ServiceContext
state changes.
Service
,
ServiceContentHandler
,
NormalContentEvent
,
AlternativeContentEvent
,
SelectionFailedEvent
,
PresentationTerminatedEvent
,
ServiceContextDestroyedEvent
,
ServiceContextListener
Method Summary | |
void |
addListener(ServiceContextListener listener)
Subscribes a listener to receive events related to this ServiceContext . |
void |
destroy()
Causes the ServiceContext to release all resources
and enter the destroyed state. |
Service |
getService()
Reports the Service being presented in this
ServiceContext . |
ServiceContentHandler[] |
getServiceContentHandlers()
Reports the current collection of ServiceContentHandlers. |
void |
removeListener(ServiceContextListener listener)
Unsubscribes a listener from receiving events related to this ServiceContext . |
void |
select(Locator[] components)
Selects content by specifying the parts of a service to be presented. |
void |
select(Service selection)
Selects a service to be presented in this ServiceContext . |
void |
stop()
Causes the ServiceContext to stop presenting content
and enter the not presenting state. |
Method Detail |
public void select(Service selection) throws java.lang.SecurityException
ServiceContext
. If the ServiceContext
is already presenting content, the new selection replaces the
content being presented. If the ServiceContext
is
not presenting, successful conclusion of this operation results in
the ServiceContext
entering the presenting
state.
This method is asynchronous and successful completion of the
selection is notified by either a NormalContentEvent
or a AlternativeContentEvent
. If an exception is
thrown when this method is called, the state of the service
context does not change. In such a case, any service being
presented before this method was called will continue to be
presented.
If the selection process fails after this method returns, a
SelectionFailedEvent
will be generated. In this
case, the system will attempt to return to presenting the
original service (if any). If this is not possible (due, for
example, to issues such as tuning or CA) the
ServiceContext
will enter the not
presenting state and a
PresentationTerminatedEvent
will be generated.
If the ServiceContext
is currently presenting a
service and components of the current service are also to be
presented in the newly selected service, these components will
continue to be presented and will not be restarted. If the
calling application is not a part of the newly selected service
and the application lifecycle policy on the receiver dictates
that the calling application be terminated, termination of the
application will be affected through the application lifecycle
API.
If the provided Service
is transport-independent,
this method will resolve the Service
to a
transport-dependent Service
before performing the
selection. The actual Service
selected will be
reported through the getService()
method.
Successful completion of a select operation using this method
provides ServiceContentHandler
instances for all
components that are signaled as "auto-start" in the selected
service. Upon entering the presenting state, these
ServiceContentHandler
instances will have begun
presenting their respective content;
ServiceMediaHandler
instances will be in the
started state.
If a service with no auto-start components is selected, the
ServiceContext
generates a
NormalContentEvent
and enters the presenting
state, but no ServiceContentHandler
s are created.
selection
- The Service
the service to be
selected.
java.lang.SecurityException
- If the caller does not have
SelectPermission(selection.getLocator(), "own")
.
java.lang.IllegalStateException
- If the ServiceContext
has been destroyed.NormalContentEvent
,
AlternativeContentEvent
,
SelectionFailedEvent
,
PresentationTerminatedEvent
,
Service
,
getService()
,
ServiceContentHandler
,
destroy()
,
SelectPermission
public void select(Locator[] components) throws InvalidLocatorException, InvalidServiceComponentException, java.lang.SecurityException
ServiceContext
is
already presenting content, the new selection replaces the
content being presented. If the
ServiceContext
is not presenting,
successful conclusion of this operation results in the
ServiceContext
entering the
presenting state.
If failure of the selection operation
is determined in the execution of this method, an
exception is generated and the state of the
ServiceContext
does not change.
(Note that such sychronous failure may result from a failure
to select the content corresponding to any locator
in the array.)
In this case, any
service being presented before this method was called will
continue to be presented.
If the method returns successfully, then the selection operation
proceeds asynchronously.
Successful completion of the operation will be signaled by either
a single
NormalContentEvent
or a single
AlternativeContentEvent
.
If the content corresponding to any of the specified locators can
be successfully presented then the selection operation is
considered successful, i.e., even if attempts to present content
corresponding to some locators fail.
If failure of the selection is determined asynchronously,
a SelectionFailedEvent
will be
generated indicating the reason for the failure.
(Note that such asychronous failure must result from a failure
to select the content corresponding to all locators
in the array.)
If the selection fails due to multiple reasons, then the
reason code will be SelectionFailedEvent.OTHER
.
After a SelectionFailedEvent
is generated,
the ServiceContext
will
try to return to presenting the original service, if any. If
this is not possible (due, for example, to issues such as tuning
or conditional access), then the ServiceContext
will enter the not presenting state and a
PresentationTerminatedEvent
will be generated.
If the ServiceContext
is currently presenting a service and
components of the current service are also to be presented in the
newly selected content, these components will continue to be
presented and will not be restarted. If the calling application
is not a part of the newly selected content and the application
lifecycle policy on the receiver dictates that the calling
application be terminated, termination of the application
will be affected through the application lifecycle API.
Successful completion of a select operation using this method
provides ServiceContentHandler
instances for all
components indicated in the components
parameter that were successfully presented.
Upon entering the presenting state, these
ServiceContentHandler
instances will have begun
presenting their respective content;
ServiceMediaHandler
instances will be in the
started state. This method will not provide
ServiceContentHandler
instances for service
components for which a locator is not specified.
For locators referencing a service component that is not
selectable and for which there is no ServiceContentHandler
defined, InvalidLocatorException
is thrown if the
condition can be detected without causing the method to block.
For example, implementations of this method do not block while
waiting for network access or tuning if such is required to determine
whether a specific component can be succesfully presented.
When such an error condition is discovered after this method returns,
a SelectionFailedEvent
with reason code
MISSING_HANDLER
is generated.
components
- An array of Locator
instances
representing the parts of this service to be selected. Each
array element must be a locator to either a
ServiceComponent
or content within a service
component (such as an Xlet).
InvalidLocatorException
- If a Locator
provided
does not reference a selectable service component or selectable
content within a service component.
InvalidServiceComponentException
- If a
specified service component must be presented in conjunction
with another service component not contained in
components
, if the specified
components are not all members of the same service, or if the
specified set of components cannot be presented as a coherent
whole.
java.lang.SecurityException
- If, for any valid i
, the
caller does not have
SelectPermission(components[i], "own")
.
java.lang.IllegalStateException
- If the ServiceContext
has been destroyed.
java.lang.IllegalArgumentException
- If components
is a
zero-length array.NormalContentEvent
,
AlternativeContentEvent
,
SelectionFailedEvent
,
PresentationTerminatedEvent
,
ServiceContentHandler
,
ServiceComponent
,
SelectionPermission
public void stop() throws java.lang.SecurityException
ServiceContext
to stop presenting content
and enter the not presenting state. Resources used
in the presentation will be released, associated
ServiceContentHandlers
will cease presentation
(ServiceMediaHandlers
will no longer be in the
started state), and a
PresentationTerminatedEvent
will be posted.
This operation completes asynchronously. No action is performed
if the ServiceContext
is already in the not
presenting state.
java.lang.SecurityException
- If the caller does not have
ServiceContextPermission("stop", "own")
.
java.lang.IllegalStateException
- If the ServiceContext
has been destroyed.ServiceContextPermission
public void destroy() throws java.lang.SecurityException
ServiceContext
to release all resources
and enter the destroyed state. This method indicates
that the the ServiceContext
must cease further
activity, and that it will no longer be used. After completion
of this method, ServiceMediaHandler
instances
associated with this ServiceContext
will have become
unrealized or will have been closed.
If the ServiceContext
is currently in the
presenting or presentation pending state, this
method will first stop the ServiceContext
, causing a
PresentationTerminatedEvent
to be posted. After the
ServiceContext
has moved to the destroyed
state, a ServiceContextDestroyedEvent
will be
posted.
This operation completes asynchronously. No action is performed
if the ServiceContext
is already in the
destroyed state.
java.lang.SecurityException
- If the caller does not have permission
to call stop()
on this ServiceContext
,
or if the caller does
not have ServiceContextPermission("destroy", "own")
.stop()
,
ServiceContextPermission
public ServiceContentHandler[] getServiceContentHandlers() throws java.lang.SecurityException
ServiceContext
is in the
not presenting or presentation pending states,
ServiceContext
is in the presenting
state, but the currently selected service contains no service
components, or
ServiceContext
is in the presenting
state, but there are no ServiceContentHandlers defined for the
types of service components which are being presented.
ServiceContentHandler
instances.
java.lang.SecurityException
- If the caller does not have
ServiceContextPermission("getServiceContentHandlers",
"own")
.
java.lang.IllegalStateException
- If the ServiceContext
has been destroyed.ServiceContextPermission
public Service getService()
Service
being presented in this
ServiceContext
. If the ServiceContext
is currently presenting a service, the Service
returned will be a network-dependent representation of the
Service
indicated in the last successful
select()
method call. If the
ServiceContext
is not in the presenting
state then null
is returned.
java.lang.IllegalStateException
- If the ServiceContext
has been destroyed.public void addListener(ServiceContextListener listener)
ServiceContext
. If the specified listener is currently
subscribed, no action is performed.
listener
- The ServiceContextListener
to subscribe.
java.lang.IllegalStateException
- If the ServiceContext
has been
destroyed.ServiceContextEvent
public void removeListener(ServiceContextListener listener)
ServiceContext
. If the specified listener is not currently
subscribed, no action is performed.
listener
- The ServiceContextListener
to unsubscribe.
java.lang.IllegalStateException
- If the ServiceContext
has been
destroyed.
|
JSR-927 (Maintenance Release) | ||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |