Class GzipHandler

  • All Implemented Interfaces:
    Handler, GzipFactory, HandlerContainer, Container, Destroyable, Dumpable, Dumpable.DumpableContainer, LifeCycle

    public class GzipHandler
    extends HandlerWrapper
    implements GzipFactory
    A Handler that can dynamically GZIP uncompress requests, and compress responses.

    The GzipHandler can be applied to the entire server (a gzip.mod is included in the jetty-home) or it may be applied to individual contexts.

    Both Request uncompress and Response compress are gated by a configurable DispatcherType check on the GzipHandler. (This is similar in behavior to a Filter configuration you would find in a Servlet Descriptor file (WEB-INF/web.xml)
    (Default: DispatcherType.REQUEST).

    Requests with a Content-Encoding header with the value gzip will be uncompressed by a GzipHttpInputInterceptor for any API that uses ServletRequest.getInputStream() or ServletRequest.getReader().

    Response compression has a number of checks before GzipHandler will perform compression.

    1. Does the request contain a Accept-Encoding header that specifies gzip value?
    2. Is the HttpServletRequest.getMethod() allowed by the configured HTTP Method Filter.
      (Default: GET)
    3. Is the incoming Path allowed by the configured Path Specs filters?
      (Default: all paths are allowed)
    4. Is the Request User-Agent allowed by the configured User-Agent filters?
      (Default: MSIE 6 is excluded)
    5. Is the Response Content-Length header present, and does its value meet the minimum gzip size requirements (default 32 bytes)?
    6. Is the Request Accept header present and does it contain the required gzip value?

    When you encounter a configurable filter in the GzipHandler (method, paths, user-agent, mime-types, etc) that has both Included and Excluded values, note that the Included values always win over the Excluded values.

    Important note about Default Values: It is important to note that the GzipHandler will automatically configure itself from the MimeType present on the Server, System, and Contexts and the ultimate set of default values for the various filters (paths, methods, mime-types, etc) can be influenced by the available mime types to work with.

    ETag (or Entity Tag) information: any Request headers for If-None-Match or If-Match will be evaluated by the GzipHandler to determine if it was involved in compression of the response earlier. This is usually present as a --gzip suffix on the ETag that the Client User-Agent is tracking and handed to the Jetty server. The special --gzip suffix on the ETag is how GzipHandler knows that the content passed through itself, and this suffix will be stripped from the Request header values before the request is sent onwards to the specific webapp / servlet endpoint for handling. If a ETag is present in the Response headers, and GzipHandler is compressing the contents, it will add the --gzip suffix before the Response headers are committed and sent to the User Agent. Note that the suffix used is determined by CompressedContentFormat.ETAG_SEPARATOR

    This implementation relies on an Jetty internal HttpOutput.Interceptor mechanism to allow for effective and efficient compression of the response on all Output API usages:

    • ServletOutputStream - Obtained from ServletResponse.getOutputStream() using the traditional Blocking I/O techniques
    • WriteListener - Provided to ServletOutputStream.setWriteListener(javax.servlet.WriteListener) using the new (since Servlet 3.1) Async I/O techniques
    • PrintWriter - Obtained from ServletResponse.getWriter() using Blocking I/O techniques

    Historically the compression of responses were accomplished via Servlet Filters (eg: GzipFilter) and usage of HttpServletResponseWrapper. Since the introduction of Async I/O in Servlet 3.1, this older form of Gzip support in web applications has been problematic and bug ridden.

    • Constructor Detail

      • GzipHandler

        public GzipHandler()
        Instantiates a new GzipHandler.
    • Method Detail

      • doStart

        protected void doStart()
                        throws java.lang.Exception
        Description copied from class: ContainerLifeCycle
        Starts the managed lifecycle beans in the order they were added.
        Overrides:
        doStart in class AbstractHandler
        Throws:
        AbstractLifeCycle.StopException - If thrown, the lifecycle will immediately be stopped.
        java.lang.Exception - If there was a problem starting. Will cause a transition to FAILED state
      • doStop

        protected void doStop()
                       throws java.lang.Exception
        Description copied from class: ContainerLifeCycle
        Stops the managed lifecycle beans in the reverse order they were added.
        Overrides:
        doStop in class AbstractHandler
        Throws:
        java.lang.Exception - If there was a problem stopping. Will cause a transition to FAILED state
      • getVary

        public HttpField getVary()
        Returns:
        The VARY field to use.
      • setVary

        public void setVary​(HttpField vary)
        Parameters:
        vary - The VARY field to use. It if is not an instance of PreEncodedHttpField, then it will be converted to one.
      • addExcludedMethods

        public void addExcludedMethods​(java.lang.String... methods)
        Add excluded to the HTTP methods filtering.
        Parameters:
        methods - The methods to exclude in compression
        See Also:
        addIncludedMethods(String...)
      • getDispatcherTypes

        public java.util.EnumSet<javax.servlet.DispatcherType> getDispatcherTypes()
        Get the Set of DispatcherType that this Filter will operate on.
        Returns:
        the set of DispatcherType this filter will operate on
      • setDispatcherTypes

        public void setDispatcherTypes​(java.util.EnumSet<javax.servlet.DispatcherType> dispatchers)
        Set of supported DispatcherType that this filter will operate on.
        Parameters:
        dispatchers - the set of DispatcherType that this filter will operate on
      • setDispatcherTypes

        public void setDispatcherTypes​(javax.servlet.DispatcherType... dispatchers)
        Set the list of supported DispatcherType that this filter will operate on.
        Parameters:
        dispatchers - the list of DispatcherType that this filter will operate on
      • addExcludedMimeTypes

        public void addExcludedMimeTypes​(java.lang.String... types)
        Adds excluded MIME types for response filtering.

        Deprecation Warning: For backward compatibility the MIME types parameters may be comma separated strings, but this will not be supported in future versions of Jetty.

        Parameters:
        types - The mime types to exclude (without charset or other parameters).
        See Also:
        addIncludedMimeTypes(String...)
      • addExcludedPaths

        public void addExcludedPaths​(java.lang.String... pathspecs)
        Adds excluded Path Specs for request filtering.

        There are 2 syntaxes supported, Servlet url-pattern based, and Regex based. This means that the initial characters on the path spec line are very strict, and determine the behavior of the path matching.

        • If the spec starts with '^' the spec is assumed to be a regex based path spec and will match with normal Java regex rules.
        • If the spec starts with '/' then spec is assumed to be a Servlet url-pattern rules path spec for either an exact match or prefix based match.
        • If the spec starts with '*.' then spec is assumed to be a Servlet url-pattern rules path spec for a suffix based match.
        • All other syntaxes are unsupported

        Note: inclusion takes precedence over exclude.

        Parameters:
        pathspecs - Path specs (as per servlet spec) to exclude. If a ServletContext is available, the paths are relative to the context path, otherwise they are absolute.
        For backward compatibility the pathspecs may be comma separated strings, but this will not be supported in future versions.
        See Also:
        addIncludedPaths(String...)
      • addIncludedMethods

        public void addIncludedMethods​(java.lang.String... methods)
        Adds included HTTP Methods (eg: POST, PATCH, DELETE) for filtering.
        Parameters:
        methods - The HTTP methods to include in compression.
        See Also:
        addExcludedMethods(String...)
      • isSyncFlush

        public boolean isSyncFlush()
        Is the Deflater running Deflater.SYNC_FLUSH or not.
        Returns:
        True if Deflater.SYNC_FLUSH is used, else Deflater.NO_FLUSH
        See Also:
        setSyncFlush(boolean)
      • setSyncFlush

        public void setSyncFlush​(boolean syncFlush)
        Set the Deflater flush mode to use. Deflater.SYNC_FLUSH should be used if the application wishes to stream the data, but this may hurt compression performance.
        Parameters:
        syncFlush - True if Deflater.SYNC_FLUSH is used, else Deflater.NO_FLUSH
        See Also:
        isSyncFlush()
      • addIncludedMimeTypes

        public void addIncludedMimeTypes​(java.lang.String... types)
        Add included MIME types for response filtering
        Parameters:
        types - The mime types to include (without charset or other parameters) For backward compatibility the mimetypes may be comma separated strings, but this will not be supported in future versions.
        See Also:
        addExcludedMimeTypes(String...)
      • addIncludedPaths

        public void addIncludedPaths​(java.lang.String... pathspecs)
        Add included Path Specs for filtering.

        There are 2 syntaxes supported, Servlet url-pattern based, and Regex based. This means that the initial characters on the path spec line are very strict, and determine the behavior of the path matching.

        • If the spec starts with '^' the spec is assumed to be a regex based path spec and will match with normal Java regex rules.
        • If the spec starts with '/' then spec is assumed to be a Servlet url-pattern rules path spec for either an exact match or prefix based match.
        • If the spec starts with '*.' then spec is assumed to be a Servlet url-pattern rules path spec for a suffix based match.
        • All other syntaxes are unsupported

        Note: inclusion takes precedence over exclusion.

        Parameters:
        pathspecs - Path specs (as per servlet spec) to include. If a ServletContext is available, the paths are relative to the context path, otherwise they are absolute
      • getExcludedMethods

        public java.lang.String[] getExcludedMethods()
        Get the current filter list of excluded HTTP methods
        Returns:
        the filter list of excluded HTTP methods
        See Also:
        getIncludedMethods()
      • getExcludedMimeTypes

        public java.lang.String[] getExcludedMimeTypes()
        Get the current filter list of excluded MIME types
        Returns:
        the filter list of excluded MIME types
        See Also:
        getIncludedMimeTypes()
      • getExcludedPaths

        public java.lang.String[] getExcludedPaths()
        Get the current filter list of excluded Path Specs
        Returns:
        the filter list of excluded Path Specs
        See Also:
        getIncludedPaths()
      • getIncludedMethods

        public java.lang.String[] getIncludedMethods()
        Get the current filter list of included HTTP Methods
        Returns:
        the filter list of included HTTP methods
        See Also:
        getExcludedMethods()
      • getIncludedMimeTypes

        public java.lang.String[] getIncludedMimeTypes()
        Get the current filter list of included MIME types
        Returns:
        the filter list of included MIME types
        See Also:
        getExcludedMimeTypes()
      • getIncludedPaths

        public java.lang.String[] getIncludedPaths()
        Get the current filter list of included Path Specs
        Returns:
        the filter list of included Path Specs
        See Also:
        getExcludedPaths()
      • getMinGzipSize

        public int getMinGzipSize()
        Get the minimum size, in bytes, that a response Content-Length must be before compression will trigger.
        Returns:
        minimum response size (in bytes) that triggers compression
        See Also:
        setMinGzipSize(int)
      • getVaryField

        protected HttpField getVaryField()
      • getInflateBufferSize

        public int getInflateBufferSize()
        Get the size (in bytes) of the Inflater buffer used to inflate compressed requests.
        Returns:
        size in bytes of the buffer, or 0 for no inflation.
      • setInflateBufferSize

        public void setInflateBufferSize​(int size)
        Set the size (in bytes) of the Inflater buffer used to inflate comrpessed requests.
        Parameters:
        size - size in bytes of the buffer, or 0 for no inflation.
      • handle

        public void handle​(java.lang.String target,
                           Request baseRequest,
                           javax.servlet.http.HttpServletRequest request,
                           javax.servlet.http.HttpServletResponse response)
                    throws java.io.IOException,
                           javax.servlet.ServletException
        Description copied from interface: Handler
        Handle a request.
        Specified by:
        handle in interface Handler
        Overrides:
        handle in class HandlerWrapper
        Parameters:
        target - The target of the request - either a URI or a name.
        baseRequest - The original unwrapped request object.
        request - The request either as the Request object or a wrapper of that request. The HttpConnection.getCurrentConnection().getHttpChannel().getRequest() method can be used access the Request object if required.
        response - The response as the Response object or a wrapper of that request. The HttpConnection.getCurrentConnection().getHttpChannel().getResponse() method can be used access the Response object if required.
        Throws:
        java.io.IOException - if unable to handle the request or response processing
        javax.servlet.ServletException - if unable to handle the request or response due to underlying servlet issue
      • isMimeTypeGzipable

        public boolean isMimeTypeGzipable​(java.lang.String mimetype)
        Test if the provided MIME type is allowed based on the MIME type filters.
        Specified by:
        isMimeTypeGzipable in interface GzipFactory
        Parameters:
        mimetype - the MIME type to test
        Returns:
        true if allowed, false otherwise
      • isPathGzipable

        protected boolean isPathGzipable​(java.lang.String requestURI)
        Test if the provided Request URI is allowed based on the Path Specs filters.
        Parameters:
        requestURI - the request uri
        Returns:
        whether compressing is allowed for the given the path
      • setExcludedMethods

        public void setExcludedMethods​(java.lang.String... methods)
        Set the excluded filter list of HTTP methods (replacing any previously set)
        Parameters:
        methods - the HTTP methods to exclude
        See Also:
        setIncludedMethods(String...)
      • setExcludedMimeTypes

        public void setExcludedMimeTypes​(java.lang.String... types)
        Set the excluded filter list of MIME types (replacing any previously set)
        Parameters:
        types - The mime types to exclude (without charset or other parameters)
        See Also:
        setIncludedMimeTypes(String...)
      • setExcludedMimeTypesList

        public void setExcludedMimeTypesList​(java.lang.String csvTypes)
        Set the excluded filter list of MIME types (replacing any previously set)
        Parameters:
        csvTypes - The list of mime types to exclude (without charset or other parameters), CSV format
        See Also:
        setIncludedMimeTypesList(String)
      • setExcludedPaths

        public void setExcludedPaths​(java.lang.String... pathspecs)
        Set the excluded filter list of Path specs (replacing any previously set)
        Parameters:
        pathspecs - Path specs (as per servlet spec) to exclude. If a ServletContext is available, the paths are relative to the context path, otherwise they are absolute.
        See Also:
        setIncludedPaths(String...)
      • setDispatcherTypes

        public void setDispatcherTypes​(java.lang.String... dispatchers)
        Set of supported DispatcherType that this filter will operate on.
        Parameters:
        dispatchers - the set of DispatcherType that this filter will operate on
      • setIncludedMethods

        public void setIncludedMethods​(java.lang.String... methods)
        Set the included filter list of HTTP methods (replacing any previously set)
        Parameters:
        methods - The methods to include in compression
        See Also:
        setExcludedMethods(String...)
      • setIncludedMimeTypes

        public void setIncludedMimeTypes​(java.lang.String... types)
        Set the included filter list of MIME types (replacing any previously set)
        Parameters:
        types - The mime types to include (without charset or other parameters)
        See Also:
        setExcludedMimeTypes(String...)
      • setIncludedMimeTypesList

        public void setIncludedMimeTypesList​(java.lang.String csvTypes)
        Set the included filter list of MIME types (replacing any previously set)
        Parameters:
        csvTypes - The list of mime types to include (without charset or other parameters), CSV format
        See Also:
        setExcludedMimeTypesList(String)
      • setIncludedPaths

        public void setIncludedPaths​(java.lang.String... pathspecs)
        Set the included filter list of Path specs (replacing any previously set)
        Parameters:
        pathspecs - Path specs (as per servlet spec) to include. If a ServletContext is available, the paths are relative to the context path, otherwise they are absolute
        See Also:
        setExcludedPaths(String...)
      • setMinGzipSize

        public void setMinGzipSize​(int minGzipSize)
        Set the minimum response size to trigger dynamic compression.

        Sizes below BREAK_EVEN_GZIP_SIZE will result a compressed response that is larger than the original data.

        Parameters:
        minGzipSize - minimum response size in bytes (not allowed to be lower then BREAK_EVEN_GZIP_SIZE)
      • setIncludedMethodList

        public void setIncludedMethodList​(java.lang.String csvMethods)
        Set the included filter list of HTTP Methods (replacing any previously set)
        Parameters:
        csvMethods - the list of methods, CSV format
        See Also:
        setExcludedMethodList(String)
      • getIncludedMethodList

        public java.lang.String getIncludedMethodList()
        Get the included filter list of HTTP methods in CSV format
        Returns:
        the included filter list of HTTP methods in CSV format
        See Also:
        getExcludedMethodList()
      • setExcludedMethodList

        public void setExcludedMethodList​(java.lang.String csvMethods)
        Set the excluded filter list of HTTP Methods (replacing any previously set)
        Parameters:
        csvMethods - the list of methods, CSV format
        See Also:
        setIncludedMethodList(String)
      • getExcludedMethodList

        public java.lang.String getExcludedMethodList()
        Get the excluded filter list of HTTP methods in CSV format
        Returns:
        the excluded filter list of HTTP methods in CSV format
        See Also:
        getIncludedMethodList()
      • getDeflaterPool

        public DeflaterPool getDeflaterPool()
        Get the DeflaterPool being used. The default value of this is null before starting, but after starting if it is null it will be set to the default DeflaterPool which is stored as a bean on the server.
        Returns:
        the DeflaterPool being used.
      • getInflaterPool

        public InflaterPool getInflaterPool()
        Get the InflaterPool being used. The default value of this is null before starting, but after starting if it is null it will be set to the default InflaterPool which is stored as a bean on the server.
        Returns:
        the DeflaterPool being used.
      • setDeflaterPool

        public void setDeflaterPool​(DeflaterPool deflaterPool)
        Set the DeflaterPool to be used. This should be called before starting. If this value is null when starting the default pool will be used from the server.
        Parameters:
        deflaterPool - the DeflaterPool to use.
      • setInflaterPool

        public void setInflaterPool​(InflaterPool inflaterPool)
        Set the InflaterPool to be used. This should be called before starting. If this value is null when starting the default pool will be used from the server.
        Parameters:
        inflaterPool - the InflaterPool to use.
      • getDeflaterPoolCapacity

        @Deprecated
        public int getDeflaterPoolCapacity()
        Deprecated.
        for custom DeflaterPool settings use setDeflaterPool(DeflaterPool).
        Gets the maximum number of Deflaters that the DeflaterPool can hold.
        Returns:
        the Deflater pool capacity
      • setDeflaterPoolCapacity

        @Deprecated
        public void setDeflaterPoolCapacity​(int capacity)
        Deprecated.
        for custom DeflaterPool settings use setDeflaterPool(DeflaterPool).
        Sets the maximum number of Deflaters that the DeflaterPool can hold.
      • getInflaterPoolCapacity

        @Deprecated
        public int getInflaterPoolCapacity()
        Deprecated.
        for custom InflaterPool settings use setInflaterPool(InflaterPool).
        Gets the maximum number of Inflaters that the InflaterPool can hold.
        Returns:
        the Inflater pool capacity
      • setInflaterPoolCapacity

        @Deprecated
        public void setInflaterPoolCapacity​(int capacity)
        Deprecated.
        for custom InflaterPool settings use setInflaterPool(InflaterPool).
        Sets the maximum number of Inflaters that the InflaterPool can hold.