javax.microedition.broadcast
Class ServiceContext

java.lang.Object
  javax.microedition.broadcast.ServiceContext

public abstract class ServiceContext
extends java.lang.Object

The ServiceContext class abstracts the concept of a broadcast receiver. It provides these functionalities:

• Selects and initiates a service.
• Manages the resources to present a service.
• Selects the individual service components to be presented.
• Retrieves the data connection that can be used to read the raw data content.
• Monitors the status of the service being presented.

State Model

ServiceContext can be in one of the six states - STOPPED, ACQUIRING_SERVICE, SERVICE_ACQUIRED, PREPARING_MEDIA, PRESENTING, CLOSED. State transition is depicted in the following diagram.

Click the image to enlarge

In the diagram, states are depicted as rounded rectangles. Transitions among them are represented as inter-connected solid lines. Conditions for the transitions are shown on the lines. The ovals depict events that may be fired in the states connected to them with dotted lines. Each event can trigger a call to the event listeners. Events that are marked as shadowed ovals are critical events that block a state transition that is designated to occur following delivery of the events. When such an event occurs, transition to the next state will not proceed until the listeners are triggered and completed. But note that this does not apply to other state changes that can be triggered asynchronously. For example, a transition to the STOPPED state caused by a call to stop() method is allowed before all the listeners complete with the COMPONENT_IDENTIFIED event.

Some ServiceContext methods throw IllegalStateException if ServiceContext is not in a valid state. In those cases IllegalStateException is thrown before any other Exceptions would be thrown. For instance, in STOPPED state getPlayer(null) will throw IllegalStateException instead of NullPointerException.

STOPPED State

The initial state is STOPPED. In this state, a ServiceContext has no selected service and has nothing to present. If a service was presented prior to entering this state, its presentation shall be stopped and all the Players created for the presentation shall be closed.

ACQUIRING_SERVICE State

This state is entered when a service is selected by either a call to select(Service); or a selection initiated by the underlying receiver implementation for reasons such as the end of a free preview period. In this state, the receiver performs a series of tasks to get ready to access the service. That includes obtaining the service's configurations and identifying its list of service components. Upon entering this state, the presentation of the previous service, if any, is stopped. If the acquisition process fails, the ServiceContext is moved to the STOPPED state, regardless of its previous state.

SERVICE_ACQUIRED State

SERVICE_ACQUIRED state is entered from the ACQUIRING_SERVICE state when the selected service becomes ready for access and the configuration of the service is fully acquired. It may also be entered from the PREPARING_MEDIA or PRESENTING state, when there is a change in the service components constituting the current service. Upon entering this state, a COMPONENTS_IDENTIFIED event is delivered with a list of service components selected for presentation by default. The listeners can override this default selection by invoking setComponents(ServiceComponent[]) before the actual presentation begins. This change only applies to the current service and will not affect the system's defaults. For more details on the default components selection, see Default Components Selection.

There may be some special cases when there is no component that can be presented in a selected service. In these cases, no component will be selected.

ServiceContext will be blocked in the SERVICE_ACQUIRED state until all of the listeners had completed the processings and returned before transitioning to the PREPARING_MEDIA state.

PREPARING_MEDIA State

MMAPI is used for the presentation of the selected components. In the PREPARING_MEDIA state, the receiver prepares the Players to present selected service components. Players previously used for presenting other services shall be reconfigured and reused if possible. New Players may be created only if necessary. The receiver shall make a best attempt at reusing Players to avoid any artifacts (e.g. video flickering) introduced by switching the Players when changing services.

Upon entering this state, COMPONENTS_SET event is delivered with a relevant reason code, and getSelectedComponents() may be invoked to obtain a list of ServiceComponents set for presentation. Later when any new Player is created, and other Players become ready to present the components, PLAYERS_REALIZED event is delivered with a list of newly created Players. Those Players are in the REALIZED state. The application selecting the current service should initialize and configure the Players. That includes for example the steps to prepare the UI for the media presentation. After all the listeners get notified of the event, completed their processings and returned, the Players are automatically started by ServiceContext. Players that are not created but are reconfigured for the presentation of new components are also started during this phase. getPlayer(ServiceComponent) and getPlayers() methods may be invoked upon the delivery of PLAYERS_REALIZED event and afterward. They can be used to query the association between ServiceComponents and Players.

