gwt-gae-channel-1.0-20010325

{info:title=Useful Information}
This page has been generated by [maven-confluence-plugin|http://code.google.com/p/maven-confluence-plugin/]
{info}

{toc}

----

{children}


h1. Description

{panel}

The Channel API creates a persistent connection between your application and Google servers, allowing your application to send messages to JavaScript clients in real time without the use of polling. This is useful for applications that are designed to update the user about new information immediately or where user input is immediately broadcast to other users. Some examples include collaborative applications, multi-player games, and chat rooms. In general, using Channel API is a better choice than polling in situations where updates can't be predicted or scripted, such as when relaying information between human users or from events not generated systematically.
{panel}

h2. Introduction
First of all, you should read and be familiar with how to use the App Engine Channel API [java|http://code.google.com/appengine/docs/java/channel/overview.html] on the server-side.

This library simply wraps the client-side JavaScript with GWT bindings to make it accessible in a GWT application, and it doesn't manage telling your client the client ID it should use. That part's up to you, and is described in the documentation for the Channel API.

h2. How To use

h3. Inherit gwt module

In your GWT descriptor you have to include the following *inherit* declaration

{code:xml}
<inherits name="com.google.gwt.appengine.channel.Channel"/>
{code}

h3. Create a service that generate a unique token to be associated with the event channel

Each channel is identified by an unique token that should be generated by application itself. In order to do this you have to implement a simple service (e.g. servlet) that accomplish this task

h3. Initialize Event Listener (client side)

{code:java|title=initialize service from client}

private void initEventsManagement() {

// GET CUSTOM TOKEN FROM SERVLET
RequestBuilder request = new RequestBuilder(RequestBuilder.POST, GWT.getModuleBaseURL() + "/service/events/token");

try {
request.sendRequest("",new RequestCallback() {

@Override
public void onResponseReceived(Request req, Response res) {
GWT.log("onResponseReceived " + res.getText() );

// REGISTER CHANNEL FOR GIVEN TOKEN (see below)
registerChannel(res.getText());

}

@Override
public void onError(Request req, Throwable t) {
GWT.log("onError ", t );
}
});
} catch (RequestException e) {
e.printStackTrace();
}

}

private void registerChannel( String token ) {

GWT.log("Event Module load!");

ChannelFactory.createChannel(token, new ChannelCreatedCallback() {
@Override
public void onChannelCreated(Channel channel) {
channel.open(new SocketListener() {
@Override
public void onOpen() {
GWT.log("Event Channel opened!");
}
@Override
public void onMessage(String message) {
GWT.log("Event Received: " + message);
}
@Override
public void onError(SocketError error) {
GWT.log("Event Channel creation error: " + error.getDescription());
}
@Override
public void onClose() {
GWT.log("Channel closed!");
}
});
}
});
}

{code}

h3. Send event (server side)

The following is a simple example of how to open a channel and send event to the client listeners when receives a message.

{code:java|title=send event from server}

public void sendEvent(String event) {
ChannelService channelService = ChannelServiceFactory.getChannelService();
channelService.sendMessage(new ChannelMessage( token /* the same token generated by application, see above */, event));

}

{code}

|Description|GWT bindings for the App Engine Channel API client|
|Homepage|[http://code.google.com/p/gwt-gae-channel/|http://code.google.com/p/gwt-gae-channel/]

|URL|[http://www.google.com|http://www.google.com]

|ArtifactId|gwt-gae-channel|
|Version|1.0-20010325|
|Type|jar|


----

h1. Issue Tracking


----

To commit changes to the repository, execute the following command to commit your changes (svn will prompt you for your password)
{noFormat}

{noFormat}
[global]
http-proxy-host = your.proxy.name
http-proxy-port = 3128
{noFormat}


----