Usage

The ContentNegotiationFilter class can be used to provide true content negotiation based on the preferred content types of both the user agent and the server. It does not require any further development to be used. It can be configured through an XML file and supports some filter parameters.

The XML file allows the variants to be configured. The behaviour of the filter when a request is received is determined through these variants. Each variant is specified by a URL pattern, a list of content types, a list of languages and an output. The URL pattern is matched to the requested resource, the URL pattern supports Java's regular expression evaluation. The content types and the languages are a list of qualified values with the same syntax as the accept-type and accept-language header elements of a HTTP request. The output describes what should happen if the variant is selected. It may fail and return a 406 response, it may redirect to another location with a specific code, it may forward the request to another servlet or it may respond with a fully customisable header.

The filter can be configured to use any variant source class with the variantSource parameter. A VariantSourceForFilter will be configured with the FilterConfig object passed into the the Filter through the init method. A ConfigurableVariantSource will be configured with the init-params passed in as part of the FilterConfig. The default class is FilterVariantXMLSource. The resource the Filter uses must be configured with the xmlInputResource parameter. The variant source will be cached using the CachedVariantSource.

Variant Sources

The VariantSource interface provides an source of variants. The ConfigurableVariantSource and the VariantSourceForFilter allow the variant source to be configured. The InputVariantSource allows the an input stream to read the variants to be specified. The BaseVariantXMLSource provides a variant source that parses XML it reads from an input stream. The FilterVariantXMLSource is a variant source that can be configured by a filter and parses XML to a variant list. The CachedVariantSource caches the variants and prevents multiple calls to the underlying variant source.

Composition is used to extend the variant sources. The CachedVariantSource can be applied to any other variant source. The FilterVariantXMLSource builds on the BaseVariantXMLSource by allowing the VariantSAXHandler and the input stream to be configured from a filter.

The BaseVariantXMLSource uses a SAX parser and can be configured with a VariantSAXHandler object that constructs the variants from the XML. This allows different XML formats to be parsed.