//  ========================================================================
//  Copyright (c) 1995-2016 Mort Bay Consulting Pty. Ltd.
//  ========================================================================
//  All rights reserved. This program and the accompanying materials
//  are made available under the terms of the Eclipse Public License v1.0
//  and Apache License v2.0 which accompanies this distribution.
//
//      The Eclipse Public License is available at
//      http://www.eclipse.org/legal/epl-v10.html
//
//      The Apache License v2.0 is available at
//      http://www.opensource.org/licenses/apache2.0.php
//
//  You may elect to redistribute this code under either of these licenses.
//  ========================================================================

[[gzip-filter]]
=== Gzip Handler

[[gzip-filter-metadata]]
==== Info

* Classname: `org.eclipse.jetty.server.handler.gzip.GzipHandler`
* Maven Artifact: org.eclipse.jetty:jetty-servlets
* Javadoc:
{JDURL}/org/eclipse/jetty/server/handler/gzip/GzipHandler.html
* Xref: {JXURL}/org/eclipse/jetty/server/handler/gzip/GzipHandler.html

[[gzip-filter-usage]]
==== Usage

The Jetty GzipHandler is a compression handler that you can apply to any dynamic resource (servlet). 
It fixes many of the bugs in commonly available compression filters: it works with asynchronous servlets; it handles all ways to set content length. 
We have tested it with Jetty continuations and suspending requests. 
Some user-agents might be excluded from compression to avoid common browser bugs (yes, this means IE!).

The GzipHandler is added to the entire server by the etc/jetty-gzip.xml file from the gzip.mod module. 
It may also be added to individual contexts in a context xml file.

[[gzip-filter-rules]]
==== Gzip Rules

GZIP Handler will gzip or deflate the content of a response if:

* It is mapped to a matching path
* The request method is configured to support gzip
* The request is not from an excluded User-Agent
* accept-encoding header is set to either gzip, deflate or a combination of those
* The response status code is >=200 and <300
* The content length is unknown or more than the minGzipSize initParameter or the minGzipSize is 0(default)
* The content-type does not match an excluded mime-type
* No content-encoding is specified by the resource

If both gzip and deflate are specified in the accept-encoding header, then gzip will be used.

Compressing the content can greatly improve the network bandwidth usage, but at a cost of memory and CPU cycles. 
The link:#default-servlet[DefaultServlet] is capable of serving pre-compressed static content, which saves memory and CPU. 
By default, the GzipHandler will check to see if pre-compressed content exists, and pass the request through to be handled by the DefaultServlet.

[[gzip-filter-init]]
==== Gzip Configuration

minGzipSize::
  Content will only be compressed if content length is either unknown or greater than minGzipSize.
checkGzExists::
  True by default. If set to false, the handler will not check for pre-compressed content.
compressionLevel::
  The compression level used for deflate compression. (0-9).
includedMethods::
  List of HTTP methods to compress. If not set, only GET requests are compressed.
includedMimeTypes::
  List of mime types to compress.
excludedMimeTypes::
  List of mime types not to compress.
excludedAgentPatterns::
  A list of regex patterns for User-Agent names from which requests should not be compressed.
excludedPaths::
  List of paths to exclude from compression. 
  Does a String.startsWith(String) comparison to check if the path matches.
  If it does match -> no compression. 
  To match subpaths use excludePathPatterns instead.
includedPaths::
  List of paths to consider for compression.
includePaths::
  List of paths to definitely consider for compression.
