com.sun.tv

Class ServiceContextImpl

java.lang.Object

com.sun.tv.ServiceContextImpl

All Implemented Interfaces:

ControllerListener, ServiceContext

public class ServiceContextImpl
extends Object
implements ServiceContext, ControllerListener

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.

ServiceContextcan 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 but 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 will be generated and the service context moves into the presenting state. If the service selection fails, a SelectionFailedEvent will be generated. If the state before the select call was not presenting, it will return to that state and a PresentationTerminatedEvent generated. If the state before the selectcall 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 the PresentationTerminatedEvent. The stopping of service presentation can be initiated by an application calling the stop method or because some change in the environment makes continued presentation impossible.

The destroyed state is entered by calling the destroy method, and is signalled by the ServiceContextDestroyedEvent. Once this state is entered, the service context can no longer be used for any purpose. A destroyed service context will be eligible for garbage collection once all references to it by application(s) have been removed.

Note that the ability to select which service is presented does not imply any ownership of the resources used for the presentation.

Applications may also use this interface to register for events associated with service context state changes.

See Also:

Service, ServiceContentHandler, NormalContentEvent, AlternativeContentEvent, SelectionFailedEvent, PresentationTerminatedEvent, ServiceContextDestroyedEvent, ServiceContextListener

Constructor Summary

Constructors

Constructor and Description
ServiceContextImpl()

Method Summary

Methods

Modifier and Type	Method and Description
void	addListener(ServiceContextListener listener) Subscribes a listener to receive events related to this ServiceContext.
void	controllerUpdate(ControllerEvent ce) Handle Controller/Player events for the player that's currently active.
void	destroy() Causes the ServiceContext to release all resources and enter the destroyed state.
Service	getService() Reports the Service being presented in this ServiceContext.
Locator[]	getServiceComponentLocators() Reports the current collection of Service Component Locators.
ServiceContentHandler[]	getServiceContentHandlers() Reports the current collection of ServiceContentHandlers.
Locator	getServiceLocator() Provides a Locator to the service being presented in this service context.
boolean	isContextOwned()
boolean	isDestroyed() The isDestroyed method is not part of the JavaTV API, it is used to indicate if this context is still valid within the RI.
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.
void	stop0(int reason)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ServiceContextImpl

public ServiceContextImpl()
                   throws Exception

Throws:

Exception

Method Detail

select

public void select(Service selection)
            throws 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 method 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.

Specified by:

select in interface ServiceContext

Parameters:

selection - The Service the service to be selected.

Throws:

SecurityException - If the caller owns this ServiceContext but does not have SelectPermission(selection.getLocator(), "own"), or if the caller does not own this ServiceContext and does not have SelectPermission(selection.getLocator(), "*").

IllegalStateException - If the ServiceContext has been destroyed.

See Also:

NormalContentEvent, AlternativeContentEvent, SelectionFailedEvent, PresentationTerminatedEvent, Service, ServiceContext.getService(), ServiceContentHandler, ServiceContext.destroy()

select

public void select(Locator[] components)
            throws InvalidLocatorException,
                   InvalidServiceComponentException,
                   SecurityException,
                   IllegalStateException

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 method 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 failure of the selection can be determined when this method is called, an exception will be generated and the state of the ServiceContext will not change. In this case, any service being presented before this method was called will continue to be presented.

If failure of the selection is determined after this method returns, a SelectionFailedEvent will be generated. In this case, the implementation of the method 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 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 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 that are indicated in the components parameter. 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.

Specified by:

select in interface ServiceContext

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.

SecurityException - If, for any valid i, the caller owns this ServiceContext but does not have SelectPermission(components[i], "own"), or if the caller does not own this ServiceContext and does not have SelectPermission(components[i], "*").

IllegalStateException - If the ServiceContext has been destroyed.

See Also:

NormalContentEvent, AlternativeContentEvent, SelectionFailedEvent, PresentationTerminatedEvent, ServiceContentHandler, ServiceComponent

stop

public void stop()
          throws SecurityException,
                 IllegalStateException

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.

Specified by:

stop in interface ServiceContext

Throws:

SecurityException - If the caller owns this ServiceContext but does not have ServiceContextPermission("stop", "own"), or if the caller does not own this ServiceContext and does not have SelectPermission("stop", "*").

IllegalStateException - If the ServiceContext has been destroyed.

stop0

public void stop0(int reason)
           throws SecurityException,
                  IllegalStateException

Throws:

SecurityException

IllegalStateException

destroy

public void destroy()
             throws 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.

Specified by:

destroy in interface ServiceContext

Throws:

SecurityException - If the caller does not have permission to call stop() on this ServiceContext, or if the caller owns this ServiceContext but does not have ServiceContextPermission("destroy", "own"), or if the caller does not own this ServiceContext and does not have SelectPermission("destroy", "*").

See Also:

stop()

getServiceContentHandlers

public ServiceContentHandler[] getServiceContentHandlers()
                                                  throws SecurityException

Reports the current collection of ServiceContentHandlers. A zero-length array is returned if the ServiceContext is in in the not presenting or presentation pending states.

Specified by:

getServiceContentHandlers in interface ServiceContext

Returns:

The current ServiceContentHandler instances.

Throws:

SecurityException - If the caller owns this ServiceContext but does not have ServiceContextPermission("getServiceContentHandlers", "own"), or if the caller does not own this ServiceContext and does not have SelectPermission("getServiceContentHandlers", "*").

IllegalStateException - If the ServiceContext has been destroyed.

getServiceLocator

public Locator getServiceLocator()

Provides a Locator to the service being presented in this service context. If the service context is currently presenting a service, the locator returned will be a network-dependent locator to the service indicated in the last successful select method call. If the service context is not currently presenting a service or has been destroyed, then null is returned.

Returns:

A locator for the service currently being presented or null if no service is being presented.

See Also:

Service

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.

Specified by:

getService in interface ServiceContext

Returns:

The service currently being presented.

Throws:

IllegalStateException - If the ServiceContext has been destroyed.

addListener

public void addListener(ServiceContextListener listener)
                 throws IllegalStateException

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

Specified by:

addListener in interface ServiceContext

Parameters:

listener - The ServiceContextListener to subscribe.

Throws:

NullPointerException - If listener is null.

IllegalStateException - If the ServiceContext has been destroyed.

See Also:

ServiceContextEvent

removeListener

public void removeListener(ServiceContextListener listener)
                    throws IllegalStateException

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

Specified by:

removeListener in interface ServiceContext

Parameters:

listener - The ServiceContextListener to unsubscribe.

Throws:

NullPointerException - if listener is null.

IllegalStateException - If the ServiceContext has been destroyed.

isContextOwned

public boolean isContextOwned()

getServiceComponentLocators

public Locator[] getServiceComponentLocators()

Reports the current collection of Service Component Locators. A zero-length array is returned if the ServiceContext is in in the not presenting or presentation pending states.

Returns:

The current Service Component Locator instances.

Throws:

IllegalStateException - If the ServiceContext has been destroyed.

isDestroyed

public boolean isDestroyed()

The isDestroyed method is not part of the JavaTV API, it is used to indicate if this context is still valid within the RI. The ServiceContextFactory needs to return a list of all non-destroyed ServiceContexts.

controllerUpdate

public void controllerUpdate(ControllerEvent ce)

Handle Controller/Player events for the player that's currently active.

Specified by:

controllerUpdate in interface ControllerListener

Parameters:

ce - The event generated.