This topic provides information on content negotiation, type-map
files, MultiViews, negotiation methods, dimensions of negotiation, negotiation
algorithm, media types, and wildcards.
Important: Information
for this topic supports the latest PTF levels for HTTP Server for i5/OS .
It is recommended that you install the latest PTFs to upgrade to the latest
level of the HTTP Server for i5/OS. Some of the topics documented here are
not available prior to this update. See
http://www.ibm.com/servers/eserver/iseries/software/http/services/service.htm 
for more information.
A resource may be available in several different representations. For example,
it might be available in different languages or different media types, or
a combination. One way of selecting the most appropriate choice is to give
the user an index page, and let them select; however it is often possible
for the server to choose automatically. This works because browsers can send
as part of each request information about what representations it prefers.
For example, a browser could indicate that it would like to see information
in French, if possible, else English will do. Browsers indicate their preferences
by headers in the request. To request only French representations, the browser
would send:
Accept-Language: fr
Note that this preference will only be applied when there is a choice of
representations and they vary by language.
As an example of a more complex request, this browser has been configured
to accept French and English, but prefers French, and to accept various media
types, preferring HTML over plain text or other text types, and preferring
GIF or JPEG over other media types, but also allowing any other media type
as a last resort:
Accept-Language: fr; q=1.0, en; q=0.5
Accept: text/html; q=1.0, text/*; q=0.8, image/gif; q=0.6,
image/jpeg; q=0.6, image/*; q=0.5, */*; q=0.1
The HTTP Server (powered by Apache) supports 'server driven' content negotiation,
as defined in the HTTP/1.1 specification. It fully supports the Accept, Accept-Language,
Accept-Charset and Accept-Encoding request headers. The HTTP Server (powered
by Apache) also supports 'transparent' content negotiation, which is an experimental
negotiation protocol defined in RFC 2295 and RFC 2296. It does not offer support
for 'feature negotiation' as defined in these RFCs.
A resource is a conceptual entity identified by a URI (RFC 2396).
The HTTP Server (powered by Apache) provides access to representations of
the resource(s) within its namespace, with each representation in the form
of a sequence of bytes with a defined media type, character set, encoding,
or other. Each resource may be associated with zero, one, or more than one
representation at any given time. If multiple representations are available,
the resource is referred to as negotiable and each of its representations
is termed a variant. The ways in which the variants for a negotiable
resource vary are called the dimensions of negotiation.
Using a type-map file
A type map is a document which is associated with the handler named type-map
(or, for backwards-compatibility with older HTTP Server (powered by Apache)
configurations, the mime type application/x-type-map). Note that to use this
feature, you must have a handler set in the configuration that defines a file
suffix as type-map; this is best done with an AddHandler in the server configuration
file, as shown below.
AddHandler type-map var
Type map files have an entry for each available variant; these entries
consist of contiguous HTTP-format header lines. Entries for different variants
are separated by blank lines. Blank lines are illegal within an entry. It
is conventional to begin a map file with an entry for the combined entity
as a whole (although this is not required, and if present will be ignored).
An example map file is:
URI: jkl
URI: jkl.en.html
Content-type: text/html
Content-language: en
URI: jkl.fr.de.html
Content-type: text/html;charset=iso-8859-2
Content-language: fr, de
If the variants have different source qualities, that may be indicated
by the "qs" parameter to the media type, as in this picture (available as
jpeg, gif, or ASCII-art):
URI: jkl
URI: jkl.jpeg
Content-type: image/jpeg; Qs=0.8
URI: jkl.gif
Content-type: image/gif; Qs=0.5
URI: jkl.txt
Content-type: text/plain; Qs=0.01
The "Qs" value can vary in the range 0.000 to 1.000. Note that any variant
with a "Qs" value of 0.000 will never be chosen. Variants with no "Qs" parameter
value are given a "Qs" factor of 1.0. The "Qs" parameter indicates the relative
'quality' of this variant compared to the other available variants, independent
of the client's capabilities. For example, a jpeg file is usually of higher
source quality than an ASCII file if its attempting to represent a photograph;
however, if the resource being represented is an original ASCII art, then
an ASCII representation would have a higher source quality than a jpeg representation.
A "Qs" value is therefore specific to a given variant depending on the nature
of the resource it represents.
The full list of headers recognized are:
- URI
- The uri of the file containing the variant (of the given media type, encoded
with the given content encoding). These are interpreted as URLs relative to
the map file; they must be on the same server, and they must refer to files
to which the client would be granted access if they were to be requested directly.
- Content-Type
- The media type --- charset, level and "Qs" parameters may be given. These
are often referred to as MIME types; typical media types are image/gif, text/plain,
or text/html; level=3.
- Content-Language
- The languages of the variant, specified as an Internet standard language
tag from RFC 1766 (for example, en for English, or kr for Korean).
- Content-Encoding
- If the file is compressed, or otherwise encoded, rather than containing
the actual raw data, this states how it was done. The HTTP Server (powered
by Apache) only recognizes encodings that are defined by an AddEncoding directive.
This normally includes the encodings x-compress for compressed files, and
x-gzip for gzip'd files. The x- prefix is ignored for encoding comparisons.
- Content-Length
- The size of the file. Specifying content lengths in the type-map allows
the server to compare file sizes without checking the actual files.
- Description
- A human-readable textual description of the variant. If the HTTP Server
(powered by Apache) cannot find any appropriate variant to return, it will
return an error response which lists all available variants instead. Such
a variant list will include the human-readable variant descriptions.
MultiViews
MultiViews is a per-directory option, meaning it can be set with an Options
directive within a <Directory>, <Location> or <Files> container in
the configuration file, or (if AllowOverride is properly set) in .htaccess
files. Note that Options All does not set MultiViews; you have to ask for
it by name.
The effect of MultiViews is as follows: if the server receives a request
for /some/dir/jkl, if /some/dir has MultiViews enabled, and /some/dir/jkl
does not exist, then the server reads the directory looking for files named
jkl.*, and effectively fakes up a type map which names all those files, assigning
them the same media types and content-encodings it would have if the client
had asked for one of them by name. It then chooses the best match to the client's
requirements.
MultiViews may also apply to searches for the file named by the DirectoryIndex
directive, if the server is trying to index a directory. If the configuration
files specify:
DirectoryIndex index
The server will arbitrate between index.html and index.html3 if both are
present.
If one of the files found when reading the directive is a CGI script, it
is not obvious what should happen. The code gives that case special treatment
--- if the request was a POST, or a GET with QUERY_ARGS or PATH_INFO, the
script is given an extremely high quality rating, and generally invoked; otherwise
it is given an extremely low quality rating, which generally causes one of
the other views (if any) to be retrieved.
Notes on hyperlinks and naming conventions
If you are using language negotiation you can choose between different
naming conventions, because files can have more than one extension, and the
order of the extensions is normally irrelevant (see mod_mime for details).
A typical file has a MIME-type extension (for example, html), maybe an
encoding extension (for example, gz), and of course a language extension (for
example, en) when we have different language variants of this file.
Examples:
- jkl.en.html
- jkl.html.en
- jkl.en.html.gz
Examples of filenames together with valid and invalid hyperlinks:
| Filename |
Valid hyperlink |
Invalid hyperlink |
|---|
| jkl.html.en |
jkl
jkl.html
|
- |
| jkl.en.html |
jkl |
jkl.html |
| jkl.html.en.gz |
jkl
jkl.html
|
jkl.gz
jkl.html.gz
|
| jkl.en.html.gz |
jkl |
jkl.html
jkl.html.gz
jkl.gz
|
| jkl.gz.html.en |
jkl
jkl.gz
jkl.gz.html
|
jkl.html |
| jkl.html.gz.en |
jkl
jkl.html
jkl.html.gz
|
jkl.gz |
Looking at the table above you will notice that it is always possible to
use the name without any extensions in an hyperlink (for example, jkl). The
advantage is that you can hide the actual type of a document rsp. file and
can change it later, for example, from html to shtml or cgi without changing
any hyperlink references.
If you want to continue to use a MIME-type in your hyperlinks (for example jkl.html)
the language extension (including an encoding extension if there is one) must
be on the right hand side of the MIME-type extension (for example, jkl.html.en).