# ApiProxy
Date: 2012-02-24

## 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
`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`
`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 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 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`

Method Summary
`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 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` `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)
                               throws ApiProxy.ApiProxyException

  Throws:
    `ApiProxy.ApiProxyException`
  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)
                               throws ApiProxy.ApiProxyException

  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.
    `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.
    `ApiProxy.ApiProxyException`

### 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 10). 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.

### 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 caled 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.

### getRequestThreads

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

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