org.ocap.environment.Environment.html Maven / Gradle / Ivy

Represents an environment that provides the context in which applications run.

Environment state machine

• Environments in the inactive state SHALL have no running applications at all.
• Environments in the selected state have all applications running to the maximum extent possible and able to interact with the end-user.
• Environments in the presenting state may have running applications which are visible to the end-user but these SHALL NOT be able to receive input from the remote control.
• Environments in the background state may have running applications but these applications SHALL NOT be in the normal mode.

Transitions from selected or presenting to background

• applications able to run in cross-environment mode SHALL be put in cross-environment mode by the implementation
• applications able to run in background mode SHALL be put in background mode by the implementation
• applications signaled as pauseable MAY be put in the paused state by the implementation
• all other applications SHALL be terminated
• The implementation SHALL hide the user interfaces of applications which are put in background or paused mode or which are terminated. HScene instances shall have their visibility set to false.

  NOTE: Applicable events announcing such changes are generated as expected. For example, org.dvb.application.AppStateChangeEvents announcing that applications have been paused or terminated; and java.awt.event.ComponentEvents announcing that an HScene has been hidden.

Transitions from background to selected or presenting

• all auto-start unbound applications which were terminated due to their environment going into the background state SHALL be started if their service is still selected
• all auto-start bound applications which were terminated due to their environment going into the background state SHALL be started if still signaled in a selected service
• all applications from the newly selected environment that are running in cross-environment or background mode SHALL be returned to normal mode and restrictions on them as a consequence of them running in those modes SHALL be lifted
• visible user interfaces of cross-environment applications whose environment becomes selected SHALL continue to remain visible
• the policy of the newly selected environment is responsible for determining which of the applications in that environment should be the first to have focus.
• Any pauseable applications which were paused when this environment went into the background state and which are still paused shall be returned to the active state

Environment

protected Environment()

Constructor for environments. This is provided for the use of implementations or other specifications and is not to be used by applications.

getHome

public static Environment getHome()

Return the calling applications home environment

Returns:

an environment

addEnvironmentListener

public void addEnvironmentListener(EnvironmentListener l)

Add a listener for environment events.

Parameters:

l - the listener to add

removeEnvironmentListener

public void removeEnvironmentListener(EnvironmentListener l)

Remove a listener for environment events.

Parameters:

l - the listener to remove

getState

public EnvironmentState getState()

Queries the state of this environment.

Returns:

the state of this environment

select

public void select()

Request this environment become selected. This call is asynchronous and completion SHALL be reported with an EnvironmentEvent being sent to registered EnvironmentListeners.

This request SHALL be unconditionally granted except under the following circumstances.

• if a deadlock is detected with two or more environments repeatedly requesting they be selected each time they become de-selected. Implementations MAY include logic to detect this situation if it happens and refuse to change selected environment after an implementation specific number of changes in an implementation specific period.
• if this environment is in the presenting state due to it running in a PiP or PoP session and making this environment selected is not permitted by a PiP control mechanism on the OCAP host device

Throws:

java.lang.IllegalStateException - if a state change is already in progress for this environment or if the request fails for one of the circumstances defined above

java.lang.SecurityException - if and only if the calling application does not have MonitorAppPermission("environment.selection")

deselect

public void deselect()

Request this environment cease being selected.

NOTE It is implementation dependent which environment becomes selected when this call is used.

Throws:

java.lang.SecurityException - if and only if the calling application does not have MonitorAppPermission("environment.selection")