Start coding today to experience the powerful engine that drives data application’s development, brought to you in partnership with Qlik.

[img_assist|nid=3421|title=|desc=|link=url|url=http://www.manning.com/affiliate/idevaffiliate.php?id|align=left|width=208|height=388]GWT enables client applications to communicate with server resources
through its own RPC and object-serialization mechanism. This
communication process involves each side of the conversation
implementing a very straightforward GWT service interface and
sending/receiving special GWT serialized data. The server side exposes
resources, and the client side invokes those resources asynchronously.

GWT
intentionally keeps things very basic and optimizes the translation of
data from Java to JavaScript and vice versa. While this mechanism is
really easy to work with and to understand, it's a GWTism. That is to
say, GWT does not use a standard or existing idiomatic approach no
XML-RPC, SOAP, or REST is involved. But despite using its own approach,
GWT can also communicate with existing services in additional ways to
facilitate integration, such as using plain XML over HTTP (POX), or
JavaScript Object Notation (JSON). These are additional methods,
though; the native mechanism for GWT client-server communication is GWT
RPC.

Starting the HelloServer project

We'll use
GWT RPC in a sample "Hello Server" application, aptly named
HelloServer. We'll first define the data we want to pass across the
wire, then create a server endpoint, which outlines a method that uses
that data, and finally implement a client to complete the process.
Figure 1 shows what our completed HelloServer application will look
like.

Figure 1 The HelloServer sample application demonstrating GWT server
communications. The last line on the screen shows the server's response
to the user's input.

We'll use the GWT ApplicationCreator
utility to create our basic project, but we'll also use the GWT
ProjectCreator utility to make Eclipse project files. After we use
ApplicationCreator and ProjectCreator, we'll build the example using
Eclipse. The ProjectCreator usage options are shown here and described
in table 1.

Running ApplicationCreator and ProjectCreator as shown will create your
default project template files and will create Eclipse-centric .project
and .classpath files. From there, you can open Eclipse and use the File
> Import > Existing Projects Into Workspace feature to import the
HelloServer project. Once you have the HelloServer project in your
Eclipse Navigator, you should see the standard GWT layout within it.
Figure 2 displays the imported HelloServer project in the Eclipse
Resource perspective.

Figure 2 The HelloServer project layout in the Eclipse Resource
perspective after ProjectCreator has generated the Eclipse project

If
you execute HelloServer-shell, you'll invoke GWTShell and you'll see
the standard template, "Click Me - Hello World", which every default
GWT project starts with. With the basic project in place, we're ready
to move on to implementing HelloServer. We'll start by defining our
simple data model and looking at GWT's serialization mechanism.

Defining GWT serializable data

The
first class we need to create is a simple data class, which we'll
call Person. Before our Person objects can be passed from a GWT client
application to an RPC service, they must be marked with either the
com.google.gwt.user.client.rpc.IsSerializable or the
java.io.Serializable interface. This is conceptually analogous to
regular Java serialization, but in this case itâ€™s used in a manner
specific to GWT. Also as in regular serialization, GWT will honor the
transient modifier on class properties, allowing them to be omitted if
they are not themselves serializable.

Note

The
IsSerializable interface is both important and problematic. It's
important because it gives the GWT compiler better information on what
classes need to support serialization. It's problematic because it
introduces a GWT-specific dependency into model classes, as you can see
in listing 1, the Person class. While this is not a big problem if
you're working entirely within the realm of your GWT application, it
could quickly become a deal breaker if you wish to share object models
with other Java projects in your organization.

Because of this the GWT-dependency of IsSerializable, GWT 1.4 added
support so that java.io.Serializable could be used in place of
IsSerializable. This allows these two marker interfaces to act
interchangeably in a GWT context. Generally, this helps to ensure that
model classes can be created without direct GWT dependencies. Yet,
it's important to understand that such model objects still need to be
otherwise GWT translatable. That means they need no-argument
constructors, and they cannot use Java 5 language features (for now).

Also,
it's important to understand that the GWT implementation of
java.io.Serializable, though convenient, is just a marker interface
meaning the same thing as IsSerializable this is not the same as
actual Java serialization support. The documentation for the GWT
version of java.io.Serializable puts it this way: "public interface
Serializable: Provided for interoperability; RPC treats this interface
synonymously with IsSerializable. The Java serialization protocol is
explicitly not supported."

The bottom line is that you can
use either IsSerializable or Serializable, and they mean exactly the
same thing to GWT this class is RPC translatable. The GWT
Serializable emulation can help you avoid the GWT-specific
IsSerializable dependency, but your model classes are still limited to
what is possible with GWT. Because of this, we'll use the
IsSerializable marker to make the association explicit. Keep in mind,
though, that in real life you may be better off using Serializable as
long as you're disciplined enough to remember the implicit GWT
limitations. We want to create our simple service infrastructure to
illustrate the GWT RPC basics.

Creating RPC services

GWT
includes a GWT RPC package for enabling communications with server
resources. Constructing an RPC service entails building two interfaces
and a service implementation.

You begin by creating a
synchronous service interface, which extends the GWT RemoteService
interface and defines the methods your service exposes. Next, you
create an asynchronous interface based on the first synchronous one.
This asynchronous interface will have the same name as the synchronous
interface, but with an Async suffix. Importantly, the asynchronous
interface does not extend RemoteService itself. The asynchronous
interface must have all the same methods as the synchronous one, except
that each of the asynchronous methods must declare a void return type,
throw no exceptions, and have an additional final reference parameter
of type AsyncCallback. These two interfaces one synchronous, one
asynchronous are the client side of the picture. Finally, you must
create a server-side implementation of your client-side synchronous
RemoteService interface. This must extend the GWT RemoteServiceServlet
class.

These three parts, the synchronous client service
interface, asynchronous client service interface, and server
implementation service servlet, are the backbone of GWT RPC. Table 2
restates these RPC components for reference.

Table 2 Components involved in creating a GWT RPC service

Required interface

Extension

Purpose

MyService

RemoteService

Client side. Synchronous interface, used internally by GWT.

MyServiceAsync

None

Client
side. Asynchronous interface which, by convention, backs the
synchronous interface. It must have the same name with an Async suffix,
must declare void return type on all methods, must throw no exceptions,
and must include AsyncCallback as the last parameter in all methods.

MyServiceImpl

RemoteServiceServlet

Server
side. An implementation of the client-side synchronous interface, which
by convention will be accessible in the client through the asynchronous
interface.

In our
example, we'll add one more element to the mix in order to decouple
our implementation just a bit and make things more flexible. We're
going to put our server-side RemoteService implementation in a separate
class, apart from our RemoteServiceServlet implementation. This could
be done in a single step we could have a server-side implementation
that both implements RemoteService and extends RemoteServiceServlet in
one fell swoop. However, we'll separate these two as a best practice,
because in a larger project you may want to use the service
implementation outside of the context of your GWT classes. With the
RemoteServiceServlet separated, youâ€™re free to implement the
RemoteService interface class itself in a Spring bean, an Enterprise
Java Bean (EJB), or even through a SOAP service. Figure 3 reinforces
these points and also shows the structure we'll use for our HelloServer
example.

Figure 3 GWT RPC class diagram for HelloServer. Notice that the
RemoteServiceAsync class is not directly related to our service
implementation or servlet; it's associated by convention.

It's
important to remember that all of the classes you use as arguments or
returns from the methods defined by your RemoteService interface must
be GWT-serializable, as we discussed in the Defining GWT
serializable data section. In addition, your remote interface and
all the data you wish to serialize must be part of your source path so
that GWTCompiler finds these resources and creates the appropriate
JavaScript versions. Getting into the RPC code, we'll start with the
client-side synchronous interface, HelloService.java, which is
displayed in listing 2.

Next, we need to create our client-side asynchronous interface,
which is almost identical to the synchronous one with the previously
noted exceptions (Async suffix, void return type, AsyncCallback as a
parameter the callback will be used to return the value). Note that
both of these client-side interfaces are in the default source path,
the .client package. Listing 3 shows our HelloServiceAsync.java
interface.

Last, we need to create the server-side implementation of our
client-side RemoteService interface. Our service implementation is just
going to be a plain old Java object (POJO), though again you could use
many different techniques at this point. This code for
HelloServiceImpl.java is shown in listing 4.

Note that even though we created two client-side interfaces, one
synchronous and one asynchronous, GWT doesn't support synchronous
communications with your client application. You'll never use the
synchronous one. The reason for this is browser-related, and technical,
and you might be familiar with it if you have done Ajax work in the
past. The XMLHttpRequest object is asynchronous; however, the
JavaScript interpreter in many browsers is a single execution thread.
This means that if you tried to send a request and "spin" while
waiting for the callback event to execute, you'd spin forever. The
callback event wouldn't fire while the JavaScript interpreter was
spinning.

Now we have three classes, but we're not quite
done yet. The final piece is our RemoteServiceServlet implementation.
This is the actual servlet that the web application exposes, and with
which the client-side classes communicate. Listing 5 shows the code for
our service servlet, HelloServlet.java.

This completes our service: two simple interfaces on the client, one
implementation class on the server, and a service servlet to host and
invoke the server-side implementation. Now that we have a basic
service, we'll explore the options available from the
RemoteServiceServlet class.

Expanding on RemoteServiceServlet

While
we're wrapping our implementation, there are certain features provided
by the servlet specification we might want. Indeed, we might want to do
a lot of things to a request before it goes to the actual service
implementation. The RemoteServiceServlet includes several methods you
can call from within your servlet to access these features. The
important ones are outlined in table 3.

Table 3 Selected methods of the RemoteServiceServlet

Method

Function

getThreadLocalRequest()

Called
from a service method to get the HttpServletRequest, and HttpSession
objects. It can be used for server-side state with session or
customizing responses.

getThreadLocalResponse()

Called
from a service method to get the HttpServletResponse object. It can be
used to customize the response, such as for setting custom headers.

onBeforeRequestDeserialized(String)

Called before the request objects are deserialized, with the serialization payload as an argument.

onAfterResponseSerialized(String)

Called before the response serialized object is returned to the client, with the serialized payload as an argument.

Called
to determine whether Gzip compression should be used on the response.
The default behavior is true if the client accepts it and the response
is greater than 256 bytes.

processCall(String)

Called to deserialize incoming payloads, call the appropriate service method, and return a string response payload.

The
most important of the methods in table 3 are the two ThreadLocal
methods, which let you access the session state. For instance, if you
were proxying the calls into the RPC service to a SOAP service, you
could check the session and authenticate the user with the SOAP service
on the first call, using the user information available in the
HttpServletRequest object. From there, you could store the connect stub
for the user in the Session object, giving each user their own instance
of the actual business object.

NOTE

We're
skipping over service security in general, for the sake of simplicity.
However, it should be kept in mind the old saw, "never trust the
client," still applies.

You might not need
the other methods listed in table 3 often, but they can be useful. It's
important to remember that the Google serialization classes are
available to you in your application in the form of the
com.google.gwt.user.server.rpc.impl.ServerSerializationStreamReader and
ServerSerializationStreamWriter. If, for instance, you wish to change
the service state based on information contained in the client request,
you can overload the methods in table 3 and inspect the message to the
server beforehand. Unfortunately these methods don't provide you with
the option to filter or modify the serialization payload. To do that,
you'd need to overload the entire processCall() method and then make
your changes before invoking the superclass method. All of this takes
place on the server, but we also want to make calls from the client.

Calling the server from the client

In
order to invoke our RPC services on the client, we need to get the
asynchronous service interface from the static GWT.create() method,
bind it to a relative URL for our HelloServlet, create a callback
handler, and make our call. Listing 6 demonstrates this directly within
the EntryPoint class, HelloServer. This class, now in our Eclipse
project, was initially created by the ApplicationCreator utility. We
have entirely replaced what was in the default HelloServer.java file
with our code here. (For the purposes of this example, we're doing
things directly in the entry point. We're not trying to develop with
reuse in mind.)

Our HelloServer entry point is intended to wire together our example
with UI and event handling. Within it, we create an AsyncCallback
object to handle the return values from our service . (This could also
have been done anonymously.) Then we use the static GWT.create() method
to obtain a runtime reference to our service , and implement a
ClickListener to connect the click on Button with the sayHello()
service call.

The final step we need to complete is to set up
our module file, HelloServer.gwt.xml, with our servlet mapped to
/HelloService. If we take a look at the existing HelloServer.gwt.xml
file created by ApplicationCreator, we can see a single element and a single class element. We need to add to that a element to represent our service, as shown in listing 7.

We now have a complete, working GWT application that makes a call
back to the server! While our example is not visually impressive, you
should now be familiar with all the moving parts involved in making an
asynchronous invocation to server-side code.

To run this
example in hosted mode, you can simply invoke GWTShell via the
HelloServer-shell shortcut script. (This script was either created when
you manually ran ApplicationCreator, if you have been following along
and building the project, or is provided with the code for this example
on the Manning web site.) When you run the example, the client will
call the server, and, under the hood, Java objects are being converted
to the GWT wire format and passed into JavaScript. Figure 4 provides a
visual overview of the entire RPC process: from the user to the client
service interface, across the wire into the remote service servlet, and
then to the service implementation and then back again.

Figure 4 An overview of the complete RPC process. Notice that the
user's browser lifeline is freed while the service call is executed;
it's monopolized again as the call is returned.

Figure 5
shows an example request in hexadecimal format so that you can see the
special characters used during a service call invocation. While it's
not important for you to have a complete understanding of the
hexadecimal values, this demonstrates an important point about the
operation of the compiler in relation to the server.

Figure 5 A GWT RPC request in hexadecimal format. Notice that the
type information is passed for deserialization on the server, along
with the attribute values.

As you can see in figure 5, the
class name is the important information used in the transfer and it's
followed by the properties and a sequence to identify which values
belong to which property. In GWT (and unlike JSON) property names on
objects can change from compilation to compilation, but the GWT client
will always know the Java class name of the object. Now for the
response:

{OK}[1,["Hello John Doe. How is the weather at Anytown, NA, 5555"],0,2]

First, we have the response code of the call to the server, followed
by our single return value. Since we're returning a simple string
value, it's returned in the native JavaScript form. Once values are
returned, they will frequently update the model level of your Ajax
application.

Troubleshooting server communication

If
you begin getting errors in the form of "Deferred binding result type
'module.client.MyService' is not instantiable" when you start creating
GWT RPC services, try the following. First, turn your -logLevel option
up on the shell logging console to provide additional clues as to what
went wrong. Then, run through this checklist:

Make sure you're casting your call to GWT.create() to MyServiceAsync and not MyService.

Make sure your MyService interface extends RemoteService.

Make sure your return types and arguments all implement IsSerializable or Serializable.

Make sure the classes used as return types and arguments all have no-args constructors.

Make sure the return types on methods in your MyServiceAsync class are all void.

In
addition to the plumbing of GWT server communications and issues with
regard to naming and types, you may also be curious about handling
synchronization and multiple outstanding callbacks. Developers familiar
with the issues surrounding asynchronous, message-based programming
will possibly look at the asynchronous nature of Ajax messaging and
overthink the issues of synchronization at the model level in their GWT
applications.

One important thing to remember is that all
JavaScript on a page is executed within the scope of a single thread.
This means that while you might have multiple outstanding callbacks
waiting for invocation, only one will be called at a time. Unlike
invoking web services via the Java API for XML Web Services (JAX-WS)
from a Swing application, there is no need to shift UI changes from the
thread invoking the callback to the painting thread, since all
JavaScript is executed on the painting thread. To borrow an analogy
from Brian Glick
(http://www.jroller.com/hifi78/entry/gwt_single_threaded_javascript_multi):

With
the single threaded browser environment, I think about a colony of
bees. (WARNING: Extremely strained metaphor coming!) The queen bee (the
application) can tell the worker bees (XMLHttpRequest), "Go get me
food." However, when the bees return, only one can give the food to
the queen at a time. The rest have to sit in line and wait. From the
bee keeper's standpoint, the environment is multi-threaded. All of
these bees are swarming around at the same time. However, we need to
look at it from the perspective of the queen, who only has to deal with
one worker bee at a time.

That is to say, the
problems usually associated with multithreaded programming in Java
don't apply. Your Java will always execute in a single thread.
You'll never have multiple callbacks executing on the client at the
same time. Attributes will never be modified outside of the current
call stack. In opposition to the standard Servlet API, your client-side
GWT code will be single threaded across all the instances you create in
the code; it will be fundamentally static. There is no Swing
event-dispatching thread. There are no daemon timers. There is a single
execution thread that all code will run in, no matter the callback
order.