Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## nextapp.echo2.app
Class ApplicationInstance

    java.lang.Object
      nextapp.echo2.app.ApplicationInstance

All Implemented Interfaces:
  java.io.Serializable

    public abstract class ApplicationInstance

extends java.lang.Object
implements java.io.Serializable

A single user-instance of an Echo application.

See Also:
  Serialized Form

Field Summary
`static java.lang.String` | `FOCUSED_COMPONENT_CHANGED_PROPERTY`
`static java.lang.String` | `ID_STRING` The name and version of the Echo API in use.
`static java.lang.String` | `LOCALE_CHANGED_PROPERTY`
`static java.lang.String` | `MODAL_COMPONENTS_CHANGED_PROPERTY`
`static java.lang.String` | `WINDOWS_CHANGED_PROPERTY`

Constructor Summary
`ApplicationInstance()` Creates an `ApplicationInstance`.

Method Summary
`void` | `addPropertyChangeListener(java.beans.PropertyChangeListener l)` Adds a `PropertyChangeListener` to receive notification of application-level property changes.
`TaskQueueHandle` | `createTaskQueue()` Creates a new task queue.
`Window` | `doInit()` Initializes the `ApplicationInstance`.
`void` | `doValidation()` Validates all components registered with the application.
`void` | `enqueueCommand(Command command)` Queues the given stateless `Command` for execution on the current client/server synchronization.
`void` | `enqueueTask(TaskQueueHandle taskQueue, java.lang.Runnable task)` Enqueues a task to be run during the next client/server synchronization.
`protected void` | `firePropertyChange(java.lang.String propertyName, java.lang.Object oldValue, java.lang.Object newValue)` Reports a bound property change.
`java.lang.String` | `generateId()` Generates an identifier which is unique within this `ApplicationInstance`.
`static java.lang.String` | `generateSystemId()` Generates a system-level identifier (an identifier which is unique to all `ApplicationInstance`s).
`static ApplicationInstance` | `getActive()` Returns a reference to the `ApplicationInstance` that is relevant to the current thread, or null if no instance is relevant.
`Component` | `getComponentByRenderId(java.lang.String renderId)` Retrieves the component currently registered with the application with the specified render id.
`java.lang.Object` | `getContextProperty(java.lang.String propertyName)` Returns the value of a contextual property.
`Window` | `getDefaultWindow()` Returns the default window of the application.
`Component` | `getFocusedComponent()` Returns the presently focused component, if known.
`LayoutDirection` | `getLayoutDirection()` Returns the application instance's default `LayoutDirection`.
`java.util.Locale` | `getLocale()` Returns the application instance's default `Locale`.
`Component` | `getModalContextRoot()` Retrieves the root component of the current modal context, or null if no modal context exists.
`Style` | `getStyle(java.lang.Class componentClass, java.lang.String styleName)` Retrieves the style for the specified specified class of component / style name.
`UpdateManager` | `getUpdateManager()` Retrieves the `UpdateManager` being used to manage the client/server synchronization of this `ApplicationInstance`
`boolean` | `hasQueuedTasks()` Determines if there are any queued tasks in any of the task queues associated with this `ApplicationInstance`.
`boolean` | `hasTaskQueues()` Determines if this `ApplicationInstance` currently has any active tasks queues, which might be monitoring external events.
`abstract Window` | `init()` Invoked to initialize the application, returning the default window.
`void` | `processInput(java.lang.String propertyName, java.lang.Object propertyValue)` Processes client input specific to the `ApplicationInstance` received from the `UpdateManager`.
`void` | `processQueuedTasks()` Processes all queued tasks.
`void` | `removePropertyChangeListener(java.beans.PropertyChangeListener l)` Removes a `PropertyChangeListener` from receiving notification of application-level property changes.
`void` | `removeTaskQueue(TaskQueueHandle taskQueueHandle)` Removes the task queue described the specified `TaskQueueHandle`.
`static void` | `setActive(ApplicationInstance applicationInstance)` Sets the `ApplicationInstance` that is relevant to the current thread.
`void` | `setContextProperty(java.lang.String propertyName, java.lang.Object propertyValue)` Sets a contextual property.
`void` | `setFocusedComponent(Component newValue)` Sets the presently focused component.
`void` | `setLocale(java.util.Locale newValue)` Sets the default locale of the application.
`void` | `setStyleSheet(StyleSheet styleSheet)` Sets the `StyleSheet` of this `ApplicationInstance`.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### ID_STRING

    public static final java.lang.String ID_STRING

  The name and version of the Echo API in use.

  See Also:
    Constant Field Values

