com.gwtplatform.dispatch.client.actionhandler

Interface ClientActionHandler<A,R>

Type Parameters:

A - The type of the action.

R - The type of the result.

All Known Implementing Classes:

AbstractCachingClientActionHandler, AbstractClientActionHandler, ActionCachingHandler

public interface ClientActionHandler<A,R>

Instances of this interface will handle specific types of action classes on the client.

When a call is executed, the ClientActionHandler that has been registered with the bound ClientActionHandlerRegistry is called and DispatchAsync or RestDispatch does not automatically send the command over HTTP to the server.

Client Action Handlers provide a number of flexible options:

• The action can be modified before sending the action to the server.
• A result can be returned without contacting the server.
• The result can be modified or processed after it is returned from the server.
• The ClientActionHandler can take over and communicate directly with the server, possibly using a different mechanism.

Important! If your action handler makes asynchronous calls, be careful with your use of fields as a second call your handler could be made while it is waiting for the asynchronous call to return.

Caching Client Action Handler Example

 
 // Interface of cache singleton
 public interface Cache {
   <A extends Action<R>, R> R get(A action);
   <A extends Action<R>, R> void put(A action, R result);
 }

 // Client action handler that injects the cache
 public class RetrieveFooClientActionHandler
     extends AbstractCachingClientActionHandler<RetrieveFooAction, RetrieveFooResult> {
   @Inject
   RetrieveFooClientActionHandler(Cache cache) {
     super(RetrieveFooAction.class, cache);
   }
 }

 // abstract client action handler that:
 // - first checks cache and returns result immediately if found in cache
 // - executes command on server
 // - saves result to cache before returning it
 public abstract class AbstractCachingClientActionHandler<A extends Action<R>, R>
     extends AbstractClientActionHandler<A, R> {

   private final Cache cache;

   public AbstractCachingClientActionHandler(Class<A> actionType, Cache cache) {
     super(actionType);
     this.cache = cache;
   }

   @Override
   public DispatchRequest execute(final A action, final AsyncCallback<R> resultCallback,
       ExecuteCommand<A, R> executeCommand) {
     R cacheResult = cache.get(action);
     if (cacheResult != null) {
       resultCallback.onSuccess(cacheResult);
       return new CompletedDispatchRequest();
     } else {
       return executeCommand.execute(action, new AsyncCallback<R>() {
         @Override
         public void onSuccess(R result) {
           if(!request.isCancelled()) {
             cache.put(action, result);
             resultCallback.onSuccess(result);
           }
         }

         @Override
         public void onFailure(Throwable caught) {
           resultCallback.onFailure(caught);
         }
       });
     }
   }
 }
 
 

Method Summary

Methods

Modifier and Type	Method and Description
DispatchRequest	execute(A action, AsyncCallback<R> resultCallback, ExecuteCommand<A,R> executeCommand) Handles the specified action.
Class<A>	getActionType()
DispatchRequest	undo(A action, R result, AsyncCallback<Void> callback, UndoCommand<A,R> undoCommand) Undoes the specified action if supported.

Method Detail

execute

DispatchRequest execute(A action,
                      AsyncCallback<R> resultCallback,
                      ExecuteCommand<A,R> executeCommand)

Handles the specified action.

If the handler makes asynchronous calls, it is recommended that you confirm that this request has not been cancelled after returning by calling com.gwtplatform.dispatch.client.DelegatingDispatchRequest#isCancelled() against the request parameter.

Parameters:

action - The action to execute.

resultCallback - The callback to use to communicate the result of the action. Unless the request is cancelled, you must invoke AsyncCallback.onSuccess(T) on this callback once you have obtained the result. If any failure occurs call AsyncCallback.onFailure(java.lang.Throwable).

executeCommand - Call ExecuteCommand.execute(Object, com.google.gwt.user.client.rpc.AsyncCallback) on this object to send the action over to the server. As a parameter you can pass resultCallback or your custom AsyncCallback if you want to process the result.

Returns:

A DispatchRequest object. Never return null, instead return a new CompletedDispatchRequest if you executed, cancelled or ignored the action.

undo

DispatchRequest undo(A action,
                   R result,
                   AsyncCallback<Void> callback,
                   UndoCommand<A,R> undoCommand)

Undoes the specified action if supported.

If the handler makes asynchronous calls, it is recommended that you confirm that this request has not been cancelled after returning by calling com.gwtplatform.dispatch.client.DelegatingDispatchRequest#isCancelled() against the request parameter.

Parameters:

action - The action to undo.

result - The result to undo.

callback - The callback to use to indicate when the action has been undone. Unless the request is cancelled, you must invoke AsyncCallback.onSuccess(T) on this callback when you have successfully undone the action. If any failure occurs call AsyncCallback.onFailure(java.lang.Throwable).

undoCommand - Call UndoCommand.undo(Object, Object, com.google.gwt.user.client.rpc.AsyncCallback) on this object to send the action over to the server via gwt-rpc. As a parameter you can pass callback or your custom AsyncCallback if you want to perform any processing following the undo.

Returns:

A DispatchRequest object. Never return null, instead return a new CompletedDispatchRequest if you executed, cancelled or ignored the action.

getActionType

Class<A> getActionType()

Returns:

The type of action supported by this handler.