javax.tv.service.selection.ServiceContext Maven / Gradle / Ivy
/*
* @(#)ServiceContext.java 1.49 00/10/09
*
* Copyright 1998-2000 by Sun Microsystems, Inc.,
* 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
* All rights reserved.
*
* This software is the confidential and proprietary information
* of Sun Microsystems, Inc. ("Confidential Information"). You
* shall not disclose such Confidential Information and shall use
* it only in accordance with the terms of the license agreement
* you entered into with Sun.
*/
package javax.tv.service.selection;
import javax.tv.locator.*;
import javax.tv.service.Service;
/**
* 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. 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. 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 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 javax.tv.service.Service
* @see ServiceContentHandler
*
* @see NormalContentEvent
* @see AlternativeContentEvent
* @see SelectionFailedEvent
* @see PresentationTerminatedEvent
* @see ServiceContextDestroyedEvent
* @see ServiceContextListener */
public interface ServiceContext {
/**
* 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.
*
* @param 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(), "*").
*
* @throws IllegalStateException If the ServiceContext
* has been destroyed.
*
* @see NormalContentEvent
* @see AlternativeContentEvent
* @see SelectionFailedEvent
* @see PresentationTerminatedEvent
* @see javax.tv.service.Service
* @see ServiceContext#getService
* @see ServiceContentHandler
* @see ServiceContext#destroy
**/
public void select(Service selection)
throws 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 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 selection operation using this method provides
* ServiceContentHandlers for those components indicated in the components
* parameter which 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.
*
* If the content corresponding to any of the locators specified can be
* successfully presented then the selection operation shall be considered
* to have succeeded even if attempts to present content corresponding to
* other locators failed. If different locators failed for different reasons
* then the reason code is implementation dependent.
*
* @param 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.
*
* For locators which reference a service component which is not selectable
* and where there is no ServiceContentHandler defined, the exception shall
* be thrown if the error condition can be detected without causing the
* method to block. For example, implementations shall not block waiting for
* network access or tuning where this is required to discover whether a
* specific locator references a selectable service component and there is a
* ServiceContentHandler. Where such an error condition is discovered after
* the return from this method, a SelectionFailedEvent with reason code
* MISSING_HANDLER shall be generated.
*
* @throws 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.
*
* @throws 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], "*").
*
* @throws IllegalStateException
* If the ServiceContext has been destroyed.
*
* @see NormalContentEvent
* @see AlternativeContentEvent
* @see SelectionFailedEvent
* @see PresentationTerminatedEvent
* @see ServiceContentHandler
* @see javax.tv.service.navigation.ServiceComponent
*/
public void select(Locator[] components)
throws InvalidLocatorException,
InvalidServiceComponentException,
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 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", "*").
*
* @throws IllegalStateException If the ServiceContext
* has been destroyed.
*/
public void stop() 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.
*
* @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 #stop */
public void destroy() 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.
*
* When a service with no components is selected, the ServiceContext shall
* generate a NormalContentEvent and enter the PRESENTING state.
*
* NOTE 1: A zero length array may also be returned if the currently
* selected service has no components at all. For example, a service which
* is only on-air for part of day and presently has no video, audio or
* applications.
* NOTE 2: Applications cannot assume anything about the order
* of the ServiceContentHandlers returned by this method.
*
* @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", "*").
*
* @return The current ServiceContentHandler instances.
*
* @throws IllegalStateException
* If the ServiceContext has been destroyed.
*/
public ServiceContentHandler[] getServiceContentHandlers()
throws SecurityException;
/**
* 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.
*
* @return The service currently being presented.
*
* @throws IllegalStateException If the ServiceContext
* has been destroyed.
*/
public Service getService();
/**
*
* Subscribes a listener to receive events related to this
* ServiceContext. If the specified listener is currently
* subscribed, no action is performed.
*
* @param listener The ServiceContextListener to subscribe.
*
* @throws IllegalStateException If the ServiceContext has been
* destroyed.
*
* @see ServiceContextEvent
*/
public void addListener(ServiceContextListener listener);
/**
* Unsubscribes a listener from receiving events related to this
* ServiceContext. If the specified listener is not currently
* subscribed, no action is performed.
*
* @param listener The ServiceContextListener to unsubscribe.
*
* @throws IllegalStateException If the ServiceContext has been
* destroyed.
*/
public void removeListener(ServiceContextListener listener);
}