com.gwtplatform.dispatch.rest.delegates.client.ResourceDelegate Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of dispatch-rest-delegates Show documentation
Allow Rest-Dispatch resources to return their raw result type directly.
The newest version!
/**
 * Copyright 2014 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.rest.delegates.client;

import com.google.gwt.user.client.rpc.AsyncCallback;
import com.gwtplatform.dispatch.client.DelegatingDispatchRequest;
import com.gwtplatform.dispatch.shared.DispatchRequest;

/**
 * Delegate used to build and call HTTP resources. You can inject this interface instead of injecting your resource
 * interface and {@link com.gwtplatform.dispatch.rest.client.RestDispatch} to simplify your code. Note that if your
 * resource interfaces don't return {@link com.gwtplatform.dispatch.rest.shared.RestAction RestAction<?>}s but the
 * result type directly, you will need to inject a {@link ResourceDelegate} to use your resource.
 * 
 * This delegate will not send the HTTP request until you call a method, that is not a sub-resource, from the underlying
 * resource. The underlying resource is returned when either {@link #withoutCallback()} or {@link
 * #withCallback(AsyncCallback)} are called.
 * 

 * The following example shows how to retrieve the {@link DispatchRequest} and delete a potential car:
 * 

 * {@literal @}Path("/cars")
 * public interface CarsResource {
 *      CarResource car(int id);
 * }
 * 
 * public interface CarResource {
 *      {@literal @}DELETE
 *      void delete();
 * }
 * 

 * public class CarPresenter {
 *     private final ResourceDelegate<CarsResource> carsResourceDelegate;
 * 

 *     {@literal @}Inject
 *     CarPresenter(ResourceDelegate<CarsResource> carsResourceDelegate) {
 *         this.carsResourceDelegate = carsResourceDelegate;
 *     }
 * 

 *     {@literal @}Override
 *     public void onReveal() {
 *         DelegatingDispatchRequest dispatchRequest = new DelegatingDispatchRequest();
 * 
 *         carsResourceDelegate
 *                 .withDelegatingDispatchRequest(dispatchRequest)
 *                 .withCallback(new AsyncCallback<Void>() {/{@literal * snip *}/});
 *                 .car(8)
 *                 .delete();
 *     }
 * }
 * 
 *
 * @param  The type of the resource used by this delegate.
 */
public interface ResourceDelegate {
    /**
     * Used as a mean to access the {@link DispatchRequest} instance returned by the underlying HTTP call. This may be
     * useful for canceling a long running call. {@code delegatingDispatchRequest} will be populated when the HTTP call
     * is sent, that is when you call any method from the service used by this delegate.
     *
     * @param delegatingDispatchRequest the {@link DelegatingDispatchRequest} to populate when the HTTP call is sent.
     *
     * @return a copy of this {@link ResourceDelegate} using the provided {@link DelegatingDispatchRequest}.
     */
    ResourceDelegate withDelegatingDispatchRequest(DelegatingDispatchRequest delegatingDispatchRequest);

    /**
     * Provide the callback when the HTTP call returns or if any error occur.
     *
     * @param callback The callback to use when the HTTP call returns or if any error occur.
     *
     * @return the service wrapped by this delegate.
     */
    T withCallback(AsyncCallback callback);

    /**
     * This method is the same as colling {@link #withCallback(AsyncCallback)} with a no-op callback.
     */
    T withoutCallback();

    /**
     * Retrieves the pure resource.
     */
    T getResource();
}