Package com.yahoo.jdisc

Class Request

  • All Implemented Interfaces:
    SharedResource
    public class Request
extends AbstractResource

    This class represents a single request (which may have any content model that a ServerProvider chooses to implement). The URI is used by the Container to route it to the appropriate RequestHandler, which in turn will provide a ContentChannel to write content to.

    To ensure application consistency throughout the lifetime of a Request, the Request itself holds an active reference to the Container for which it was created. This has the unfortunate side-effect of requiring the creator of a Request to do explicit reference counting during the setup of a content stream.

    For every successfully dispatched Request (i.e. a non-null ContentChannel has been retrieved), there will be exactly one Response returned to the provided ResponseHandler.

    Author:
    Simon Thoresen Hult
    See Also:
    Container, Response

    • Constructor Detail

      • Request

        public Request​(CurrentContainer current,
               java.net.URI uri)

        Creates a new instance of this class. As a ServerProvider you need to inject a CurrentContainer instance at construction time and use that as argument to this method. As a RequestHandler that needs to spawn child Requests, use the other constructor.

        Because a Request holds an active reference to the owning Container, it is necessary to call AbstractResource.release() once a ContentChannel has been established. Suggested usage:

         Request request = null;
 ContentChannel content = null;
 try {
     request = new Request(currentContainer, uri);
     (...)
     content = request.connect(responseHandler);
 } finally {
    if (request != null) request.release();
 }
 content.write(...);
        Parameters:
        current - The CurrentContainer for which this Request is created.
        uri - The identifier of this request.

      • Request

        public Request​(Request parent,
               java.net.URI uri)

        Creates a new instance of this class. As a RequestHandler you should use this method to spawn child Requests of another. As a ServerProvider that needs to spawn new Requests, us the other constructor.

        Because a Request holds an active reference to the owning Container, it is necessary to call AbstractResource.release() once a ContentChannel has been established. Suggested usage:

         Request request = null;
 ContentChannel content = null;
 try {
     request = new Request(parentRequest, uri);
     (...)
     content = request.connect(responseHandler);
 } finally {
    if (request != null) request.release();
 }
 content.write(...);
        Parameters:
        parent - The parent Request of this.
        uri - The identifier of this request.

    • Method Detail

      • container

        public Container container()

        Returns the Container for which this Request was created.

        Returns:
        The container instance.

      • getUri

        public java.net.URI getUri()

        Returns the Uniform Resource Identifier used by the Container to resolve the appropriate RequestHandler for this Request.

        Returns:
        The resource identifier.
        See Also:
        setUri(URI)

      • setUri

        public Request setUri​(java.net.URI uri)

        Sets the Uniform Resource Identifier used by the Container to resolve the appropriate RequestHandler for this Request. Because access to the URI is not guarded by any lock, any changes made after calling connect(ResponseHandler) might never become visible to other threads.

        Parameters:
        uri - The URI to set.
        Returns:
        This, to allow chaining.
        See Also:
        getUri()

      • isServerRequest

        public boolean isServerRequest()

        Returns whether or not this Request was created by a ServerProvider. The value of this is used by Container.resolveHandler(Request) to decide whether to match against server- or client-bindings.

        Returns:
        True, if this is a server request.

      • setServerRequest

        public Request setServerRequest​(boolean serverRequest)

        Sets whether or not this Request was created by a ServerProvider. The constructor that accepts a CurrentContainer sets this to true, whereas the constructor that accepts a parent Request sets this to false.

        Parameters:
        serverRequest - Whether or not this is a server request.
        Returns:
        This, to allow chaining.
        See Also:
        isServerRequest()

      • setBindingMatch

        public Request setBindingMatch​(com.yahoo.jdisc.application.BindingMatch<RequestHandler> bindingMatch)

        Sets the last resolved BindingMatch of this Request. This is called by the Container.resolveHandler(Request) method.

        Parameters:
        bindingMatch - The BindingMatch to set.
        Returns:
        This, to allow chaining.
        See Also:
        getBindingMatch()

      • context

        public java.util.Map<java.lang.String,​java.lang.Object> context()

        Returns the named application context objects. This data is not intended for network transport, rather they are intended for passing shared data between components of an Application.

        Returns:
        The context map.

      • headers

        public HeaderFields headers()

        Returns the set of header fields of this Request. These are the meta-data of the Request, and are not applied to any internal Container logic. As opposed to the context(), the headers ARE intended for network transport. Modifying headers is a thread-unsafe operation -- any changes made after calling connect(ResponseHandler) might never become visible to other threads, and might throw ConcurrentModificationExceptions in other threads.

        Returns:
        The header fields.

      • setTimeoutManager

        public void setTimeoutManager​(TimeoutManager timeoutManager)

        Sets a TimeoutManager to be called when setTimeout(long, TimeUnit) is invoked. If a timeout has already been set for this Request, the TimeoutManager is called before returning. This method will throw an IllegalStateException if it has already been called.

        NOTE: This is used by the default timeout management implementation, so unless you are replacing that mechanism you should avoid calling this method. If you do want to replace that mechanism, you need to call this method prior to calling the target RequestHandler (since that injects the default manager).

        Parameters:
        timeoutManager - The manager to set.
        Throws:
        java.lang.NullPointerException - If the TimeoutManager is null.
        java.lang.IllegalStateException - If another TimeoutManager has already been set.
        See Also:
        getTimeoutManager(), setTimeout(long, TimeUnit)

      • getTimeout

        public java.lang.Long getTimeout​(java.util.concurrent.TimeUnit unit)

        Returns the allocated number of time units that this Request is allowed to exist. If no timeout has been set for this Request, this method returns null.

        Parameters:
        unit - The unit to return the timeout in.
        Returns:
        The timeout of this Request.
        See Also:
        setTimeout(long, TimeUnit)

      • timeRemaining

        public java.lang.Long timeRemaining​(java.util.concurrent.TimeUnit unit)

        Returns the time that this Request is allowed to exist. If no timeout has been set, this method will return null.

        Parameters:
        unit - The unit to return the time in.
        Returns:
        The number of time units left until this Request times out, or null.

      • timeElapsed

        public long timeElapsed​(java.util.concurrent.TimeUnit unit)

        Returns the time that this Request has existed so far.

        Parameters:
        unit - The unit to return the time in.
        Returns:
        The number of time units elapsed since this Request was created.

      • creationTime

        public long creationTime​(java.util.concurrent.TimeUnit unit)

        Returns the time at which this Request was created. This is whatever value was returned by Timer.currentTimeMillis() when constructing this.

        Parameters:
        unit - The unit to return the time in.
        Returns:
        The creation time of this Request.

      • isCancelled

        public boolean isCancelled()

        Returns whether or not this Request has been cancelled. This can be thought of as the Thread.isInterrupted() of Requests - it does not enforce anything in ways of blocking the Request, it is simply a signal to allow the developer to break early if the Request has already been dropped.

        This method will also return true if the Request has a non-null timeout, and that timeout has expired.

        Finally, this method will also return true if this Request has a parent Request that has been cancelled.

        Returns:
        True if this Request has timed out or been cancelled.
        See Also:
        cancel(), setTimeout(long, TimeUnit)

      • cancel

        public void cancel()

        Mark this request as cancelled and frees any resources held by the request if possible. All subsequent calls to isCancelled() on this Request return true.

        See Also:
        isCancelled()

      • destroy

        protected void destroy()
        Description copied from class: AbstractResource

        This method signals that this AbstractResource can dispose of any internal resources, and commence with shut down of any internal threads. This will be called once the reference count of this resource reaches zero.

        Overrides:
        destroy in class AbstractResource