Package org.eclipse.jetty.server.handler.gzip

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

      • addExcludedAgentPatterns

        public void addExcludedAgentPatterns​(java.lang.String... patterns)
        Add excluded to the User-Agent filtering.
        Parameters:
        patterns - Regular expressions matching user agents to exclude
        See Also:
        addIncludedAgentPatterns(String...)

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

      • addIncludedAgentPatterns

        public void addIncludedAgentPatterns​(java.lang.String... patterns)
        Adds included User-Agents for filtering.
        Parameters:
        patterns - Regular expressions matching user agents to include
        See Also:
        addExcludedAgentPatterns(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

      • 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:
        java.lang.Exception

      • getCheckGzExists

        @Deprecated
public boolean getCheckGzExists()
        Deprecated.
        feature will be removed in Jetty 10.x, with no replacement.

      • getCompressionLevel

        public int getCompressionLevel()

      • getDeflater

        public java.util.zip.Deflater getDeflater​(Request request,
                                          long contentLength)
        Specified by:
        getDeflater in interface GzipFactory

      • getExcludedAgentPatterns

        public java.lang.String[] getExcludedAgentPatterns()
        Get the current filter list of excluded User-Agent patterns
        Returns:
        the filter list of excluded User-Agent patterns
        See Also:
        getIncludedAgentPatterns()

      • 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()

      • getIncludedAgentPatterns

        public java.lang.String[] getIncludedAgentPatterns()
        Get the current filter list of included User-Agent patterns
        Returns:
        the filter list of included User-Agent patterns
        See Also:
        getExcludedAgentPatterns()

      • 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()

      • getMethods

        @Deprecated
public java.lang.String[] getMethods()
        Deprecated.
        use getIncludedMethods() instead. (Will be removed in Jetty 10)
        Get the current filter list of included HTTP methods
        Returns:
        the filter list of included HTTP methods

      • 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

      • isAgentGzipable

        protected boolean isAgentGzipable​(java.lang.String ua)
        Test if the provided User-Agent is allowed based on the User-Agent filters.
        Parameters:
        ua - the user agent
        Returns:
        whether compressing is allowed for the given user agent

      • 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

      • recycle

        public void recycle​(java.util.zip.Deflater deflater)
        Specified by:
        recycle in interface GzipFactory

      • setCheckGzExists

        @Deprecated
public void setCheckGzExists​(boolean checkGzExists)
        Deprecated.
        feature will be removed in Jetty 10.x, with no replacement.
        Set the Check if *.gz file for the incoming file exists.
        Parameters:
        checkGzExists - whether to check if a static gz file exists for the resource that the DefaultServlet may serve as precompressed.

      • setCompressionLevel

        public void setCompressionLevel​(int compressionLevel)
        Set the Compression level that Deflater uses.
        Parameters:
        compressionLevel - The compression level to use to initialize Deflater.setLevel(int)
        See Also:
        Deflater.setLevel(int)

      • setExcludedAgentPatterns

        public void setExcludedAgentPatterns​(java.lang.String... patterns)
        Set the excluded filter list of User-Agent patterns (replacing any previously set)
        Parameters:
        patterns - Regular expressions list matching user agents to exclude
        See Also:
        setIncludedAgentPatterns(String...)

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

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

      • setIncludedAgentPatterns

        public void setIncludedAgentPatterns​(java.lang.String... patterns)
        Set the included filter list of User-Agent patterns (replacing any previously set)
        Parameters:
        patterns - Regular expressions matching user agents to include
        See Also:
        setExcludedAgentPatterns(String...)

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

      • 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()

      • getDeflaterPoolCapacity

        public int getDeflaterPoolCapacity()
        Gets the maximum number of Deflaters that the DeflaterPool can hold.
        Returns:
        the Deflater pool capacity

      • setDeflaterPoolCapacity

        public void setDeflaterPoolCapacity​(int capacity)
        Sets the maximum number of Deflaters that the DeflaterPool can hold.

      • newDeflaterPool

        protected DeflaterPool newDeflaterPool​(int capacity)