granicus.if.org Git - apache/blob - docs/manual/content-negotiation.html

   1 <html>
   2 <head>
   3 <title>Apache server Content arbitration: MultiViews and *.var files</title>
   4 </head>
   5
   6 <body>
   7 <!--#include virtual="header.html" -->
   8 <h1>Content Arbitration:  MultiViews and *.var files</h1>
   9
  10 The HTTP standard allows clients (i.e., browsers like Mosaic or
  11 Netscape) to specify what data formats they are prepared to accept.
  12 The intention is that when information is available in multiple
  13 variants (e.g., in different data formats), servers can use this
  14 information to decide which variant to send.  This feature has been
  15 supported in the CERN server for a while, and while it is not yet
  16 supported in the NCSA server, it is likely to assume a new importance
  17 in light of the emergence of HTML3 capable browsers. <p>
  18
  19 The Apache module <A HREF="mod_negotiation.html">mod_negotiation</A> handles
  20 content negotiation in two different ways; special treatment for the
  21 pseudo-mime-type <code>application/x-type-map</code>, and the
  22 MultiViews per-directory Option (which can be set in srm.conf, or in
  23 .htaccess files, as usual).  These features are alternate user
  24 interfaces to what amounts to the same piece of code (in the new file
  25 <code>http_mime_db.c</code>) which implements the content negotiation
  26 portion of the HTTP protocol. <p>
  27
  28 Each of these features allows one of several files to satisfy a
  29 request, based on what the client says it's willing to accept; the
  30 differences are in the way the files are identified:
  31
  32 <ul>
  33   <li> A type map (i.e., a <code>*.var</code> file) names the files
  34        containing the variants explicitly
  35   <li> In a MultiViews search, the server does an implicit filename
  36        pattern match, and chooses from among the results.
  37 </ul>
  38
  39 Apache also supports a new pseudo-MIME type,
  40 text/x-server-parsed-html3, which is treated as text/html;level=3
  41 for purposes of content negotiation, and as server-side-included HTML
  42 elsewhere.
  43
  44 <h3>Type maps (*.var files)</h3>
  45
  46 A type map is a document which is typed by the server (using its
  47 normal suffix-based mechanisms) as
  48 <code>application/x-type-map</code>.  Note that to use this feature,
  49 you've got to have an <code>AddType</code> some place which defines a
  50 file suffix as <code>application/x-type-map</code>; the easiest thing
  51 may be to stick a
  52 <pre>
  53
  54   AddType application/x-type-map var
  55
  56 </pre>
  57 in <code>srm.conf</code>.  See comments in the sample config files for
  58 details. <p>
  59
  60 Type map files have an entry for each available variant; these entries
  61 consist of contiguous RFC822-format header lines.  Entries for
  62 different variants are separated by blank lines.  Blank lines are
  63 illegal within an entry.  It is conventional to begin a map file with
  64 an entry for the combined entity as a whole, e.g.,
  65 <pre>
  66
  67   URI: foo; vary="type,language"
  68
  69   URI: foo.en.html
  70   Content-type: text/html; level=2
  71   Content-language: en
  72
  73   URI: foo.fr.html
  74   Content-type: text/html; level=2
  75   Content-language: fr
  76
  77 </pre>
  78 If the variants have different qualities, that may be indicated by the
  79 "qs" parameter, as in this picture (available as jpeg, gif, or ASCII-art):
  80 <pre>
  81
  82   URI: foo; vary="type,language"
  83
  84   URI: foo.jpeg
  85   Content-type: image/jpeg; qs=0.8
  86
  87   URI: foo.gif
  88   Content-type: image/gif; qs=0.5
  89
  90   URI: foo.txt
  91   Content-type: text/plain; qs=0.01
  92
  93 </pre><p>
  94
  95 The full list of headers recognized is:
  96
  97 <dl>
  98   <dt> <code>URI:</code>
  99   <dd> uri of the file containing the variant (of the given media
 100        type, encoded with the given content encoding).  These are
 101        interpreted as URLs relative to the map file; they must be on
 102        the same server (!), and they must refer to files to which the
 103        client would be granted access if they were to be requested
 104        directly.
 105   <dt> <code>Content-type:</code>
 106   <dd> media type --- level may be specified, along with "qs".  These
 107        are often referred to as MIME types; typical media types are
 108        <code>image/gif</code>, <code>text/plain</code>, or
 109        <code>text/html;&nbsp;level=3</code>.
 110   <dt> <code>Content-language:</code>
 111   <dd> The language of the variant, specified as an Internet standard
 112        language code (e.g., <code>en</code> for English,
 113        <code>kr</code> for Korean, etc.).
 114   <dt> <code>Content-encoding:</code>
 115   <dd> If the file is compressed, or otherwise encoded, rather than
 116        containing the actual raw data, this says how that was done.
 117        For compressed files (the only case where this generally comes
 118        up), content encoding should be
 119        <code>x-compress</code>, or <code>gzip</code>, as appropriate.
 120   <dt> <code>Content-length:</code>
 121   <dd> The size of the file.  Clients can ask to receive a given media
 122        type only if the variant isn't too big; specifying a content
 123        length in the map allows the server to compare against these
 124        thresholds without checking the actual file.
 125 </dl>
 126
 127 <h3>Multiviews</h3>
 128
 129 This is a per-directory option, meaning it can be set with an
 130 <code>Options</code> directive within a <code>&lt;Directory&gt;</code>
 131 section in <code>access.conf</code>, or (if <code>AllowOverride</code>
 132 is properly set) in <code>.htaccess</code> files.  Note that
 133 <code>Options All</code> does not set <code>MultiViews</code>; you
 134 have to ask for it by name.  (Fixing this is a one-line change to
 135 <code>httpd.h</code>).
 136
 137 <p>
 138
 139 The effect of <code>MultiViews</code> is as follows: if the server
 140 receives a request for <code>/some/dir/foo</code>, if
 141 <code>/some/dir</code> has <code>MultiViews</code> enabled, and
 142 <code>/some/dir/foo</code> does *not* exist, then the server reads the
 143 directory looking for files named foo.*, and effectively fakes up a
 144 type map which names all those files, assigning them the same media
 145 types and content-encodings it would have if the client had asked for
 146 one of them by name.  It then chooses the best match to the client's
 147 requirements, and forwards them along.
 148
 149 <p>
 150
 151 This applies to searches for the file named by the
 152 <code>DirectoryIndex</code> directive, if the server is trying to
 153 index a directory; if the configuration files specify
 154 <pre>
 155
 156   DirectoryIndex index
 157
 158 </pre> then the server will arbitrate between <code>index.html</code>
 159 and <code>index.html3</code> if both are present.  If neither are
 160 present, and <code>index.cgi</code> is there, the server will run it.
 161
 162 <p>
 163
 164 If one of the files found by the globbing is a CGI script, it's not
 165 obvious what should happen.  My code gives that case gets special
 166 treatment --- if the request was a POST, or a GET with QUERY_ARGS or
 167 PATH_INFO, the script is given an extremely high quality rating, and
 168 generally invoked; otherwise it is given an extremely low quality
 169 rating, which generally causes one of the other views (if any) to be
 170 retrieved.  This is the only jiggering of quality ratings done by the
 171 MultiViews code; aside from that, all Qualities in the synthesized
 172 type maps are 1.0.
 173
 174 <p>
 175
 176 <B>New as of 0.8:</B> Documents in multiple languages can also be resolved through the use
 177 of the <code>AddLanguage</code> and <code>LanguagePriority</code>
 178 directives:
 179
 180 <pre>
 181 AddLanguage en .en
 182 AddLanguage fr .fr
 183 AddLanguage de .de
 184 AddLanguage da .da
 185 AddLanguage el .el
 186 AddLanguage it .it
 187
 188 # LanguagePriority allows you to give precedence to some languages
 189 # in case of a tie during content negotiation.
 190 # Just list the languages in decreasing order of preference.
 191
 192 LanguagePriority en fr de
 193 </pre>
 194
 195 Here, a request for "foo.html" matched against "foo.html.en" and
 196 "foo.html.fr" would return an French document to a browser that
 197 indicated a preference for French, or an English document otherwise.
 198 In fact, a request for "foo" matched against "foo.html.en",
 199 "foo.html.fr", "foo.ps.en", "foo.pdf.de", and "foo.txt.it" would do
 200 just what you expect - treat those suffices as a database and compare
 201 the request to it, returning the best match.  The languages and data
 202 types share the same suffix name space.
 203
 204 <p>
 205
 206 Note that this machinery only comes into play if the file which the
 207 user attempted to retrieve does <em>not</em> exist by that name; if it
 208 does, it is simply retrieved as usual.  (So, someone who actually asks
 209 for <code>foo.jpeg</code>, as opposed to <code>foo</code>, never gets
 210 <code>foo.gif</code>).
 211
 212 <!--#include virtual="footer.html" -->
 213 </body> </html>