You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by rb...@apache.org on 2011/03/18 14:37:22 UTC

svn commit: r1082915 [6/7] - /httpd/httpd/branches/2.2.x/docs/manual/rewrite/

Added: httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewritemap.html.en
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewritemap.html.en?rev=1082915&view=auto
==============================================================================
--- httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewritemap.html.en (added)
+++ httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewritemap.html.en Fri Mar 18 13:37:20 2011
@@ -0,0 +1,450 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
+        XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+              This file is generated from xml source: DO NOT EDIT
+        XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+      -->
+<title>Using RewriteMap - Apache HTTP Server</title>
+<link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
+<link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
+<link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
+<link href="../images/favicon.ico" rel="shortcut icon" /></head>
+<body id="manual-page"><div id="page-header">
+<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>
+<p class="apache">Apache HTTP Server Version 2.2</p>
+<img alt="" src="../images/feather.gif" /></div>
+<div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
+<div id="path">
+<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.2</a> &gt; <a href="./">Rewrite</a></div><div id="page-content"><div id="preamble"><h1>Using RewriteMap</h1>
+<div class="toplang">
+<p><span>Available Languages: </span><a href="../en/rewrite/rewritemap.html" title="English">&nbsp;en&nbsp;</a></p>
+</div>
+
+
+    <p>This document supplements the <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> 
+<a href="../mod/mod_rewrite.html">reference documentation</a>. It describes
+the use of the <code class="directive"><a href="../mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> directive,
+and provides examples of each of the various <code>RewriteMap</code> types.</p>
+
+    <div class="warning">Note that many of these examples won't work unchanged in your
+particular server configuration, so it's important that you understand
+them, rather than merely cutting and pasting the examples into your
+configuration.</div>
+
+  </div>
+<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#introduction">Introduction</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#txt">txt: Plain text maps</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#rnd">rnd: Randomized Plain Text</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#dbm">dbm: DBM Hash File</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#int">int: Internal Function</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#prg">prg: External Rewriting Program</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#dbd">dbd or fastdbd: SQL Query</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#summary">Summary</a></li>
+</ul><h3>See also</h3><ul class="seealso"><li><a href="../mod/mod_rewrite.html">Module documentation</a></li><li><a href="intro.html">mod_rewrite introduction</a></li><li><a href="remapping.html">Redirection and remapping</a></li><li><a href="access.html">Controlling access</a></li><li><a href="vhosts.html">Virtual hosts</a></li><li><a href="proxy.html">Proxying</a></li><li><a href="advanced.html">Advanced techniques and tricks</a></li><li><a href="avoid.html">When not to use mod_rewrite</a></li></ul></div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="introduction" id="introduction">Introduction</a></h2>
+    
+
+   <p>
+   The <code class="directive"><a href="../mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> directive
+   defines an external function which can be called in the context of
+   <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> or
+   <code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> directives to
+   perform rewriting that is too complicated, or too specialized to be
+   performed just by regular expressions. The source of this lookup can
+   be any of the types listed in the sections below, and enumerated in
+   the <code class="directive"><a href="../mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> reference
+   documentation.</p>
+
+   <p>The syntax of the <code>RewriteMap</code> directive is as
+   follows:</p>
+
+<div class="example"><p><code>
+RewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em>
+</code></p></div>
+    
+    <p>The <a id="mapfunc" name="mapfunc"><em>MapName</em></a> is an
+    arbitray name that you assign to the map, and which you will use in
+    directives later on. Arguments are passed to the map via the
+    following syntax:</p>
+
+    <p class="indent">
+      <strong>
+        <code>${</code> <em>MapName</em> <code>:</code> <em>LookupKey</em>
+        <code>}</code> <br /> <code>${</code> <em>MapName</em> <code>:</code>
+        <em>LookupKey</em> <code>|</code> <em>DefaultValue</em> <code>}</code>
+      </strong>
+    </p>
+
+    <p>When such a construct occurs, the map <em>MapName</em> is
+      consulted and the key <em>LookupKey</em> is looked-up. If the
+      key is found, the map-function construct is substituted by
+      <em>SubstValue</em>. If the key is not found then it is
+      substituted by <em>DefaultValue</em> or by the empty string
+      if no <em>DefaultValue</em> was specified.</p>
+
+    <p>For example, you might define a
+      <code class="directive">RewriteMap</code> as:</p>
+    <div class="example"><p><code>
+      RewriteMap examplemap txt:/path/to/file/map.txt
+      </code></p></div>
+    <p>You would then be able to use this map in a
+      <code class="directive">RewriteRule</code> as follows:</p>
+<div class="example"><p><code>
+  RewriteRule ^/ex/(.*) ${examplemap:$1}
+</code></p></div>
+
+<p>A default value can be specified in the event that nothing is found
+in the map:</p>
+
+<div class="example"><p><code>
+RewriteRule ^/ex/(.*) ${examplemap:$1|/not_found.html}
+</code></p></div>
+
+<div class="note"><h3>Per-directory and .htaccess context</h3>
+<p>
+The <code>RewriteMap</code> directive  may not be used in
+&lt;Directory&gt; sections or <code>.htaccess</code> files. You must
+declare the map in server or virtualhost context. You may use the map,
+once created, in your <code>RewriteRule</code> and
+<code>RewriteCond</code> directives in those scopes. You just can't
+<strong>declare</strong> it in those scopes.
+</p>
+</div>
+
+<p>The sections that follow describe the various <em>MapType</em>s that
+may be used, and give examples of each.</p>
+  </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="txt" id="txt">txt: Plain text maps</a></h2>
+    
+
+    <p>When a MapType of <code>txt</code> is used, the MapSource is a filesystem path to a
+    plain-text mapping file, containing space-separated key/value pair
+    per line. Optionally, a line may be contain a comment, starting with
+    a '#' character.</p>
+
+    <p>For example, the following might be valid entries in a map
+    file.</p>
+
+    <p class="indent">
+      # Comment line<br />
+      <strong><em>MatchingKey</em> <em>SubstValue</em></strong><br />
+      <strong><em>MatchingKey</em> <em>SubstValue</em></strong> # comment<br />
+    </p>
+
+    <p>When the RewriteMap is invoked the argument is looked for in the
+    first argument of a line, and, if found, the substitution value is
+    returned.</p>
+
+    <p>For example, we might use a mapfile to translate product names to
+    product IDs for easier-to-remember URLs, using the following
+    recipe:</p>
+
+    <div class="example"><h3>Product to ID configuration</h3><p><code>
+    RewriteMap product2id txt:/etc/apache2/productmap.txt<br />
+    RewriteRule ^/product/(.*) /prods.php?id=${product2id:$1|NOTFOUND} [PT]
+    </code></p></div>
+
+    <p>We assume here that the <code>prods.php</code> script knows what
+    to do when it received an argument of <code>id=NOTFOUND</code> when
+    a product is not found in the lookup map.</p>
+
+    <p>The file <code>/etc/apache2/productmap.txt</code> then contains
+    the following:</p>
+
+    <div class="example"><h3>Product to ID map</h3><p><code>
+##<br />
+##  productmap.txt - Product to ID map file<br />
+##<br />
+<br />
+television 993<br />
+stereo     198<br />
+fishingrod 043<br />
+basketball 418<br />
+telephone  328
+    </code></p></div>
+
+    <p>Thus, when <code>http://example.com/product/television</code> is
+    requested, the <code>RewriteRule</code> is applied, and the request
+    is internally mapped to <code>/prods.php?id=993</code>.</p>
+
+    <div class="note"><h3>Note: .htaccess files</h3>
+    The example given is crafted to be used in server or virtualhost
+    scope. If you're planning to use this in a <code>.htaccess</code>
+    file, you'll need to remove the leading slash from the rewrite
+    pattern in order for it to match anything:
+    <div class="example"><p><code>
+    RewriteRule ^product/(.*) /prods.php?id=${product2id:$1|NOTFOUND} [PT]
+    </code></p></div>
+    </div>
+
+    <div class="note"><h3>Cached lookups</h3>
+    <p>
+    The looked-up keys are cached by httpd until the <code>mtime</code>
+    (modified time) of the mapfile changes, or the httpd server is
+    restarted. This ensures better performance on maps that are called
+    by many requests.
+    </p>
+    </div>
+
+  </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="rnd" id="rnd">rnd: Randomized Plain Text</a></h2>
+    
+
+    <p>When a MapType of <code>rnd</code> is used, the MapSource is a
+    filesystem path to a plain-text mapping file, each line of which
+    contains a key, and one or more values separated by <code>|</code>.
+    One of these values will be chosen at random if the key is
+    matched.</p>
+
+    <p>For example, you might use the following map
+    file and directives to provide a random load balancing between
+    several back-end server, via a reverse-proxy. Images are sent
+    to one of the servers in the 'static' pool, while everything
+    else is sent to one of the 'dynamic' pool.</p>
+
+    <div class="example"><h3>Rewrite map file</h3><p><code>
+##<br />
+##  map.txt -- rewriting map<br />
+##<br />
+<br />
+static   www1|www2|www3|www4<br />
+dynamic  www5|www6
+    </code></p></div>
+
+    <div class="example"><h3>Configuration directives</h3><p><code>
+    RewriteMap servers rnd:/path/to/file/map.txt<br />
+    <br />
+    RewriteRule ^/(.*\.(png|gif|jpg)) http://${servers:static}/$1 [NC,P,L]<br />
+    RewriteRule ^/(.*) http://${servers:dynamic}/$1 [P,L]
+    </code></p></div>
+
+    <p>So, when an image is requested and the first of these rules is
+    matched, <code>RewriteMap</code> looks up the string
+    <code>static</code> in the map file, which returns one of the
+    specified hostnames at random, which is then used in the
+    <code>RewriteRule</code> target.</p>
+
+    <p>If you wanted to have one of the servers more likely to be chosen
+    (for example, if one of the server has more memory than the others,
+    and so can handle more requests) simply list it more times in the
+    map file.</p>
+
+    <div class="example"><p><code>
+static   www1|www1|www2|www3|www4
+    </code></p></div>
+
+  </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="dbm" id="dbm">dbm: DBM Hash File</a></h2>
+    
+
+    <p>When a MapType of <code>dbm</code> is used, the MapSource is a
+    filesystem path to a DBM database file containing key/value pairs to
+    be used in the mapping. This works exactly the same way as the
+    <code>txt</code> map, but is much faster, because a DBM is indexed,
+    whereas a text file is not. This allows more rapid access to the
+    desired key.</p>
+
+    <p>You may optionally specify a particular dbm type:</p>
+
+ <div class="example"><p><code>
+ RewriteMap examplemap dbm=sdbm:/etc/apache/mapfile.dbm
+ </code></p></div>
+
+    <p>The type can be sdbm, gdbm, ndbm or db.
+    However, it is recommended that you just use the <a href="../programs/httxt2dbm.html">httxt2dbm</a> utility that is
+    provided with Apache HTTP Server, as it will use the correct DBM library,
+    matching the one that was used when httpd itself was built.</p>
+
+    <p>To create a dbm file, first create a text map file as described
+    in the <a href="#txt">txt</a> section. Then run
+    <code>httxt2dbm</code>:</p>
+
+<div class="example"><p><code>
+$ httxt2dbm -i mapfile.txt -o mapfile.map
+</code></p></div>
+
+<p>You can then reference the resulting file in your
+<code>RewriteMap</code> directive:</p>
+
+<div class="example"><p><code>
+RewriteMap mapname dbm:/etc/apache/mapfile.map
+</code></p></div>
+
+<div class="note">
+<p>Note that with some dbm types, more than one file is generated, with
+a common base name. For example, you may have two files named
+<code>mapfile.map.dir</code> and <code>mapfiile.map.pag</code>. This is
+normal, and you need only use the base name <code>mapfile.map</code> in
+your <code>RewriteMap</code> directive.</p>
+</div>
+
+<div class="note"><h3>Cached lookups</h3>
+<p>
+The looked-up keys are cached by httpd until the <code>mtime</code>
+(modified time) of the mapfile changes, or the httpd server is
+restarted. This ensures better performance on maps that are called
+by many requests.
+</p>
+</div>
+
+  </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="int" id="int">int: Internal Function</a></h2>
+    
+
+    <p>When a MapType of <code>int</code> is used, the MapSource is one
+    of the available internal RewriteMap functions.  Module authors can provide 
+    additional internal functions by registering them with the
+    <code>ap_register_rewrite_mapfunc</code> API. 
+    The functions that are provided by default are:
+    </p>
+
+    <ul>
+      <li><strong>toupper</strong>:<br />
+             Converts the key to all upper case.</li>
+      <li><strong>tolower</strong>:<br />
+             Converts the key to all lower case.</li>
+      <li><strong>escape</strong>:<br />
+             Translates special characters in the key to
+            hex-encodings.</li>
+      <li><strong>unescape</strong>:<br />
+             Translates hex-encodings in the key back to
+            special characters.</li>
+    </ul>
+
+    <p>
+    To use one of these functions, create a <code>RewriteMap</code> referencing
+    the int function, and then use that in your <code>RewriteRule</code>:
+    </p>
+
+    <div class="example"><h3>Redirect a URI to an all-lowercase version of itself</h3><p><code>
+    RewriteMap lc int:tolower<br />
+    RewriteRule (.*[A-Z]+.*) ${lc:$1} [R]
+    </code></p></div>
+
+    <div class="note">
+    <p>Please note that the example offered here is for
+    illustration purposes only, and is not a recommendation. If you want
+    to make URLs case-insensitive, consider using
+    <code class="module"><a href="../mod/mod_speling.html">mod_speling</a></code> instead.
+    </p>
+    </div>
+
+  </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="prg" id="prg">prg: External Rewriting Program</a></h2>
+
+    <p>When a MapType of <code>prg</code> is used, the MapSource is a
+    filesystem path to an executable program which will providing the
+    mapping behavior. This can be a compiled binary file, or a program
+    in an interpreted language such as Perl or Python.</p>
+
+    <p>This program is started once, when the Apache HTTP Server is
+    started, and then communicates with the rewriting engine via
+    <code>STDIN</code> and <code>STDOUT</code>. That is, for each map
+    function lookup, it expects one argument via <code>STDIN</code>, and
+    should return one new-line terminated response string on
+    <code>STDOUT</code>. If there is no corresponding lookup value, the
+    map program should return the four-character string
+    "<code>NULL</code>" to indicate this.</p>
+
+    <p>External rewriting programs are not started if they're defined in
+    a context that does not have <code class="directive"><a href="../mod/mod_rewrite.html#rewriteengine">RewriteEngine</a></code> set to
+    <code>on</code>.</p>
+
+    <p>This feature utilizes the <code>rewrite-map</code> mutex,
+    which is required for reliable communication with the program.
+    The mutex mechanism and lock file can be configured with the
+    <code class="directive"><a href="../mod/core.html#mutex">Mutex</a></code> directive.</p>
+
+    <p>A simple example is shown here which will replace all dashes with
+    underscores in a request URI.</p>
+
+    <div class="example"><h3>Rewrite configuration</h3><p><code>
+    RewriteMap d2u prg:/www/bin/dash2under.pl<br />
+    RewriteRule - ${d2u:%{REQUEST_URI}}
+    </code></p></div>
+
+    <div class="example"><h3>dash2under.pl</h3><p><code>
+    #!/usr/bin/perl<br />
+    $| = 1; # Turn off I/O buffering<br />
+    while (&lt;STDIN&gt;) {<br />
+        <span class="indent">
+        s/-/_/g; # Replace dashes with underscores<br />
+        print $_;<br />
+        </span>
+    }<br />
+    </code></p></div>
+
+<div class="note"><h3>Caution!</h3>
+<ul>
+<li>Keep your rewrite map program as simple as possible. If the program
+hangs, it will cause httpd to wait indefinitely for a response from the
+map, which will, in turn, cause httpd to stop responding to
+requests.</li>
+<li>Be sure to turn off buffering in your program. In Perl this is done
+by the second line in the example script: <code>$| = 1;</code> This will
+of course vary in other languages. Buffered I/O will cause httpd to wait
+for the output, and so it will hang.</li>
+<li>Remember that there is only one copy of the program, started at
+server startup. All requests will need to go through this one bottleneck.
+This can cause significant slowdowns if many requests must go through
+this process, or if the script itself is very slow.</li>
+</ul>
+</div>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="dbd" id="dbd">dbd or fastdbd: SQL Query</a></h2>
+    
+
+    <p>When a MapType of <code>dbd</code> or <code>fastdbd</code> is
+    used, the MapSource is a SQL SELECT statement that takes a single
+    argument and returns a single value.</p>
+
+    <p><code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code> will need to be configured to point at
+    the right database for this statement to be executed.</p>
+
+    <p>There are two forms of this MapType.
+    Using a MapType of <code>dbd</code> causes the query to be
+    executed with each map request, while using <code>fastdbd</code>
+    caches the database lookups internally. So, while
+    <code>fastdbd</code> is more efficient, and therefore faster, it
+    won't pick up on changes to the database until the server is
+    restarted.</p>
+
+    <p>If a query returns more than one row, a random row from
+the result set is used.</p>
+
+    <div class="example"><h3>Example</h3><p><code>
+RewriteMap myquery "fastdbd:SELECT destination FROM rewrite WHERE source = %s"
+    </code></p></div>
+
+  </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="summary" id="summary">Summary</a></h2>
+    
+
+    <p>The <code class="directive">RewriteMap</code> directive can occur more than
+    once. For each mapping-function use one
+    <code class="directive">RewriteMap</code> directive to declare its rewriting
+    mapfile.</p>
+      
+    <p>While you cannot <strong>declare</strong> a map in
+    per-directory context (<code>.htaccess</code> files or
+    &lt;Directory&gt; blocks) it is possible to
+    <strong>use</strong> this map in per-directory context. </p>
+
+  </div></div>
+<div class="bottomlang">
+<p><span>Available Languages: </span><a href="../en/rewrite/rewritemap.html" title="English">&nbsp;en&nbsp;</a></p>
+</div><div id="footer">
+<p class="apache">Copyright 2011 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>
+<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>
+</body></html>
\ No newline at end of file

