2.4/user/src/com/google/gwt/user/client/rpc/impl/RemoteServiceProxy.java

/*
 * Copyright 2008 Google 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.google.gwt.user.client.rpc.impl;

import com.google.gwt.core.client.JavaScriptObject;
import com.google.gwt.http.client.Request;
import com.google.gwt.http.client.RequestBuilder;
import com.google.gwt.http.client.RequestCallback;
import com.google.gwt.http.client.RequestException;
import com.google.gwt.user.client.rpc.AsyncCallback;
import com.google.gwt.user.client.rpc.HasRpcToken;
import com.google.gwt.user.client.rpc.InvocationException;
import com.google.gwt.user.client.rpc.RpcRequestBuilder;
import com.google.gwt.user.client.rpc.RpcToken;
import com.google.gwt.user.client.rpc.RpcTokenExceptionHandler;
import com.google.gwt.user.client.rpc.SerializationException;
import com.google.gwt.user.client.rpc.SerializationStreamFactory;
import com.google.gwt.user.client.rpc.SerializationStreamReader;
import com.google.gwt.user.client.rpc.SerializationStreamWriter;
import com.google.gwt.user.client.rpc.ServiceDefTarget;
import com.google.gwt.user.client.rpc.impl.RequestCallbackAdapter.ResponseReader;

/**
 * Superclass for client-side
 * {@link com.google.gwt.user.client.rpc.RemoteService RemoteService} proxies.
 *
 * For internal use only.
 */
