Rebuild

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1295297 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 73 insertions, 6 deletions

diff --git a/docs/manual/mod/mod_session.html.en b/docs/manual/mod/mod_session.html.en
index 933c17cd3a..7a3e3112d2 100644
--- a/docs/manual/mod/mod_session.html.en
+++ b/docs/manual/mod/mod_session.html.en
@@ -76,6 +76,7 @@
 <li><img alt="" src="../images/down.gif" /> <a href="#sessionprivacy">Session Privacy</a></li>
 <li><img alt="" src="../images/down.gif" /> <a href="#cookieprivacy">Cookie Privacy</a></li>
 <li><img alt="" src="../images/down.gif" /> <a href="#authentication">Session Support for Authentication</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#integration">Integrating Sessions with External Applications</a></li>
 </ul><h3>See also</h3>
 <ul class="seealso">
 <li><code class="module"><a href="../mod/mod_session_cookie.html">mod_session_cookie</a></code></li>
@@ -86,10 +87,17 @@
 <div class="section">
 <h2><a name="whatisasession" id="whatisasession">What is a session?</a></h2>
       <p>At the core of the session interface is a table of key and value pairs
-      that are made accessible across browser requests.</p>
+      that are made accessible across browser requests. These pairs can be set
+      to any valid string, as needed by the application making use of the
+      session.</p>
 
-      <p>These pairs can be set to any valid string, as needed by the
-      application making use of the session.</p>
+      <p>The "session" is a <strong>application/x-www-form-urlencoded</strong>
+      string containing these key value pairs, as defined by the
+      <a href="http://www.w3.org/TR/html4/">HTML specification</a>.</p>
+
+      <p>The session can optionally be encrypted and base64 encoded before
+      being written to the storage mechanism, as defined by the
+      administrator.</p>
 
     </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 <div class="section">
@@ -124,9 +132,9 @@
     </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 <div class="section">
 <h2><a name="browsersession" id="browsersession">Keeping sessions on the browser</a></h2>
-      <p>Where keeping track of a session on a server is too resource
-      intensive or inconvenient, the option exists to store the contents
-      of the session within a cookie on the client browser instead.</p>
+      <p>In high traffic environments where keeping track of a session on a
+      server is too resource intensive or inconvenient, the option exists to store
+      the contents of the session within a cookie on the client browser instead.</p>
 
       <p>This has the advantage that minimal resources are required on the
       server to keep track of sessions, and multiple servers within a server
@@ -278,6 +286,65 @@
       <p>See the <code class="module"><a href="../mod/mod_auth_form.html">mod_auth_form</a></code> module for documentation and complete
       examples.</p>
 
+    </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="integration" id="integration">Integrating Sessions with External Applications</a></h2>
+
+      <p>In order for sessions to be useful, it must be possible to share the contents
+      of a session with external applications, and it must be possible for an
+      external application to write a session of its own.</p>
+
+      <p> A typical example might be an application that changes a user's password set by
+      <code class="module"><a href="../mod/mod_auth_form.html">mod_auth_form</a></code>. This application would need to read the current
+      username and password from the session, make the required changes to the user's
+      password, and then write the new password to the session in order to provide a
+      seamless transition to the new password.</p>
+
+      <p>A second example might involve an application that registers a new user for
+      the first time. When registration is complete, the username and password is
+      written to the session, providing a seamless transition to being logged in.</p>
+
+      <dl>
+      <dt>Apache modules</dt>
+      <dd>Modules within the server that need access to the session can use the
+      <strong>mod_session.h</strong> API in order to read from and write to the
+      session. This mechanism is used by modules like <code class="module"><a href="../mod/mod_auth_form.html">mod_auth_form</a></code>.
+      </dd>
+
+      <dt>CGI programs and scripting languages</dt>
+      <dd>Applications that run within the webserver can optionally retrieve the
+      value of the session from the <strong>HTTP_SESSION</strong> environment
+      variable. The session should be encoded as a
+      <strong>application/x-www-form-urlencoded</strong> string as described by the
+      <a href="http://www.w3.org/TR/html4/">HTML specification</a>. The environment
+      variable is controlled by the setting of the
+      <code class="directive"><a href="#sessionenv">SessionEnv</a></code> directive. The session
+      can be written to by the script by returning a
+      <strong>application/x-www-form-urlencoded</strong> response header with a name
+      set by the <code class="directive"><a href="#sessionheader">SessionHeader</a></code>
+      directive. In both cases, any encryption or decryption, and the reading the
+      session from or writing the session to the chosen storage mechanism is handled
+      by the <code class="module"><a href="../mod/mod_session.html">mod_session</a></code> modules and corresponding configuration.
+      </dd>
+      
+      <dt>Applications behind <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code></dt>
+      <dd>If the <code class="directive"><a href="#sessionheader">SessionHeader</a></code>
+      directive is used to define an HTTP request header, the session, encoded as
+      a <strong>application/x-www-form-urlencoded</strong> string, will be made
+      available to the application. If the same header is provided in the response,
+      the value of this response header will be used to replace the session. As
+      above, any encryption or decryption, and the reading the session from or
+      writing the session to the chosen storage mechanism is handled by the
+      <code class="module"><a href="../mod/mod_session.html">mod_session</a></code> modules and corresponding configuration.</dd>
+      
+      <dt>Standalone applications</dt>
+      <dd>Applications might choose to manipulate the session outside the control
+      of the Apache HTTP server. In this case, it is the responsibility of the
+      application to read the session from the chosen storage mechanism,
+      decrypt the session, update the session, encrypt the session and write
+      the session to the chosen storage mechanism, as appropriate.</dd>
+      </dl>
+
     </div>
 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 <div class="directive-section"><h2><a name="Session" id="Session">Session</a> <a name="session" id="session">Directive</a></h2>