RequestScope (Jersey 2.37 API)

java.lang.Object
- org.glassfish.jersey.process.internal.RequestScope

Direct Known Subclasses:

CdiRequestScope, Hk2RequestScope
```
public abstract class RequestScope
extends Object
```
Scopes a single request/response processing execution on a single thread.
To execute a code inside of the request scope use one of the runInScope(...) methods and supply the task encapsulating the code that should be executed in the scope.

Example:
```
 @Inject
 RequestScope requestScope;

 ...

 requestScope.runInScope(new Runnable() {
     @Override
     public void run() {
          System.out.println("This is executed in the request scope...");
     }
 });
 
```
An instance of the request scope can be suspended and retrieved via a call to suspendCurrent() method. This instance can be later used to resume the same request scope and run another task in the same scope:
```
  RequestContext requestScopeContext =
      requestScope.runInScope(new Callable<Instance>() {
          @Override
          public RequestContext call() {
              // This is executed in the new request scope.

              // The following call will cause that the
              // RequestContext will not be released
              // automatically and we will have to release
              // it explicitly at the end.
              return requestScope.suspendCurrent();
          }
      });

  requestScope.runInScope(requestScopeContext, new Runnable() {

      @Override
      public void run() {
          // This is executed in the same request scope as code above.
      }
  });

  // The scope context must be explicitly released.
  requestScopeContext.release();
 
```
In the previous example the request scope context was suspended and retrieved which also informs requestScope that it should not automatically release the instance once the running task is finished. The requestScopeContext is then used to initialize the next request-scoped execution. The second task will run in the same request scope as the first task. At the end the suspended requestScopeContext must be manually released. Not releasing the instance could cause memory leaks. Please note that calling suspendCurrent() does not retrieve an immutable snapshot of the current request scope but a live reference to the internal request scope context which may change it's state during each request-scoped task execution for which this scope context is used.
Author:

Marek Potociar, Miroslav Fuksa

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`RequestScope.RequestScopeConfigurator` Configurator which initializes and register `RequestScope` instance int `InjectionManager` and `BootstrapBag`.

Constructor Summary

Constructors
Constructor and Description

RequestScope()

Constructors
Constructor and Description
`RequestScope()`

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`protected void`	`activate(RequestContext context, RequestContext oldContext)` Stores the provided `RequestContext` to thread-local variable belonging to current request scope.
`abstract RequestContext`	`createContext()` Creates a new instance of the `request scope context`.
`RequestContext`	`current()` Returns the current `RequestContext` which has to be active on the given thread.
`boolean`	`isActive()`
`RequestContext`	`referenceCurrent()` Get a new reference for to currently running request scope context.
`protected void`	`release(RequestContext context)` Releases the provided `RequestContext` to thread-local variable belonging to current request scope.
`protected void`	`resume(RequestContext context)` Resumes the provided `RequestContext` to thread-local variable belonging to current request scope.
`<T> T`	`runInScope(Callable<T> task)` Runs the `task` in the new request scope.
`<T> T`	`runInScope(org.glassfish.jersey.internal.util.Producer<T> task)` Runs the `task` in the new request scope.
`<T> T`	`runInScope(RequestContext context, Callable<T> task)` Runs the `task` in the request scope initialized from the `scope context`.
`<T> T`	`runInScope(RequestContext context, org.glassfish.jersey.internal.util.Producer<T> task)` Runs the `task` in the request scope initialized from the `scope context`.
`void`	`runInScope(RequestContext context, Runnable task)` Runs the `task` in the request scope initialized from the `scope context`.
`void`	`runInScope(Runnable task)` Runs the `task` in the new request scope.
`void`	`shutdown()`
`protected void`	`suspend(RequestContext context)` Executes the action when the request scope comes into suspended state.
`RequestContext`	`suspendCurrent()` Get the current `request scope context` and mark it as suspended.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - RequestScope
```
public RequestScope()
```
- Method Detail
  - isActive
```
public boolean isActive()
```
  - shutdown
```
public void shutdown()
```
  - referenceCurrent
```
public RequestContext referenceCurrent()
                                throws IllegalStateException
```
    Get a new reference for to currently running request scope context. This call prevents automatic release of the scope context once the task that runs in the scope has finished.
    The returned scope context may be used to run additional task(s) in the same request scope using one of the #runInScope(RequestContext, ...) methods.
    
    Note that the returned context must be released manually once not needed anymore to prevent memory leaks.
    
    Returns:
    
    currently active request scope context.
    
    Throws:
    
    IllegalStateException - in case there is no active request scope associated with the current thread or if the request scope has been already shut down.
    
    See Also:
    
    suspendCurrent()
  - current
```
public RequestContext current()
```
    Returns the current RequestContext which has to be active on the given thread.
    
    Returns:
    
    current active request context.
  - suspendCurrent
