com.google.apphosting.api

## Class ApiProxy

- java.lang.Object
- - com.google.apphosting.api.ApiProxy

-     public class ApiProxy
      extends java.lang.Object

  ApiProxy is a static class that serves as the collection point for all API calls from user code into the application server. It is responsible for proxying makeSyncCall() calls to a delegate, which actually implements the API calls. It also stores an Environment for each thread, which contains additional user-visible information about the request.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `ApiProxy.ApiConfig` `ApiConfig` encapsulates one or more configuration parameters scoped to an individual API call.
    `static class` | `ApiProxy.ApiDeadlineExceededException`
    `static class` | `ApiProxy.ApiProxyException` An exception produced when trying to perform an API call.
    `static interface` | `ApiProxy.ApiResultFuture<T>` A subtype of `Future` that provides more detailed information about the timing and resource consumption of particular API calls.
    `static class` | `ApiProxy.ApplicationException`
    `static class` | `ApiProxy.ArgumentException`
    `static class` | `ApiProxy.CallNotFoundException`
    `static class` | `ApiProxy.CancelledException`
    `static class` | `ApiProxy.CapabilityDisabledException`
    `static interface` | `ApiProxy.Delegate<E extends ApiProxy.Environment>` This interface can be used to provide a class that actually implements API calls.
    `static interface` | `ApiProxy.Environment` Environment is a simple data container that provides additional information about the current request (e.g.
    `static interface` | `ApiProxy.EnvironmentFactory` Used to create an Environment object to use if no thread local Environment is set.
    `static interface` | `ApiProxy.EnvironmentWithTrace` A specialization of Environment with call-tracing metadata.
    `static class` | `ApiProxy.FeatureNotEnabledException`
    `static class` | `ApiProxy.LogRecord` `LogRecord` represents a single apphosting log entry, including a Java-specific logging level, a timestamp in microseconds, and a message, which is a formatted string containing the rest of the logging information (e.g.
    `static class` | `ApiProxy.OverQuotaException`
    `static class` | `ApiProxy.RequestTooLargeException`
    `static class` | `ApiProxy.ResponseTooLargeException`
    `static class` | `ApiProxy.RPCFailedException`
    `static class` | `ApiProxy.UnknownException` An exception whose cause is not known or understood by the API code.

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `clearEnvironmentForCurrentThread()` Removes any environment associated with the current thread.
    `static void` | `flushLogs()` Synchronously flush all pending application logs.
    `static ApiProxy.Environment` | `getCurrentEnvironment()` Gets the environment associated with this thread.
    `static ApiProxy.Delegate` | `getDelegate()` Gets the delegate to which we will proxy requests.
    `static ApiProxy.EnvironmentFactory` | `getEnvironmentFactory()`
    `static java.util.List<java.lang.Thread>` | `getRequestThreads()` Returns a list of all threads which are currently running requests.
    `static void` | `log(ApiProxy.LogRecord record)`
    `static java.util.concurrent.Future<byte[]>` | `makeAsyncCall(java.lang.String packageName, java.lang.String methodName, byte[] request)`
    `static java.util.concurrent.Future<byte[]>` | `makeAsyncCall(java.lang.String packageName, java.lang.String methodName, byte[] request, ApiProxy.ApiConfig apiConfig)` Make an asynchronous call to the specified method in the specified API package.
    `static byte[]` | `makeSyncCall(java.lang.String packageName, java.lang.String methodName, byte[] request)`
    `static byte[]` | `makeSyncCall(java.lang.String packageName, java.lang.String methodName, byte[] request, ApiProxy.ApiConfig apiConfig)` Make a synchronous call to the specified method in the specified API package.
    `static void` | `setDelegate(ApiProxy.Delegate<?> aDelegate)` Sets a delegate to which we will proxy requests.
    `static void` | `setEnvironmentFactory(ApiProxy.EnvironmentFactory factory)` Set the EnvironmentFactory instance to use, which will be used to create Environment instances when a thread local one is not set.
    `static void` | `setEnvironmentForCurrentThread(ApiProxy.Environment environment)` Sets an environment for the current thread.

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### makeSyncCall

          public static byte[] makeSyncCall(java.lang.String packageName,
                                            java.lang.String methodName,
                                            byte[] request)

      See Also:
        `makeSyncCall(String,String,byte[],ApiConfig)`

    - #### makeSyncCall

          public static byte[] makeSyncCall(java.lang.String packageName,
                                            java.lang.String methodName,
                                            byte[] request,
                                            ApiProxy.ApiConfig apiConfig)

      Make a synchronous call to the specified method in the specified API package.

      Note: if you have not installed a `Delegate` and called `setEnvironmentForCurrentThread` in this thread before calling this method, it will act like no API calls are available (i.e. always throw `CallNotFoundException`).

      Parameters:
        `packageName` - the name of the API package.
        `methodName` - the name of the method within the API package.
        `request` - a byte array containing the serialized form of the request protocol buffer.
        `apiConfig` - that specifies API-specific configuration parameters.
      Returns:
        a byte array containing the serialized form of the response protocol buffer.
      Throws:
        `ApiProxy.ApplicationException` - For any error that is the application's fault.
        `ApiProxy.RPCFailedException` - If we could not connect to a backend service.
        `ApiProxy.CallNotFoundException` - If the specified method does not exist, or if the thread making the call is neither a request thread nor a thread created by `ThreadManager`.
        `ApiProxy.ArgumentException` - If the request could not be parsed.
        `ApiProxy.ApiDeadlineExceededException` - If the request took too long.
        `ApiProxy.CancelledException` - If the request was explicitly cancelled.
        `ApiProxy.CapabilityDisabledException` - If the API call is currently unavailable.
        `ApiProxy.OverQuotaException` - If the API call required more quota than is available.
        `ApiProxy.RequestTooLargeException` - If the request to the API was too large.
        `ApiProxy.ResponseTooLargeException` - If the response to the API was too large.
        `ApiProxy.UnknownException` - If any other error occurred.

    - #### makeAsyncCall

          public static java.util.concurrent.Future<byte[]> makeAsyncCall(java.lang.String packageName,
                                                                          java.lang.String methodName,
                                                                          byte[] request)

      See Also:
        `makeAsyncCall(String,String,byte[],ApiConfig)`

    - #### makeAsyncCall

          public static java.util.concurrent.Future<byte[]> makeAsyncCall(java.lang.String packageName,
                                                                          java.lang.String methodName,
                                                                          byte[] request,
                                                                          ApiProxy.ApiConfig apiConfig)

      Make an asynchronous call to the specified method in the specified API package.

      Note: if you have not installed a `Delegate` and called `setEnvironmentForCurrentThread` in this thread before calling this method, it will act like no API calls are available (i.e. the returned `Future` will throw `CallNotFoundException`).

      There is a limit to the number of simultaneous asynchronous API calls (currently 100). Invoking this method while this number of API calls are outstanding will block.

      Parameters:
        `packageName` - the name of the API package.
        `methodName` - the name of the method within the API package.
        `request` - a byte array containing the serialized form of the request protocol buffer.
        `apiConfig` - that specifies API-specific configuration parameters.
      Returns:
        a `Future` that will resolve to a byte array containing the serialized form of the response protocol buffer on success, or throw one of the exceptions documented for `makeSyncCall(String, String, byte[], ApiConfig)` on failure.

    - #### log

          public static void log(ApiProxy.LogRecord record)

    - #### flushLogs

          public static void flushLogs()

      Synchronously flush all pending application logs.

    - #### getCurrentEnvironment

          public static ApiProxy.Environment getCurrentEnvironment()

      Gets the environment associated with this thread. This can be used to discover additional information about the current request. The value returned is the `Environment` that this thread most recently set with `setEnvironmentForCurrentThread(com.google.apphosting.api.ApiProxy.Environment)`. If that is null and `setEnvironmentFactory(com.google.apphosting.api.ApiProxy.EnvironmentFactory)` has set an `ApiProxy.EnvironmentFactory`, that `EnvironmentFactory` is used to create an `Environment` instance which is returned by this call and future calls. If there is no `EnvironmentFactory` either, then null is returned.

    - #### setDelegate

          public static void setDelegate(ApiProxy.Delegate<?> aDelegate)

      Sets a delegate to which we will proxy requests. This should not be used from user-code.

    - #### getDelegate

          public static ApiProxy.Delegate getDelegate()

      Gets the delegate to which we will proxy requests. This should really only be called from test-code where, for example, you might want to downcast and invoke methods on a specific implementation that you happen to know has been installed.

    - #### setEnvironmentForCurrentThread

          public static void setEnvironmentForCurrentThread(ApiProxy.Environment environment)

      Sets an environment for the current thread. This should not be used from user-code.

    - #### clearEnvironmentForCurrentThread

          public static void clearEnvironmentForCurrentThread()

      Removes any environment associated with the current thread. This should not be used from user-code.

    - #### getEnvironmentFactory

          public static ApiProxy.EnvironmentFactory getEnvironmentFactory()

    - #### setEnvironmentFactory

          public static void setEnvironmentFactory(ApiProxy.EnvironmentFactory factory)

      Set the EnvironmentFactory instance to use, which will be used to create Environment instances when a thread local one is not set. This should not be used from user-code, and it should only be called once, with a value that must not be null.

    - #### getRequestThreads

          public static java.util.List<java.lang.Thread> getRequestThreads()

      Returns a list of all threads which are currently running requests.