As a special case, there may be no component set for presentation. Even in that case, ServiceContext shall move to PRESENTING state.

There are occasions when there are not enough resources to present the selected components. Then ServiceContext is moved to the STOPPED state, regardless of its previous state.

PRESENTING State

The PRESENTING state is entered from the PREPARING_MEDIA state when Players configured in PREPARING_MEDIA state are actually started. Upon entering this state, a PRESENTATION_STARTED event is delivered.

Note that even when a service is being presented successfully, the presentation may be stopped inadvertently. When this happens, ServiceContext will move to the STOPPED state. This includes the cases when the required resources are reclaimed for some reason.

CLOSED State

The CLOSED state is entered when an application calls close(). Any method called on a closed ServiceContext except getState() shall throw an IllegalStateException. Before closing a ServiceContext, an underlying implementation may retain some resources either for caching or implementation-specific purposes. Those resources are guaranteed to be released upon entering the CLOSED state. ServiceContextListener.CONTEXT_CLOSED is delivered when ServiceContext is entering this state. After that ServiceContext removes all listeners from itself.

Impact of PlatformProvider Change

When the current PlatformProvider changes, it stops the ServiceContext, transitions it to the STOPPED state and CONTEXT_STOPPED event with reason code REASON_SERVICE_UNAVAILABLE is posted to ServiceContextListeners, unless the ServiceContext is already in the CLOSED or STOPPED states.

Default Instance

There is always one ServiceContext instance automatically created by the underlying implementation. This is the default instance that is shared by all the applications running on a broadcast receiver. A device may also support a system-level native ESG and channel navigator application. Any activity on the native application may also affect the default ServiceContext; such as the user using the native application to change the current service.

The default instance is thus used to affect the current user selection of service. For instance, an application bound to a preview channel for paid channels may want to switch the current service on user's selection. To avoid affecting the current user selection, an application should create new instances of ServiceContext if it need to select services without changing the current user selection. For example, a broadcast receiver may be capable of playing back two video services simultaneously. In that case, a secondary video may be controlled by another ServiceContext.

Resource Management

An application can create any number of ServiceContexts, if it has the required permissions and there are enough resources such as memory space to create the instances. However the resources required for the presentation of a service are not reserved at the time of creation. Therefore in some cases, a service selection may fail if any of the required resources are not available. A presenting service may also be stopped when any of the resources in use are withdrawn by the receiver implementation or other applications. The details of the resource allocation schemes are implementation-dependent.

Alternative Content

When selecting a Service, it is possible that the selection succeeds but the resulted content is different from what the original selection is intended for. For example, a Pay-Per-View channel can be selected without a prior purchase. Upon selecting the service, it is possible for the operator to switch the content to some promotional material, or a teaser for the viewer, to further entice the purchase.

When this happens, the service selection will succeed resulting in a SELECTION_INITIATED event. But since the content was substituted, in this case, a second SELECTION_INITIATED event will be sent. The event's reasons code will be set to REASON_ALTERNATIVE_CONTENT.

Audio/Video Presentation

The ServiceContext exclusively creates and manages the Players for presenting the media. If a selected service contains video components, the corresponding Players are created and set to the REALIZED state. When the ServiceContextListener.PLAYERS_REALIZED event is delivered, the application may access those Players. Then it can fetch VideoControl from the Player and set up the UI necessary to present the video. Note that the presentation of audio and video components sharing a common time base shall be represented as one single Player.

Once a Player is created, it is reused whenever possible. In PREPARING_MEDIA state, ServiceContext first checks whether there is any unclosed Player, which was previously used to present media of the same configuration. That is, a Player for presenting a audio may not be reconfigured for presenting a video, and vice versa. After reconfiguring some Players, remaining ones are closed, and new ones are created if some service components cannot be presented by reconfiguring existing ones. The Players are closed when the corresponding ServiceContext is closed, they remain unused after the above mentioned reconfiguration, or when an application closes the Players explicitly by invoking Player.close(). Explicit closing of Players is required when new Player instances must be created to perform some configurations such as invoking javax.microedition.media.control.VideoControl#initDisplayMode(int, Object), which is permitted to be invoked only once during the lifespan of a Player.

