AppProxy

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.dvb.application
Interface AppProxy

All Known Subinterfaces:
  DVBHTMLProxy, DVBJProxy

    public interface AppProxy

An `AppProxy` Object is a proxy to an application. A call to the start, stop or pause will cause the resident Application Manager to respectively start, stop or pause the application bound to this AppProxy object. Each of these three method calls can throw a Security Exception if the calling application is not entitled to do so.

Each of these method calls are asynchronous and will result in exactly one AppStateChangeEvent to be generated whether the method call was successful or not. If the method call was not successful, any call to the `hasFailed` method of the corresponding `AppStateChangeEvent` will return true.

Some of the methods here allow the AppProxy to transition through several states before the final state is reached. If this compound state transition is unsuccessful at any point, the resulting AppStateChangeEvent shall have a fromstate which is the last state in this transition which the AppProxy successfully entered and a toState which would have been the next state in the compound state transition.

For instance, if an application were to call start on an AppProxy for a DVB-J application in the NOT_LOADED state and that DVB-J application was to throw a XletStateChangeException from its startXlet method, the getFromState will return PAUSED and getToState will return STARTED. If an application were to call start on an AppProxy for a DVB-J application in the NOT_LOADED state and that DVB-J application was to throw a XletStateChangeException from its initXlet method, the getFromState will return NOT_LOADED and getToState will return PAUSED. Calling the start method for an application which is already running shall fail and generate an AppStateChangeEvent with hasFailed returning true and both fromstate and tostate being STARTED.”

See the definition of `AppStateChangeEvent` for more information. Having more than one application attempt to control the lifecycle of the same (other) application at the same time is not recommended. The ordering of AppStateChangeEvents if this is done will be implementation dependent.

See Also:
  `AppStateChangeEvent`

Field Summary
`static int` | `DESTROYED` The application is in the destroyed state.
`static int` | `INVALID` The application is not signalled in the currently selected service and hence not listed in the applications database.
`static int` | `NOT_LOADED` The application has not yet been loaded from the network at all.
`static int` | `PAUSED` The application is in the paused state.
`static int` | `STARTED` The application is in the active state.

Method Summary
`void` | `addAppStateChangeEventListener(AppStateChangeEventListener listener)` Add a listener to the application proxy so that an application can be informed if the application changes state.
`int` | `getState()` Return the current state of the application.
`void` | `pause()` Request that the application manager pause the application bound to this information structure.
`void` | `removeAppStateChangeEventListener(AppStateChangeEventListener listener)` Remove a listener on the database.
`void` | `resume()` Request that the application manager resume the execution of the application.
`void` | `start()` Request that the application manager start the application bound to this information structure.
`void` | `start(String[] args)` Request that the application manager start the application bound to this information structure passing to that application the specified parameters.
`void` | `stop(boolean forced)` Request that the application manager stop the application bound to this information structure.

Field Detail

### STARTED

    static final int STARTED

  The application is in the active state.

  See Also:
    Constant Field Values

### DESTROYED

    static final int DESTROYED

  The application is in the destroyed state. This state is transient and entry to this state shall be followed with a transition to the NOT_LOADED state almost immediately. It shall be possible to re-start the application after the transition to the NOT_LOADED state.

  See Also:
    Constant Field Values

### NOT_LOADED

    static final int NOT_LOADED

  The application has not yet been loaded from the network at all.

  See Also:
    Constant Field Values

### PAUSED

    static final int PAUSED

  The application is in the paused state.

  See Also:
    Constant Field Values

### INVALID

    static final int INVALID

  The application is not signalled in the currently selected service and hence not listed in the applications database. Once an AppProxy is in this state, all attempts to cause further state transitions on that AppProxy instance shall fail with an AppStateChangeEvent from INVALID to INVALID, even if a service is selected where that application is signalled.

  See Also:
    Constant Field Values

Method Detail

### getState

    int getState()

  Return the current state of the application.

  Returns:
    the state of the application.

