Geomajas common-gwt plug-in guide

Geomajas makes use of GWT RPC, which is a mechanism for passing Java objects to and from a server over standard HTTP. GWT RPC allows the client to call a server-based service through an automatically generated proxy class. Synchronous or asynchronous calls can be made to the server through a very efficient protocol on top of HTTP. The service endpoint is defined by configuring a standard servlet mapping or an MVC controller, which is more in line with Spring MVC practices.

Because the GWT module name is the first part of the service endpoint URL, the MVC controller should also be mapped to this module name. This requires the following addition to the web.xml file:

<servlet-mapping>
  <servlet-name>dispatcher</servlet-name>
  <url-pattern>/d/*</url-pattern>
  <url-pattern>/<GWT module name>/*</url-pattern> <!-- add this line -->
</servlet-mapping>

This is all that is necessary to enable the communication and should work for all GWT faces. This will also establish a fallback resource controller that ensures that static resources can be successfully retrieved through the dispatcher servlet. This is necessary because the above mapping will catch any request that has the module name as the first part in its path.

The command dispatcher allows you to communicate to the server using the Geomajas command interface with the Geomajas built-in support for security and localization. Using the GwtCommandDispatcher class, you can send your request objects to the server and process the response.

A simple invocation looks like this:

        MySuperDoItRequest commandRequest = new MySuperDoItRequest();
        // .... add parameters to the request.

        // Create the command, with the correct Spring bean name:
        GwtCommand command = new GwtCommand(MySuperDoItRequest.COMMAND);
        command.setCommandRequest(commandRequest);

        // Execute the command, and do something with the response:
        GwtCommandDispatcher.getInstance().execute(command, new AbstractCommandCallback<MySuperDoItResponse>() {

            public void execute(MySuperDoItResponse response) {
                // Command returned successfully. Do something with the result.
            }
        });

The security will be handled automatically by the command dispatcher.

You can register a token request handler which is invoked when the command returns with an invalid token exception (or any security exception when the token is null). Once the new token is available, the command will be retried.

There are events on the dispatcher for changes in token. You can register a handler for them.

There are also events to indicate when a command is in process or not.

The dispatcher includes methods to request details about the current token and the logged i user.

This module also provides definitions for event controllers on the map. A controller is meant to catch mouse or touch events and react upon them. Together with the controller interface, an AbstractController class is provided as a more suitable base to start working from. Still, each face has extended this base controller interface with it's own methods (for activation and deactivation for example). Each face also has an abstract controller class to be used as a base to implement your own controllers.

There is a special service for getting the client configuration from the server. This is the ClientConfigurationService class. It serves as a central access point for your application configuration and limits the number of request for configuration information to the server.

It is specifically built to be extensible. You con define how the application configuration is obtained from the server. This allows you to replace the invocation of the GetConfiguration command by something which also contains application specific information. Have a look at the staticsecurity example application for an example how this can be used.

Several utility classes have been provided.