```
public RequestContext suspendCurrent()
```
    Get the current request scope context and mark it as suspended. This call prevents automatic release of the scope context once the task that runs in the scope has finished.
    The returned scope context may be used to run additional task(s) in the same request scope using one of the #runInScope(RequestContext, ...) methods.
    
    Note that the returned context must be released manually once not needed anymore to prevent memory leaks.
    
    Returns:
    
    currently active request scope context that was suspended or null if the thread is not currently running in an active request scope.
    
    See Also:
    
    referenceCurrent()
  - suspend
```
protected void suspend(RequestContext context)
```
    Executes the action when the request scope comes into suspended state. For example, implementation can call deactivation of the underlying request scope storage.
    
    Parameters:
    
    context - current request context to be suspended.
  - createContext
```
public abstract RequestContext createContext()
```
    Creates a new instance of the request scope context. This instance can be then used to run task in the request scope. Returned context is suspended by default and must therefore be closed explicitly as it is shown in the following example:
```
 RequestContext context = requestScope.createContext();
 requestScope.runInScope(context, someRunnableTask);
 context.release();
 
```
    Returns:
    
    New suspended request scope context.
  - activate
```
protected void activate(RequestContext context,
                        RequestContext oldContext)
```
    Stores the provided RequestContext to thread-local variable belonging to current request scope.
    
    Parameters:
    
    context - storage with request scoped objects.
  - resume
```
protected void resume(RequestContext context)
```
    Resumes the provided RequestContext to thread-local variable belonging to current request scope.
    
    Parameters:
    
    context - storage with request scoped objects.
  - release
```
protected void release(RequestContext context)
```
    Releases the provided RequestContext to thread-local variable belonging to current request scope.
    
    Parameters:
    
    context - storage with request scoped objects.
  - runInScope
```
public void runInScope(RequestContext context,
                       Runnable task)
```
    Runs the task in the request scope initialized from the scope context. The scope context is NOT released by the method (this must be done explicitly). The current thread might be already in any request scope and in that case the scope will be changed to the scope defined by the scope instance. At the end of the method the request scope is returned to its original state.
    
    Parameters:
    
    context - The request scope context from which the request scope will be initialized.
    
    task - Task to be executed.
  - runInScope
```
public void runInScope(Runnable task)
```
    Runs the task in the new request scope. The current thread might be already in any request scope and in that case the scope will be changed to the scope defined by the scope context. At the end of the method the request scope is returned to its original state. The newly created scope context will be implicitly released at the end of the method call except the task will call suspendCurrent().
    
    Parameters:
    
    task - Task to be executed.
  - runInScope
```
public <T> T runInScope(RequestContext context,
                        Callable<T> task)
                 throws Exception
```
    Runs the task in the request scope initialized from the scope context. The scope context is NOT released by the method (this must be done explicitly). The current thread might be already in any request scope and in that case the scope will be changed to the scope defined by the scope instance. At the end of the method the request scope is returned to its original state.
    
    Type Parameters:
    
    T - task result type.
    
    Parameters:
    
    context - The request scope context from which the request scope will be initialized.
    
    task - Task to be executed.
    
    Returns:
    
    result returned by the task.
    
    Throws:
    
    Exception - Exception thrown by the task.
  - runInScope
```
public <T> T runInScope(Callable<T> task)
                 throws Exception
```
    Runs the task in the new request scope. The current thread might be already in any request scope and in that case the scope will be changed to the scope defined by the scope context. At the end of the method the request scope is returned to its original state. The newly created scope context will be implicitly released at the end of the method call except the task will call suspendCurrent().
    
    Type Parameters:
    
    T - task result type.
    
    Parameters:
    
    task - Task to be executed.
    
    Returns:
    
    result returned by the task.
    
    Throws:
    
    Exception - Exception thrown by the task.
  - runInScope
```
public <T> T runInScope(RequestContext context,
                        org.glassfish.jersey.internal.util.Producer<T> task)
```
    Runs the task in the request scope initialized from the scope context. The scope context is NOT released by the method (this must be done explicitly). The current thread might be already in any request scope and in that case the scope will be changed to the scope defined by the scope context. At the end of the method the request scope is returned to its original state.
    
    Type Parameters:
    
    T - task result type.
    
    Parameters:
    
    context - The request scope context from which the request scope will be initialized.
    
    task - Task to be executed.
    
    Returns:
    
    result returned by the task
  - runInScope
```
public <T> T runInScope(org.glassfish.jersey.internal.util.Producer<T> task)
```
    Runs the task in the new request scope. The current thread might be already in any request scope and in that case the scope will be changed to the scope defined by the scope instance. At the end of the method the request scope is returned to its original state. The newly created scope context will be implicitly released at the end of the method call except the task will call suspendCurrent().
    
    Type Parameters:
    
    T - task result type.
    
    Parameters:
    
    task - Task to be executed.
    
    Returns:
    
    result returned by the task.

Class RequestScope

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

RequestScope

Method Detail

isActive

shutdown

referenceCurrent

current

suspendCurrent

suspend

createContext

activate

resume

release

runInScope

runInScope

runInScope

runInScope

runInScope

runInScope