### FOCUSED_COMPONENT_CHANGED_PROPERTY

    public static final java.lang.String FOCUSED_COMPONENT_CHANGED_PROPERTY

See Also:
  Constant Field Values

### LOCALE_CHANGED_PROPERTY

    public static final java.lang.String LOCALE_CHANGED_PROPERTY

See Also:
  Constant Field Values

### MODAL_COMPONENTS_CHANGED_PROPERTY

    public static final java.lang.String MODAL_COMPONENTS_CHANGED_PROPERTY

See Also:
  Constant Field Values

### WINDOWS_CHANGED_PROPERTY

    public static final java.lang.String WINDOWS_CHANGED_PROPERTY

See Also:
  Constant Field Values

Constructor Detail

### ApplicationInstance

    public ApplicationInstance()

  Creates an `ApplicationInstance`.

Method Detail

### generateSystemId

    public static final java.lang.String generateSystemId()

  Generates a system-level identifier (an identifier which is unique to all `ApplicationInstance`s).

  Returns:
    the generated identifier
  See Also:
    `generateId()`

### getActive

    public static final ApplicationInstance getActive()

  Returns a reference to the `ApplicationInstance` that is relevant to the current thread, or null if no instance is relevant.

  Returns:
    the relevant `ApplicationInstance`

### setActive

    public static final void setActive(ApplicationInstance applicationInstance)

  Sets the `ApplicationInstance` that is relevant to the current thread. This method should be invoked with a null argument when the previously set `ApplicationInstance` is no longer relevant.

  This method should only be invoked by the application container.

  Parameters:
    `applicationInstance` - the relevant `ApplicationInstance`

### addPropertyChangeListener

    public void addPropertyChangeListener(java.beans.PropertyChangeListener l)

  Adds a `PropertyChangeListener` to receive notification of application-level property changes.

  Parameters:
    `l` - the listener to add

### createTaskQueue

    public TaskQueueHandle createTaskQueue()

  Creates a new task queue. A handle object representing the created task queue is returned. The created task queue will remain active until it is provided to the `removeTaskQueue()` method. Developers must take care to invoke `removeTaskQueue()` on any created task queues.

  Returns:
    a `TaskQueueHandler` representing the created task queue
  See Also:
    `removeTaskQueue(TaskQueueHandle)`

### doInit

    public final Window doInit()

  Initializes the `ApplicationInstance`. This method is invoked by the application container.

  Returns:
    the default `Window` of the application
  Throws:
    `java.lang.IllegalStateException` - in the event that the current thread is not permitted to update the state of the user interface

### doValidation

    public final void doValidation()

  Validates all components registered with the application.

### enqueueCommand

    public void enqueueCommand(Command command)

  Queues the given stateless `Command` for execution on the current client/server synchronization.

  Parameters:
    `command` - the `Command` to execute

### enqueueTask

    public void enqueueTask(TaskQueueHandle taskQueue,
                            java.lang.Runnable task)

  Enqueues a task to be run during the next client/server synchronization. The task will be run synchronously in the user interface update thread. Enqueuing a task in response to an external event will result in changes being pushed to the client.

  Parameters:
    `taskQueue` - the `TaskQueueHandle` representing the queue into which this task should be placed
    `task` - the task to run on client/server synchronization

### firePropertyChange

    protected void firePropertyChange(java.lang.String propertyName,
                                      java.lang.Object oldValue,
                                      java.lang.Object newValue)

  Reports a bound property change.

  Parameters:
    `propertyName` - the name of the changed property
    `oldValue` - the previous value of the property
    `newValue` - the present value of the property

### generateId

    public java.lang.String generateId()

  Generates an identifier which is unique within this `ApplicationInstance`. This identifier should not be used outside of the context of this `ApplicationInstance`.

  Returns:
    the unique identifier
  See Also:
    `generateSystemId()`

### getContextProperty

    public java.lang.Object getContextProperty(java.lang.String propertyName)

  Returns the value of a contextual property. Contextual properties are typically set by an application container, e.g., the Web Container, in order to provide container-specific information. The property names of contextual properties are provided within the application container documentation when their use is required.

  Parameters:
    `propertyName` - the name of the object
  Returns:
    the object