Added: httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewritemap.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewritemap.xml?rev=1082915&view=auto
==============================================================================
--- httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewritemap.xml (added)
+++ httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewritemap.xml Fri Mar 18 13:37:20 2011
@@ -0,0 +1,445 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+<!-- $LastChangedRevision: 882992 $ -->
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements.  See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License.  You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<manualpage metafile="rewritemap.xml.meta">
+  <parentdocument href="./">Rewrite</parentdocument>
+  <title>Using RewriteMap</title>
+  <summary>
+
+    <p>This document supplements the <module>mod_rewrite</module> 
+<a href="../mod/mod_rewrite.html">reference documentation</a>. It describes
+the use of the <directive module="mod_rewrite">RewriteMap</directive> directive,
+and provides examples of each of the various <code>RewriteMap</code> types.</p>
+
+    <note type="warning">Note that many of these examples won't work unchanged in your
+particular server configuration, so it's important that you understand
+them, rather than merely cutting and pasting the examples into your
+configuration.</note>
+
+  </summary>
+  <seealso><a href="../mod/mod_rewrite.html">Module documentation</a></seealso>
+  <seealso><a href="intro.html">mod_rewrite introduction</a></seealso>
+  <seealso><a href="remapping.html">Redirection and remapping</a></seealso>
+  <seealso><a href="access.html">Controlling access</a></seealso>
+  <seealso><a href="vhosts.html">Virtual hosts</a></seealso>
+  <seealso><a href="proxy.html">Proxying</a></seealso>
+  <seealso><a href="advanced.html">Advanced techniques and tricks</a></seealso>
+  <seealso><a href="avoid.html">When not to use mod_rewrite</a></seealso>
+
+  <section id="introduction">
+    <title>Introduction</title>
+
+   <p>
+   The <directive module="mod_rewrite">RewriteMap</directive> directive
+   defines an external function which can be called in the context of
+   <directive module="mod_rewrite">RewriteRule</directive> or
+   <directive module="mod_rewrite">RewriteCond</directive> directives to
+   perform rewriting that is too complicated, or too specialized to be
+   performed just by regular expressions. The source of this lookup can
+   be any of the types listed in the sections below, and enumerated in
+   the <directive module="mod_rewrite">RewriteMap</directive> reference
+   documentation.</p>
+
+   <p>The syntax of the <code>RewriteMap</code> directive is as
+   follows:</p>
+
+<example>
+RewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em>
+</example>
+    
+    <p>The <a id="mapfunc" name="mapfunc"><em>MapName</em></a> is an
+    arbitray name that you assign to the map, and which you will use in
+    directives later on. Arguments are passed to the map via the
+    following syntax:</p>
+
+    <p class="indent">
+      <strong>
+        <code>${</code> <em>MapName</em> <code>:</code> <em>LookupKey</em>
+        <code>}</code> <br/> <code>${</code> <em>MapName</em> <code>:</code>
+        <em>LookupKey</em> <code>|</code> <em>DefaultValue</em> <code>}</code>
+      </strong>
+    </p>
+
+    <p>When such a construct occurs, the map <em>MapName</em> is
+      consulted and the key <em>LookupKey</em> is looked-up. If the
+      key is found, the map-function construct is substituted by
+      <em>SubstValue</em>. If the key is not found then it is
+      substituted by <em>DefaultValue</em> or by the empty string
+      if no <em>DefaultValue</em> was specified.</p>
+
+    <p>For example, you might define a
+      <directive>RewriteMap</directive> as:</p>
+    <example>
+      RewriteMap examplemap txt:/path/to/file/map.txt
+      </example>
+    <p>You would then be able to use this map in a
+      <directive>RewriteRule</directive> as follows:</p>
+<example>
+  RewriteRule ^/ex/(.*) ${examplemap:$1}
+</example>
+
+<p>A default value can be specified in the event that nothing is found
+in the map:</p>
+
+<example>
+RewriteRule ^/ex/(.*) ${examplemap:$1|/not_found.html}
+</example>
+
+<note><title>Per-directory and .htaccess context</title>
+<p>
+The <code>RewriteMap</code> directive  may not be used in
+&lt;Directory&gt; sections or <code>.htaccess</code> files. You must
+declare the map in server or virtualhost context. You may use the map,
+once created, in your <code>RewriteRule</code> and
+<code>RewriteCond</code> directives in those scopes. You just can't
+<strong>declare</strong> it in those scopes.
+</p>
+</note>
+
+<p>The sections that follow describe the various <em>MapType</em>s that
+may be used, and give examples of each.</p>
+  </section>
+
+  <section id="txt">
+    <title>txt: Plain text maps</title>
+
+    <p>When a MapType of <code>txt</code> is used, the MapSource is a filesystem path to a
+    plain-text mapping file, containing space-separated key/value pair
+    per line. Optionally, a line may be contain a comment, starting with
+    a '#' character.</p>
+
+    <p>For example, the following might be valid entries in a map
+    file.</p>
+
+    <p class="indent">
+      # Comment line<br />
+      <strong><em>MatchingKey</em> <em>SubstValue</em></strong><br />
+      <strong><em>MatchingKey</em> <em>SubstValue</em></strong> # comment<br />
+    </p>
+
+    <p>When the RewriteMap is invoked the argument is looked for in the
+    first argument of a line, and, if found, the substitution value is
+    returned.</p>
+
+    <p>For example, we might use a mapfile to translate product names to
+    product IDs for easier-to-remember URLs, using the following
+    recipe:</p>
+
+    <example><title>Product to ID configuration</title>
+    RewriteMap product2id txt:/etc/apache2/productmap.txt<br />
+    RewriteRule ^/product/(.*) /prods.php?id=${product2id:$1|NOTFOUND} [PT]
+    </example>
+
+    <p>We assume here that the <code>prods.php</code> script knows what
+    to do when it received an argument of <code>id=NOTFOUND</code> when
+    a product is not found in the lookup map.</p>
+
+    <p>The file <code>/etc/apache2/productmap.txt</code> then contains
+    the following:</p>
+
+    <example><title>Product to ID map</title>
+##<br />
+##  productmap.txt - Product to ID map file<br />
+##<br />
+<br />
+television 993<br />
+stereo     198<br />
+fishingrod 043<br />
+basketball 418<br />
+telephone  328
+    </example>
+
+    <p>Thus, when <code>http://example.com/product/television</code> is
+    requested, the <code>RewriteRule</code> is applied, and the request
+    is internally mapped to <code>/prods.php?id=993</code>.</p>
+
+    <note><title>Note: .htaccess files</title>
+    The example given is crafted to be used in server or virtualhost
+    scope. If you're planning to use this in a <code>.htaccess</code>
+    file, you'll need to remove the leading slash from the rewrite
+    pattern in order for it to match anything:
+    <example>
+    RewriteRule ^product/(.*) /prods.php?id=${product2id:$1|NOTFOUND} [PT]
+    </example>
+    </note>
+
+    <note><title>Cached lookups</title>
+    <p>
+    The looked-up keys are cached by httpd until the <code>mtime</code>
+    (modified time) of the mapfile changes, or the httpd server is
+    restarted. This ensures better performance on maps that are called
+    by many requests.
+    </p>
+    </note>
+
+  </section>
+  <section id="rnd">
+    <title>rnd: Randomized Plain Text</title>
+
+    <p>When a MapType of <code>rnd</code> is used, the MapSource is a
+    filesystem path to a plain-text mapping file, each line of which
+    contains a key, and one or more values separated by <code>|</code>.
+    One of these values will be chosen at random if the key is
+    matched.</p>
+
+    <p>For example, you might use the following map
+    file and directives to provide a random load balancing between
+    several back-end server, via a reverse-proxy. Images are sent
+    to one of the servers in the 'static' pool, while everything
+    else is sent to one of the 'dynamic' pool.</p>
+
+    <example><title>Rewrite map file</title>
+##<br />
+##  map.txt -- rewriting map<br />
+##<br />
+<br />
+static   www1|www2|www3|www4<br />
+dynamic  www5|www6
+    </example>
+
+    <example><title>Configuration directives</title>
+    RewriteMap servers rnd:/path/to/file/map.txt<br/>
+    <br/>
+    RewriteRule ^/(.*\.(png|gif|jpg)) http://${servers:static}/$1 [NC,P,L]<br/>
+    RewriteRule ^/(.*) http://${servers:dynamic}/$1 [P,L]
+    </example>
+
+    <p>So, when an image is requested and the first of these rules is
+    matched, <code>RewriteMap</code> looks up the string
+    <code>static</code> in the map file, which returns one of the
+    specified hostnames at random, which is then used in the
+    <code>RewriteRule</code> target.</p>
+
+    <p>If you wanted to have one of the servers more likely to be chosen
+    (for example, if one of the server has more memory than the others,
+    and so can handle more requests) simply list it more times in the
+    map file.</p>
+
+    <example>
+static   www1|www1|www2|www3|www4
+    </example>
+
+  </section>
+
+  <section id="dbm">
+    <title>dbm: DBM Hash File</title>
+
+    <p>When a MapType of <code>dbm</code> is used, the MapSource is a
+    filesystem path to a DBM database file containing key/value pairs to
+    be used in the mapping. This works exactly the same way as the
+    <code>txt</code> map, but is much faster, because a DBM is indexed,
+    whereas a text file is not. This allows more rapid access to the
+    desired key.</p>
+
+    <p>You may optionally specify a particular dbm type:</p>
+
+ <example>
+ RewriteMap examplemap dbm=sdbm:/etc/apache/mapfile.dbm
+ </example>
+
+    <p>The type can be sdbm, gdbm, ndbm or db.
+    However, it is recommended that you just use the <a
+    href="../programs/httxt2dbm.html">httxt2dbm</a> utility that is
+    provided with Apache HTTP Server, as it will use the correct DBM library,
+    matching the one that was used when httpd itself was built.</p>
+
+    <p>To create a dbm file, first create a text map file as described
+    in the <a href="#txt">txt</a> section. Then run
+    <code>httxt2dbm</code>:</p>
+
+<example>
+$ httxt2dbm -i mapfile.txt -o mapfile.map
+</example>
+
+<p>You can then reference the resulting file in your
+<code>RewriteMap</code> directive:</p>
+
+<example>
+RewriteMap mapname dbm:/etc/apache/mapfile.map
+</example>
+
+<note>
+<p>Note that with some dbm types, more than one file is generated, with
+a common base name. For example, you may have two files named
+<code>mapfile.map.dir</code> and <code>mapfiile.map.pag</code>. This is
+normal, and you need only use the base name <code>mapfile.map</code> in
+your <code>RewriteMap</code> directive.</p>
+</note>
+
+<note><title>Cached lookups</title>
+<p>
+The looked-up keys are cached by httpd until the <code>mtime</code>
+(modified time) of the mapfile changes, or the httpd server is
+restarted. This ensures better performance on maps that are called
+by many requests.
+</p>
+</note>
+
+  </section>
+
+  <section id="int">
+    <title>int: Internal Function</title>
+
+    <p>When a MapType of <code>int</code> is used, the MapSource is one
+    of the available internal RewriteMap functions.  Module authors can provide 
+    additional internal functions by registering them with the
+    <code>ap_register_rewrite_mapfunc</code> API. 
+    The functions that are provided by default are:
+    </p>
+
+    <ul>
+      <li><strong>toupper</strong>:<br/>
+             Converts the key to all upper case.</li>
+      <li><strong>tolower</strong>:<br/>
+             Converts the key to all lower case.</li>
+      <li><strong>escape</strong>:<br/>
+             Translates special characters in the key to
+            hex-encodings.</li>
+      <li><strong>unescape</strong>:<br/>
+             Translates hex-encodings in the key back to
+            special characters.</li>
+    </ul>
+
+    <p>
+    To use one of these functions, create a <code>RewriteMap</code> referencing
+    the int function, and then use that in your <code>RewriteRule</code>:
+    </p>
+
+    <example><title>Redirect a URI to an all-lowercase version of itself</title>
+    RewriteMap lc int:tolower<br />
+    RewriteRule (.*[A-Z]+.*) ${lc:$1} [R]
+    </example>
+
+    <note>
+    <p>Please note that the example offered here is for
+    illustration purposes only, and is not a recommendation. If you want
+    to make URLs case-insensitive, consider using
+    <module>mod_speling</module> instead.
+    </p>
+    </note>
+
+  </section>
+
+  <section id="prg"><title>prg: External Rewriting Program</title>
+
+    <p>When a MapType of <code>prg</code> is used, the MapSource is a
+    filesystem path to an executable program which will providing the
+    mapping behavior. This can be a compiled binary file, or a program
+    in an interpreted language such as Perl or Python.</p>
+
+    <p>This program is started once, when the Apache HTTP Server is
+    started, and then communicates with the rewriting engine via
+    <code>STDIN</code> and <code>STDOUT</code>. That is, for each map
+    function lookup, it expects one argument via <code>STDIN</code>, and
+    should return one new-line terminated response string on
+    <code>STDOUT</code>. If there is no corresponding lookup value, the
+    map program should return the four-character string
+    "<code>NULL</code>" to indicate this.</p>
+
+    <p>External rewriting programs are not started if they're defined in
+    a context that does not have <directive
+    module="mod_rewrite">RewriteEngine</directive> set to
+    <code>on</code>.</p>
+
+    <p>This feature utilizes the <code>rewrite-map</code> mutex,
+    which is required for reliable communication with the program.
+    The mutex mechanism and lock file can be configured with the
+    <directive module="core">Mutex</directive> directive.</p>
+
+    <p>A simple example is shown here which will replace all dashes with
+    underscores in a request URI.</p>
+
+    <example><title>Rewrite configuration</title>
+    RewriteMap d2u prg:/www/bin/dash2under.pl<br />
+    RewriteRule - ${d2u:%{REQUEST_URI}}
+    </example>
+
+    <example><title>dash2under.pl</title>
+    #!/usr/bin/perl<br />
+    $| = 1; # Turn off I/O buffering<br />
+    while (&lt;STDIN&gt;) {<br />
+        <indent>
+        s/-/_/g; # Replace dashes with underscores<br />
+        print $_;<br />
+        </indent>
+    }<br />
+    </example>
+
+<note><title>Caution!</title>
+<ul>
+<li>Keep your rewrite map program as simple as possible. If the program
+hangs, it will cause httpd to wait indefinitely for a response from the
+map, which will, in turn, cause httpd to stop responding to
+requests.</li>
+<li>Be sure to turn off buffering in your program. In Perl this is done
+by the second line in the example script: <code>$| = 1;</code> This will
+of course vary in other languages. Buffered I/O will cause httpd to wait
+for the output, and so it will hang.</li>
+<li>Remember that there is only one copy of the program, started at
+server startup. All requests will need to go through this one bottleneck.
+This can cause significant slowdowns if many requests must go through
+this process, or if the script itself is very slow.</li>
+</ul>
+</note>
+
+</section>
+
+
+  <section id="dbd">
+    <title>dbd or fastdbd: SQL Query</title>
+
+    <p>When a MapType of <code>dbd</code> or <code>fastdbd</code> is
+    used, the MapSource is a SQL SELECT statement that takes a single
+    argument and returns a single value.</p>
+
+    <p><module>mod_dbd</module> will need to be configured to point at
+    the right database for this statement to be executed.</p>
+
+    <p>There are two forms of this MapType.
+    Using a MapType of <code>dbd</code> causes the query to be
+    executed with each map request, while using <code>fastdbd</code>
+    caches the database lookups internally. So, while
+    <code>fastdbd</code> is more efficient, and therefore faster, it
+    won't pick up on changes to the database until the server is
+    restarted.</p>
+
+    <p>If a query returns more than one row, a random row from
+the result set is used.</p>
+
+    <example><title>Example</title>
+RewriteMap myquery "fastdbd:SELECT destination FROM rewrite WHERE source = %s"
+    </example>
+
+  </section>
+  <section id="summary">
+    <title>Summary</title>
+
+    <p>The <directive>RewriteMap</directive> directive can occur more than
+    once. For each mapping-function use one
+    <directive>RewriteMap</directive> directive to declare its rewriting
+    mapfile.</p>
+      
+    <p>While you cannot <strong>declare</strong> a map in
+    per-directory context (<code>.htaccess</code> files or
+    &lt;Directory&gt; blocks) it is possible to
+    <strong>use</strong> this map in per-directory context. </p>
+
+  </section>
+</manualpage>

Added: httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewritemap.xml.meta
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewritemap.xml.meta?rev=1082915&view=auto
==============================================================================
--- httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewritemap.xml.meta (added)
+++ httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewritemap.xml.meta Fri Mar 18 13:37:20 2011
@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!-- GENERATED FROM XML: DO NOT EDIT -->
+
+<metafile reference="rewritemap.xml">
+  <basename>rewritemap</basename>
+  <path>/rewrite/</path>
+  <relpath>..</relpath>
+
+  <variants>
+    <variant>en</variant>
+  </variants>
+</metafile>

Added: httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.html
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.html?rev=1082915&view=auto
==============================================================================
--- httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.html (added)
+++ httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.html Fri Mar 18 13:37:20 2011
@@ -0,0 +1,9 @@
+# GENERATED FROM XML -- DO NOT EDIT
+
+URI: tech.html.en
+Content-Language: en
+Content-type: text/html; charset=ISO-8859-1
+
+URI: tech.html.fr
+Content-Language: fr
+Content-type: text/html; charset=ISO-8859-1

Added: httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.html.en
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.html.en?rev=1082915&view=auto
==============================================================================
--- httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.html.en (added)
+++ httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.html.en Fri Mar 18 13:37:20 2011
@@ -0,0 +1,165 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
+        XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+              This file is generated from xml source: DO NOT EDIT
+        XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+      -->
+<title>Apache mod_rewrite Technical Details - Apache HTTP Server</title>
+<link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
+<link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
+<link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
+<link href="../images/favicon.ico" rel="shortcut icon" /></head>
+<body id="manual-page"><div id="page-header">
+<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>
+<p class="apache">Apache HTTP Server Version 2.2</p>
+<img alt="" src="../images/feather.gif" /></div>
+<div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
+<div id="path">
+<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.2</a> &gt; <a href="./">Rewrite</a></div><div id="page-content"><div id="preamble"><h1>Apache mod_rewrite Technical Details</h1>
+<div class="toplang">
+<p><span>Available Languages: </span><a href="../en/rewrite/tech.html" title="English">&nbsp;en&nbsp;</a> |
+<a href="../fr/rewrite/tech.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a></p>
+</div>
+
+<p>This document discusses some of the technical details of mod_rewrite
+and URL matching.</p>
+</div>
+<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#Internal">Internal Processing</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#InternalAPI">API Phases</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#InternalRuleset">Ruleset Processing</a></li>
+</ul><h3>See also</h3><ul class="seealso"><li><a href="../mod/mod_rewrite.html">Module documentation</a></li><li><a href="intro.html">mod_rewrite introduction</a></li><li><a href="remapping.html">Redirection and remapping</a></li><li><a href="access.html">Controlling access</a></li><li><a href="vhosts.html">Virtual hosts</a></li><li><a href="proxy.html">Proxying</a></li><li><a href="rewritemap.html">Using RewriteMap</a></li><li><a href="advanced.html">Advanced techniques and tricks</a></li><li><a href="avoid.html">When not to use mod_rewrite</a></li></ul></div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="Internal" id="Internal">Internal Processing</a></h2>
+
+      <p>The internal processing of this module is very complex but
+      needs to be explained once even to the average user to avoid
+      common mistakes and to let you exploit its full
+      functionality.</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="InternalAPI" id="InternalAPI">API Phases</a></h2>
+
+      <p>First you have to understand that when Apache processes a
+      HTTP request it does this in phases. A hook for each of these
+      phases is provided by the Apache API. Mod_rewrite uses two of
+      these hooks: the URL-to-filename translation hook which is
+      used after the HTTP request has been read but before any
+      authorization starts and the Fixup hook which is triggered
+      after the authorization phases and after the per-directory
+      config files (<code>.htaccess</code>) have been read, but
+      before the content handler is activated.</p>
+
+      <p>So, after a request comes in and Apache has determined the
+      corresponding server (or virtual server) the rewriting engine
+      starts processing of all mod_rewrite directives from the
+      per-server configuration in the URL-to-filename phase. A few
+      steps later when the final data directories are found, the
+      per-directory configuration directives of mod_rewrite are
+      triggered in the Fixup phase. In both situations mod_rewrite
+      rewrites URLs either to new URLs or to filenames, although
+      there is no obvious distinction between them. This is a usage
+      of the API which was not intended to be this way when the API
+      was designed, but as of Apache 1.x this is the only way
+      mod_rewrite can operate. To make this point more clear
+      remember the following two points:</p>
+
+      <ol>
+        <li>Although mod_rewrite rewrites URLs to URLs, URLs to
+        filenames and even filenames to filenames, the API
+        currently provides only a URL-to-filename hook. In Apache
+        2.0 the two missing hooks will be added to make the
+        processing more clear. But this point has no drawbacks for
+        the user, it is just a fact which should be remembered:
+        Apache does more in the URL-to-filename hook than the API
+        intends for it.</li>
+
+        <li>
+          Unbelievably mod_rewrite provides URL manipulations in
+          per-directory context, <em>i.e.</em>, within
+          <code>.htaccess</code> files, although these are reached
+          a very long time after the URLs have been translated to
+          filenames. It has to be this way because
+          <code>.htaccess</code> files live in the filesystem, so
+          processing has already reached this stage. In other
+          words: According to the API phases at this time it is too
+          late for any URL manipulations. To overcome this chicken
+          and egg problem mod_rewrite uses a trick: When you
+          manipulate a URL/filename in per-directory context
+          mod_rewrite first rewrites the filename back to its
+          corresponding URL (which is usually impossible, but see
+          the <code>RewriteBase</code> directive below for the
+          trick to achieve this) and then initiates a new internal
+          sub-request with the new URL. This restarts processing of
+          the API phases. 
+
+          <p>Again mod_rewrite tries hard to make this complicated
+          step totally transparent to the user, but you should
+          remember here: While URL manipulations in per-server
+          context are really fast and efficient, per-directory
+          rewrites are slow and inefficient due to this chicken and
+          egg problem. But on the other hand this is the only way
+          mod_rewrite can provide (locally restricted) URL
+          manipulations to the average user.</p>
+        </li>
+      </ol>
+
+      <p>Don't forget these two points!</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="InternalRuleset" id="InternalRuleset">Ruleset Processing</a></h2>
+ 
+      <p>Now when mod_rewrite is triggered in these two API phases, it
+      reads the configured rulesets from its configuration
+      structure (which itself was either created on startup for
+      per-server context or during the directory walk of the Apache
+      kernel for per-directory context). Then the URL rewriting
+      engine is started with the contained ruleset (one or more
+      rules together with their conditions). The operation of the
+      URL rewriting engine itself is exactly the same for both
+      configuration contexts. Only the final result processing is
+      different. </p>
+
+      <p>The order of rules in the ruleset is important because the
+      rewriting engine processes them in a special (and not very
+      obvious) order. The rule is this: The rewriting engine loops
+      through the ruleset rule by rule (<code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> directives) and
+      when a particular rule matches it optionally loops through
+      existing corresponding conditions (<code>RewriteCond</code>
+      directives). For historical reasons the conditions are given
+      first, and so the control flow is a little bit long-winded. See
+      Figure 1 for more details.</p>
+<p class="figure">
+      <img src="../images/rewrite_rule_flow.png" alt="Flow of RewriteRule and RewriteCond matching" /><br />
+      <dfn>Figure 1:</dfn>The control flow through the rewriting ruleset
+</p>
+      <p>As you can see, first the URL is matched against the
+      <em>Pattern</em> of each rule. When it fails mod_rewrite
+      immediately stops processing this rule and continues with the
+      next rule. If the <em>Pattern</em> matches, mod_rewrite looks
+      for corresponding rule conditions. If none are present, it
+      just substitutes the URL with a new value which is
+      constructed from the string <em>Substitution</em> and goes on
+      with its rule-looping. But if conditions exist, it starts an
+      inner loop for processing them in the order that they are
+      listed. For conditions the logic is different: we don't match
+      a pattern against the current URL. Instead we first create a
+      string <em>TestString</em> by expanding variables,
+      back-references, map lookups, <em>etc.</em> and then we try
+      to match <em>CondPattern</em> against it. If the pattern
+      doesn't match, the complete set of conditions and the
+      corresponding rule fails. If the pattern matches, then the
+      next condition is processed until no more conditions are
+      available. If all conditions match, processing is continued
+      with the substitution of the URL with
+      <em>Substitution</em>.</p>
+
+</div></div>
+<div class="bottomlang">
+<p><span>Available Languages: </span><a href="../en/rewrite/tech.html" title="English">&nbsp;en&nbsp;</a> |
+<a href="../fr/rewrite/tech.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a></p>
+</div><div id="footer">
+<p class="apache">Copyright 2011 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>
+<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>
+</body></html>
\ No newline at end of file

Added: httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.html.fr
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.html.fr?rev=1082915&view=auto
==============================================================================
--- httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.html.fr (added)
+++ httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.html.fr Fri Mar 18 13:37:20 2011
@@ -0,0 +1,178 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="fr" xml:lang="fr"><head><!--
+        XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+              This file is generated from xml source: DO NOT EDIT
+        XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+      -->
+<title>Détails techniques sur le module Apache mod_rewrite - Serveur Apache HTTP</title>
+<link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
+<link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
+<link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
+<link href="../images/favicon.ico" rel="shortcut icon" /></head>
+<body id="manual-page"><div id="page-header">
+<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossaire</a> | <a href="../sitemap.html">Plan du site</a></p>
+<p class="apache">Serveur Apache HTTP Version 2.2</p>
+<img alt="" src="../images/feather.gif" /></div>
+<div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
+<div id="path">
+<a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">Serveur HTTP</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.2</a> &gt; <a href="./">Rewrite</a></div><div id="page-content"><div id="preamble"><h1>Détails techniques sur le module Apache mod_rewrite</h1>
+<div class="toplang">
+<p><span>Langues Disponibles: </span><a href="../en/rewrite/tech.html" hreflang="en" rel="alternate" title="English">&nbsp;en&nbsp;</a> |
+<a href="../fr/rewrite/tech.html" title="Français">&nbsp;fr&nbsp;</a></p>
+</div>
+
+<p>Ce document passe en revue certains détails techniques à propos du
+module mod_rewrite et de la mise en correspondance des URLs</p>
+</div>
+<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#Internal">Fonctionnement interne</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#InternalAPI">Phases de l'API</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#InternalRuleset">Traitement du jeu de règles</a></li>
+</ul><h3>Voir aussi</h3><ul class="seealso"><li><a href="../mod/mod_rewrite.html">Documentation du module mod_rewrite</a></li><li><a href="intro.html">Introduction à mod_rewrite</a></li><li><a href="remapping.html">Redirection et remise en
+correspondance</a></li><li><a href="access.html">Contrôle d'accès</a></li><li><a href="vhosts.html">Serveurs virtuels</a></li><li><a href="proxy.html">Mise en cache</a></li><li><a href="rewritemap.html">Utilisation de RewriteMap</a></li><li><a href="advanced.html">Techniques avancées et astuces</a></li><li><a href="avoid.html">Quand ne pas utiliser mod_rewrite</a></li></ul></div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="Internal" id="Internal">Fonctionnement interne</a></h2>
+
+      <p>Le fonctionnement interne de ce module est très complexe, mais
+      il est nécessaire de l'expliquer, même à l'utilisateur "standard",
+      afin d'éviter les erreurs courantes et de pouvoir exploiter toutes
+      ses fonctionnalités.</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="InternalAPI" id="InternalAPI">Phases de l'API</a></h2>
+
+      <p>Il faut tout d'abord bien comprendre que le traitement d'une
+      requête HTTP par Apache s'effectue en plusieurs phases. L'API
+      d'Apache fournit un point d'accroche (hook) pour chacune de ces
+      phases. Mod_rewrite utilise deux de ces hooks : le hook de
+      conversion des URLs en noms de fichiers qui est utilisé quand la
+      requête HTTP a été lue mais avant le démarrage de tout processus
+      d'autorisation, et le hook "Fixup" qui est déclenché après les
+      phases d'autorisation et après la lecture des fichiers de
+      configuration niveau répertoire (<code>.htaccess</code>), mais
+      avant que le gestionnaire de contenu soit activé.</p>
+
+      <p>Donc, lorsqu'une requête arrive et quand Apache a déterminé le
+      serveur correspondant (ou le serveur virtuel), le moteur de
+      réécriture commence le traitement de toutes les directives de
+      mod_rewrite de la configuration du serveur principal dans la phase
+      de conversion URL vers nom de fichier. Une fois ces étapes
+      franchies, lorsque les repertoires de données finaux ont été
+      trouvés, les directives de configuration de mod_rewrite au niveau
+      répertoire sont éxécutées dans la phase Fixup. Dans les deux cas,
+      mod_rewrite réécrit les URLs soit en nouvelles URLs, soit en noms
+      de fichiers, bien que la distinction entre les deux ne soit pas
+      évidente. Cette utilisation de l'API n'était pas sensée s'opérer
+      de cette manière lorsque l'API fut conçue, mais depuis Apache 1.x,
+      c'est le seul mode opératoire possible pour mod_rewrite. Afin de
+      rendre les choses plus claires, souvenez-vous de ces deux points :</p>
+
+      <ol>
+        <li>Bien que mod_rewrite réécrive les URLs en URLs, les URLs en
+	noms de fichiers et même des noms de fichiers en d'autres noms
+	de fichiers, l'API ne propose actuellement qu'un hook URL vers
+	nom de fichier. Les deux hooks manquants seront ajoutés dans
+	Apache à partir de la version 2.0 afin de rendre le processus
+	plus clair. Mais ce point ne présente pas d'inconvénient pour
+	l'utilisateur, il s'agit simplement d'un fait que vous devez
+	garder à l'esprit : Apache en fait plus avec le hook URL vers
+	nom de fichier que l'API n'a la prétention d'en faire.</li>
+
+        <li>
+          Paradoxalement, mod_rewrite permet la manipulation d'URLs dans
+	  un contexte de répertoire, <em>c'est à dire</em> dans les
+	  fichiers <code>.htaccess</code>, bien que ces derniers
+	  soient traités bien longtemps après que les URLs n'aient été
+	  traduites en noms de fichiers. Les choses doivent se dérouler
+	  ainsi car les fichiers <code>.htaccess</code> résident dans le
+	  système de fichiers, et le traitement a déjà atteint
+	  cette étape. Autrement dit, en accord avec les phases de
+	  l'API, à ce point du traitement, il est trop tard pour
+	  effectuer des manipulations d'URLs. Pour résoudre ce problème
+	  d'antériorité, mod_rewrite utilise une astuce : pour effectuer
+	  une manipulation URL/nom de fichier dans un contexte de
+	  répertoire, mod_rewrite réécrit tout d'abord le nom de fichier
+	  en son URL d'origine (ce qui est normalement impossible, mais
+	  voir ci-dessous l'astuce utilisée par la directive
+	  <code>RewriteBase</code> pour y parvenir), puis
+	  initialise une nouvelle sous-requête interne avec la nouvelle
+	  URL ; ce qui a pour effet de redémarrer le processus des
+	  phases de l'API.
+
+          <p>Encore une fois, mod_rewrite fait tout ce qui est en son
+	  pouvoir pour rendre la complexité de cette étape complètement
+	  transparente à l'utilisateur, mais vous devez garder ceci à
+	  l'esprit : alors que les manipulations d'URLs dans le contexte
+	  du serveur sont vraiment rapides et efficaces, les réécritures
+	  dans un contexte de répertoire sont lentes et inefficaces à
+	  cause du problème d'antériorité précité. Cependant, c'est la
+	  seule manière dont mod_rewrite peut proposer des manipulations
+	  d'URLs (limitées à une branche du système de fichiers) à
+	  l'utilisateur standard.</p>
+        </li>
+      </ol>
+
+      <p>Ne perdez pas de vue ces deux points!</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="InternalRuleset" id="InternalRuleset">Traitement du jeu de règles</a></h2>
+
+      <p>Maintenant, quand mod_rewrite se lance dans ces deux phases de
+      l'API, il lit le jeu de règles configurées depuis la structure
+      contenant sa configuration (qui a été elle-même créée soit au
+      démarrage d'Apache pour le contexte du serveur, soit lors du
+      parcours des répertoires par le noyau d'Apache pour le contexte de
+      répertoire). Puis le moteur de réécriture est démarré avec le jeu
+      de règles contenu (une ou plusieurs règles associées à leurs
+      conditions). En lui-même, le mode opératoire du moteur de
+      réécriture d'URLs est exactement le même dans les deux contextes
+      de configuration. Seul le traitement du résultat final diffère.</p>
+
+      <p>L'ordre dans lequel les règles sont définies est important car
+      le moteur de réécriture les traite selon une chronologie
+      particulière (et pas très évidente). Le principe est le suivant :
+      le moteur de réécriture traite les règles (les directives <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>) les unes
+      à la suite des autres, et lorsqu'une règle s'applique, il parcourt
+      les éventuelles conditions (directives
+      <code>RewriteCond</code>directives) associées.
+      Pour des raisons historiques, les
+      conditions précèdent les règles, si bien que le déroulement du
+      contrôle est un peu compliqué. Voir la figure 1 pour plus de
+      détails.</p>
+<p class="figure">
+      <img src="../images/rewrite_rule_flow.png" alt="Flux des comparaisons des directives RewriteRule et RewriteCond" /><br />
+      <dfn>Figure 1:</dfn>Déroulement du contrôle à travers le jeu de
+      règles de réécriture
+</p>
+      <p>Comme vous pouvez le voir, l'URL est tout d'abord comparée au
+      <em>Modèle</em> de chaque règle. Lorsqu'une règle ne s'applique
+      pas, mod_rewrite stoppe immédiatement le traitement de cette règle
+      et passe à la règle suivante. Si l'URL correspond au
+      <em>Modèle</em>, mod_rewrite recherche la présence de conditions
+      correspondantes. S'il n'y en a pas, mod_rewrite remplace
+      simplement l'URL par une chaîne élaborée à partir de la chaîne de
+      <em>Substitution</em>, puis passe à la règle suivante. Si des
+      conditions sont présentes, mod_rewrite lance un bouclage
+      secondaire afin de les traiter selon l'ordre dans lequel elles
+      sont définies. La logique de traitement des conditions est
+      différente : on ne compare pas l'URL à un modèle. Une chaîne de
+      test <em>TestString</em> est tout d'abord élaborée en développant
+      des variables, des références arrières, des recherches dans des
+      tables de correspondances, etc..., puis cette chaîne de test est
+      comparée au modèle de condition <em>CondPattern</em>. Si le modèle
+      ne correspond pas, les autres conditions du jeu ne sont pas
+      examinées et la règle correspondante ne s'applique pas. Si le
+      modèle correspond, la condition suivante est examinée et ainsi de
+      suite jusqu'à la dernière condition. Si toutes les conditions sont
+      satisfaites, le traitement de la règle en cours se poursuit avec
+      le remplacement de l'URL par la chaîne de <em>Substitution</em>.</p>
+
+</div></div>
+<div class="bottomlang">
+<p><span>Langues Disponibles: </span><a href="../en/rewrite/tech.html" hreflang="en" rel="alternate" title="English">&nbsp;en&nbsp;</a> |
+<a href="../fr/rewrite/tech.html" title="Français">&nbsp;fr&nbsp;</a></p>
+</div><div id="footer">
+<p class="apache">Copyright 2011 The Apache Software Foundation.<br />Autorisé sous <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
+<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossaire</a> | <a href="../sitemap.html">Plan du site</a></p></div>
+</body></html>
\ No newline at end of file

Added: httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.xml?rev=1082915&view=auto
==============================================================================
--- httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.xml (added)
+++ httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.xml Fri Mar 18 13:37:20 2011
@@ -0,0 +1,172 @@
+<?xml version='1.0' encoding='UTF-8' ?>
+<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+<!-- $LastChangedRevision: 945974 $ -->
+
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements.  See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License.  You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<manualpage metafile="tech.xml.meta">
+<parentdocument href="./">Rewrite</parentdocument>
+
+  <title>Apache mod_rewrite Technical Details</title>
+
+<summary>
+<p>This document discusses some of the technical details of mod_rewrite
+and URL matching.</p>
+</summary>
+<seealso><a href="../mod/mod_rewrite.html">Module documentation</a></seealso>
+<seealso><a href="intro.html">mod_rewrite introduction</a></seealso>
+<seealso><a href="remapping.html">Redirection and remapping</a></seealso>
+<seealso><a href="access.html">Controlling access</a></seealso>
+<seealso><a href="vhosts.html">Virtual hosts</a></seealso>
+<seealso><a href="proxy.html">Proxying</a></seealso>
+<seealso><a href="rewritemap.html">Using RewriteMap</a></seealso>
+<seealso><a href="advanced.html">Advanced techniques and tricks</a></seealso>
+<seealso><a href="avoid.html">When not to use mod_rewrite</a></seealso>
+
+<section id="Internal"><title>Internal Processing</title>
+
+      <p>The internal processing of this module is very complex but
+      needs to be explained once even to the average user to avoid
+      common mistakes and to let you exploit its full
+      functionality.</p>
+</section>
+
+<section id="InternalAPI"><title>API Phases</title>
+
+      <p>First you have to understand that when Apache processes a
+      HTTP request it does this in phases. A hook for each of these
+      phases is provided by the Apache API. Mod_rewrite uses two of
+      these hooks: the URL-to-filename translation hook which is
+      used after the HTTP request has been read but before any
+      authorization starts and the Fixup hook which is triggered
+      after the authorization phases and after the per-directory
+      config files (<code>.htaccess</code>) have been read, but
+      before the content handler is activated.</p>
+
+      <p>So, after a request comes in and Apache has determined the
+      corresponding server (or virtual server) the rewriting engine
+      starts processing of all mod_rewrite directives from the
+      per-server configuration in the URL-to-filename phase. A few
+      steps later when the final data directories are found, the
+      per-directory configuration directives of mod_rewrite are
+      triggered in the Fixup phase. In both situations mod_rewrite
+      rewrites URLs either to new URLs or to filenames, although
+      there is no obvious distinction between them. This is a usage
+      of the API which was not intended to be this way when the API
+      was designed, but as of Apache 1.x this is the only way
+      mod_rewrite can operate. To make this point more clear
+      remember the following two points:</p>
+
+      <ol>
+        <li>Although mod_rewrite rewrites URLs to URLs, URLs to
+        filenames and even filenames to filenames, the API
+        currently provides only a URL-to-filename hook. In Apache
+        2.0 the two missing hooks will be added to make the
+        processing more clear. But this point has no drawbacks for
+        the user, it is just a fact which should be remembered:
+        Apache does more in the URL-to-filename hook than the API
+        intends for it.</li>
+
+        <li>
+          Unbelievably mod_rewrite provides URL manipulations in
+          per-directory context, <em>i.e.</em>, within
+          <code>.htaccess</code> files, although these are reached
+          a very long time after the URLs have been translated to
+          filenames. It has to be this way because
+          <code>.htaccess</code> files live in the filesystem, so
+          processing has already reached this stage. In other
+          words: According to the API phases at this time it is too
+          late for any URL manipulations. To overcome this chicken
+          and egg problem mod_rewrite uses a trick: When you
+          manipulate a URL/filename in per-directory context
+          mod_rewrite first rewrites the filename back to its
+          corresponding URL (which is usually impossible, but see
+          the <code>RewriteBase</code> directive below for the
+          trick to achieve this) and then initiates a new internal
+          sub-request with the new URL. This restarts processing of
+          the API phases. 
+
+          <p>Again mod_rewrite tries hard to make this complicated
+          step totally transparent to the user, but you should
+          remember here: While URL manipulations in per-server
+          context are really fast and efficient, per-directory
+          rewrites are slow and inefficient due to this chicken and
+          egg problem. But on the other hand this is the only way
+          mod_rewrite can provide (locally restricted) URL
+          manipulations to the average user.</p>
+        </li>
+      </ol>
+
+      <p>Don't forget these two points!</p>
+</section>
+
+<section id="InternalRuleset"><title>Ruleset Processing</title>
+ 
+      <p>Now when mod_rewrite is triggered in these two API phases, it
+      reads the configured rulesets from its configuration
+      structure (which itself was either created on startup for
+      per-server context or during the directory walk of the Apache
+      kernel for per-directory context). Then the URL rewriting
+      engine is started with the contained ruleset (one or more
+      rules together with their conditions). The operation of the
+      URL rewriting engine itself is exactly the same for both
+      configuration contexts. Only the final result processing is
+      different. </p>
+
+      <p>The order of rules in the ruleset is important because the
+      rewriting engine processes them in a special (and not very
+      obvious) order. The rule is this: The rewriting engine loops
+      through the ruleset rule by rule (<directive
+      module="mod_rewrite">RewriteRule</directive> directives) and
+      when a particular rule matches it optionally loops through
+      existing corresponding conditions (<code>RewriteCond</code>
+      directives). For historical reasons the conditions are given
+      first, and so the control flow is a little bit long-winded. See
+      Figure 1 for more details.</p>
+<p class="figure">
+      <img src="../images/rewrite_rule_flow.png"
+          alt="Flow of RewriteRule and RewriteCond matching" /><br />
+      <dfn>Figure 1:</dfn>The control flow through the rewriting ruleset
+</p>
+      <p>As you can see, first the URL is matched against the
+      <em>Pattern</em> of each rule. When it fails mod_rewrite
+      immediately stops processing this rule and continues with the
+      next rule. If the <em>Pattern</em> matches, mod_rewrite looks
+      for corresponding rule conditions. If none are present, it
+      just substitutes the URL with a new value which is
+      constructed from the string <em>Substitution</em> and goes on
+      with its rule-looping. But if conditions exist, it starts an
+      inner loop for processing them in the order that they are
+      listed. For conditions the logic is different: we don't match
+      a pattern against the current URL. Instead we first create a
+      string <em>TestString</em> by expanding variables,
+      back-references, map lookups, <em>etc.</em> and then we try
+      to match <em>CondPattern</em> against it. If the pattern
+      doesn't match, the complete set of conditions and the
+      corresponding rule fails. If the pattern matches, then the
+      next condition is processed until no more conditions are
+      available. If all conditions match, processing is continued
+      with the substitution of the URL with
+      <em>Substitution</em>.</p>
+
+</section>
+
+
+</manualpage>
+

Added: httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.xml.fr
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.xml.fr?rev=1082915&view=auto
==============================================================================
--- httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.xml.fr (added)
+++ httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.xml.fr Fri Mar 18 13:37:20 2011
@@ -0,0 +1,187 @@
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.fr.xsl"?>
+<!-- English Revision : 945974 -->
+<!-- French translation : Lucien GENTIS -->
+<!-- Reviewed by : Vincent Deffontaines -->
+
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements.  See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License.  You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<manualpage metafile="tech.xml.meta">
+<parentdocument href="./">Rewrite</parentdocument>
+
+  <title>D&eacute;tails techniques sur le module Apache mod_rewrite</title>
+
+<summary>
+<p>Ce document passe en revue certains d&eacute;tails techniques &agrave; propos du
+module mod_rewrite et de la mise en correspondance des URLs</p>
+</summary>
+<seealso><a href="../mod/mod_rewrite.html">Documentation du module mod_rewrite</a></seealso>
+<seealso><a href="intro.html">Introduction &agrave; mod_rewrite</a></seealso>
+<seealso><a href="remapping.html">Redirection et remise en
+correspondance</a></seealso>
+<seealso><a href="access.html">Contr&ocirc;le d'acc&egrave;s</a></seealso>
+<seealso><a href="vhosts.html">Serveurs virtuels</a></seealso>
+<seealso><a href="proxy.html">Mise en cache</a></seealso>
+<seealso><a href="rewritemap.html">Utilisation de RewriteMap</a></seealso>
+<seealso><a href="advanced.html">Techniques avanc&eacute;es et astuces</a></seealso>
+<seealso><a href="avoid.html">Quand ne pas utiliser mod_rewrite</a></seealso>
+
+<section id="Internal"><title>Fonctionnement interne</title>
+
+      <p>Le fonctionnement interne de ce module est tr&egrave;s complexe, mais
+      il est n&eacute;cessaire de l'expliquer, m&ecirc;me &agrave; l'utilisateur "standard",
+      afin d'&eacute;viter les erreurs courantes et de pouvoir exploiter toutes
+      ses fonctionnalit&eacute;s.</p>
+</section>
+
+<section id="InternalAPI"><title>Phases de l'API</title>
+
+      <p>Il faut tout d'abord bien comprendre que le traitement d'une
+      requ&ecirc;te HTTP par Apache s'effectue en plusieurs phases. L'API
+      d'Apache fournit un point d'accroche (hook) pour chacune de ces
+      phases. Mod_rewrite utilise deux de ces hooks : le hook de
+      conversion des URLs en noms de fichiers qui est utilis&eacute; quand la
+      requ&ecirc;te HTTP a &eacute;t&eacute; lue mais avant le d&eacute;marrage de tout processus
+      d'autorisation, et le hook "Fixup" qui est d&eacute;clench&eacute; apr&egrave;s les
+      phases d'autorisation et apr&egrave;s la lecture des fichiers de
+      configuration niveau r&eacute;pertoire (<code>.htaccess</code>), mais
+      avant que le gestionnaire de contenu soit activ&eacute;.</p>
+
+      <p>Donc, lorsqu'une requ&ecirc;te arrive et quand Apache a d&eacute;termin&eacute; le
+      serveur correspondant (ou le serveur virtuel), le moteur de
+      r&eacute;&eacute;criture commence le traitement de toutes les directives de
+      mod_rewrite de la configuration du serveur principal dans la phase
+      de conversion URL vers nom de fichier. Une fois ces &eacute;tapes
+      franchies, lorsque les repertoires de donn&eacute;es finaux ont &eacute;t&eacute;
+      trouv&eacute;s, les directives de configuration de mod_rewrite au niveau
+      r&eacute;pertoire sont &eacute;x&eacute;cut&eacute;es dans la phase Fixup. Dans les deux cas,
+      mod_rewrite r&eacute;&eacute;crit les URLs soit en nouvelles URLs, soit en noms
+      de fichiers, bien que la distinction entre les deux ne soit pas
+      &eacute;vidente. Cette utilisation de l'API n'&eacute;tait pas sens&eacute;e s'op&eacute;rer
+      de cette mani&egrave;re lorsque l'API fut con&ccedil;ue, mais depuis Apache 1.x,
+      c'est le seul mode op&eacute;ratoire possible pour mod_rewrite. Afin de
+      rendre les choses plus claires, souvenez-vous de ces deux points :</p>
+
+      <ol>
+        <li>Bien que mod_rewrite r&eacute;&eacute;crive les URLs en URLs, les URLs en
+	noms de fichiers et m&ecirc;me des noms de fichiers en d'autres noms
+	de fichiers, l'API ne propose actuellement qu'un hook URL vers
+	nom de fichier. Les deux hooks manquants seront ajout&eacute;s dans
+	Apache &agrave; partir de la version 2.0 afin de rendre le processus
+	plus clair. Mais ce point ne pr&eacute;sente pas d'inconv&eacute;nient pour
+	l'utilisateur, il s'agit simplement d'un fait que vous devez
+	garder &agrave; l'esprit : Apache en fait plus avec le hook URL vers
+	nom de fichier que l'API n'a la pr&eacute;tention d'en faire.</li>
+
+        <li>
+          Paradoxalement, mod_rewrite permet la manipulation d'URLs dans
+	  un contexte de r&eacute;pertoire, <em>c'est &agrave; dire</em> dans les
+	  fichiers <code>.htaccess</code>, bien que ces derniers
+	  soient trait&eacute;s bien longtemps apr&egrave;s que les URLs n'aient &eacute;t&eacute;
+	  traduites en noms de fichiers. Les choses doivent se d&eacute;rouler
+	  ainsi car les fichiers <code>.htaccess</code> r&eacute;sident dans le
+	  syst&egrave;me de fichiers, et le traitement a d&eacute;j&agrave; atteint
+	  cette &eacute;tape. Autrement dit, en accord avec les phases de
+	  l'API, &agrave; ce point du traitement, il est trop tard pour
+	  effectuer des manipulations d'URLs. Pour r&eacute;soudre ce probl&egrave;me
+	  d'ant&eacute;riorit&eacute;, mod_rewrite utilise une astuce : pour effectuer
+	  une manipulation URL/nom de fichier dans un contexte de
+	  r&eacute;pertoire, mod_rewrite r&eacute;&eacute;crit tout d'abord le nom de fichier
+	  en son URL d'origine (ce qui est normalement impossible, mais
+	  voir ci-dessous l'astuce utilis&eacute;e par la directive
+	  <code>RewriteBase</code> pour y parvenir), puis
+	  initialise une nouvelle sous-requ&ecirc;te interne avec la nouvelle
+	  URL ; ce qui a pour effet de red&eacute;marrer le processus des
+	  phases de l'API.
+
+          <p>Encore une fois, mod_rewrite fait tout ce qui est en son
+	  pouvoir pour rendre la complexit&eacute; de cette &eacute;tape compl&egrave;tement
+	  transparente &agrave; l'utilisateur, mais vous devez garder ceci &agrave;
+	  l'esprit : alors que les manipulations d'URLs dans le contexte
+	  du serveur sont vraiment rapides et efficaces, les r&eacute;&eacute;critures
+	  dans un contexte de r&eacute;pertoire sont lentes et inefficaces &agrave;
+	  cause du probl&egrave;me d'ant&eacute;riorit&eacute; pr&eacute;cit&eacute;. Cependant, c'est la
+	  seule mani&egrave;re dont mod_rewrite peut proposer des manipulations
+	  d'URLs (limit&eacute;es &agrave; une branche du syst&egrave;me de fichiers) &agrave;
+	  l'utilisateur standard.</p>
+        </li>
+      </ol>
+
+      <p>Ne perdez pas de vue ces deux points!</p>
+</section>
+
+<section id="InternalRuleset"><title>Traitement du jeu de r&egrave;gles</title>
+
+      <p>Maintenant, quand mod_rewrite se lance dans ces deux phases de
+      l'API, il lit le jeu de r&egrave;gles configur&eacute;es depuis la structure
+      contenant sa configuration (qui a &eacute;t&eacute; elle-m&ecirc;me cr&eacute;&eacute;e soit au
+      d&eacute;marrage d'Apache pour le contexte du serveur, soit lors du
+      parcours des r&eacute;pertoires par le noyau d'Apache pour le contexte de
+      r&eacute;pertoire). Puis le moteur de r&eacute;&eacute;criture est d&eacute;marr&eacute; avec le jeu
+      de r&egrave;gles contenu (une ou plusieurs r&egrave;gles associ&eacute;es &agrave; leurs
+      conditions). En lui-m&ecirc;me, le mode op&eacute;ratoire du moteur de
+      r&eacute;&eacute;criture d'URLs est exactement le m&ecirc;me dans les deux contextes
+      de configuration. Seul le traitement du r&eacute;sultat final diff&egrave;re.</p>
+
+      <p>L'ordre dans lequel les r&egrave;gles sont d&eacute;finies est important car
+      le moteur de r&eacute;&eacute;criture les traite selon une chronologie
+      particuli&egrave;re (et pas tr&egrave;s &eacute;vidente). Le principe est le suivant :
+      le moteur de r&eacute;&eacute;criture traite les r&egrave;gles (les directives <directive
+      module="mod_rewrite">RewriteRule</directive>) les unes
+      &agrave; la suite des autres, et lorsqu'une r&egrave;gle s'applique, il parcourt
+      les &eacute;ventuelles conditions (directives
+      <code>RewriteCond</code>directives) associ&eacute;es.
+      Pour des raisons historiques, les
+      conditions pr&eacute;c&egrave;dent les r&egrave;gles, si bien que le d&eacute;roulement du
+      contr&ocirc;le est un peu compliqu&eacute;. Voir la figure 1 pour plus de
+      d&eacute;tails.</p>
+<p class="figure">
+      <img src="../images/rewrite_rule_flow.png"
+          alt="Flux des comparaisons des directives RewriteRule et RewriteCond" /><br />
+      <dfn>Figure 1:</dfn>D&eacute;roulement du contr&ocirc;le &agrave; travers le jeu de
+      r&egrave;gles de r&eacute;&eacute;criture
+</p>
+      <p>Comme vous pouvez le voir, l'URL est tout d'abord compar&eacute;e au
+      <em>Mod&egrave;le</em> de chaque r&egrave;gle. Lorsqu'une r&egrave;gle ne s'applique
+      pas, mod_rewrite stoppe imm&eacute;diatement le traitement de cette r&egrave;gle
+      et passe &agrave; la r&egrave;gle suivante. Si l'URL correspond au
+      <em>Mod&egrave;le</em>, mod_rewrite recherche la pr&eacute;sence de conditions
+      correspondantes. S'il n'y en a pas, mod_rewrite remplace
+      simplement l'URL par une cha&icirc;ne &eacute;labor&eacute;e &agrave; partir de la cha&icirc;ne de
+      <em>Substitution</em>, puis passe &agrave; la r&egrave;gle suivante. Si des
+      conditions sont pr&eacute;sentes, mod_rewrite lance un bouclage
+      secondaire afin de les traiter selon l'ordre dans lequel elles
+      sont d&eacute;finies. La logique de traitement des conditions est
+      diff&eacute;rente : on ne compare pas l'URL &agrave; un mod&egrave;le. Une cha&icirc;ne de
+      test <em>TestString</em> est tout d'abord &eacute;labor&eacute;e en d&eacute;veloppant
+      des variables, des r&eacute;f&eacute;rences arri&egrave;res, des recherches dans des
+      tables de correspondances, etc..., puis cette cha&icirc;ne de test est
+      compar&eacute;e au mod&egrave;le de condition <em>CondPattern</em>. Si le mod&egrave;le
+      ne correspond pas, les autres conditions du jeu ne sont pas
+      examin&eacute;es et la r&egrave;gle correspondante ne s'applique pas. Si le
+      mod&egrave;le correspond, la condition suivante est examin&eacute;e et ainsi de
+      suite jusqu'&agrave; la derni&egrave;re condition. Si toutes les conditions sont
+      satisfaites, le traitement de la r&egrave;gle en cours se poursuit avec
+      le remplacement de l'URL par la cha&icirc;ne de <em>Substitution</em>.</p>
+
+</section>
+
+
+</manualpage>
+

Added: httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.xml.meta
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.xml.meta?rev=1082915&view=auto
==============================================================================
--- httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.xml.meta (added)
+++ httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.xml.meta Fri Mar 18 13:37:20 2011
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!-- GENERATED FROM XML: DO NOT EDIT -->
+
+<metafile reference="tech.xml">
+  <basename>tech</basename>
+  <path>/rewrite/</path>
+  <relpath>..</relpath>
+
+  <variants>
+    <variant>en</variant>
+    <variant>fr</variant>
+  </variants>
+</metafile>

Added: httpd/httpd/branches/2.2.x/docs/manual/rewrite/vhosts.html
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/docs/manual/rewrite/vhosts.html?rev=1082915&view=auto
==============================================================================
--- httpd/httpd/branches/2.2.x/docs/manual/rewrite/vhosts.html (added)
+++ httpd/httpd/branches/2.2.x/docs/manual/rewrite/vhosts.html Fri Mar 18 13:37:20 2011
@@ -0,0 +1,5 @@
+# GENERATED FROM XML -- DO NOT EDIT
+
+URI: vhosts.html.en
+Content-Language: en
+Content-type: text/html; charset=ISO-8859-1