{title:'Encoders', created:'9.0.0'}

The {@link oaj.encoders} package defines an API for handling encoding-based matching of Accept-Encoding/Content-Encoding HTTP headers. It consists of the following classes:

- {@link oaj.encoders.EncoderSet}
- {@link oaj.encoders.Encoder}
  - {@link oaj.encoders.IdentityEncoder}
  - {@link oaj.encoders.GzipEncoder}

##### EncoderSet

The {@link oaj.encoders.EncoderSet} class represents the set of {@link Encoder encoders} keyed by codings. It maintains a set of encoders and the codings that they can handle. The {@link oaj.encoders.EncoderSet#getEncoderMatch(String) getEncoderMatch(String)} and {@link oaj.encoders.EncoderSet#getEncoder(String)} methods are then used to find appropriate encoders for specific Accept-Encoding and Content-Encoding header values.

##### Match ordering

Encoders are tried in the order they appear in the set. The {@link oaj.encoders.EncoderSet.Builder#add(Class...)} / {@link oaj.encoders.EncoderSet.Builder#add(Encoder...)} methods prepend the values to the list to allow them the opportunity to override encoders already in the list.

For example, calling `builder.add(E1.class,E2.class).add(E3.class, E4.class)` will result in the order E3, E4, E1, E2.

##### Example:

| // Create an encoder group with support for gzip compression. | EncoderSet encoders = EncoderSet | .create() | .add(GzipEncoder.class) | .build(); | | // Should return "gzip" | String matchedCoding = encoders.findMatch("compress;q=1.0, gzip;q=0.8, identity;q=0.5, *;q=0"); | | // Get the encoder | Encoder encoder = encoders.getEncoder(matchedCoding);

##### Encoder API

The {@link oaj.encoders.Encoder} interface is used for enabling decompression on requests and compression on responses, such as support for GZIP compression. It is used to wrap input and output streams within compression/decompression streams.

- {@link oaj.encoders.Encoder}
  - {@link oaj.encoders.Encoder#getCodings() getCodings()}
  - {@link oaj.encoders.Encoder#getInputStream(InputStream) getInputStream(InputStream)}
  - {@link oaj.encoders.Encoder#getOutputStream(OutputStream) getOutputStream(OutputStream)}

Encoders are registered with RestServlets through the @Rest(encoders) annotation.