Filecasting

A service may also contains filecast contents. Filecasts are identified as ServiceComponents with type ServiceComponent.FILECAST. Filecast contents may not be presented with a Player. They are generally read as raw data via a BroadcastDatagramConnection. Filecast components along with other types of components can be retrieved with the getAllComponents() method. The BroadcastDatagramConnection associated with each filecast component can be obtained from the getBroadcastDatagramConnection(ServiceComponent) method.

Components Selection

A service consists of one or more components, such as audios, videos, and subtitles. Those components are represented as ServiceComponent objects. They may be obtained by calling getAllComponents() after COMPONENTS_IDENTIFIED event is received. Note that the components are also accessible within the registered listeners when the event is delivered. During the presentation of a service, new components may be added for presentation; and others may be removed or replaced. Such controls are all done via setComponents(ServiceComponent[]). In this way, it is possible for instance to turn on and off a subtitle of a specific language.

When a set of components are selected in the course of a service selection, setComponents(ServiceComponent[]) is called, or a component change is initiated for other reasons, COMPONENTS_SET is delivered.

For filecast components, it is not necessary to call setComponents to select them for accessing the raw content. The getBroadcastDatagramConnection method can be called directly to obtain the connection which can be used to access the contents. Calling setComponents on a filecast component may or may not fail depending on whether the implementation can present the filecast content with a Player, i.e., the filecast content may contain custom data type that the implementation can handle as time-based media.

Default Components Selection

When a selected service contains multiple alternatives for a given kind of service components, the ServiceContext implementation will choose one default component based on the preference set in the receiver using setPreference(String,Object). For example, a service may contain more than one audio tracks, each of which is recorded in a different language. In that case, only one of these audio tracks is selected. The selection of default components is basically implementation-specific. It may differ from one broadcast technology to another, from one broadcaster to another, or from one receiver to another. Therefore JSR 272 does not define a standard policy for it.

But every implementation of ServiceContext must respect at least, one standard preference, LANGUAGE. In addition to that, implementation-specific preferences may be defined and respected by some implementations. In evaluating preferences set to a ServiceContext against components contained in a selected service, there may be occasions where no components are fully compliant with the current preferences. For example, the system preference may be set to a particular language. But that language may not be available at all in a service. In that case, the ServiceContext implementation must still select at least one available component rather than picking nothing.

An application may affect the default selection when COMPONENTS_IDENTIFIED is received. The event is delivered with an array of ServiceComponent containing a list of components selected for presentation. An application may invoke setComponents(ServiceComponent[]) within the listeners to affect the initial choice of components used in a selected service.

Preference Setting

Preferences can be set to a ServiceContext instance to affect its behavior. For example, LANGUAGE preference may be set to affect the choice of the default components based on the language associated with each component. The LANGUAGE preference is mandatory, and every implementation should respect it when selecting default components from a selected service. Note that implementations may add additional preferences and respect them. The list of all the recognized preference keys can be obtained via getAllPreferenceKeys().

Service or Program Bound Java Applications

In the context of JSR 272, a service selection by ServiceContext does not entail launching of Java applications. There may be plenty of policies in launching and managing Java applications that have the same lifespan as services or programs. So JSR 272 assumes that such functionality may be implemented, for example, by ESG using various mechanisms such as JSR 211 content handler API by associating a BroadcastConnection with a content handler. See Appendix A for more details.

Permissions

Some operations are security-protected. They adhere to the security policy as dictated by the platform. The list of permissions specific to the MIDP platform is defined in the Security Permissions Section.

See ServiceContext examples for some usage examples.

Field Summary

static int	ACQUIRING_SERVICE A constant indicating that ServiceContext is in the ACQUIRING_SERVICE state.
static int	CLOSED A constant indicating that ServiceContext is in the CLOSED state.
static java.lang.String	LANGUAGE The preferred language of choice.
static int	PREPARING_MEDIA A constant indicating that ServiceContext is in the PREPARING_MEDIA state.
static int	PRESENTING A constant indicating that ServiceContext is in the PRESENTING state.
static int	SERVICE_ACQUIRED A constant indicating that ServiceContext is in the SERVICE_ACQUIRED state.
static int	STOPPED A constant indicating that ServiceContext is in the STOPPED state.

