Use is subject to License Terms. Your use of this web site or any of its content or software indicates your agreement to be bound by these License Terms.

Copyright © 2006 Sun Microsystems, Inc. All rights reserved.

javax.tv.service.selection
Interface ServiceContext

public interface ServiceContext

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.

See Also:

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

select

public void select(Service selection)
            throws java.lang.SecurityException

Selects a service to be presented in this 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 ServiceContentHandlers are created.

Parameters:

selection - The Service the service to be selected.

Throws:

java.lang.SecurityException - If the caller does not have SelectPermission(selection.getLocator(), "own").

java.lang.IllegalStateException - If the ServiceContext has been destroyed.

See Also:

NormalContentEvent, AlternativeContentEvent, SelectionFailedEvent, PresentationTerminatedEvent, Service, getService(), ServiceContentHandler, destroy(), SelectPermission

select

public void select(Locator[] components)
            throws InvalidLocatorException,
                   InvalidServiceComponentException,
                   java.lang.SecurityException

Selects content by specifying the parts of a service to be presented. 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.

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.

Parameters:

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).

Throws:

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.

See Also:

NormalContentEvent, AlternativeContentEvent, SelectionFailedEvent, PresentationTerminatedEvent, ServiceContentHandler, ServiceComponent, SelectionPermission

stop

public void stop()
          throws java.lang.SecurityException

Causes the 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.

Throws:

java.lang.SecurityException - If the caller does not have ServiceContextPermission("stop", "own").

java.lang.IllegalStateException - If the ServiceContext has been destroyed.

See Also:

ServiceContextPermission

destroy

public void destroy()
             throws java.lang.SecurityException

Causes the 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.

Throws:

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").

See Also:

stop(), ServiceContextPermission

getServiceContentHandlers

public ServiceContentHandler[] getServiceContentHandlers()
                                                  throws java.lang.SecurityException

Reports the current collection of ServiceContentHandlers. The order of the ServiceContentHandlers in the returned array is arbitrary. A zero-length array is returned

• if the ServiceContext is in the not presenting or presentation pending states,
• if the ServiceContext is in the presenting state, but the currently selected service contains no service components, or
• if the ServiceContext is in the presenting state, but there are no ServiceContentHandlers defined for the types of service components which are being presented.

Returns:

The current ServiceContentHandler instances.

Throws:

java.lang.SecurityException - If the caller does not have ServiceContextPermission("getServiceContentHandlers", "own").

java.lang.IllegalStateException - If the ServiceContext has been destroyed.

See Also:

ServiceContextPermission

getService

public Service getService()

Reports the 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.

Returns:

The service currently being presented.

Throws:

java.lang.IllegalStateException - If the ServiceContext has been destroyed.

addListener

public void addListener(ServiceContextListener listener)

Subscribes a listener to receive events related to this ServiceContext. If the specified listener is currently subscribed, no action is performed.

Parameters:

listener - The ServiceContextListener to subscribe.

Throws:

java.lang.IllegalStateException - If the ServiceContext has been destroyed.

See Also:

ServiceContextEvent

removeListener

public void removeListener(ServiceContextListener listener)

Unsubscribes a listener from receiving events related to this ServiceContext. If the specified listener is not currently subscribed, no action is performed.

Parameters:

listener - The ServiceContextListener to unsubscribe.

Throws:

java.lang.IllegalStateException - If the ServiceContext has been destroyed.