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

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(jakarta.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

  • Constructor Details

    • GzipHandler

      public GzipHandler()
      Instantiates a new GzipHandler.

  • Method Details

    • 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:
      AbstractLifeCycle.StopException - If thrown, the lifecycle will immediately be stopped.
      Exception - If there was a problem starting. Will cause a transition to FAILED state

    • doStop

      protected void doStop() throws Exception
      Description copied from class: ContainerLifeCycle
      Stops the managed lifecycle beans in the reverse order they were added.
      Overrides:
      doStop in class AbstractHandler
      Throws:
      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(String... methods)
      Add excluded to the HTTP methods filtering.
      Parameters:
      methods - The methods to exclude in compression
      See Also:

    • getDispatcherTypes

      public EnumSet<jakarta.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<jakarta.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(jakarta.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:

    • addExcludedInflationPaths

      public void addExcludedInflationPaths(String... pathspecs)
      Adds excluded Path Specs for request filtering on request inflation.

      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:

    • 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

    • addIncludedInflationPaths

      public void addIncludedInflationPaths(String... pathspecs)
      Add included Path Specs for filtering on request inflation.

      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

    • getDeflaterEntry

      public CompressionPool<Deflater>.Entry getDeflaterEntry(Request request, long contentLength)
      Specified by:
      getDeflaterEntry in interface GzipFactory

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

    • getExcludedInflationPaths

      public String[] getExcludedInflationPaths()
      Get the current filter list of excluded Path Specs for request inflation.
      Returns:
      the filter list of excluded Path Specs
      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:

    • getIncludedInflationPaths

      public String[] getIncludedInflationPaths()
      Get the current filter list of included Path Specs for request inflation.
      Returns:
      the filter list of included Path Specs
      See Also:

    • 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, jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response) throws IOException, jakarta.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
      jakarta.servlet.ServletException - if unable to handle the request or response due to underlying servlet issue

    • 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

    • isPathInflatable

      protected boolean isPathInflatable(String requestURI)
      Test if the provided Request URI is allowed to be inflated based on the Path Specs filters.
      Parameters:
      requestURI - the request uri
      Returns:
      whether decompressing is allowed for the given the path.

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

    • setExcludedMimeTypesList

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

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

    • setExcludedInflatePaths

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

    • setDispatcherTypes

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

    • setIncludedMimeTypesList

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

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

    • setIncludedInflatePaths

      public void setIncludedInflatePaths(String... pathspecs)
      Set the included filter list of Path specs (replacing any previously set)
      Parameters:
      pathspecs - Path specs (as per servlet spec) to include for inflation. 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:

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

    • toString

      public String toString()
      Overrides:
      toString in class AbstractLifeCycle