Constructor Summary

ServiceContext()

Method Summary

abstract void	addListener(ServiceContextListener listener) Adds a ServiceContextListener to monitor changes in this context.
abstract void	close() Closes this current instance of ServiceContext.
static ServiceContext	createServiceContext() Creates a new instance of ServiceContext.
abstract ServiceComponent[]	getAllComponents() Returns all the ServiceComponents available within the current service.
abstract java.lang.String[]	getAllPreferenceKeys() Returns the list of all the preference keys recognized by this ServiceContext.
abstract BroadcastDatagramConnection	getBroadcastDatagramConnection(ServiceComponent component) Returns a BroadcastDatagramConnection corresponding to the given ServiceComponent.
static ServiceContext	getDefaultContext() Returns the default ServiceContext instance.
abstract javax.microedition.media.Player	getPlayer(ServiceComponent component) Returns a Player corresponding to the given ServiceComponent that is currently being presented.
abstract javax.microedition.media.Player[]	getPlayers() Returns all the Players that control the presentation of the selected media components of the current service.
abstract java.lang.Object	getPreference(java.lang.String key) Returns a value set for the given preference key.
abstract ServiceComponent[]	getSelectedComponents() Returns all the ServiceComponents selected for presentation.
abstract Service	getService() Returns the current Service.
abstract int	getSignalQuality() Returns the signal quality of the received transmission.
abstract int	getState() Returns the current state of this ServiceContext object.
abstract ServiceComponent[]	getUnrecognizedComponents() Returns all the ServiceComponents that contains media types the system does not support.
abstract ServiceComponent[]	getUnselectedComponents() Returns all the ServiceComponents that are currently not selected for presentation but are presentable.
abstract void	removeListener(ServiceContextListener listener) Removes a ServiceContextListener.
abstract void	select(Service service) Selects a service represented by the given Service object.
abstract void	setComponents(ServiceComponent[] components) Sets components to be presented in the context of the current service.
abstract java.lang.Object	setPreference(java.lang.String key, java.lang.Object value) Sets a preference that can affect the service selection.
abstract void	stop() Stops the presentation of the current service.

Methods inherited from class java.lang.Object

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

Field Detail

ACQUIRING_SERVICE

public static final int ACQUIRING_SERVICE

A constant indicating that ServiceContext is in the ACQUIRING_SERVICE state. See State Model for more details.

See Also:

getState(), Constant Field Values

CLOSED

public static final int CLOSED

A constant indicating that ServiceContext is in the CLOSED state. See State Model for more details.

See Also:

getState(), Constant Field Values

LANGUAGE

public static final java.lang.String LANGUAGE

The preferred language of choice. This is mandatory, so every ServiceContext implementation must respect the setting of this preference. It may affect the selection of, for example, the default audio track when more than one audio tracks are available in various languages. The value shall be a language tag defined in RFC 3066.

See Also:

setPreference(String,Object), Constant Field Values

PREPARING_MEDIA

public static final int PREPARING_MEDIA

A constant indicating that ServiceContext is in the PREPARING_MEDIA state. See State Model for more details.

See Also:

getState(), Constant Field Values

PRESENTING

public static final int PRESENTING

A constant indicating that ServiceContext is in the PRESENTING state. See State Model for more details.

See Also:

getState(), Constant Field Values

SERVICE_ACQUIRED

public static final int SERVICE_ACQUIRED

A constant indicating that ServiceContext is in the SERVICE_ACQUIRED state. See State Model for more details.

See Also:

getState(), Constant Field Values

STOPPED

public static final int STOPPED

A constant indicating that ServiceContext is in the STOPPED state. See State Model for more details.

See Also:

getState(), Constant Field Values

Constructor Detail

ServiceContext

public ServiceContext()

Method Detail

addListener

public abstract void addListener(ServiceContextListener listener)
                          throws java.lang.IllegalStateException

Adds a ServiceContextListener to monitor changes in this context.

Parameters:

listener - The listener to add. If null is given or the same listener object is added more than once, it is silently ignored

Throws:

java.lang.IllegalStateException - Thrown if the ServiceContext is closed

close

