org.ocap.environment
Class Environment

java.lang.Object
  extended by org.ocap.environment.Environment

public abstract class Environment
extends java.lang.Object

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

Environment state machine

Environments SHALL be in one of four states; inactive, selected, presenting and background. These are defined as follows;

Transitions from selected or presenting to background

When an environment changes state from either selected or presenting to background, the following SHALL apply:

Transitions from background to selected or presenting

When an environment changes state from background to either selected or presenting, the following SHALL apply:


Constructor Summary
protected Environment()
          Constructor for environments.
 
Method Summary
 void addEnvironmentListener(EnvironmentListener l)
          Add a listener for environment events.
 void deselect()
          Request this environment cease being selected.
static Environment getHome()
          Return the calling applications home environment
 EnvironmentState getState()
          Queries the state of this environment.
 void removeEnvironmentListener(EnvironmentListener l)
          Remove a listener for environment events.
 void select()
          Request this environment become selected.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

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.

Method Detail

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.

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")