GettingStarted

Summary

A short introduction to the GWT Dispatch API.

Introduction

This is a quick walkthrough of configuring the GWT Dispatch library and creating your own Action/Result/Handler. The code for this project is available at the gwt-dispatch-sample Github page.

Details

This example is going to create a simple counter on the server. For simplicity, it will store it in memory.

Firstly, we'll create an IncrementCounter action.

public class IncrementCounter implements Action<IncrementCounterResult> {
    private int amount;

    /** For serialization only. */
    IncrementCounter() {
    }
 
    public IncrementCounter( int amount ) {
        this.amount = amount;
    }

    public int getAmount() {
        return amount;
    }
}

Next, we define the IncrementCounterResult, which will also return the current counter value.

public class IncrementCounterResult implements Result {
    private int amount;
    private int current;

    /** For serialization only. */
    IncrementCounterResult() {
    }

    public IncrementCounterResult( int amount, int current ) {
        this.amount = amount;
        this.current = current;
    }

    public int getAmount() {
        return amount;
    }

    public int getCurrent() {
        return current;
    }
}

Lastly, we define our IncrementCounterHandler class, which does the actual incrementing.

public class IncrementCounterHandler implements ActionHandler<IncrementCounter, IncrementCounterResult> {

    private int current = 0;

    public Class<IncrementCounter> getActionType() {
        return IncrementCounter.class;
    }

    public synchronized IncrementCounterResult execute( IncrementCounter action, ExecutionContext context ) throws ActionException {
        current += action.getAmount();
        return new IncrementCounterResult( action.getAmount(), current );
    }

    public synchronized void rollback( IncrementCounter action, IncrementCounterResult result, ExecutionContext context ) throws ActionException {
        // Reset to the previous value.
        current = result.getCurrent() - result.getAmount();
    }
}

Now, we have to hook up our action handler to the Dispatch service on the server side.

Firstly, we create an implementation of the StandardDispatchService, which is GWT-dispatch's entry point for executing actions:

public class SimpleDispatchServlet extends RemoteServiceServlet implements StandardDispatchService {

    private Dispatch dispatch;

    public SimpleDispatchServlet() {

        InstanceActionHandlerRegistry registry = new DefaultActionHandlerRegistry();
        registry.addHandler(new IncrementCounterHandler());
        dispatch = new SimpleDispatch(registry);
    }

    public Result execute(Action<?> action) throws DispatchException {

        try {
            return dispatch.execute(action);
        } catch ( RuntimeException e) {
            log( "Exception while executing " + action.getClass().getName() + ": " + e.getMessage(), e );
            throw e;
        }
    }
}

The SimpleDispatchService is in itself a GWT Remote Service, so it extends RemoteServiceServlet. It holds an ActionHandlerRegistry, which is used to route Actions to ActionHandlers. The execute implementation is trivial, since the Dispatch object does all of the hard work.

Now, on the client-side, we first need to import the library into our *.gwt.xml file. Just add this:

<inherits name='net.customware.gwt.dispatch.Dispatch' />

When you will first compile, the GWT compiler will output errors regarding com.google.gwt.inject and com.google.inject imports not being resolved. These can be safely ignored, as these classes are not referenced in our example.

Next, you need to initialise an instance of DispatchAsync on the client side. The simplest way of doing this is to create an instance of StandardDispatchAsync:

private final DispatchAsync dispatchAsync = new StandardDispatchAsync(new DefaultExceptionHandler());

Now, from your GWT client side code, use the dispatchAsync instance to execution Actions and handle Results.

myButton.addClickHandler( new ClickHandler() {
    public void onClick( ClickEvent evt ) {
        dispatchAsync.execute( new IncrementCounter( 1 ), new AsyncCallback<IncrementCounterResult>() {
            public void onFailure( Throwable e ) {
                Window.alert( "Error: " + e.getMessage() );
            }
            
            public void onSuccess( IncrementCounterResult result ) {
                Window.alert( "Incremented by " + result.getAmount() + ", new total is " + result.getCurrent() );
            }
        } );
    }
});

Server-sided integration

GWT-dispatch features rich integration with both Guice and Spring on the server side. Please see the manual configuration, Guice or Spring sections for details.