Package org.glassfish.jersey.process.internal

Class RequestScope

  • 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

    • 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.