public abstract void close()
                    throws java.lang.SecurityException

Closes this current instance of ServiceContext. Applications must not invoke methods on a closed instance. If any other method than this is invoked, an IllegalStateException shall be thrown.

If this method is called on a closed ServiceContext the request is ignored.

Throws:

java.lang.SecurityException - Thrown when this method is called on the default context returned from getDefaultContext() method. It is not allowed for applications to close the default context

createServiceContext

public static ServiceContext createServiceContext()
                                           throws java.lang.SecurityException

Creates a new instance of ServiceContext.

Returns:

the created ServiceContext instance

Throws:

java.lang.SecurityException - Thrown when the calling application has no permission to call this method.

getAllComponents

public abstract ServiceComponent[] getAllComponents()
                                             throws java.lang.IllegalStateException

Returns all the ServiceComponents available within the current service.

Returns:

An array of all the service components available within the current service. When the ServiceContext is not in one of SERVICE_ACQUIRED, PREPARING_MEDIA, and PRESENTING states, an array of zero-length is returned

Throws:

java.lang.IllegalStateException - Thrown if the ServiceContext is closed or stopped.

getAllPreferenceKeys

public abstract java.lang.String[] getAllPreferenceKeys()
                                                 throws java.lang.IllegalStateException

Returns the list of all the preference keys recognized by this ServiceContext.

Returns:

list of all the preference keys. Since LANGUAGE must be supported by all implementations of ServiceContext, the returned list must contain at least the LANGUAGE key.

Throws:

java.lang.IllegalStateException - Thrown if the ServiceContext is closed

getBroadcastDatagramConnection

public abstract BroadcastDatagramConnection getBroadcastDatagramConnection(ServiceComponent component)
                                                                    throws BroadcastServiceException,
                                                                           java.lang.SecurityException,
                                                                           java.lang.IllegalStateException,
                                                                           java.lang.NullPointerException

Returns a BroadcastDatagramConnection corresponding to the given ServiceComponent. The BroadcastDatagramConnection returned can be used to access the raw data from the service component.

There are two cases when the broadcast object cannot be returned for a service component:

1. The content from the service component is subject to DRM protection and cannot be accessed by the application. In this case, a SecurityException will be thrown.
2. The underlying implementation is not capable of providing the raw data from the given service component, possibly because of implementation or resource limitations. In this case, a BroadcastServiceException will be thrown.

Parameters:

component - service component whose data stream is wanted .

Returns:

the corresponding BroadcastDatagramConnection

Throws:

InsufficientResourcesException - Thrown if there was not enough resource to retrieve the designate BroadcastConnection

java.lang.SecurityException - if access to the content is not allowed.

BroadcastServiceException - Thrown if the given component is not an appropriate component, That is, it is not a component of the currently selected service, or the underlying implementation is not capable of providing the raw data from the given service component

java.lang.IllegalStateException - Thrown if the ServiceContext is closed or stopped. If conditions to throw this exception are met it is thrown instead of any other possible exception.

java.lang.NullPointerException - Thrown the given component argument is null

getDefaultContext

public static ServiceContext getDefaultContext()
                                        throws java.lang.SecurityException

Returns the default ServiceContext instance. The default instance is automatically created by underlying implementation, and shared among all applications. It reflects the current service selection by user. Thus, ESG and/or channel navigator application, regardless of whether they are native or not, effectively behave as if they select current service via the default instance.

Note that the default context can't be closed by applications. If close() is called on it, it throws a SecurityException.

Returns:

the default ServiceContext instance

Throws:

java.lang.SecurityException - Thrown when the calling application has no permission to call this method.

getPlayer

public abstract javax.microedition.media.Player getPlayer(ServiceComponent component)
                                                   throws BroadcastServiceException,
                                                          java.lang.IllegalStateException,
                                                          java.lang.NullPointerException

Returns a Player corresponding to the given ServiceComponent that is currently being presented. This method returns a valid result only when it is in PRESENTING state, or upon delivery of ServiceContextListener.PLAYERS_REALIZED event and afterward if this context is in PREPARING_MEDIA state. In all the other states, this method throws IllegalStateException.

Note that during the duration of the service, the Player returned may be closed if it is not reconfigured for presentation. Any closed Player will also be notified via MMAPI's PlayerListener.CLOSED event.

