A Command API is also available that provides a stream of command objects from the server to the client. This abstraction handles many of the complexities inherent to implementing a Command Pattern using the ICEpush protocol. For instance, commands are queued on the server and pulled in batches so as to avoid command loss. The Command Pattern API guarantees the delivery of any command placed on the queue (assuming the connection is healthy and the client is still running).
At the server, GWT adheres to the standard Java Servlet model, and as such the basic Java EE Integration applies. Notification triggers are typically implemented within the GWT RemoteServiceServlet RPC.
ICEpush integration with GWT involves two JAR libraries.
The GWT integration is an extension of the basic Java EE Integration. The server side of the integration uses org.icepush.PushContext class to create push ids, add group memberships and initiate push events. In most cases, group membership and push ids are abstracted from the developer, so calling these methods on the PushContext is not necessary. With respect to the client side of the integration, any third-party Java code must be "inherited" explicitly via the module configuration file - including the integration library itself. This is accomplished by adding "org.icepush.gwt.ICEpush" as an inherited module. To inherit the ICEpush library, simply add the following line to your module configuration file:
The icepush.jar and icepush-gwt.jar then must included in the compile time and runtime classpath. After this, the classes can be used inside your project.
And finally the ICEpush servlet component is added to the web.xml file:
The class com.icesoft.icepush.integration.gwt.GWTPushContext provides a singleton client-side push context that can be used to programatically react to push events that are generated on the server. It provides following API:
Please see the related JavaDoc for more information regarding the use of each of these methods.
The class com.icesoft.icepush.integration.gwt.PushEventListener provides an abstract base class for push event listeners. It provides following API:
An example listener might be:
This listener would simply popup the message "Notification Received" when the listener is triggered
Client-side push event registration is achieved using the GWTPushContext.addPushEventListener() method. Continuing with the previous example:
This will cause the popup when "myGroup" is pushed to.
Currently, client initiated push events are not permitted. All push notifications must originate from the server. As typically notification triggers are associated with some server-side state change, this does not represent a major obstacle. Simply place calls to the PushContext in RemoteService servlets (or any other server-side component) and the push events will be received on the client.
For more information on server initiated push in GWT see the next section.
The standard ICEpush Java EE Integration APIs are used to access and manipulate the PushContext from server-side logic. This logic is typically implemented within the GWT RemoteServiceServlet Remote Procedure Call, as illustrated below.
As previously mentioned, the ICEpush GWT integration also provides developers with a Command Pattern API. This API abstracts out much of the complexity involved with queuing and delivering commands using the lower-level GWT integration API.
The client side aspect of the Command API consists of three basic items: the ClientPushCommandContext controller class, the ICommand interface and the ICommandExecutor interface.
The ICommand is the simplest so lets start with that. The ICommand interface is a marker interface that is used by ICEpush to identify a command POJO. A Command in the API is simply a POJO that implements the ICommand interface. Note that commands are serialized by GWT and thus must implement java.io.Serializable and not utilize any unsupported libraries. Other than that - the Command is simply a POJO. An example command is shown below:
Next lets discuss the ICommandExecutor interface. Command Executors are invoked by the framework when a command is received from the server. One of the guarantees of the API is that a command executor will be invoked for every command that is placed on the server queue. Thus developers do not need to worry about the lower-level details of the ICEpush protocol. Implementors of the ICommandExecutor interface need to provide one method:
This method will get invoked for each command received by the client. Continuing for the previous example, a command executor for the ParticipantEntryCommand might look as follows:
Now the only remaining client-side step is to actually associate this command executor with the specific command type. The ClientPushCommandContext class is responsible for maintaining the command registry. Please view the JavaDoc for this class on information on the features this controller provides. Most notable there are two methods defined that every GWT Command Application will need to use:
To complete the previous example, the ParticipantEntryCommand can be registered to the ParticipantEntryCommandExecutor via the following line of code:
As soon as the registerExecutor() method is used to tie a handler to a command, that handler will be called for any command of that class that is received.
The server side of the Command API is very simple. It consists of a singleton ServerPushCommandContext which is tied to the Servlet context. Commands can be created and queued into the ServerPushCommandContext, and they will be streamed to the appropriate clients.
The ServerPushCommandContext can be fetched via the ServerPushCommandContext.getInstance(ServletContext context) method.
The pushCommand() method can then be used to place a command on the queue.
A tutorial on extending the example "Greeting" GWT application can be found here.
© Copyright 2017 ICEsoft Technologies Canada Corp.