public class

ServletScopes

extends Object
java.lang.Object
   ↳ com.google.inject.servlet.ServletScopes

Class Overview

Servlet scopes.

Summary

Constants
Scope REQUEST HTTP servlet request scope.
Scope SESSION HTTP session scope.
Public Methods
static <T> Callable<T> continueRequest(Callable<T> callable, Map<Key<?>, Object> seedMap)
Wraps the given callable in a contextual callable that "continues" the HTTP request in another thread.
static boolean isRequestScoped(Binding<?> binding)
Returns true if binding is request-scoped.
static <T> Callable<T> scopeRequest(Callable<T> callable, Map<Key<?>, Object> seedMap)
Scopes the given callable inside a request scope.
static <T> Callable<T> transferRequest(Callable<T> callable)
Wraps the given callable in a contextual callable that "transfers" the request to another thread.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final Scope REQUEST

HTTP servlet request scope.

public static final Scope SESSION

HTTP session scope.

Public Methods

public static Callable<T> continueRequest (Callable<T> callable, Map<Key<?>, Object> seedMap)

Wraps the given callable in a contextual callable that "continues" the HTTP request in another thread. This acts as a way of transporting request context data from the request processing thread to to worker threads.

There are some limitations:

  • Derived objects (i.e. anything marked @RequestScoped will not be transported.
  • State changes to the HttpServletRequest after this method is called will not be seen in the continued thread.
  • Only the HttpServletRequest, ServletContext and request parameter map are available in the continued thread. The response and session are not available.

The returned callable will throw a ScopingException when called if the HTTP request scope is still active on the current thread.

Parameters
callable code to be executed in another thread, which depends on the request scope.
seedMap the initial set of scoped instances for Guice to seed the request scope with. To seed a key with null, use null as the value.
Returns
  • a callable that will invoke the given callable, making the request context available to it.
Throws
OutOfScopeException if this method is called from a non-request thread, or if the request has completed.

public static boolean isRequestScoped (Binding<?> binding)

Returns true if binding is request-scoped. If the binding is a linked key binding and belongs to an injector (i. e. it was retrieved via Injector.getBinding()), then this method will also return true if the target binding is request-scoped.

public static Callable<T> scopeRequest (Callable<T> callable, Map<Key<?>, Object> seedMap)

Scopes the given callable inside a request scope. This is not the same as the HTTP request scope, but is used if no HTTP request scope is in progress. In this way, keys can be scoped as @RequestScoped and exist in non-HTTP requests (for example: RPC requests) as well as in HTTP request threads.

The returned callable will throw a ScopingException when called if there is a request scope already active on the current thread.

Parameters
callable code to be executed which depends on the request scope. Typically in another thread, but not necessarily so.
seedMap the initial set of scoped instances for Guice to seed the request scope with. To seed a key with null, use null as the value.
Returns
  • a callable that when called will run inside the a request scope that exposes the instances in the seedMap as scoped keys.

public static Callable<T> transferRequest (Callable<T> callable)

Wraps the given callable in a contextual callable that "transfers" the request to another thread. This acts as a way of transporting request context data from the current thread to a future thread.

As opposed to continueRequest(Callable, Map, Object>), this method propagates all existing scoped objects. The primary use case is in server implementations where you can detach the request processing thread while waiting for data, and reattach to a different thread to finish processing at a later time.

Because HttpServletRequest objects are not typically thread-safe, the callable returned by this method must not be run on a different thread until the current request scope has terminated. In other words, do not use this method to propagate the current request scope to worker threads that may run concurrently with the current thread.

The returned callable will throw a ScopingException when called if the request scope being transferred is still active on a different thread.

Parameters
callable code to be executed in another thread, which depends on the request scope.
Returns
  • a callable that will invoke the given callable, making the request context available to it.
Throws
OutOfScopeException if this method is called from a non-request thread, or if the request has completed.