public abstract class RemoteServiceProxy implements SerializationStreamFactory,
    ServiceDefTarget, HasRpcToken {

  /**
   * The content type to be used in HTTP requests.
   */
  private static final String RPC_CONTENT_TYPE = "text/x-gwt-rpc; charset=utf-8";

  /**
   * A helper class that prepares the service to serialize data.
   */
  public class ServiceHelper {

    private final String fullServiceName;
    private final String methodName;
    private final RpcStatsContext statsContext;
    private SerializationStreamWriter streamWriter;

    public ServiceHelper(String serviceName, String methodName) {
      this.fullServiceName = serviceName + "." + methodName;
      this.methodName = methodName;
      this.statsContext = new RpcStatsContext();
    }

    /**
     * Finishes the serialization.
     */
    public Request finish(AsyncCallback callback, ResponseReader responseHeader)
        throws SerializationException {
      String payload = streamWriter.toString();
      boolean toss = statsContext.isStatsAvailable()
          && statsContext.stats(statsContext.timeStat(fullServiceName,  "requestSerialized"));
      return doInvoke(responseHeader, fullServiceName, statsContext, payload, callback);
    }

    /**
     * Finishes the serialization and return a RequestBuilder.
     */
    public RequestBuilder finishForRequestBuilder(AsyncCallback callback,
        ResponseReader responseHeader) throws SerializationException {
      String payload = streamWriter.toString();
      boolean toss = statsContext.isStatsAvailable()
          && statsContext.stats(statsContext.timeStat(fullServiceName,  "requestSerialized"));
      return doPrepareRequestBuilder(
          responseHeader, fullServiceName, statsContext, payload, callback);
    }

    /**
     * Starts the serialization.
     */
    public SerializationStreamWriter start(String remoteServiceInterfaceName,
        int paramCount) throws SerializationException {
      boolean toss = statsContext.isStatsAvailable()
          && statsContext.stats(statsContext.timeStat(fullServiceName, "begin"));
      streamWriter = createStreamWriter();
      if (getRpcToken() != null) {
        streamWriter.writeObject(getRpcToken());
      }
      streamWriter.writeString(remoteServiceInterfaceName);
      streamWriter.writeString(methodName);
      streamWriter.writeInt(paramCount);
      return streamWriter;
    }
  }

  /**
   * @deprecated use {@link RpcStatsContext}.
   */
  @Deprecated
  public static JavaScriptObject bytesStat(String method, int count,
      int bytes, String eventType) {
    return new RpcStatsContext(count).bytesStat(method, bytes, eventType);
  }

  /**
   * Indicates if RPC statistics should be gathered.
   *
   * @deprecated use {@link RpcStatsContext}.
   */
  @Deprecated
  public static boolean isStatsAvailable() {
    return new RpcStatsContext(0).isStatsAvailable();
  }

  /**
   * Always use this as {@link #isStatsAvailable()} &&
   * {@link #stats(JavaScriptObject)}.
   *
   * @deprecated use {@link RpcStatsContext}.
   */
  @Deprecated
  public static boolean stats(JavaScriptObject data) {
    return new RpcStatsContext(0).stats(data);
  }

  /**
   * @deprecated use {@link RpcStatsContext}.
   */
  @Deprecated
  public static JavaScriptObject timeStat(String method, int count,
      String eventType) {
    return new RpcStatsContext(count).timeStat(method, eventType);
  }

  /**
   * @deprected use {@link RpcStatsContext}.
   */
  @Deprecated
  protected static int getNextRequestId() {
    return RpcStatsContext.getNextRequestId();
  }

  /**
   * @deprecated Use {@link RpcRequestBuilder} instead.
   */
  @Deprecated
  protected static int getRequestId() {
    return RpcStatsContext.getLastRequestId();
  }

  /**
   * Return <code>true</code> if the encoded response contains a value returned
   * by the method invocation.
   *
   * @param encodedResponse
   * @return <code>true</code> if the encoded response contains a value returned
   *         by the method invocation
   */
  static boolean isReturnValue(String encodedResponse) {
    return encodedResponse.startsWith("//OK");
  }

  /**
   * Return <code>true</code> if the encoded response contains a checked
   * exception that was thrown by the method invocation.
   *
   * @param encodedResponse
   * @return <code>true</code> if the encoded response contains a checked
   *         exception that was thrown by the method invocation
   */
  static boolean isThrownException(String encodedResponse) {
    return encodedResponse.startsWith("//EX");
  }

  /**
   * Returns a string that encodes the result of a method invocation.
   * Effectively, this just removes any headers from the encoded response.
   *
   * @param encodedResponse
   * @return string that encodes the result of a method invocation
   */
  private static String getEncodedInstance(String encodedResponse) {
    if (isReturnValue(encodedResponse) || isThrownException(encodedResponse)) {
      return encodedResponse.substring(4);
    }

    return encodedResponse;
  }

  /**
   * The module base URL as specified during construction.
   */
  private final String moduleBaseURL;

  /**
   * URL of the {@link com.google.gwt.user.client.rpc.RemoteService
   * RemoteService}.
   */
  private String remoteServiceURL;

  private RpcRequestBuilder rpcRequestBuilder;

  private RpcToken rpcToken;

  private RpcTokenExceptionHandler rpcTokenExceptionHandler;

  /**
   * The name of the serialization policy file specified during construction.
   */
  private final String serializationPolicyName;

  /**
   * The {@link Serializer} instance used to serialize and deserialize
   * instances.
   */
  private final Serializer serializer;

  protected RemoteServiceProxy(String moduleBaseURL,
      String remoteServiceRelativePath, String serializationPolicyName,
      Serializer serializer) {
    this.moduleBaseURL = moduleBaseURL;
    if (remoteServiceRelativePath != null) {
      /*
       * If the module relative URL is not null we set the remote service URL to
       * be the module base URL plus the module relative remote service URL.
       * Otherwise an explicit call to
       * ServiceDefTarget.setServiceEntryPoint(String) is required.
       */
      this.remoteServiceURL = moduleBaseURL + remoteServiceRelativePath;
    }
    this.serializer = serializer;
    this.serializationPolicyName = serializationPolicyName;
  }

  /**
   * Returns a {@link com.google.gwt.user.client.rpc.SerializationStreamReader
   * SerializationStreamReader} that is ready for reading.
   *
   * @param encoded string that encodes the response of an RPC request
   * @return {@link com.google.gwt.user.client.rpc.SerializationStreamReader
   *         SerializationStreamReader} that is ready for reading
   * @throws SerializationException
   */
  public SerializationStreamReader createStreamReader(String encoded)
      throws SerializationException {
    ClientSerializationStreamReader clientSerializationStreamReader = new ClientSerializationStreamReader(
        serializer);
    clientSerializationStreamReader.prepareToRead(getEncodedInstance(encoded));
    return clientSerializationStreamReader;
  }

  /**
   * Returns a {@link com.google.gwt.user.client.rpc.SerializationStreamWriter
   * SerializationStreamWriter} that has had
   * {@link ClientSerializationStreamWriter#prepareToWrite()} called on it and
   * it has already had had the name of the remote service interface written as
   * well.
   *
   * @return {@link com.google.gwt.user.client.rpc.SerializationStreamWriter
   *         SerializationStreamWriter} that has had
   *         {@link ClientSerializationStreamWriter#prepareToWrite()} called on
   *         it and it has already had had the name of the remote service
   *         interface written as well
   */
  public SerializationStreamWriter createStreamWriter() {
    ClientSerializationStreamWriter clientSerializationStreamWriter = new ClientSerializationStreamWriter(
        serializer, moduleBaseURL, serializationPolicyName);
    clientSerializationStreamWriter.prepareToWrite();
    return clientSerializationStreamWriter;
  }

  /**
   * @see HasRpcToken#getRpcToken()
   */
  public RpcToken getRpcToken() {
    return rpcToken;
  }

  /**
   * @see HasRpcToken#getRpcTokenExceptionHandler()
   */
  public RpcTokenExceptionHandler getRpcTokenExceptionHandler() {
    return rpcTokenExceptionHandler;
  }

  public String getSerializationPolicyName() {
    return serializationPolicyName;
  }

  /**
   * @see ServiceDefTarget#getServiceEntryPoint()
   */
  public String getServiceEntryPoint() {
    return remoteServiceURL;
  }

  public void setRpcRequestBuilder(RpcRequestBuilder builder) {
    this.rpcRequestBuilder = builder;
  }

  /**
   * @see HasRpcToken#setRpcToken(RpcToken)
   */
  public void setRpcToken(RpcToken token) {
    checkRpcTokenType(token);
    this.rpcToken = token;
  }

  /**
   * @see HasRpcToken#setRpcTokenExceptionHandler(RpcTokenExceptionHandler)
   */
  public void setRpcTokenExceptionHandler(RpcTokenExceptionHandler handler) {
    this.rpcTokenExceptionHandler = handler;
  }

  /**
   * @see ServiceDefTarget#setServiceEntryPoint(String)
   */
  public void setServiceEntryPoint(String url) {
    this.remoteServiceURL = url;
  }

  /**
   * This method is overridden by generated proxy classes to ensure that
   * current service's {@link RpcToken} is of the type specified in {@link
   * RpcToken.RpcTokenImplementation} annotation.
   *
   * @param token currently set {@link RpcToken}.
   */
  protected void checkRpcTokenType(RpcToken token) {
  }

  protected <T> RequestCallback doCreateRequestCallback(
      ResponseReader responseReader, String methodName, RpcStatsContext statsContext,
      AsyncCallback<T> callback) {
    return new RequestCallbackAdapter<T>(this, methodName, statsContext,
        callback, getRpcTokenExceptionHandler(), responseReader);
  }

  /**
   * Performs a remote service method invocation. This method is called by
   * generated proxy classes.
   *
   * @param <T> return type for the AsyncCallback
   * @param responseReader instance used to read the return value of the
   *          invocation
   * @param requestData payload that encodes the addressing and arguments of the
   *          RPC call
   * @param callback callback handler
   *
   * @return a {@link Request} object that can be used to track the request
   */
  protected <T> Request doInvoke(ResponseReader responseReader,
      String methodName, RpcStatsContext statsContext, String requestData,
      AsyncCallback<T> callback) {

    RequestBuilder rb = doPrepareRequestBuilderImpl(responseReader, methodName,
        statsContext, requestData, callback);

    try {
      return rb.send();
    } catch (RequestException ex) {
      InvocationException iex = new InvocationException(
          "Unable to initiate the asynchronous service invocation (" +
          methodName + ") -- check the network connection",
          ex);
      callback.onFailure(iex);
    } finally {
      if (statsContext.isStatsAvailable()) {
        statsContext.stats(statsContext.bytesStat(methodName,
            requestData.length(), "requestSent"));
      }
    }
    return null;
  }

  /**
   * Configures a RequestBuilder to send an RPC request when the RequestBuilder
   * is intended to be returned through the asynchronous proxy interface.
   *
   * @param <T> return type for the AsyncCallback
   * @param responseReader instance used to read the return value of the
   *          invocation
   * @param requestData payload that encodes the addressing and arguments of the
   *          RPC call
   * @param callback callback handler
   *
   * @return a RequestBuilder object that is ready to have its
   *         {@link RequestBuilder#send()} method invoked.
   */
  protected <T> RequestBuilder doPrepareRequestBuilder(
      ResponseReader responseReader, String methodName, RpcStatsContext statsContext,
      String requestData, AsyncCallback<T> callback) {

    RequestBuilder rb = doPrepareRequestBuilderImpl(responseReader, methodName,
        statsContext, requestData, callback);

    return rb;
  }

  /**
   * Configures a RequestBuilder to send an RPC request.
   *
   * @param <T> return type for the AsyncCallback
   * @param responseReader instance used to read the return value of the
   *          invocation
   * @param requestData payload that encodes the addressing and arguments of the
   *          RPC call
   * @param callback callback handler
   *
   * @return a RequestBuilder object that is ready to have its
   *         {@link RequestBuilder#send()} method invoked.
   */
  private <T> RequestBuilder doPrepareRequestBuilderImpl(
      ResponseReader responseReader, String methodName, RpcStatsContext statsContext,
      String requestData, AsyncCallback<T> callback) {

    if (getServiceEntryPoint() == null) {
      throw new NoServiceEntryPointSpecifiedException();
    }

    RequestCallback responseHandler = doCreateRequestCallback(responseReader,
        methodName, statsContext, callback);

    ensureRpcRequestBuilder();

    rpcRequestBuilder.create(getServiceEntryPoint());
    rpcRequestBuilder.setCallback(responseHandler);
    rpcRequestBuilder.setContentType(RPC_CONTENT_TYPE);
    rpcRequestBuilder.setRequestData(requestData);
    rpcRequestBuilder.setRequestId(statsContext.getRequestId());
    return rpcRequestBuilder.finish();
  }

  private void ensureRpcRequestBuilder() {
    if (rpcRequestBuilder == null) {
      rpcRequestBuilder = new RpcRequestBuilder();
    }
  }
}