And the state of the returned Players may be changed by invoking methods such as stop and start on them. Players are configured by ServiceContext only at the points designated to do so in this specification. Once configured, they can be manipulated as designated by MMAPI specification. Also, any changes on the Players do not affect state of the corresponding ServiceContext.

Parameters:

component - A service component being presented.

Returns:

The Player corresponding to the given service component.

Throws:

BroadcastServiceException - Thrown when the specified component is invalid or unrecognized by the receiver

java.lang.NullPointerException - when the given component argument is null

java.lang.IllegalStateException - Thrown if the ServiceContext is in PREPARING_MEDIA and PLAYERS_REALIZED has not been delivered, or if it is in a state other than the PREPARING_MEDIA and PRESENTING states. If conditions to throw this exception are met it is thrown instead of any other possible exception.

See Also:

getPlayers()

getPlayers

public abstract javax.microedition.media.Player[] getPlayers()
                                                      throws java.lang.IllegalStateException

Returns all the Players that control the presentation of the selected media components of the current service. This method returns a valid result if this context is in the PRESENTING state; or in the PREPARING_MEDIA state upon delivery of the ServiceContextListener.PLAYERS_REALIZED event. In all the other states, this method throws IllegalStateException.

Note that the state of the returned Players may be changed by invoking methods such as stop and start on them. Players are configured by ServiceContext only at the points designated in this specification. Once configured, they can be manipulated by using the MMAPI functions. Changes on the Players do not affect the state of the corresponding ServiceContext.

Returns:

Players for the selected service content

Throws:

java.lang.IllegalStateException - Thrown if the ServiceContext is in PREPARING_MEDIA and PLAYERS_REALIZED has not been delivered, or if it is in a state other than the PREPARING_MEDIA and PRESENTING states.

getPreference

public abstract java.lang.Object getPreference(java.lang.String key)
                                        throws java.lang.IllegalStateException,
                                               java.lang.NullPointerException

Returns a value set for the given preference key.

Parameters:

key - The preference key.

Returns:

The value set for the key.

Throws:

java.lang.IllegalStateException - Thrown if the ServiceContext is closed. If conditions to throw this exception are met it is thrown instead of any other possible exception.

java.lang.NullPointerException - Thrown when the given key is null

getSelectedComponents

public abstract ServiceComponent[] getSelectedComponents()
                                                  throws java.lang.IllegalStateException

Returns all the ServiceComponents selected for presentation.

Returns:

An array containing all the service components selected for presentation. When the ServiceContext is not in one of SERVICE_ACQUIRED, PREPARING_MEDIA, PRESENTING states, an array of zero-length is returned

Throws:

java.lang.IllegalStateException - Thrown if the ServiceContext is closed

getService

public abstract Service getService()
                            throws java.lang.IllegalStateException

Returns the current Service.

Returns:

the current selected Service if the ServiceContext is not in STOPPED or CLOSED state. Otherwise returns null

Throws:

java.lang.IllegalStateException - Thrown if the ServiceContext is closed

getSignalQuality

public abstract int getSignalQuality()
                              throws java.lang.IllegalStateException

Returns the signal quality of the received transmission.

Returns:

the signal quality in percents

Throws:

java.lang.IllegalStateException - if this ServiceContext is in STOPPED or CLOSED state

getState

public abstract int getState()

Returns the current state of this ServiceContext object.

Returns:

the current state of this ServiceContext in one of the states: STOPPED, ACQUIRING_SERVICE, SERVICE_ACQUIRED, PREPARING_MEDIA, PRESENTING, CLOSED

getUnrecognizedComponents

public abstract ServiceComponent[] getUnrecognizedComponents()
                                                      throws java.lang.IllegalStateException

Returns all the ServiceComponents that contains media types the system does not support.

Returns:

The list of ServiceComponents that contains media types the system cannot present. When the ServiceContext is not in one of SERVICE_ACQUIRED, PREPARING_MEDIA, PRESENTING states, an array of zero-length is returned

Throws:

java.lang.IllegalStateException - Thrown if the ServiceContext is closed

getUnselectedComponents

public abstract ServiceComponent[] getUnselectedComponents()
                                                    throws java.lang.IllegalStateException

