nextapp.echo.app
Class ApplicationInstance

java.lang.Object
  nextapp.echo.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	activate() Invoked after the application has been passivated (such that its state may be persisted or moved amongst VMs) and is about to be reactivated.
void	addPropertyChangeListener(java.beans.PropertyChangeListener l) Adds a PropertyChangeListener to receive notification of application-level property changes.
TaskQueueHandle	createTaskQueue() Creates a new task queue.
void	dispose() Invoked when the application is disposed and will not be used again.
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 ApplicationInstances).
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.
StyleSheet	getStyleSheet() Returns the application-wide StyleSheet, if present.
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	passivate() Invoked before the application is passivated (such that its state may be persisted or moved amongst VMs).
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 ApplicationInstances).

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

activate

public void activate()

Invoked after the application has been passivated (such that its state may be persisted or moved amongst VMs) and is about to be reactivated. Implementations must invoke super.activate().

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)

dispose

public void dispose()

Invoked when the application is disposed and will not be used again. Implementations must invoke super.dispose().

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

getStyleSheet

public StyleSheet getStyleSheet()

Returns the application-wide StyleSheet, if present.

Returns:

the StyleSheet

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 by an application in order to check on the status of long-running operations and enqueue tasks just-in-time. In such cases tasks should be enqueued and the value of super.hasQueuedTasks() should be returned. This method is not invoked by a user-interface thread and thus the component hierarchy may not be modified in overriding implementations.

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

passivate

public void passivate()

Invoked before the application is passivated (such that its state may be persisted or moved amongst VMs). Implementations must invoke super.passivate().

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. Components 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