### start

    void start()

  Request that the application manager start the application bound to this information structure.

  The `application` will be started. This method will throw a security exception if the application does not have the authority to start applications. Calls to this method shall only succeed if the application if the application is signalled with a control code which is either AUTOSTART or PRESENT and any one of the following applies:

  - if the application (DVB-J or DVB-HTML) is in the not loaded or paused states,
  - if a DVB-J application is in the "loaded" state,
  - if a DVB-HTML application is in the "loading" state.

  If the application was not loaded at the moment of this call, then the application will be started. In the case of a DVB-J application, it will be initialized and then started by the Application Manager, hence causing the Xlet to go from NotLoaded to Paused and then from Paused to Active. If the application was in the Paused state at the moment of the call and had never been in the Active state, then the application will be started. If the application represented by this AppProxy is a DVB-J application, calling this method will, if successful, result in the `startXlet` method being called on the Xlet making up the DVB-J application.

  This method is asynchronous and its completion will be notified by an AppStateChangeEvent. In case of failure, the hasFailed method of the `AppStateChangeEvent` will return true.

  Throws:
    `SecurityException` - if the application is not entitled to start this application.
  Since:
    MHP1.0

### start

    void start(String[] args)

  Request that the application manager start the application bound to this information structure passing to that application the specified parameters.

  The `application` will be started. This method will throw a security exception if the application does not have the authority to start applications. Calls to this method shall only succeed if the application if the application is signalled with a control code which is either AUTOSTART or PRESENT and any one of the following applies:

  - if the application (DVB-J or DVB-HTML) is in the not loaded or paused states,
  - if a DVB-J application is in the "loaded" state,
  - if a DVB-HTML application is in the "loading" state.

  If the application was not loaded at the moment of this call, then the application will be started. In the case of a DVB-J application, it will be initialized and then started by the Application Manager, hence causing the Xlet to go from NotLoaded to Paused and then from Paused to Active. If the application was in the Paused state at the moment of the call and had never been in the Active state, then the application will be started. If the application represented by this AppProxy is a DVB-J application, calling this method will, if successful, result in the `startXlet` method being called on the Xlet making up the DVB-J application.

  This method is asynchronous and its completion will be notified by an AppStateChangeEvent. In case of failure, the hasFailed method of the `AppStateChangeEvent` will return true.

  Parameters:
    `args` - the parameters to be passed into the application being started
  Throws:
    `SecurityException` - if the application is not entitled to start this application.
  Since:
    MHP1.0.1

### stop

    void stop(boolean forced)

  Request that the application manager stop the application bound to this information structure.

  The `application` will be stopped. A call to this method shall fail if the application was already in the destroyed state. This method call will stop the application if it was in any other state before the call. If the application is in the NOT_LOADED state then it shall move directly to the DESTROYED state with no other action being taken. If the application represented by this AppProxy is a DVB-J application and is not in the DESTROYED state then calling this method will, if successful, result in the `destroyXlet` method being called on the Xlet making up the DVB-J application with the same value for the parameter as passed to this method.

  This method is asynchronous and its completion will be notified by an AppStateChangeEvent. In case of failure, the hasFailed method of the `AppStateChangeEvent` will return true.

  Parameters:
    `forced` - if true then do not ask the application but forcibly terminate it, if false give the application an opportunity to refuse.
  Throws:
    `SecurityException` - if the application is not entitled to stop this application.
  Since:
    MHP1.0

### pause

    void pause()

  Request that the application manager pause the application bound to this information structure.

  The `application` will be paused. Calls to this method shall fail if the application is not in the active state. If the application represented by this AppProxy is a DVB-J application, calling this method will, if successful, result in the `pauseXlet` method being called on the Xlet making up the DVB-J application.

  Throws:
    `SecurityException` - if the application is not entitled to pause this application. Note that if an application is entitled to stop an application, it is also entitled to pause it: having the right to stop an application is logically equivalent to having the right to pause it.
  Since:
    MHP1.0

### resume

    void resume()

  Request that the application manager resume the execution of the application. The `application` will be started. This method will throw a security exception if the application does not have the authority to resume the application. Calls to this method shall fail if the application is not in the paused state.

  This method is asynchronous and its completion will be notified by an AppStateChangeEvent. In case of failure, the hasFailed method of the `AppStateChangeEvent` will return true. If the application represented by this AppProxy is a DVB-J application, calling this method will, if successful, result in the `startXlet` method being called on the Xlet making up the DVB-J application.

  Throws:
    `SecurityException` - if the application is not entitled to resume this application.
  Since:
    MHP1.0

### addAppStateChangeEventListener

    void addAppStateChangeEventListener(AppStateChangeEventListener listener)

  Add a listener to the application proxy so that an application can be informed if the application changes state.

  Parameters:
    `listener` - the listener to be added.
  Since:
    MHP1.0

### removeAppStateChangeEventListener

    void removeAppStateChangeEventListener(AppStateChangeEventListener listener)

  Remove a listener on the database.

  Parameters:
    `listener` - the listener to be removed.
  Since:
    MHP1.0

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD