org.glassfish.jersey.process.internal
Class RequestScope

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

All Implemented Interfaces:

org.glassfish.hk2.api.Context<RequestScoped>

@Singleton
public class RequestScope
extends Object
implements org.glassfish.hk2.api.Context<RequestScoped>

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 execute 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:

  Instance requestScopeInstance =
      requestScope.runInScope(new Callable<Instance>() {
          @Override
          public Instance call() {
              // This is execute in the new request scope.

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

  requestScope.runInScope(requestScopeInstance, new Runnable() {

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

  // we must release the scope instance explicitly
  requestScopeInstance.release();
 

In the previous example the request scope instance was suspended and retrieved which also informs requestScope that it should not automatically release the instance once the running task is finished. The requestScopeInstance 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 requestScopeInstance 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 instance which may change it's state during each request-scoped task execution for which this scope instance is used.

Author:

Marek Potociar (marek.potociar at oracle.com), Miroslav Fuksa (miroslav.fuksa at oracle.com)

Nested Class Summary

static class	RequestScope.Binder Request scope injection binder.
static class	RequestScope.Instance Implementation of the request scope instance.

Constructor Summary

RequestScope()

Method Summary

boolean	containsKey(org.glassfish.hk2.api.ActiveDescriptor<?> descriptor)
RequestScope.Instance	createInstance() Creates a new instance of the request scope instance.
void	destroyOne(org.glassfish.hk2.api.ActiveDescriptor<?> descriptor)
<U> U	findOrCreate(org.glassfish.hk2.api.ActiveDescriptor<U> activeDescriptor, org.glassfish.hk2.api.ServiceHandle<?> root)
Class<? extends Annotation>	getScope()
boolean	isActive()
RequestScope.Instance	referenceCurrent() Get a new reference for to currently running request scope instance.
<T> T	runInScope(Callable<T> task) Runs the task in the new request scope.
<T> T	runInScope(Producer<T> task) Runs the task in the new request scope.
<T> T	runInScope(RequestScope.Instance scopeInstance, Callable<T> task) Runs the task in the request scope initialized from the scope instance.
<T> T	runInScope(RequestScope.Instance scopeInstance, Producer<T> task) Runs the task in the request scope initialized from the scope instance.
void	runInScope(RequestScope.Instance scopeInstance, Runnable task) Runs the task in the request scope initialized from the scope instance.
void	runInScope(Runnable task) Runs the task in the new request scope.
void	shutdown()
boolean	supportsNullCreation()
RequestScope.Instance	suspendCurrent() Get the current request scope instance 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

getScope

public Class<? extends Annotation> getScope()

Specified by:

getScope in interface org.glassfish.hk2.api.Context<RequestScoped>

findOrCreate

public <U> U findOrCreate(org.glassfish.hk2.api.ActiveDescriptor<U> activeDescriptor,
                          org.glassfish.hk2.api.ServiceHandle<?> root)

Specified by:

findOrCreate in interface org.glassfish.hk2.api.Context<RequestScoped>

containsKey

public boolean containsKey(org.glassfish.hk2.api.ActiveDescriptor<?> descriptor)

Specified by:

containsKey in interface org.glassfish.hk2.api.Context<RequestScoped>

supportsNullCreation

public boolean supportsNullCreation()

Specified by:

supportsNullCreation in interface org.glassfish.hk2.api.Context<RequestScoped>

isActive

public boolean isActive()

Specified by:

isActive in interface org.glassfish.hk2.api.Context<RequestScoped>

destroyOne

public void destroyOne(org.glassfish.hk2.api.ActiveDescriptor<?> descriptor)

Specified by:

destroyOne in interface org.glassfish.hk2.api.Context<RequestScoped>

shutdown

public void shutdown()

Specified by:

shutdown in interface org.glassfish.hk2.api.Context<RequestScoped>

referenceCurrent

public RequestScope.Instance referenceCurrent()
                                       throws IllegalStateException

Get a new reference for to currently running request scope instance. This call prevents automatic release of the scope instance once the task that runs in the scope has finished.

The returned scope instance may be used to run additional task(s) in the same request scope using one of the #runInScope(Instance, ...) methods.

Note that the returned instance must be released manually once not needed anymore to prevent memory leaks.

Returns:

currently active request scope instance.

Throws:

IllegalStateException - in case there is no active request scope associated with the current thread.

See Also:

suspendCurrent()

suspendCurrent

public RequestScope.Instance suspendCurrent()

Get the current request scope instance and mark it as suspended. This call prevents automatic release of the scope instance once the task that runs in the scope has finished.

The returned scope instance may be used to run additional task(s) in the same request scope using one of the #runInScope(Instance, ...) methods.

Note that the returned instance must be released manually once not needed anymore to prevent memory leaks.

Returns:

currently active request scope instance that was suspended or null if the thread is not currently running in an active request scope.

See Also:

referenceCurrent()

createInstance

public RequestScope.Instance createInstance()

Creates a new instance of the request scope instance. This instance can be then used to run task in the request scope. Returned instance is suspended by default and must therefore be closed explicitly as it is shown in the following example:

 Instance instance = requestScope.createInstance();
 requestScope.runInScope(instance, someRunnableTask);
 instance.release();
 

Returns:

New suspended request scope instance.

runInScope

public void runInScope(RequestScope.Instance scopeInstance,
                       Runnable task)

Runs the task in the request scope initialized from the scope instance. The scope instance 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:

scopeInstance - The request scope instance 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 instance. At the end of the method the request scope is returned to its original state. The newly created scope instance 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(RequestScope.Instance scopeInstance,
                        Callable<T> task)
             throws Exception

Runs the task in the request scope initialized from the scope instance. The scope instance 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:

scopeInstance - The request scope instance 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 instance. At the end of the method the request scope is returned to its original state. The newly created scope instance 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(RequestScope.Instance scopeInstance,
                        Producer<T> task)

Runs the task in the request scope initialized from the scope instance. The scope instance 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:

scopeInstance - The request scope instance from which the request scope will be initialized.

task - Task to be executed.

Returns:

result returned by the task

runInScope

public <T> T runInScope(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 instance 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.