Package org.eclipse.jetty.server

Interface PushBuilder

  • All Known Implementing Classes:
    PushBuilderImpl
    public interface PushBuilder
    Build a request to be pushed.

    A PushBuilder is obtained by calling Request.getPushBuilder() (Eventually HttpServletRequest.getPushBuilder()). Each call to this method will return a new instance of a PushBuilder based off the current HttpServletRequest. Any mutations to the returned PushBuilder are not reflected on future returns.

    The instance is initialized as follows:

    • The method is initialized to "GET"
    • The existing headers of the current HttpServletRequest are added to the builder, except for:
      • Conditional headers (eg. If-Modified-Since)
      • Range headers
      • Expect headers
      • Authorization headers
      • Referrer headers
    • If the request was authenticated, an Authorization header will be set with a container generated token that will result in equivalent Authorization for the pushed request.
    • The HttpServletRequest.getRequestedSessionId() value, unless at the time of the call HttpServletRequest.getSession(boolean) has previously been called to create a new HttpSession, in which case the new session ID will be used as the PushBuilder's requested session ID. The source of the requested session id will be the same as for the request
    • The Referer(sic) header will be set to HttpServletRequest.getRequestURL() plus any HttpServletRequest.getQueryString()
    • If HttpServletResponse.addCookie(Cookie) has been called on the associated response, then a corresponding Cookie header will be added to the PushBuilder, unless the Cookie.getMaxAge() is <=0, in which case the Cookie will be removed from the builder.
    • If this request has has the conditional headers If-Modified-Since or If-None-Match, then the isConditional() header is set to true.

    The path(java.lang.String) method must be called on the PushBuilder instance before the call to push(). Failure to do so must cause an exception to be thrown from push(), as specified in that method.

    A PushBuilder can be customized by chained calls to mutator methods before the push() method is called to initiate an asynchronous push request with the current state of the builder. After the call to push(), the builder may be reused for another push, however the implementation must make it so the path(String), etag(String) and lastModified(String) values are cleared before returning from push(). All other values are retained over calls to push().

    Since:
    4.0

    • Method Detail

      • method

        PushBuilder method​(java.lang.String method)

        Set the method to be used for the push.

        Any non-empty String may be used for the method.

        Parameters:
        method - the method to be used for the push.
        Returns:
        this builder.
        Throws:
        java.lang.NullPointerException - if the argument is null
        java.lang.IllegalArgumentException - if the argument is the empty String

      • queryString

        PushBuilder queryString​(java.lang.String queryString)
        Set the query string to be used for the push. Will be appended to any query String included in a call to path(String). Any duplicate parameters must be preserved. This method should be used instead of a query in path(String) when multiple push() calls are to be made with the same query string.
        Parameters:
        queryString - the query string to be used for the push.
        Returns:
        this builder.

      • sessionId

        PushBuilder sessionId​(java.lang.String sessionId)
        Set the SessionID to be used for the push. The session ID will be set in the same way it was on the associated request (ie as a cookie if the associated request used a cookie, or as a url parameter if the associated request used a url parameter). Defaults to the requested session ID or any newly assigned session id from a newly created session.
        Parameters:
        sessionId - the SessionID to be used for the push.
        Returns:
        this builder.

      • conditional

        PushBuilder conditional​(boolean conditional)
        Set if the request is to be conditional. If the request is conditional, any available values from etag(String) or lastModified(String) will be set in the appropriate headers. If the request is not conditional, then etag and lastModified values are ignored. Defaults to true if the associated request was conditional.
        Parameters:
        conditional - true if the push request is conditional
        Returns:
        this builder.

      • setHeader

        PushBuilder setHeader​(java.lang.String name,
                      java.lang.String value)

        Set a header to be used for the push. If the builder has an existing header with the same name, its value is overwritten.

        Parameters:
        name - The header name to set
        value - The header value to set
        Returns:
        this builder.

      • addHeader

        PushBuilder addHeader​(java.lang.String name,
                      java.lang.String value)

        Add a header to be used for the push.

        Parameters:
        name - The header name to add
        value - The header value to add
        Returns:
        this builder.

      • removeHeader

        PushBuilder removeHeader​(java.lang.String name)

        Remove the named header. If the header does not exist, take no action.

        Parameters:
        name - The name of the header to remove
        Returns:
        this builder.

      • path

        PushBuilder path​(java.lang.String path)
        Set the URI path to be used for the push. The path may start with "/" in which case it is treated as an absolute path, otherwise it is relative to the context path of the associated request. There is no path default and path(String) must be called before every call to push(). If a query string is present in the argument path, its contents must be merged with the contents previously passed to queryString(java.lang.String), preserving duplicates.
        Parameters:
        path - the URI path to be used for the push, which may include a query string.
        Returns:
        this builder.

      • etag

        PushBuilder etag​(java.lang.String etag)
        Set the etag to be used for conditional pushes. The etag will be used only if isConditional() is true. Defaults to no etag. The value is nulled after every call to push()
        Parameters:
        etag - the etag to be used for the push.
        Returns:
        this builder.

      • lastModified

        PushBuilder lastModified​(java.lang.String lastModified)
        Set the last modified date to be used for conditional pushes. The last modified date will be used only if isConditional() is true. Defaults to no date. The value is nulled after every call to push()
        Parameters:
        lastModified - the last modified date to be used for the push.
        Returns:
        this builder.

      • push

        void push()
        Push a resource given the current state of the builder, returning immediately without blocking.

        Push a resource based on the current state of the PushBuilder. If isConditional() is true and an etag or lastModified value is provided, then an appropriate conditional header will be generated. If both an etag and lastModified value are provided only an If-None-Match header will be generated. If the builder has a session ID, then the pushed request will include the session ID either as a Cookie or as a URI parameter as appropriate. The builders query string is merged with any passed query string.

        Before returning from this method, the builder has its path, etag and lastModified fields nulled. All other fields are left as is for possible reuse in another push.

        Throws:
        java.lang.IllegalArgumentException - if the method set expects a request body (eg POST)
        java.lang.IllegalStateException - if there was no call to path(java.lang.String) on this instance either between its instantiation or the last call to push() that did not throw an IllegalStateException.

      • getMethod

        java.lang.String getMethod()

      • getQueryString

        java.lang.String getQueryString()

      • getSessionId

        java.lang.String getSessionId()

      • isConditional

        boolean isConditional()

      • getHeaderNames

        java.util.Set<java.lang.String> getHeaderNames()

      • getHeader

        java.lang.String getHeader​(java.lang.String name)

      • getPath

        java.lang.String getPath()

      • getEtag

        java.lang.String getEtag()

      • getLastModified

        java.lang.String getLastModified()