com.gwtplatform.dispatch.client.actionhandler.ClientActionHandler Maven / Gradle / Ivy
/**
* Copyright 2011 ArcBees Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not
* use this file except in compliance with the License. You may obtain a copy of
* the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations under
* the License.
*/
package com.gwtplatform.dispatch.client.actionhandler;
import com.google.gwt.user.client.rpc.AsyncCallback;
import com.gwtplatform.dispatch.shared.Action;
import com.gwtplatform.dispatch.shared.DispatchRequest;
import com.gwtplatform.dispatch.shared.Result;
/**
* Instances of this interface will handle specific types of {@link Action}
* classes on the client.
*
* When a command is executed (or undone), the {@link ClientActionHandler} that
* has been registered with the bound {@link ClientActionHandlerRegistry} is
* called and {@link com.gwtplatform.dispatch.shared.DispatchAsync DispatchAsync} does
* not automatically send the command over gwt-rpc to the server.
*
* Client Action Handlers provide a number of flexible options:
*
* - The action can be modified before sending the action over gwt-rpc 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 {@link ClientActionHandler} can take over and communicate directly
* with the server, possibly using a different mechanism than gwt-rpc.
*
*
*
* 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 extends Result> R get(A action);
* <A extends Action<R>, R extends Result> void put(A action, R result);
* }
*
* // Client action handler that injects the cache
* public class RetrieveFooClientActionHandler
* extends
* AbstractCachingClientActionHandler<RetrieveFooAction, RetrieveFooResult> {
* {@literal}@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 using gwt-rpc
* // - saves result to cache before returning it
* public abstract class AbstractCachingClientActionHandler<A extends Action<R>, R extends Result>
* extends AbstractClientActionHandler<A, R> {
*
* private final Cache cache;
*
* public AbstractCachingClientActionHandler(
* Class<A> actionType, Cache cache) {
*
* super(actionType);
* this.cache = cache;
* }
*
* {@literal}@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>() {
* {@literal}@Override
* public void onSuccess(R result) {
* if(!request.isCancelled()) {
* cache.put(action, result);
* resultCallback.onSuccess(result);
* }
* }
*
* {@literal}@Override
* public void onFailure(Throwable caught) {
* resultCallback.onFailure(caught);
* }
* });
* }
* }
*
* {@literal}@Override
* public DispatchRequest undo(A action, R result, AsyncCallback<Void> callback,
* ClientDispatchRequest request, UndoCommand<A, R> undoCommand) {
* // do nothing
* return new CompletedDispatchRequest();
* }
* }
*
*
*
* @param The type of the action extending {@link Action}.
* @param The type of the result extending {@link Result}.
* @author Brendan Doherty
*/
public interface ClientActionHandler, R extends Result> {
/**
* 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
* {@link DelegatingDispatchRequest#isCancelled()} against the request
* parameter.
*
* @param action The {@link Action} to execute.
* @param resultCallback The callback to use to communicate the result of the
* action. Unless the request is cancelled, you must invoke
* {@link AsyncCallback#onSuccess} on this callback once you have
* obtained the result. If any failure occurs call
* {@link AsyncCallback#onFailure}.
* @param executeCommand Call {@link ExecuteCommand#execute(Action, 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 {@code resultCallback} or your custom
* {@link AsyncCallback} if you want to process the result.
* @return A {@link DispatchRequest} object. Never return {@code null},
* instead return a new {@link com.gwtplatform.dispatch.client.CompletedDispatchRequest
* CompletedDispatchRequest}
* if you executed, cancelled or ignored the action.
*/
DispatchRequest execute(A action, AsyncCallback resultCallback,
ExecuteCommand executeCommand);
/**
* @return The type of {@link Action} supported by this handler.
*/
Class getActionType();
/**
* Undoes 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
* {@link DelegatingDispatchRequest#isCancelled()} against the request
* parameter.
*
* @param action The {@link Action} to undo.
* @param result The {@link Result} to undo.
* @param callback The callback to use to indicate when the action has been
* undone. Unless the request is cancelled, you must invoke
* {@link AsyncCallback#onSuccess} on this callback when you have
* successfully undone the action. If any failure occurs call
* {@link AsyncCallback#onFailure}.
* @param undoCommand Call {@link UndoCommand#undo(Action, Result, 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 {@code callback} or your custom
* {@link AsyncCallback} if you want to perform any processing
* following the undo.
* @return A {@link DispatchRequest} object. Never return {@code null},
* instead return a new {@link com.gwtplatform.dispatch.client.CompletedDispatchRequest
* CompletedDispatchRequest}
* if you executed, cancelled or ignored the action.
*/
DispatchRequest undo(A action, R result, AsyncCallback callback,
UndoCommand undoCommand);
}