Class ServletScopes
- java.lang.Object
-
- com.google.inject.servlet.ServletScopes
-
public class ServletScopes extends java.lang.Object
Servlet scopes.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description private static class
ServletScopes.Context
(package private) static class
ServletScopes.NullObject
A sentinel attribute value representing null.private static class
ServletScopes.RequestScope
private static class
ServletScopes.SessionScope
-
Field Summary
Fields Modifier and Type Field Description static Scope
REQUEST
HTTP servlet request scope.private static java.lang.ThreadLocal<ServletScopes.Context>
requestScopeContext
A threadlocal scope map for non-http request scopes.static Scope
SESSION
HTTP session scope.
-
Constructor Summary
Constructors Modifier Constructor Description private
ServletScopes()
-
Method Summary
All Methods Static Methods Concrete Methods Deprecated Methods Modifier and Type Method Description private static void
checkScopingState(boolean condition, java.lang.String msg)
static <T> java.util.concurrent.Callable<T>
continueRequest(java.util.concurrent.Callable<T> callable, java.util.Map<Key<?>,java.lang.Object> seedMap)
Deprecated.You probably want to usetransferRequest
insteadprivate static RequestScoper
continueRequest(java.util.Map<Key<?>,java.lang.Object> seedMap)
static boolean
isRequestScoped(Binding<?> binding)
Returns true ifbinding
is request-scoped.static <T> java.util.concurrent.Callable<T>
scopeRequest(java.util.concurrent.Callable<T> callable, java.util.Map<Key<?>,java.lang.Object> seedMap)
Scopes the given callable inside a request scope.static RequestScoper
scopeRequest(java.util.Map<Key<?>,java.lang.Object> seedMap)
Returns an object that will apply request scope to a block of code.private static RequestScoper
transferHttpRequest()
private static RequestScoper
transferNonHttpRequest()
static RequestScoper
transferRequest()
Returns an object that "transfers" the request to another thread.static <T> java.util.concurrent.Callable<T>
transferRequest(java.util.concurrent.Callable<T> callable)
Wraps the given callable in a contextual callable that "transfers" the request to another thread.private static java.lang.Object
validateAndCanonicalizeValue(Key<?> key, java.lang.Object object)
Validates the key and object, ensuring the value matches the key type, and canonicalizing null objects to the null sentinel.private static <T> java.util.concurrent.Callable<T>
wrap(java.util.concurrent.Callable<T> delegate, RequestScoper requestScoper)
-
-
-
Field Detail
-
requestScopeContext
private static final java.lang.ThreadLocal<ServletScopes.Context> requestScopeContext
A threadlocal scope map for non-http request scopes. TheREQUEST
scope falls back to this scope map if no http request is available, and requiresscopeRequest(java.util.concurrent.Callable<T>, java.util.Map<com.google.inject.Key<?>, java.lang.Object>)
to be called as an alternative.
-
REQUEST
public static final Scope REQUEST
HTTP servlet request scope.
-
SESSION
public static final Scope SESSION
HTTP session scope.
-
-
Method Detail
-
continueRequest
@Deprecated public static <T> java.util.concurrent.Callable<T> continueRequest(java.util.concurrent.Callable<T> callable, java.util.Map<Key<?>,java.lang.Object> seedMap)
Deprecated.You probably want to usetransferRequest
insteadWraps 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, usenull
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.- Since:
- 3.0
-
continueRequest
private static RequestScoper continueRequest(java.util.Map<Key<?>,java.lang.Object> seedMap)
-
transferRequest
public static <T> java.util.concurrent.Callable<T> transferRequest(java.util.concurrent.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(java.util.concurrent.Callable<T>, java.util.Map<com.google.inject.Key<?>, java.lang.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 request-scoped 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. The returned callable will block until the current thread has released the request scope.
- 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.- Since:
- 4.0
-
transferRequest
public static RequestScoper transferRequest()
Returns an object 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. The transferred scope is the one active for the thread that calls this method. A later call toopen()
activates the transferred the scope, including propagating any objects scoped at that time.As opposed to
continueRequest(java.util.concurrent.Callable<T>, java.util.Map<com.google.inject.Key<?>, java.lang.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 request-scoped objects are not typically thread-safe, it is important to avoid applying the same request scope concurrently. The returned Scoper will block on open until the current thread has released the request scope.
- Returns:
- an object that when opened will initiate the request scope
- Throws:
OutOfScopeException
- if this method is called from a non-request thread, or if the request has completed.- Since:
- 4.1
-
transferHttpRequest
private static RequestScoper transferHttpRequest()
-
transferNonHttpRequest
private static RequestScoper transferNonHttpRequest()
-
isRequestScoped
public static boolean isRequestScoped(Binding<?> binding)
Returns true ifbinding
is request-scoped. If the binding is alinked key binding
and belongs to an injector (i. e. it was retrieved viaInjector.getBinding()
), then this method will also return true if the target binding is request-scoped.- Since:
- 4.0
-
scopeRequest
public static <T> java.util.concurrent.Callable<T> scopeRequest(java.util.concurrent.Callable<T> callable, java.util.Map<Key<?>,java.lang.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, usenull
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. - Since:
- 3.0
-
scopeRequest
public static RequestScoper scopeRequest(java.util.Map<Key<?>,java.lang.Object> seedMap)
Returns an object that will apply request scope to a block of code. 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 object will throw a
ScopingException
when opened if there is a request scope already active on the current thread.- Parameters:
seedMap
- the initial set of scoped instances for Guice to seed the request scope with. To seed a key with null, usenull
as the value.- Returns:
- an object that when opened will initiate the request scope
- Since:
- 4.1
-
validateAndCanonicalizeValue
private static java.lang.Object validateAndCanonicalizeValue(Key<?> key, java.lang.Object object)
Validates the key and object, ensuring the value matches the key type, and canonicalizing null objects to the null sentinel.
-
checkScopingState
private static void checkScopingState(boolean condition, java.lang.String msg)
-
wrap
private static <T> java.util.concurrent.Callable<T> wrap(java.util.concurrent.Callable<T> delegate, RequestScoper requestScoper)
-
-