### getComponentByRenderId

    public Component getComponentByRenderId(java.lang.String renderId)

  Retrieves the component currently registered with the application with the specified render id.

  Parameters:
    `renderId` - the render id of the component
  Returns:
    the component (or null if no component with the specified render id is registered)

### getDefaultWindow

    public Window getDefaultWindow()

  Returns the default window of the application.

  Returns:
    the default `Window`

### getFocusedComponent

    public Component getFocusedComponent()

  Returns the presently focused component, if known.

  Returns:
    the focused component

### getLayoutDirection

    public LayoutDirection getLayoutDirection()

  Returns the application instance's default `LayoutDirection`.

  Returns:
    the `Locale`

### getLocale

    public java.util.Locale getLocale()

  Returns the application instance's default `Locale`.

  Returns:
    the `Locale`

### getModalContextRoot

    public Component getModalContextRoot()

  Retrieves the root component of the current modal context, or null if no modal context exists. Components which are not within the descendant hierarchy of the modal context are barred from receiving user input.

  Returns:
    the root component of the modal context

### getStyle

    public Style getStyle(java.lang.Class componentClass,
                          java.lang.String styleName)

  Retrieves the style for the specified specified class of component / style name.

  Parameters:
    `componentClass` - the component `Class`
    `styleName` - the component's specified style name
  Returns:
    the appropriate application-wide style, or null if none exists

### getUpdateManager

    public UpdateManager getUpdateManager()

  Retrieves the `UpdateManager` being used to manage the client/server synchronization of this `ApplicationInstance`

  Returns:
    the `UpdateManager`

### hasTaskQueues

    public final boolean hasTaskQueues()

  Determines if this `ApplicationInstance` currently has any active tasks queues, which might be monitoring external events.

  Returns:
    true if the instance has any task queues

### hasQueuedTasks

    public boolean hasQueuedTasks()

  Determines if there are any queued tasks in any of the task queues associated with this `ApplicationInstance`. This method may be overridden to check to enqueue tasks if desired.

  Returns:
    true if any tasks are queued

### init

    public abstract Window init()

  Invoked to initialize the application, returning the default window. The returned window must be visible.

  Returns:
    the default window of the application

### processInput

    public void processInput(java.lang.String propertyName,
                             java.lang.Object propertyValue)

  Processes client input specific to the `ApplicationInstance` received from the `UpdateManager`. Derivative implementations should take care to invoke `super.processInput()`.

### processQueuedTasks

    public void processQueuedTasks()

  Processes all queued tasks. This method may only be invoked from within a UI thread by the `UpdateManager`. Tasks are removed from queues once they have been processed.

### removePropertyChangeListener

    public void removePropertyChangeListener(java.beans.PropertyChangeListener l)

  Removes a `PropertyChangeListener` from receiving notification of application-level property changes.

  Parameters:
    `l` - the listener to remove

### removeTaskQueue

    public void removeTaskQueue(TaskQueueHandle taskQueueHandle)

  Removes the task queue described the specified `TaskQueueHandle`.

  Parameters:
    `taskQueueHandle` - the `TaskQueueHandle` specifying the task queue to remove
  See Also:
    `createTaskQueue()`

### setContextProperty

    public void setContextProperty(java.lang.String propertyName,
                                   java.lang.Object propertyValue)

  Sets a contextual property.

  Parameters:
    `propertyName` - the property name
    `propertyValue` - the property value
  See Also:
    `getContextProperty(java.lang.String)`

### setFocusedComponent

    public void setFocusedComponent(Component newValue)

  Sets the presently focused component.

  Parameters:
    `newValue` - the component to be focused

### setLocale

    public void setLocale(java.util.Locale newValue)

  Sets the default locale of the application.

  Parameters:
    `newValue` - the new locale

### setStyleSheet

    public void setStyleSheet(StyleSheet styleSheet)

  Sets the `StyleSheet` of this `ApplicationInstance`. `Component`s registered with this instance will retrieve properties from the `StyleSheet` when property values are not specified directly in a `Component` or in its specified `Style`.

  Note that setting the style sheet should be done sparingly, given that doing so forces the entire client state to be updated. Generally style sheets should only be reconfigured at application initialization and/or when the user changes the visual theme of a theme-capable application.

  Parameters:
    `styleSheet` - the new style sheet

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD