rubbos/app/apache2/manual/content-negotiation.html.en

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
   4         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   5               This file is generated from xml source: DO NOT EDIT
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7       -->
   8 <title>Content Negotiation - Apache HTTP Server</title>
   9 <link href="./style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  10 <link href="./style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  11 <link href="./style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
  12 <link href="./images/favicon.ico" rel="shortcut icon" /></head>
  13 <body id="manual-page"><div id="page-header">
  14 <p class="menu"><a href="./mod/">Modules</a> | <a href="./mod/directives.html">Directives</a> | <a href="./faq/">FAQ</a> | <a href="./glossary.html">Glossary</a> | <a href="./sitemap.html">Sitemap</a></p>
  15 <p class="apache">Apache HTTP Server Version 2.0</p>
  16 <img alt="" src="./images/feather.gif" /></div>
  17 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="./images/left.gif" /></a></div>
  18 <div id="path">
  19 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="./">Version 2.0</a></div><div id="page-content"><div id="preamble"><h1>Content Negotiation</h1>
  20 <div class="toplang">
  21 <p><span>Available Languages: </span><a href="./en/content-negotiation.html" title="English">&nbsp;en&nbsp;</a> |
  22 <a href="./fr/content-negotiation.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a> |
  23 <a href="./ja/content-negotiation.html" hreflang="ja" rel="alternate" title="Japanese">&nbsp;ja&nbsp;</a> |
  24 <a href="./ko/content-negotiation.html" hreflang="ko" rel="alternate" title="Korean">&nbsp;ko&nbsp;</a> |
  25 <a href="./tr/content-negotiation.html" hreflang="tr" rel="alternate" title="Türkçe">&nbsp;tr&nbsp;</a></p>
  26 </div>
  27
  28
  29     <p>Apache supports content negotiation as described in
  30     the HTTP/1.1 specification. It can choose the best
  31     representation of a resource based on the browser-supplied
  32     preferences for media type, languages, character set and
  33     encoding. It also implements a couple of features to give
  34     more intelligent handling of requests from browsers that send
  35     incomplete negotiation information.</p>
  36
  37     <p>Content negotiation is provided by the
  38     <code class="module"><a href="./mod/mod_negotiation.html">mod_negotiation</a></code> module, which is compiled in
  39     by default.</p>
  40 </div>
  41 <div id="quickview"><ul id="toc"><li><img alt="" src="./images/down.gif" /> <a href="#about">About Content Negotiation</a></li>
  42 <li><img alt="" src="./images/down.gif" /> <a href="#negotiation">Negotiation in Apache</a></li>
  43 <li><img alt="" src="./images/down.gif" /> <a href="#methods">The Negotiation Methods</a></li>
  44 <li><img alt="" src="./images/down.gif" /> <a href="#better">Fiddling with Quality
  45     Values</a></li>
  46 <li><img alt="" src="./images/down.gif" /> <a href="#extensions">Extensions to Transparent Content
  47 Negotiation</a></li>
  48 <li><img alt="" src="./images/down.gif" /> <a href="#naming">Note on hyperlinks and naming conventions</a></li>
  49 <li><img alt="" src="./images/down.gif" /> <a href="#caching">Note on Caching</a></li>
  50 </ul></div>
  51 <div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
  52 <div class="section">
  53 <h2><a name="about" id="about">About Content Negotiation</a></h2>
  54
  55     <p>A resource may be available in several different
  56     representations. For example, it might be available in
  57     different languages or different media types, or a combination.
  58     One way of selecting the most appropriate choice is to give the
  59     user an index page, and let them select. However it is often
  60     possible for the server to choose automatically. This works
  61     because browsers can send, as part of each request, information
  62     about what representations they prefer. For example, a browser
  63     could indicate that it would like to see information in French,
  64     if possible, else English will do. Browsers indicate their
  65     preferences by headers in the request. To request only French
  66     representations, the browser would send</p>
  67
  68 <div class="example"><p><code>Accept-Language: fr</code></p></div>
  69
  70     <p>Note that this preference will only be applied when there is
  71     a choice of representations and they vary by language.</p>
  72
  73     <p>As an example of a more complex request, this browser has
  74     been configured to accept French and English, but prefer
  75     French, and to accept various media types, preferring HTML over
  76     plain text or other text types, and preferring GIF or JPEG over
  77     other media types, but also allowing any other media type as a
  78     last resort:</p>
  79
  80 <div class="example"><p><code>
  81   Accept-Language: fr; q=1.0, en; q=0.5<br />
  82   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
  83 </code></p></div>
  84
  85     <p>Apache supports 'server driven' content negotiation, as
  86     defined in the HTTP/1.1 specification. It fully supports the
  87     <code>Accept</code>, <code>Accept-Language</code>,
  88     <code>Accept-Charset</code> and<code>Accept-Encoding</code>
  89     request headers. Apache also supports 'transparent'
  90     content negotiation, which is an experimental negotiation
  91     protocol defined in RFC 2295 and RFC 2296. It does not offer
  92     support for 'feature negotiation' as defined in these RFCs.</p>
  93
  94     <p>A <strong>resource</strong> is a conceptual entity
  95     identified by a URI (RFC 2396). An HTTP server like Apache
  96     provides access to <strong>representations</strong> of the
  97     resource(s) within its namespace, with each representation in
  98     the form of a sequence of bytes with a defined media type,
  99     character set, encoding, etc. Each resource may be associated
 100     with zero, one, or more than one representation at any given
 101     time. If multiple representations are available, the resource
 102     is referred to as <strong>negotiable</strong> and each of its
 103     representations is termed a <strong>variant</strong>. The ways
 104     in which the variants for a negotiable resource vary are called
 105     the <strong>dimensions</strong> of negotiation.</p>
 106 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
 107 <div class="section">
 108 <h2><a name="negotiation" id="negotiation">Negotiation in Apache</a></h2>
 109
 110     <p>In order to negotiate a resource, the server needs to be
 111     given information about each of the variants. This is done in
 112     one of two ways:</p>
 113
 114     <ul>
 115       <li>Using a type map (<em>i.e.</em>, a <code>*.var</code>
 116       file) which names the files containing the variants
 117       explicitly, or</li>
 118
 119       <li>Using a 'MultiViews' search, where the server does an
 120       implicit filename pattern match and chooses from among the
 121       results.</li>
 122     </ul>
 123
 124    <h3><a name="type-map" id="type-map">Using a type-map file</a></h3>
 125
 126     <p>A type map is a document which is associated with the
 127     handler named <code>type-map</code> (or, for
 128     backwards-compatibility with older Apache configurations, the
 129     MIME type <code>application/x-type-map</code>). Note that to
 130     use this feature, you must have a handler set in the
 131     configuration that defines a file suffix as
 132     <code>type-map</code>; this is best done with</p>
 133
 134 <div class="example"><p><code>AddHandler type-map .var</code></p></div>
 135
 136     <p>in the server configuration file.</p>
 137
 138     <p>Type map files should have the same name as the resource
 139     which they are describing, and have an entry for each available
 140     variant; these entries consist of contiguous HTTP-format header
 141     lines. Entries for different variants are separated by blank
 142     lines. Blank lines are illegal within an entry. It is
 143     conventional to begin a map file with an entry for the combined
 144     entity as a whole (although this is not required, and if
 145     present will be ignored). An example map file is shown below.
 146     This file would be named <code>foo.var</code>, as it describes
 147     a resource named <code>foo</code>.</p>
 148
 149 <div class="example"><p><code>
 150   URI: foo<br />
 151 <br />
 152   URI: foo.en.html<br />
 153   Content-type: text/html<br />
 154   Content-language: en<br />
 155 <br />
 156   URI: foo.fr.de.html<br />
 157   Content-type: text/html;charset=iso-8859-2<br />
 158   Content-language: fr, de<br />
 159 </code></p></div>
 160     <p>Note also that a typemap file will take precedence over the
 161     filename's extension, even when Multiviews is on. If the
 162     variants have different source qualities, that may be indicated
 163     by the "qs" parameter to the media type, as in this picture
 164     (available as JPEG, GIF, or ASCII-art): </p>
 165
 166 <div class="example"><p><code>
 167   URI: foo<br />
 168 <br />
 169   URI: foo.jpeg<br />
 170   Content-type: image/jpeg; qs=0.8<br />
 171 <br />
 172   URI: foo.gif<br />
 173   Content-type: image/gif; qs=0.5<br />
 174 <br />
 175   URI: foo.txt<br />
 176   Content-type: text/plain; qs=0.01<br />
 177 </code></p></div>
 178
 179     <p>qs values can vary in the range 0.000 to 1.000. Note that
 180     any variant with a qs value of 0.000 will never be chosen.
 181     Variants with no 'qs' parameter value are given a qs factor of
 182     1.0. The qs parameter indicates the relative 'quality' of this
 183     variant compared to the other available variants, independent
 184     of the client's capabilities. For example, a JPEG file is
 185     usually of higher source quality than an ASCII file if it is
 186     attempting to represent a photograph. However, if the resource
 187     being represented is an original ASCII art, then an ASCII
 188     representation would have a higher source quality than a JPEG
 189     representation. A qs value is therefore specific to a given
 190     variant depending on the nature of the resource it
 191     represents.</p>
 192
 193     <p>The full list of headers recognized is available in the <a href="mod/mod_negotiation.html#typemaps">mod_negotation
 194     typemap</a> documentation.</p>
 195
 196
 197 <h3><a name="multiviews" id="multiviews">Multiviews</a></h3>
 198
 199     <p><code>MultiViews</code> is a per-directory option, meaning it
 200     can be set with an <code class="directive"><a href="./mod/core.html#options">Options</a></code>
 201     directive within a <code class="directive"><a href="./mod/core.html#directory">&lt;Directory&gt;</a></code>, <code class="directive"><a href="./mod/core.html#location">&lt;Location&gt;</a></code> or <code class="directive"><a href="./mod/core.html#files">&lt;Files&gt;</a></code> section in
 202     <code>httpd.conf</code>, or (if <code class="directive"><a href="./mod/core.html#allowoverride">AllowOverride</a></code> is properly set) in
 203     <code>.htaccess</code> files. Note that <code>Options All</code>
 204     does not set <code>MultiViews</code>; you have to ask for it by
 205     name.</p>
 206
 207     <p>The effect of <code>MultiViews</code> is as follows: if the
 208     server receives a request for <code>/some/dir/foo</code>, if
 209     <code>/some/dir</code> has <code>MultiViews</code> enabled, and
 210     <code>/some/dir/foo</code> does <em>not</em> exist, then the
 211     server reads the directory looking for files named foo.*, and
 212     effectively fakes up a type map which names all those files,
 213     assigning them the same media types and content-encodings it
 214     would have if the client had asked for one of them by name. It
 215     then chooses the best match to the client's requirements.</p>
 216
 217     <p><code>MultiViews</code> may also apply to searches for the file
 218     named by the <code class="directive"><a href="./mod/mod_dir.html#directoryindex">DirectoryIndex</a></code> directive, if the
 219     server is trying to index a directory. If the configuration files
 220     specify</p>
 221 <div class="example"><p><code>DirectoryIndex index</code></p></div>
 222     <p>then the server will arbitrate between <code>index.html</code>
 223     and <code>index.html3</code> if both are present. If neither
 224     are present, and <code>index.cgi</code> is there, the server
 225     will run it.</p>
 226
 227     <p>If one of the files found when reading the directory does not
 228     have an extension recognized by <code>mod_mime</code> to designate
 229     its Charset, Content-Type, Language, or Encoding, then the result
 230     depends on the setting of the <code class="directive"><a href="./mod/mod_mime.html#multiviewsmatch">MultiViewsMatch</a></code> directive.  This
 231     directive determines whether handlers, filters, and other
 232     extension types can participate in MultiViews negotiation.</p>
 233
 234 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
 235 <div class="section">
 236 <h2><a name="methods" id="methods">The Negotiation Methods</a></h2>
 237
 238     <p>After Apache has obtained a list of the variants for a given
 239     resource, either from a type-map file or from the filenames in
 240     the directory, it invokes one of two methods to decide on the
 241     'best' variant to return, if any. It is not necessary to know
 242     any of the details of how negotiation actually takes place in
 243     order to use Apache's content negotiation features. However the
 244     rest of this document explains the methods used for those
 245     interested. </p>
 246
 247     <p>There are two negotiation methods:</p>
 248
 249     <ol>
 250       <li><strong>Server driven negotiation with the Apache
 251       algorithm</strong> is used in the normal case. The Apache
 252       algorithm is explained in more detail below. When this
 253       algorithm is used, Apache can sometimes 'fiddle' the quality
 254       factor of a particular dimension to achieve a better result.
 255       The ways Apache can fiddle quality factors is explained in
 256       more detail below.</li>
 257
 258       <li><strong>Transparent content negotiation</strong> is used
 259       when the browser specifically requests this through the
 260       mechanism defined in RFC 2295. This negotiation method gives
 261       the browser full control over deciding on the 'best' variant,
 262       the result is therefore dependent on the specific algorithms
 263       used by the browser. As part of the transparent negotiation
 264       process, the browser can ask Apache to run the 'remote
 265       variant selection algorithm' defined in RFC 2296.</li>
 266     </ol>
 267
 268 <h3><a name="dimensions" id="dimensions">Dimensions of Negotiation</a></h3>
 269
 270     <table>
 271
 272       <tr valign="top">
 273         <th>Dimension</th>
 274
 275         <th>Notes</th>
 276       </tr>
 277
 278       <tr valign="top">
 279         <td>Media Type</td>
 280
 281         <td>Browser indicates preferences with the <code>Accept</code>
 282         header field. Each item can have an associated quality factor.
 283         Variant description can also have a quality factor (the "qs"
 284         parameter).</td>
 285       </tr>
 286
 287       <tr valign="top">
 288         <td>Language</td>
 289
 290         <td>Browser indicates preferences with the
 291         <code>Accept-Language</code> header field. Each item can have
 292         a quality factor. Variants can be associated with none, one or
 293         more than one language.</td>
 294       </tr>
 295
 296       <tr valign="top">
 297         <td>Encoding</td>
 298
 299         <td>Browser indicates preference with the
 300         <code>Accept-Encoding</code> header field. Each item can have
 301         a quality factor.</td>
 302       </tr>
 303
 304       <tr valign="top">
 305         <td>Charset</td>
 306
 307         <td>Browser indicates preference with the
 308         <code>Accept-Charset</code> header field. Each item can have a
 309         quality factor. Variants can indicate a charset as a parameter
 310         of the media type.</td>
 311       </tr>
 312     </table>
 313
 314
 315 <h3><a name="algorithm" id="algorithm">Apache Negotiation Algorithm</a></h3>
 316
 317     <p>Apache can use the following algorithm to select the 'best'
 318     variant (if any) to return to the browser. This algorithm is
 319     not further configurable. It operates as follows:</p>
 320
 321     <ol>
 322       <li>First, for each dimension of the negotiation, check the
 323       appropriate <em>Accept*</em> header field and assign a
 324       quality to each variant. If the <em>Accept*</em> header for
 325       any dimension implies that this variant is not acceptable,
 326       eliminate it. If no variants remain, go to step 4.</li>
 327
 328       <li>
 329         Select the 'best' variant by a process of elimination. Each
 330         of the following tests is applied in order. Any variants
 331         not selected at each test are eliminated. After each test,
 332         if only one variant remains, select it as the best match
 333         and proceed to step 3. If more than one variant remains,
 334         move on to the next test.
 335
 336         <ol>
 337           <li>Multiply the quality factor from the <code>Accept</code>
 338           header with the quality-of-source factor for this variants
 339           media type, and select the variants with the highest
 340           value.</li>
 341
 342           <li>Select the variants with the highest language quality
 343           factor.</li>
 344
 345           <li>Select the variants with the best language match,
 346           using either the order of languages in the
 347           <code>Accept-Language</code> header (if present), or else
 348           the order of languages in the <code>LanguagePriority</code>
 349           directive (if present).</li>
 350
 351           <li>Select the variants with the highest 'level' media
 352           parameter (used to give the version of text/html media
 353           types).</li>
 354
 355           <li>Select variants with the best charset media
 356           parameters, as given on the <code>Accept-Charset</code>
 357           header line.  Charset ISO-8859-1 is acceptable unless
 358           explicitly excluded. Variants with a <code>text/*</code>
 359           media type but not explicitly associated with a particular
 360           charset are assumed to be in ISO-8859-1.</li>
 361
 362           <li>Select those variants which have associated charset
 363           media parameters that are <em>not</em> ISO-8859-1. If
 364           there are no such variants, select all variants
 365           instead.</li>
 366
 367           <li>Select the variants with the best encoding. If there
 368           are variants with an encoding that is acceptable to the
 369           user-agent, select only these variants. Otherwise if
 370           there is a mix of encoded and non-encoded variants,
 371           select only the unencoded variants. If either all
 372           variants are encoded or all variants are not encoded,
 373           select all variants.</li>
 374
 375           <li>Select the variants with the smallest content
 376           length.</li>
 377
 378           <li>Select the first variant of those remaining. This
 379           will be either the first listed in the type-map file, or
 380           when variants are read from the directory, the one whose
 381           file name comes first when sorted using ASCII code
 382           order.</li>
 383         </ol>
 384       </li>
 385
 386       <li>The algorithm has now selected one 'best' variant, so
 387       return it as the response. The HTTP response header
 388       <code>Vary</code> is set to indicate the dimensions of
 389       negotiation (browsers and caches can use this information when
 390       caching the resource).  End.</li>
 391
 392       <li>To get here means no variant was selected (because none
 393       are acceptable to the browser). Return a 406 status (meaning
 394       "No acceptable representation") with a response body
 395       consisting of an HTML document listing the available
 396       variants. Also set the HTTP <code>Vary</code> header to
 397       indicate the dimensions of variance.</li>
 398     </ol>
 399
 400 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
 401 <div class="section">
 402 <h2><a name="better" id="better">Fiddling with Quality
 403     Values</a></h2>
 404
 405     <p>Apache sometimes changes the quality values from what would
 406     be expected by a strict interpretation of the Apache
 407     negotiation algorithm above. This is to get a better result
 408     from the algorithm for browsers which do not send full or
 409     accurate information. Some of the most popular browsers send
 410     <code>Accept</code> header information which would otherwise
 411     result in the selection of the wrong variant in many cases. If a
 412     browser sends full and correct information these fiddles will not
 413     be applied.</p>
 414
 415 <h3><a name="wildcards" id="wildcards">Media Types and Wildcards</a></h3>
 416
 417     <p>The <code>Accept:</code> request header indicates preferences
 418     for media types. It can also include 'wildcard' media types, such
 419     as "image/*" or "*/*" where the * matches any string. So a request
 420     including:</p>
 421
 422 <div class="example"><p><code>Accept: image/*, */*</code></p></div>
 423
 424     <p>would indicate that any type starting "image/" is acceptable,
 425     as is any other type.
 426     Some browsers routinely send wildcards in addition to explicit
 427     types they can handle. For example:</p>
 428
 429 <div class="example"><p><code>
 430   Accept: text/html, text/plain, image/gif, image/jpeg, */*
 431 </code></p></div>
 432     <p>The intention of this is to indicate that the explicitly listed
 433     types are preferred, but if a different representation is
 434     available, that is ok too.  Using explicit quality values,
 435     what the browser really wants is something like:</p>
 436 <div class="example"><p><code>
 437   Accept: text/html, text/plain, image/gif, image/jpeg, */*; q=0.01
 438 </code></p></div>
 439     <p>The explicit types have no quality factor, so they default to a
 440     preference of 1.0 (the highest). The wildcard */* is given a
 441     low preference of 0.01, so other types will only be returned if
 442     no variant matches an explicitly listed type.</p>
 443
 444     <p>If the <code>Accept:</code> header contains <em>no</em> q
 445     factors at all, Apache sets the q value of "*/*", if present, to
 446     0.01 to emulate the desired behavior. It also sets the q value of
 447     wildcards of the format "type/*" to 0.02 (so these are preferred
 448     over matches against "*/*". If any media type on the
 449     <code>Accept:</code> header contains a q factor, these special
 450     values are <em>not</em> applied, so requests from browsers which
 451     send the explicit information to start with work as expected.</p>
 452
 453
 454 <h3><a name="exceptions" id="exceptions">Language Negotiation Exceptions</a></h3>
 455
 456     <p>New in Apache 2.0, some exceptions have been added to the
 457     negotiation algorithm to allow graceful fallback when language
 458     negotiation fails to find a match.</p>
 459
 460     <p>When a client requests a page on your server, but the server
 461     cannot find a single page that matches the
 462     <code>Accept-language</code> sent by
 463     the browser, the server will return either a "No Acceptable
 464     Variant" or "Multiple Choices" response to the client.  To avoid
 465     these error messages, it is possible to configure Apache to ignore
 466     the <code>Accept-language</code> in these cases and provide a
 467     document that does not explicitly match the client's request.  The
 468     <code class="directive"><a href="./mod/mod_negotiation.html#forcelanguagepriority">ForceLanguagePriority</a></code>
 469     directive can be used to override one or both of these error
 470     messages and substitute the servers judgement in the form of the
 471     <code class="directive"><a href="./mod/mod_negotiation.html#languagepriority">LanguagePriority</a></code>
 472     directive.</p>
 473
 474     <p>The server will also attempt to match language-subsets when no
 475     other match can be found.  For example, if a client requests
 476     documents with the language <code>en-GB</code> for British
 477     English, the server is not normally allowed by the HTTP/1.1
 478     standard to match that against a document that is marked as simply
 479     <code>en</code>.  (Note that it is almost surely a configuration
 480     error to include <code>en-GB</code> and not <code>en</code> in the
 481     <code>Accept-Language</code> header, since it is very unlikely
 482     that a reader understands British English, but doesn't understand
 483     English in general.  Unfortunately, many current clients have
 484     default configurations that resemble this.)  However, if no other
 485     language match is possible and the server is about to return a "No
 486     Acceptable Variants" error or fallback to the <code class="directive"><a href="./mod/mod_negotiation.html#languagepriority">LanguagePriority</a></code>, the server
 487     will ignore the subset specification and match <code>en-GB</code>
 488     against <code>en</code> documents.  Implicitly, Apache will add
 489     the parent language to the client's acceptable language list with
 490     a very low quality value.  But note that if the client requests
 491     "en-GB; q=0.9, fr; q=0.8", and the server has documents
 492     designated "en" and "fr", then the "fr" document will be returned.
 493     This is necessary to maintain compliance with the HTTP/1.1
 494     specification and to work effectively with properly configured
 495     clients.</p>
 496
 497     <p>In order to support advanced techniques (such as cookies or
 498     special URL-paths) to determine the user's preferred language,
 499     since Apache 2.0.47 <code class="module"><a href="./mod/mod_negotiation.html">mod_negotiation</a></code> recognizes
 500     the <a href="env.html">environment variable</a>
 501     <code>prefer-language</code>. If it exists and contains an
 502     appropriate language tag, <code class="module"><a href="./mod/mod_negotiation.html">mod_negotiation</a></code> will
 503     try to select a matching variant. If there's no such variant,
 504     the normal negotiation process applies.</p>
 505
 506     <div class="example"><h3>Example</h3><p><code>
 507       SetEnvIf Cookie "language=en" prefer-language=en<br />
 508       SetEnvIf Cookie "language=fr" prefer-language=fr
 509    </code></p></div>
 510
 511 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
 512 <div class="section">
 513 <h2><a name="extensions" id="extensions">Extensions to Transparent Content
 514 Negotiation</a></h2>
 515
 516 <p>Apache extends the transparent content negotiation protocol (RFC
 517 2295) as follows. A new <code>{encoding ..}</code> element is used in
 518 variant lists to label variants which are available with a specific
 519 content-encoding only. The implementation of the RVSA/1.0 algorithm
 520 (RFC 2296) is extended to recognize encoded variants in the list, and
 521 to use them as candidate variants whenever their encodings are
 522 acceptable according to the <code>Accept-Encoding</code> request
 523 header. The RVSA/1.0 implementation does not round computed quality
 524 factors to 5 decimal places before choosing the best variant.</p>
 525 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
 526 <div class="section">
 527 <h2><a name="naming" id="naming">Note on hyperlinks and naming conventions</a></h2>
 528
 529     <p>If you are using language negotiation you can choose between
 530     different naming conventions, because files can have more than
 531     one extension, and the order of the extensions is normally
 532     irrelevant (see the <a href="mod/mod_mime.html#multipleext">mod_mime</a> documentation
 533     for details).</p>
 534
 535     <p>A typical file has a MIME-type extension (<em>e.g.</em>,
 536     <code>html</code>), maybe an encoding extension (<em>e.g.</em>,
 537     <code>gz</code>), and of course a language extension
 538     (<em>e.g.</em>, <code>en</code>) when we have different
 539     language variants of this file.</p>
 540
 541     <p>Examples:</p>
 542
 543     <ul>
 544       <li>foo.en.html</li>
 545
 546       <li>foo.html.en</li>
 547
 548       <li>foo.en.html.gz</li>
 549     </ul>
 550
 551     <p>Here some more examples of filenames together with valid and
 552     invalid hyperlinks:</p>
 553
 554     <table class="bordered">
 555
 556       <tr>
 557         <th>Filename</th>
 558
 559         <th>Valid hyperlink</th>
 560
 561         <th>Invalid hyperlink</th>
 562       </tr>
 563
 564       <tr>
 565         <td><em>foo.html.en</em></td>
 566
 567         <td>foo<br />
 568          foo.html</td>
 569
 570         <td>-</td>
 571       </tr>
 572
 573       <tr>
 574         <td><em>foo.en.html</em></td>
 575
 576         <td>foo</td>
 577
 578         <td>foo.html</td>
 579       </tr>
 580
 581       <tr>
 582         <td><em>foo.html.en.gz</em></td>
 583
 584         <td>foo<br />
 585          foo.html</td>
 586
 587         <td>foo.gz<br />
 588          foo.html.gz</td>
 589       </tr>
 590
 591       <tr>
 592         <td><em>foo.en.html.gz</em></td>
 593
 594         <td>foo</td>
 595
 596         <td>foo.html<br />
 597          foo.html.gz<br />
 598          foo.gz</td>
 599       </tr>
 600
 601       <tr>
 602         <td><em>foo.gz.html.en</em></td>
 603
 604         <td>foo<br />
 605          foo.gz<br />
 606          foo.gz.html</td>
 607
 608         <td>foo.html</td>
 609       </tr>
 610
 611       <tr>
 612         <td><em>foo.html.gz.en</em></td>
 613
 614         <td>foo<br />
 615          foo.html<br />
 616          foo.html.gz</td>
 617
 618         <td>foo.gz</td>
 619       </tr>
 620     </table>
 621
 622     <p>Looking at the table above, you will notice that it is always
 623     possible to use the name without any extensions in a hyperlink
 624     (<em>e.g.</em>, <code>foo</code>). The advantage is that you
 625     can hide the actual type of a document rsp. file and can change
 626     it later, <em>e.g.</em>, from <code>html</code> to
 627     <code>shtml</code> or <code>cgi</code> without changing any
 628     hyperlink references.</p>
 629
 630     <p>If you want to continue to use a MIME-type in your
 631     hyperlinks (<em>e.g.</em> <code>foo.html</code>) the language
 632     extension (including an encoding extension if there is one)
 633     must be on the right hand side of the MIME-type extension
 634     (<em>e.g.</em>, <code>foo.html.en</code>).</p>
 635 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
 636 <div class="section">
 637 <h2><a name="caching" id="caching">Note on Caching</a></h2>
 638
 639     <p>When a cache stores a representation, it associates it with
 640     the request URL. The next time that URL is requested, the cache
 641     can use the stored representation. But, if the resource is
 642     negotiable at the server, this might result in only the first
 643     requested variant being cached and subsequent cache hits might
 644     return the wrong response. To prevent this, Apache normally
 645     marks all responses that are returned after content negotiation
 646     as non-cacheable by HTTP/1.0 clients. Apache also supports the
 647     HTTP/1.1 protocol features to allow caching of negotiated
 648     responses.</p>
 649
 650     <p>For requests which come from a HTTP/1.0 compliant client
 651     (either a browser or a cache), the directive <code class="directive"><a href="./mod/mod_negotiation.html#cachenegotiateddocs">CacheNegotiatedDocs</a></code> can be
 652     used to allow caching of responses which were subject to
 653     negotiation. This directive can be given in the server config or
 654     virtual host, and takes no arguments. It has no effect on requests
 655     from HTTP/1.1 clients.</p>
 656 </div></div>
 657 <div class="bottomlang">
 658 <p><span>Available Languages: </span><a href="./en/content-negotiation.html" title="English">&nbsp;en&nbsp;</a> |
 659 <a href="./fr/content-negotiation.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a> |
 660 <a href="./ja/content-negotiation.html" hreflang="ja" rel="alternate" title="Japanese">&nbsp;ja&nbsp;</a> |
 661 <a href="./ko/content-negotiation.html" hreflang="ko" rel="alternate" title="Korean">&nbsp;ko&nbsp;</a> |
 662 <a href="./tr/content-negotiation.html" hreflang="tr" rel="alternate" title="Türkçe">&nbsp;tr&nbsp;</a></p>
 663 </div><div id="footer">
 664 <p class="apache">Copyright 2009 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
 665 <p class="menu"><a href="./mod/">Modules</a> | <a href="./mod/directives.html">Directives</a> | <a href="./faq/">FAQ</a> | <a href="./glossary.html">Glossary</a> | <a href="./sitemap.html">Sitemap</a></p></div>
 666 </body></html>