Module org.omnifaces
Package org.omnifaces.filter

Class CompressedResponseFilter

  • All Implemented Interfaces:
    Filter
    public class CompressedResponseFilter
extends HttpFilter

    The CompressedResponseFilter will apply compression on HTTP responses whenever applicable. It will greatly reduce the HTTP response size when applied on character based responses like HTML, CSS and JS, on average it can save up to ~70% of bandwidth.

    While HTTP response compression is normally to be configured in the servlet container (e.g. <Context compression="on"> in Tomcat, or <property name="compression" value="on"> in GlassFish), this filter allows a servlet container independent way of configuring HTTP response compression and also allows enabling HTTP response compression anyway on 3rd party hosts where you have no control over servlet container configuration.

    Compression algorithms

    Currently three compression algorithms are supported: Brotli, GZIP and Deflate. When the client supports Brotli compression and one of the classes specified in CompressedHttpServletResponse.Algorithm.BROTLI is present in the runtime classpath, then Brotli will be used. Else when the client supports GZIP compression, then GZIP will be used via the standard JDK GZIPOutputStream. As last resort, when the client supports Deflate compression, then Deflate will be used via the standard JDK DeflaterOutputStream.

    Installation

    To get it to run, map this filter on the desired <url-pattern> or maybe even on the <servlet-name> of the FacesServlet. A Filter is by default dispatched on REQUEST only, you might want to explicitly add the ERROR dispatcher to get it to run on error pages as well. 

     <filter>
     <filter-name>compressedResponseFilter</filter-name>
     <filter-class>org.omnifaces.filter.CompressedResponseFilter</filter-class>
 </filter>
 <filter-mapping>
     <filter-name>compressedResponseFilter</filter-name>
     <url-pattern>/*</url-pattern>
     <dispatcher>REQUEST</dispatcher>
     <dispatcher>ERROR</dispatcher>
 </filter-mapping>

    Mapping on /* may be too global as some types of requests (comet, long polling, etc) cannot be compressed. In that case, consider mapping it to the exact <servlet-name> of the FacesServlet in the same web.xml. 

     <filter>
     <filter-name>compressedResponseFilter</filter-name>
     <filter-class>org.omnifaces.filter.CompressedResponseFilter</filter-class>
 </filter>
 <filter-mapping>
     <filter-name>compressedResponseFilter</filter-name>
     <servlet-name>facesServlet</servlet-name>
     <dispatcher>REQUEST</dispatcher>
     <dispatcher>ERROR</dispatcher>
 </filter-mapping>

    Configuration (optional)

    This filter supports three initialization parameters which needs to be placed in <filter> element as follows: 

     <init-param>
     <description>The preferred algorithm. Must be one of Brotli, GZIP or Deflate (case insensitive). Defaults to automatic.</description>
     <param-name>algorithm</param-name>
     <param-value>GZIP</param-value>
 </init-param>
 <init-param>
     <description>The threshold size in bytes. Must be a number between 0 and 9999. Defaults to 150.</description>
     <param-name>threshold</param-name>
     <param-value>150</param-value>
 </init-param>
 <init-param>
     <description>The mimetypes which needs to be compressed. Must be a commaseparated string. Defaults to the below values.</description>
     <param-name>mimetypes</param-name>
     <param-value>
         text/plain, text/html, text/xml, text/css, text/javascript, text/csv, text/rtf,
         application/xml, application/xhtml+xml, application/javascript, application/x-javascript, application/json,
         image/svg+xml
     </param-value>
 </init-param>

    The default algorithm is thus automatic. It will then find the best matching algorithm depending on whether the algorithm is available and the client supports it, in this order: Brotli, GZIP or Deflate. In case you explicitly specify a value of Brotli, and it is not available, then an exception will be thrown. In case you happen to have Brotli libraries (transitively) included for other purposes and you actually want to use GZIP, then specify a value of GZIP.

    The default threshold is thus 150 bytes. This means that when the response is not larger than 150 bytes, then it will not be compressed. Only when it's larger than 150 bytes, then it will be compressed. A threshold of between 150 and 1000 bytes is recommended due to overhead and latency of compression/decompression. The value must be a number between 0 and 9999. A value larger than 2000 is not recommended.

    The mimetypes represents a comma separated string of mime types which needs to be compressed. It's exactly that value which appears in the Content-Type header of the response. The in the above example mentioned mime types are already the default values. Note that HTTP response compression does not have any benefit when applied on binary mimetypes like images, office documents, PDF files, etcetera. So setting it for them is not recommended.

    Since:
    4.5
    Author:
    Bauke Scholtz
    See Also:
    CompressedHttpServletResponse, HttpServletResponseOutputWrapper, ResettableBuffer, ResettableBufferedOutputStream, ResettableBufferedWriter, HttpFilter