Package com.google.apphosting.api

Class ApiProxy

java.lang.Object

com.google.apphosting.api.ApiProxy

public class ApiProxy
extends 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	Description
static final 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 final 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

Modifier and Type	Method	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 List<Thread>	getRequestThreads()	Returns a list of all threads which are currently running requests.
static void	log(ApiProxy.LogRecord record)
static Future<byte[]>	makeAsyncCall(String packageName, String methodName, byte[] request)
static Future<byte[]>	makeAsyncCall(String packageName, String methodName, byte[] request, ApiProxy.ApiConfig apiConfig)	Make an asynchronous call to the specified method in the specified API package.
static byte[]	makeSyncCall(String packageName, String methodName, byte[] request)
static byte[]	makeSyncCall(String packageName, String methodName, byte[] request, ApiProxy.ApiConfig apiConfig)	Make a synchronous call to the specified method in the specified API package.
static void	setDelegate(@Nullable 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

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

makeSyncCall

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

See Also:

• makeSyncCall(String,String,byte[],ApiConfig)

makeSyncCall

public static byte[] makeSyncCall(String packageName,
 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 Future<byte[]> makeAsyncCall(String packageName,
 String methodName,
 byte[] request)

See Also:

• makeAsyncCall(String,String,byte[],ApiConfig)

makeAsyncCall

public static Future<byte[]> makeAsyncCall(String packageName,
 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(@Nullable 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 List<Thread> getRequestThreads()

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