Class GzipHandler

java.lang.Object
org.eclipse.jetty.util.component.AbstractLifeCycle
org.eclipse.jetty.util.component.ContainerLifeCycle
org.eclipse.jetty.server.handler.AbstractHandler
org.eclipse.jetty.server.handler.AbstractHandlerContainer
org.eclipse.jetty.server.handler.HandlerWrapper
org.eclipse.jetty.server.handler.gzip.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.

  • Field Details

    • GZIP_HANDLER_ETAGS

      public static final String GZIP_HANDLER_ETAGS
      See Also:

    • GZIP

      public static final String GZIP
      See Also:

    • DEFLATE

      public static final String DEFLATE
      See Also:

    • DEFAULT_MIN_GZIP_SIZE

      public static final int DEFAULT_MIN_GZIP_SIZE
      See Also:

    • BREAK_EVEN_GZIP_SIZE

      public static final int BREAK_EVEN_GZIP_SIZE
      See Also:

    • LOG

      private static final Logger LOG

    • X_CE_GZIP

      private static final HttpField X_CE_GZIP

    • COMMA_GZIP

      private static final Pattern COMMA_GZIP

    • _poolCapacity

      private int _poolCapacity

    • _deflaterPool

      private DeflaterPool _deflaterPool

    • _minGzipSize

      private int _minGzipSize

    • _compressionLevel

      private int _compressionLevel

    • _checkGzExists

      @Deprecated private boolean _checkGzExists
      Deprecated.
      feature will be removed in Jetty 10.x, with no replacement.

    • _syncFlush

      private boolean _syncFlush

    • _inflateBufferSize

      private int _inflateBufferSize

    • _dispatchers

      private EnumSet<javax.servlet.DispatcherType> _dispatchers

    • _agentPatterns

      private final IncludeExclude<String> _agentPatterns

    • _methods

      private final IncludeExclude<String> _methods

    • _paths

      private final IncludeExclude<String> _paths

    • _mimeTypes

      private final IncludeExclude<String> _mimeTypes

    • _vary

      private HttpField _vary

  • Constructor Details

    • GzipHandler

      public GzipHandler()
      Instantiates a new GzipHandler.

  • Method Details

    • addExcludedAgentPatterns

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

    • addExcludedMethods

      public void addExcludedMethods(String... methods)
      Add excluded to the HTTP methods filtering.
      Parameters:
      methods - The methods to exclude in compression
      See Also:

    • getDispatcherTypes

      public 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(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(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:

    • addExcludedPaths

      public void addExcludedPaths(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:

    • addIncludedAgentPatterns

      public void addIncludedAgentPatterns(String... patterns)
      Adds included User-Agents for filtering.
      Parameters:
      patterns - Regular expressions matching user agents to include
      See Also:

    • addIncludedMethods

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

    • 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

      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:

    • addIncludedMimeTypes

      public void addIncludedMimeTypes(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:

    • addIncludedPaths

      public void addIncludedPaths(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 Exception
      Description copied from class: ContainerLifeCycle
      Starts the managed lifecycle beans in the order they were added.
      Overrides:
      doStart in class AbstractHandler
      Throws:
      Exception

    • getCheckGzExists

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

    • getCompressionLevel

      public int getCompressionLevel()

    • getDeflater

      public Deflater getDeflater(Request request, long contentLength)
      Specified by:
      getDeflater in interface GzipFactory

    • getExcludedAgentPatterns

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

    • getExcludedMethods

      public String[] getExcludedMethods()
      Get the current filter list of excluded HTTP methods
      Returns:
      the filter list of excluded HTTP methods
      See Also:

    • getExcludedMimeTypes

      public String[] getExcludedMimeTypes()
      Get the current filter list of excluded MIME types
      Returns:
      the filter list of excluded MIME types
      See Also:

    • getExcludedPaths

      public String[] getExcludedPaths()
      Get the current filter list of excluded Path Specs
      Returns:
      the filter list of excluded Path Specs
      See Also:

    • getIncludedAgentPatterns

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

    • getIncludedMethods

      public String[] getIncludedMethods()
      Get the current filter list of included HTTP Methods
      Returns:
      the filter list of included HTTP methods
      See Also:

    • getIncludedMimeTypes

      public String[] getIncludedMimeTypes()
      Get the current filter list of included MIME types
      Returns:
      the filter list of included MIME types
      See Also:

    • getIncludedPaths

      public String[] getIncludedPaths()
      Get the current filter list of included Path Specs
      Returns:
      the filter list of included Path Specs
      See Also:

    • getMethods

      @Deprecated public 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:

    • 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(String target, Request baseRequest, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) throws 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:
      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(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(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(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(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:

    • setExcludedAgentPatterns

      public void setExcludedAgentPatterns(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:

    • setExcludedMethods

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

    • setExcludedMimeTypes

      public void setExcludedMimeTypes(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:

    • setExcludedPaths

      public void setExcludedPaths(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:

    • setIncludedAgentPatterns

      public void setIncludedAgentPatterns(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:

    • setIncludedMethods

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

    • setIncludedMimeTypes

      public void setIncludedMimeTypes(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:

    • setIncludedPaths

      public void setIncludedPaths(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:

    • 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(String csvMethods)
      Set the included filter list of HTTP Methods (replacing any previously set)
      Parameters:
      csvMethods - the list of methods, CSV format
      See Also:

    • getIncludedMethodList

      public 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:

    • setExcludedMethodList

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

    • getExcludedMethodList

      public 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:

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

    • toString

      public String toString()
      Overrides:
      toString in class AbstractLifeCycle