javax.tv.service.selection.ServiceContext Maven / Gradle / Ivy

Neither this file nor any files generated from it describe a complete specification, and they may only be used as described below.

Sun Microsystems Inc. owns the copyright in this file and it is provided to you for informative use only. For example, this file and any files generated from it may be used to generate other documentation, such as a unified set of documents of API signatures for a platform that includes technologies expressed as Java APIs. This file may also be used to produce "compilation stubs," which allow applications to be compiled and validated for such platforms. By contrast, no permission is given for you to incorporate this file, in whole or in part, in an implementation of a Java specification.

Any work generated from this file, such as unified javadocs or compiled stub files, must be accompanied by this notice in its entirety.

This work corresponds to the API signatures of JSR 927: Java TV API 1.1.1. In the event of a discrepency between this work and the JSR 927 specification, which is available at http://www.jcp.org/en/jsr/detail?id=927, the latter takes precedence. */ 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. * 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 * {@link 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 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 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 the Service that is currently selected in this * ServiceContext is re-selected, its auto-start * components are ignored and no change is made to the content * being presented. * A {@link NormalContentEvent} is generated immediately. * *

* 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. * * @param selection The Service the service to be * selected. * * @throws SecurityException If the caller does not have * SelectPermission(selection.getLocator(), "own"). * * @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 * @see SelectPermission */ 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 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. *