#summary A short introduction to the GWT Dispatch API.
#labels Featured

= Introduction =

This is a quick walkthrough of configuring the GWT Dispatch library and creating your own Action/Result/Handler.

*Note:* This example uses Google Guice and GIN for configuration.

= 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 extension of the `ActionHandlerModule` class and register our handlers:

{{{
public class CounterModule extends ActionHandlerModule {
    @Override
    public void configureHandlers() {
        bindHandler( IncrementCounter.class, IncrementCounterHandler.class );
    }
}
}}}

Then, you wire that up to Guice in the usual way. You will now have an instance of 'Dispatch' configured and ready to go.

Next, we need to publish the service to the client side. As such, we need to set up a servlet to handle RPC calls and pass them to our Dispatch. I recommend using the Guice Servlet extension library to do this, but you can do it any way you like.

{{{
public class DispatchServletModule extends ServletModule {
    @Override
    public void configureServlets() {
        serve( "/path/to/dispatch" ).with( DispatchServiceServlet.class );
    }
}
}}}

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' />
}}}

Next, you need to initialise an instance of `DispatchAsync` on the client side. If you're using GIN, you can just hook in the `ClientDispatchModule` into your `Ginjector` class as a regular module. This will wire up `DispatchAsync` to the `DefaultDispatchAsync` implementation. Otherwise, just create a new instance of `DefaultDispatchAsync` somewhere globally accessible.

Now, from your GWT client side code, just inject your `DispatchAsync` instance and do something the following (a button click triggers the increment):

{{{
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() );
            }

        } );
    }
});
}}}