Returns all the ServiceComponents that are currently not selected for presentation but are presentable. i.e. it excludes the ones that are not supported by the system (returned by getUnrecognizedComponents()).

Returns:

ServiceComponents not selected for presentation. When the ServiceContext is not in one of SERVICE_ACQUIRED, PREPARING_MEDIA, PRESENTING states, an array of zero-length is returned

Throws:

java.lang.IllegalStateException - Thrown if the ServiceContext is closed

removeListener

public abstract void removeListener(ServiceContextListener listener)
                             throws java.lang.IllegalStateException

Removes a ServiceContextListener. If the given listener is not registered previously, it is silently ignored.

Parameters:

listener - The listener to remove. If null is given or if the given listener is already removed, this method is silently ignored

Throws:

java.lang.IllegalStateException - Thrown if the ServiceContext is closed

select

public abstract void select(Service service)
                     throws java.lang.IllegalArgumentException,
                            java.lang.SecurityException,
                            java.lang.IllegalStateException,
                            java.lang.NullPointerException

Selects a service represented by the given Service object. This method returns immediately. A series of events will be notified via ServiceContextListener. See State Model for more details.

Change of components initiated by a call to this method will make COMPONENTS_SET event to have the reason code REASON_APPLICATION_REQUESTED.

If there is any service being presented in this ServiceContext, it will be completely replaced by the new service designated. And as a special case, if the current service is selected repeatedly, the request is silently ignored.

Parameters:

service - The Service to select.

Throws:

java.lang.IllegalArgumentException - Thrown if the given service is from a PlatformProvider other than the current selection to the PlatformProviderSelector

java.lang.SecurityException - Thrown when the calling application has no permission to call this method.

java.lang.IllegalStateException - Thrown if the ServiceContext is closed. If conditions to throw this exception are met it is thrown instead of any other possible exception.

java.lang.NullPointerException - Thrown if the given argument is null

setComponents

public abstract void setComponents(ServiceComponent[] components)
                            throws InsufficientResourcesException,
                                   java.lang.IllegalStateException,
                                   BroadcastServiceException,
                                   java.lang.NullPointerException

Sets components to be presented in the context of the current service. Components newly introduced will be added and missing ones removed. In the course of that, the current content presentation is not interrupted unless it is strictly required. This method returns immediately. Underlying implementation can perform some operations to select the components that were set. Therefore, COMPONENTS_SET event isn't necessarily posted immediately after call to this method. However, getSelectedComponents() will return components set in this method after the method call has returned.

Parameters:

components - list of components to be set. If an array of zero length is specified, it means presenting nothing

Throws:

InsufficientResourcesException - Thrown when it is impossible to present the given set of service components because of insufficient resources.

BroadcastServiceException - Thrown when the specified list of components cannot be all presented. Such cases include when more than one audio are specified in the receiver capable of rendering only one audio at a time, or some components are not supported and cannot be presented by the receiver, or the components are not available for some reasons.

java.lang.IllegalStateException - Thrown if the ServiceContext is not in SERVICE_ACQUIRED or PRESENTING state. If conditions to throw this exception are met it is thrown instead of any other possible exception.

java.lang.NullPointerException - Thrown when the given argument is null

setPreference

public abstract java.lang.Object setPreference(java.lang.String key,
                                               java.lang.Object value)
                                        throws java.lang.IllegalStateException,
                                               java.lang.NullPointerException

Sets a preference that can affect the service selection.

Parameters:

key - A preference key.

value - The value to be set for the given key.

Returns:

The previous value that was associated with the given key.

Throws:

java.lang.IllegalArgumentException - Thrown if the given key is unknown

java.lang.IllegalStateException - Thrown if the ServiceContext is closed. If conditions to throw this exception are met it is thrown instead of any other possible exception.

java.lang.NullPointerException - Thrown when the given key is null

stop

public abstract void stop()
                   throws java.lang.IllegalStateException

Stops the presentation of the current service. This method returns immediately. The events will be notified via ServiceContextListener. If this method is called when this ServiceContext is already in the STOPPED state, it will be ignored. See State Model for more details.

Throws:

java.lang.IllegalStateException - Thrown if the ServiceContext is closed