Echo Web Framework

Echo2 provides for the capability for the server to initiate and push updates to the client of its own accord. This capability can be used to update the client when the server receives notification of external events, or simply to update the client at regular time intervals. Practical uses for server push capability include implementing multi-user interactive applications such as chatrooms, keeping users of an application up-to-date with status information or news, and providing feedback during long-running operations.

Task Queues

In order to provide the capability to push to an Echo client, your application must first create a Task Queue. When the application determines that it needs to push updates to the client, it will add tasks to the Task Queue. When the push capability is no longer required, the application should remove the Task Queue.

Creating and Removing Task Queues: The ApplicationInstance is responsible for creating and removing task queues. In order to create a Task Queue, the developer should invoke the createTaskQueue() method. A handle object, TaskQueueHandle, is returned which represents the created queue. When the application has finished with the created queue, it should invoke the removeTaskQueue() method and pass in the handle as its parameter.

The following example shows the creation of a TaskQueue:

TaskQueueHandle taskQueue = app.createTaskQueue();

It is critical that you retain a reference to the created TaskQueue until it has been destroyed, as shown in the following example:

app.removeTaskQueue(taskQueue);

Performing Push Operations: A push operation is performed by adding a task to a Task Queue. The operation to perform is encapsulated in a java.lang.Runnable which will be executed once a lock has been established on the state of the client's user interface.

The following example shows a hypothetical pushed update to the client. In this example, we assume app is a reference to the ApplicationInstance, taskQueue represents an active TaskQueueHandle, progressLabel represents a Label displaying progress information for a long-running task, and progressPercent represents the current percentage of that task which has been completed:

app.enqueueTask(taskQueue, new Runnable() {
  public void run() {
    progressLabel.setText("Progress: " + progressPercent 
        + "% complete");
  }
});

All operations which will update the state of the client user interface (i.e., which will manipulate the state of the ApplicationInstance and its hierarchy of Components) must be performed within the Runnable. Manipulating the state of an Echo2 application externally in other fashions will result in the Echo2 application throwing an IllegalStateException.

Server Push in Echo Web Applications

How server push works: In order to push tasks to the client, the Echo client engine periodically makes poll requests to the server to determine whether any server-pushed operations must be performed. If the server's response indicates that pushed operations have been queued, the Echo2 client engine will initiate a client-server synchronization operation. If there are no active Task Queues, the client will not make polling requests to the server. It is thus important to dispose of any queues that are no longer required.

Session timeout issues: A client which is repeatedly making polling requests to the server will cause the server to not expire the session, even if no real user activity has occurred. In such a case the session would only expire if the user navigated away from the application or closed the application's browser window. This can be both a feature and a problem, depending on the requirements of your application. This issue will only occur if active Task Queues are in use.

How server push should NOT be used: The asynchronous task queue capabilities of Echo2 are not generally intended for the creation of "server-interactive AJAX components." High-performance AJAX components should be developed using custom HTML-and-JavaScript-rendering synchronization peers that make asynchronous calls to their own server-side services. Server push requires locking the state of the client browser while tasks are executed, which may contribute negatively to the user experience of an AJAX component.

Multithreading Concerns

Until JEE 1.3 (J2EE 1.3), the Java Enterprise Edition specifically forbade the creation of threads not managed by the application server. Certain application containers and servlet containers may not require applications to abide by this specification. If you intend to create your own threads to perform background processing with any Java servlet based application (including Echo2 applications) you should check the documentation for the container.

Echo2's server push capabilities do not make use of multithreading. It is safe to run an Echo2 application with server-push capabilities under a servlet container that does not allow multithreading, provided that your application does not spawn its own threads.