nextapp.echoservlet
Class Controller

java.lang.Object
  nextapp.echoservlet.Controller

All Implemented Interfaces:

CacheableService, java.io.Serializable, Service

final class Controller

extends java.lang.Object

implements java.io.Serializable, CacheableService

The Controller is a service that is used to receive input from the client and issue commands to it.

Every window of an Echo application contains a frameset at its root. This frameset contains two frames: The first, which fills 100% of the window, is whatever content service (e.g. a ContainerPane or ContentPane) the application desires to display in the window. The second frame is a Controller frame, which occupies 0% of the window, and is thus entirely hidden from view (although it can be made enabling certain debugging options in your application's servlet properties file).

The HTML document rendered by this service contains a form that provides a hidden field for each form component currently visible in any window. Each form component rendered on the client must copy its data to the controller's form when its data is changed by the user. This enables ALL available client data to be submitted to the server with every user gesture that may require server interaction.

The controller form will be submitted when the setAction() script method is called on the client. When this form is submitted, its data is parsed and each ComponentPeer is notified of the value of its respective hidden field if said value has changed. Then the component whose Id was provided to the setAction() script is notified of its having had its action invoked. This process will cause the ComponentPeers to notify their represented components, resulting in the application receiving events and doing work.

The application will (most likely) make changes as a result of receiving input. The ComponentPeers will be notified of the changes made to their respective Components, and the ComponentPeers will add their containing services to the OutgoingUpdateQueue such that they will be re-rendered. When the application has finished its work, the Controller will re-render a new hidden form, in addition to JavaScript method calls that will synchronize the client browser's state with the application's changes.
NOTE: Controller implements CacheableService in order to avoid issues with browsers (notably IE) whereby the user pressing the back button will cause a client-side application failure due to the browser being unable to retrieve a copy of the previous Controller's document from cache, and being unable to request a new copy by virtue of the document having been generated in response to an HTTP POST request.

Field Summary

private int	debugRenderCounter
private static Id	ID
private IncomingUpdateQueue	incomingUpdateQueue
private InstancePeer	instancePeer
private OutgoingUpdateQueue	outgoingUpdateQueue
(package private) static java.lang.String	PARAMETER_INPUT_PREFIX
(package private) static int	PARAMETER_INPUT_PREFIX_LENGTH
(package private) static java.lang.String	PARAMETER_PANE_SCROLL_POSITION_PREFIX
(package private) static int	PARAMETER_PANE_SCROLL_POSITION_PREFIX_LENGTH
(package private) static java.lang.String	PARAMETER_REQUEST_DATA
(package private) static java.lang.String	PARAMETER_REQUEST_TYPE
(package private) static java.lang.String	PARAMETER_SEQUENCE_NUMBER
(package private) static java.lang.String	REQUEST_TYPE_ACTION A parameter that is provided on the request URI when the controller's form is being submitted in response to an action by the user.
(package private) static java.lang.String	REQUEST_TYPE_STATE_VALID An acknowledgement from the client that the state of the client is valid.
(package private) static java.lang.String	REQUEST_TYPE_SYNCHRONIZE A parameter that is provided on the request URI when the controller's form is being submitted on a synchronize request.
(package private) static java.lang.String	REQUEST_TYPE_WINDOW_UNLOAD A parameter that is provided on the request URI when the controller's form is being submitted in response to a window unloading.
(package private) static java.lang.String	REQUEST_TYPE_WINDOWS_CLOSED A parameter that is provided on the request URI when the controller's form is being submitted in response to one or more windows being closed, by way of their close buttons having been clicked.
(package private) static java.lang.String	REQUEST_TYPE_WINDOWS_MISSING A parameter that is provided on the request URI when the controller's form is being submitted in response to the controller's script having found an inconsistency between the windows that should be open on the client and the windows that actually are open on the client.
private static Service	SERVICE_COMPONENT_HIERARCHY_VIEWER
private static Service	SERVICE_CONTROLLER_DEBUG_SCRIPT A JavaScript service containing debugging methods.
private static Service	SERVICE_CONTROLLER_SCRIPT A JavaScript service containing methods used by the Controller.
private static java.lang.String	SET_READY_FLAG
private int	version Version number for CacheableService.

Constructor Summary

(package private)

Controller(InstancePeer instancePeer) Create a new controller for the specified InstancePeer with the specified OutgoingUpdateQueue.

Method Summary

private void	addDebugOptions(Connection conn, HtmlDocument doc, Element parent) Adds debugging options to (visible) controller frame.
private static int	getComponentIndex(ComponentPeer parent, ComponentPeer child) Returns the index of the child component in the ComponentPeer.
Id	getId() Returns a unique identifier for this service.
private java.lang.String	getScriptAdjustWindowZIndices(Connection conn) Returns a JavaScript method call which will adjust the Z-indices of raised and lowered windows.
private java.lang.String	getScriptChangeFrameContent(Connection conn) Produces a JavaScript method invocation string which will cause the client to update the content of one or more frames based on the OutgoingUpdateQueue's collection of frames that require updates.
private java.lang.String	getScriptChangeWindowContent(Connection conn) Produces a JavaScript method invocation string which will cause the client to update the root content of one or more windows based on the OutgoingUpdateQueue's collection of windows that require updates.
private java.lang.String	getScriptCloseWindow(WindowUI windowUI) Returns a string containing a JavaScript method call that will cause a window to close.
private java.lang.String	getScriptOpenWindow(Connection conn, WindowUI windowUI) Returns a string containing a JavaScript method call that will cause a new window to open.
private java.lang.String	getScriptSetWindowTitles() Returns a string containing a JavaScript method call that will cause windows to have their titles changed.
private java.lang.String	getScriptVerifyClientState(boolean acknowledgementRequired) Returns a string containing a JavaScript method call that will cause the client to verify that the windows it has open are the same as the windows the server wants open.
int	getVersion() Returns the version of the service to be retrieved.
private void	render(Connection conn) Render a "normal" copy of the controller frame, with instuctions to synchronize the state of the client with that of the server.
private void	renderShutdown(Connection conn) Renders output for the case where the application needs to shutdown and redirect to a different URI.
void	service(Connection conn) Services an HTTP request.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PARAMETER_SEQUENCE_NUMBER

static final java.lang.String PARAMETER_SEQUENCE_NUMBER

See Also:

Constant Field Values

PARAMETER_REQUEST_TYPE

static final java.lang.String PARAMETER_REQUEST_TYPE

See Also:

Constant Field Values

PARAMETER_REQUEST_DATA

static final java.lang.String PARAMETER_REQUEST_DATA

See Also:

Constant Field Values

PARAMETER_INPUT_PREFIX

static final java.lang.String PARAMETER_INPUT_PREFIX

See Also:

Constant Field Values

PARAMETER_INPUT_PREFIX_LENGTH

static final int PARAMETER_INPUT_PREFIX_LENGTH

PARAMETER_PANE_SCROLL_POSITION_PREFIX

static final java.lang.String PARAMETER_PANE_SCROLL_POSITION_PREFIX

See Also:

Constant Field Values

PARAMETER_PANE_SCROLL_POSITION_PREFIX_LENGTH

static final int PARAMETER_PANE_SCROLL_POSITION_PREFIX_LENGTH

ID

private static final Id ID

SET_READY_FLAG

private static final java.lang.String SET_READY_FLAG

See Also:

Constant Field Values

REQUEST_TYPE_ACTION

static final java.lang.String REQUEST_TYPE_ACTION

A parameter that is provided on the request URI when the controller's form is being submitted in response to an action by the user.

See Also:

Constant Field Values

REQUEST_TYPE_SYNCHRONIZE

static final java.lang.String REQUEST_TYPE_SYNCHRONIZE

A parameter that is provided on the request URI when the controller's form is being submitted on a synchronize request.

See Also:

Constant Field Values

REQUEST_TYPE_WINDOW_UNLOAD

static final java.lang.String REQUEST_TYPE_WINDOW_UNLOAD

A parameter that is provided on the request URI when the controller's form is being submitted in response to a window unloading.

See Also:

Constant Field Values

REQUEST_TYPE_WINDOWS_CLOSED

static final java.lang.String REQUEST_TYPE_WINDOWS_CLOSED

A parameter that is provided on the request URI when the controller's form is being submitted in response to one or more windows being closed, by way of their close buttons having been clicked.

See Also:

Constant Field Values

REQUEST_TYPE_WINDOWS_MISSING

static final java.lang.String REQUEST_TYPE_WINDOWS_MISSING

A parameter that is provided on the request URI when the controller's form is being submitted in response to the controller's script having found an inconsistency between the windows that should be open on the client and the windows that actually are open on the client.

See Also:

Constant Field Values

REQUEST_TYPE_STATE_VALID

static final java.lang.String REQUEST_TYPE_STATE_VALID

An acknowledgement from the client that the state of the client is valid. This will cause any delayed updates to be processed.

See Also:

Constant Field Values

SERVICE_CONTROLLER_SCRIPT

private static final Service SERVICE_CONTROLLER_SCRIPT

A JavaScript service containing methods used by the Controller.

SERVICE_CONTROLLER_DEBUG_SCRIPT

private static final Service SERVICE_CONTROLLER_DEBUG_SCRIPT

A JavaScript service containing debugging methods.

SERVICE_COMPONENT_HIERARCHY_VIEWER

private static final Service SERVICE_COMPONENT_HIERARCHY_VIEWER

instancePeer

private InstancePeer instancePeer

incomingUpdateQueue

private IncomingUpdateQueue incomingUpdateQueue

outgoingUpdateQueue

private OutgoingUpdateQueue outgoingUpdateQueue

debugRenderCounter

private int debugRenderCounter

version

private int version

Version number for CacheableService.

Constructor Detail

Controller

Controller(InstancePeer instancePeer)

Create a new controller for the specified InstancePeer with the specified OutgoingUpdateQueue.

Parameters:

instancePeer - The instance peer for which this controller will be used.

Method Detail

getComponentIndex

private static int getComponentIndex(ComponentPeer parent,
                                     ComponentPeer child)

Returns the index of the child component in the ComponentPeer.

Parameters:

parent - A component peer whose component may contain child's component.

child - A component peer whose component's parent may be parent's component.

Returns:

The index of child in parent, or -1 if child is not a child of parent.

addDebugOptions

private void addDebugOptions(Connection conn,
                             HtmlDocument doc,
                             Element parent)

Adds debugging options to (visible) controller frame.

getId

public Id getId()

Description copied from interface: Service

Returns a unique identifier for this service.

Specified by:

getId in interface Service

Returns:

A unique identifier for this service.

See Also:

Service.getId()

getScriptAdjustWindowZIndices

private java.lang.String getScriptAdjustWindowZIndices(Connection conn)

Returns a JavaScript method call which will adjust the Z-indices of raised and lowered windows. The OutgoingUpdateQueue will be queried to determine windows that need to be raised or lowered.

Parameters:

conn - The connection wrapping the response.

Returns:

A JavaScript method call to adjust the Z-indices of raised and lowered windows.

getScriptChangeFrameContent

private java.lang.String getScriptChangeFrameContent(Connection conn)

Produces a JavaScript method invocation string which will cause the client to update the content of one or more frames based on the OutgoingUpdateQueue's collection of frames that require updates. Removes all pane update tasks from the OutgoingUpdateQueue.

Parameters:

conn - The connection on which the JavaScript will be rendered.

Returns:

A JavaScript invocation string which will cause the update.

getScriptChangeWindowContent

private java.lang.String getScriptChangeWindowContent(Connection conn)

Produces a JavaScript method invocation string which will cause the client to update the root content of one or more windows based on the OutgoingUpdateQueue's collection of windows that require updates. Removes all window update tasks from the OutgoingUpdateQueue.

Parameters:

conn - The connection on which the JavaScript will be rendered.

Returns:

A JavaScript invocation string which will cause the update.

getScriptCloseWindow

private java.lang.String getScriptCloseWindow(WindowUI windowUI)

Returns a string containing a JavaScript method call that will cause a window to close.

Parameters:

windowUI - The peer of the window to be closed.

Returns:

A JavaScript method call to close the window.

getScriptOpenWindow

private java.lang.String getScriptOpenWindow(Connection conn,
                                             WindowUI windowUI)

Returns a string containing a JavaScript method call that will cause a new window to open.

Parameters:

conn - The Connection wrapping the request.

windowUI - The peer of the window to be opened.

Returns:

A JavaScript method call that will open the window.

getScriptSetWindowTitles

private java.lang.String getScriptSetWindowTitles()

Returns a string containing a JavaScript method call that will cause windows to have their titles changed.

Returns:

A JavaScript method call that will update window titles.

getScriptVerifyClientState

private java.lang.String getScriptVerifyClientState(boolean acknowledgementRequired)

Returns a string containing a JavaScript method call that will cause the client to verify that the windows it has open are the same as the windows the server wants open.

Returns:

A JavaScript method call that will verify the client state.

getVersion

public int getVersion()

Description copied from interface: CacheableService

Returns the version of the service to be retrieved. When a service is requested with an updated version number, a non-cached copy will be used. getVersion() should return distinct values whenever the service's content may have changed.

Specified by:

getVersion in interface CacheableService

Returns:

The current version number of the service.

See Also:

CacheableService.getVersion()

render

private void render(Connection conn)

Render a "normal" copy of the controller frame, with instuctions to synchronize the state of the client with that of the server.

Parameters:

conn - The connection wrapping the response.

renderShutdown

private void renderShutdown(Connection conn)

Renders output for the case where the application needs to shutdown and redirect to a different URI.

Parameters:

conn - The connection wrapping the response.

service

public void service(Connection conn)

Description copied from interface: Service

Services an HTTP request. Information about the HTTP request as well as methods for issuing a response are available from the provided Connection object.

Specified by:

service in interface Service

Parameters:

conn - A Connection object which wraps HttpServletRequest and HttpServletResponse objects and provides access to the facilities of the Echo application container.

See Also:

Service.service(Connection)