com.planetj.servlet.filter.compression
Class CompressingFilter

java.lang.Object
  com.planetj.servlet.filter.compression.CompressingFilter

All Implemented Interfaces:

javax.servlet.Filter

public final class CompressingFilter
extends java.lang.Object
implements javax.servlet.Filter

This filter can, based on HTTP headers in a HttpServletRequest, compress data written to the HttpServletResponse, or decompress data read from the request. When supported by the client browser, this can potentially greatly reduce the number of bytes written across the network from and to the client. As a Filter, this class can also be easily added to any J2EE 1.3+ web application.

Features

Why might you want to use this solution compared to others?

1. Little in-memory buffering
2. Handles compressed requests too
3. Selective compression based on content type, size, or user agent
4. Exposes compression statistics

Installation

1. Add the pjl-comp-filter-XX.jar file containing CompressingFilter to your web application's WEB-INF/lib directory.
2. Add the following entries to your web.xml deployment descriptor:
   

    <filter>
     <filter-name>CompressingFilter</filter-name>
     <filter-class>com.planetj.servlet.filter.compression.CompressingFilter</filter-class>
    </filter>
    ...
    <filter-mapping>
     <filter-name>CompressingFilter</filter-name>
     <url-pattern>/*</url-pattern>
    </filter-mapping>
    

Configuration

CompressingFilter supports the following parameters:

• debug (optional): if set to "true", additional debug information will be written to the servlet log. Defaults to false.
• compressionThreshold (optional): sets the size of the smallest response that will be compressed, in bytes. That is, if less than compressionThreshold bytes are written to the response, it will not be compressed and the response will go to the client unmodified. If 0, compression always begins immediately. Defaults to 1024.
• statsEnabled (optional): enables collection of statistics. See CompressingFilterStats. Defaults to false.
• includeContentTypes (optional): if specified, this is treated as a comma-separated list of content types (e.g. text/html,text/xml). The filter will attempt to only compress responses which specify one of these values as its content type, for example via ServletResponse.setContentType(String). Note that the filter does not know the response content type at the time it is applied, and so must apply itself and later attempt to disable compression when content type has been set. This will fail if the response has already been committed. Also note that this parameter cannot be specified if excludeContentTypes is too.
• excludeContentTypes (optional): same as above, but specifies a list of content types to not compress. Everything else will be compressed. However note that any content type that indicates a compressed format (e.g. application/gzip, application/x-compress) will not be compressed in any event.
• includePathPatterns (optional): if specified, this is treated as a comma-separated list of regular expressions (of the type accepted by Pattern) which match exactly those paths which should be compressed by this filter. Anything else will not be compressed. One can also merely apply the filter to a subset of all URIs served by the web application using standard filter-mapping elements in web.xml; this element provides more fine-grained control for when that mechanism is insufficient. "Paths" here means values returned by HttpServletRequest.getRequestURI(). Note that the regex must match the filename exactly; pattern "static" does not match everything containing the string "static. Use ".*static.*" for that, for example. This cannot be specified if excludeFileTypes is too.
• excludePathPatterns (optional): same as above, but specifies a list of patterns which match paths that should not be compressed. Everything else will be compressed.
• includeUserAgentPatterns (optional): Like includePathPatterns. Only requests with User-Agent headers whose value matches one of these regular expressions will be compressed. Can't be specified if excludeUserAgentPatterns is too.
• excludeUserAgentPatterns (optional): as above, requests whose User-Agent header matches one of these patterns will not be compressed.
• javaUtilLogger (optional): if specified, the named java.util.logging.Logger will also receive log messages from this filter.
• jakartaCommonsLogger (optional): if specified the named Jakarta Commons Log will also receive log messages from this filter.

These values are configured in web.xml as well with init-param elements:

 <filter>
  <filter-name>CompressingFilter</filter-name>
  <filter-class>com.planetj.servlet.filter.compression.CompressingFilter</filter-class>
  <init-param>
   <param-name>debug</param-name>
   <param-value>true</param-value>
  </init-param>
 </filter>
 

Supported compression algorithms

Response

This filter supports the following compression algorithms when compressing data to the repsonse, as specified in the "Accept-Encoding" HTTP request header:

• gzip
• x-gzip
• compress
• x-compress
• deflate
• identity (that is, no compression)

Request

This filter supports the following compression algorithms when decompressing data from the request body, as specified in the "Content-Encoding" HTTP request header:

• gzip
• x-gzip
• compress
• x-compress
• deflate
• identity

Controlling runtime behavior

An application may force the encoding / compression used by setting an "Accept-Encoding" value into the request as an attribute under the key FORCE_ENCODING_KEY. Obviously this has to be set upstream from the filter, not downstream.

Caveats and Notes

The filter requires Java 5 and J2EE 1.4 or better.

Note that if this filter decides that it should try to compress the response, it will close the response (whether or not it ends up compressing the response). No more can be written to the response after this filter has been applied; this should never be necessary anyway. Put this filter ahead of any filters that might try to write to the repsonse, since presumably you want this content compressed too anyway.

If a OutputStream.flush() occurs before the filter has decided whether to compress or not, it will be forced into compression mode.

The filter will not compress if the response sets Cache-Control: no-transform header in the response.

The filter attempts to modify the ETag response header, if present, when compressing. This is because the compressed response must be considered a separate entity by caches. It simply appends, for example, "-gzip" to the ETag header value when compressing with gzip. This is not guaranteed to work in all containers, in the sense that some containers may not properly associated this ETag with the compressed content and simply return the response again.

The filter always sets the Vary response header to indicate that a different response may be returned based on the Accept-Encoding header of the request.

Since:

1.0

Author:

Sean Owen

Field Summary

static java.lang.String	COMPRESSED_KEY A request attribute is set under this key with a non-null value if this filter has applied compression to the response.
static java.lang.String	FORCE_ENCODING_KEY One may force the filter to use a particular encoding by setting its value as an attribute of the ServletRequest passed to this filter, under this key.

Constructor Summary

CompressingFilter()

Method Summary

void	destroy()
void	doFilter(javax.servlet.ServletRequest request, javax.servlet.ServletResponse response, javax.servlet.FilterChain chain)
void	init(javax.servlet.FilterConfig config)
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

FORCE_ENCODING_KEY

public static final java.lang.String FORCE_ENCODING_KEY

One may force the filter to use a particular encoding by setting its value as an attribute of the ServletRequest passed to this filter, under this key. The value should be a valid "Accept-Encoding" header value, like "gzip". Specify "identity" to force no compression.

Since:

1.2

See Also:

Constant Field Values

COMPRESSED_KEY

public static final java.lang.String COMPRESSED_KEY

A request attribute is set under this key with a non-null value if this filter has applied compression to the response. Upstream filters may check for this flag. Note that if the response has been compressed, then it will be closed by the time this filter finishes as well.

Since:

1.2

See Also:

Constant Field Values

Constructor Detail

CompressingFilter

public CompressingFilter()

Method Detail

init

public void init(javax.servlet.FilterConfig config)
          throws javax.servlet.ServletException

Specified by:

init in interface javax.servlet.Filter

Throws:

javax.servlet.ServletException

doFilter

public void doFilter(javax.servlet.ServletRequest request,
                     javax.servlet.ServletResponse response,
                     javax.servlet.FilterChain chain)
              throws java.io.IOException,
                     javax.servlet.ServletException

Specified by:

doFilter in interface javax.servlet.Filter

Throws:

java.io.IOException

javax.servlet.ServletException

destroy

public void destroy()

Specified by:

destroy in interface javax.servlet.Filter

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object