1.1 --- a/docs/developing.html Sun Nov 20 02:36:31 2005 +0000
1.2 +++ b/docs/developing.html Sun Nov 20 02:37:06 2005 +0000
1.3 @@ -78,4 +78,8 @@
1.4 be reviewed when encountering problems with input and output text:</p>
1.5 <ul><li><a href="encodings.html">Character Encodings</a></li></ul>
1.6 <h2>Deployment</h2><p>The following topics (illustrated by the programs found in the other subdirectories of the <code>examples</code> directory) describe how WebStack applications may be deployed in server environments:</p><ul><li><a href="deploying.html">Deploying a WebStack Application</a></li><ul><li><a href="writing-adapters.html">Writing Adapters</a></li><li><a href="pythonpath.html">Getting PYTHONPATH Right</a></li><li><a href="deploying-applications.html">Deploying an Application</a></li><ul><li><a href="BaseHTTPRequestHandler/NOTES.txt">BaseHTTPRequestHandler</a> (see <code>examples/BaseHTTPRequestHandler</code>)</li><li><a href="CGI/NOTES.txt">CGI</a> (see <code>examples/CGI</code>)</li><li><a href="JavaServlet/NOTES.txt">Java Servlet</a> (see <code>examples/JavaServlet</code>)</li><li><a href="ModPython/NOTES.txt">mod_python</a> (see <code>examples/ModPython</code>)</li><li><a href="Twisted/NOTES.txt">Twisted</a> (see <code>examples/Twisted</code>)</li><li><a href="Webware/NOTES.txt">Webware</a> (see <code>examples/Webware</code>)</li><li><a href="WSGI/NOTES.txt">WSGI</a> (see <code>examples/WSGI</code>)</li><li><a href="Zope/NOTES.txt">Zope</a> (see <code>examples/Zope</code>)</li></ul></ul><li>Technical note: <a href="features.html">Support for WebStack
1.7 -Features in Server Environments</a></li></ul></body></html>
1.8 \ No newline at end of file
1.9 +Features in Server Environments</a></li></ul><h2>Useful Additions</h2><p>WebStack
1.10 +provides a number of potentially useful modules either providing
1.11 +resource classes for direct use in applications, or providing other
1.12 +kinds of classes and functions which may be used to perform particular
1.13 +activities.</p><p>The following resources are provided for direct use in applications:</p><ul><li><a href="login-redirect.html">LoginRedirect and Login Modules</a></li><li><a href="resource-map.html">ResourceMap - Simple Mappings from Names to Resources</a></li><li><a href="directory-resource.html">DirectoryResource - Serving Static Content</a></li></ul><p>WebStack also provides modules which provide session-like access to different kinds of repositories:</p><ul><li><a href="directory-repository.html">DirectoryRepository - Simple Access to Files in a Directory</a></li></ul></body></html>
1.14 \ No newline at end of file
2.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
2.2 +++ b/docs/directory-repository.html Sun Nov 20 02:37:06 2005 +0000
2.3 @@ -0,0 +1,32 @@
2.4 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2.5 +<html xmlns="http://www.w3.org/1999/xhtml"><head><meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
2.6 +
2.7 + <title>DirectoryRepository - Simple Access to Files in a Directory</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
2.8 + <link href="styles.css" rel="stylesheet" type="text/css" /></head>
2.9 +<body>
2.10 +<h1>DirectoryRepository - Simple Access to Files in a Directory</h1>
2.11 +<p>In applications it is often convenient to be able to save or remember information provided or edited by a user. Whilst <a href="sessions.html">sessions</a>
2.12 +often provide a convenient means of remembering such information, they
2.13 +have certain limitations, notably that they are only available to a
2.14 +particular user and cannot be shared with other users, and that their
2.15 +data is stored in a form that is not necessarily convenient to access
2.16 +by other tools or systems.</p><p>The principle behind the <code>DirectoryRepository</code>
2.17 +class is that it stores information as files in a designated directory,
2.18 +that such files can be accessed by any resource with access to that
2.19 +directory, and that a certain degree of locking is provided to avoid
2.20 +contention between resources. Once created, instances of <code>DirectoryRepository</code>
2.21 +can be accessed almost like sessions, although it is possible to obtain
2.22 +the full paths to files in the repository and to use file objects and
2.23 +methods to obtain and deposit content in such files.</p><div class="WebStack"><h3>WebStack API - DirectoryRepository Initialisation</h3><p>The <code>DirectoryRepository</code> class (found in the <code>WebStack.Repositories.Directory</code> module) accepts the following parameters when being initialised:</p><dl><dt><code>path</code></dt><dd>This parameter specifies the path to the directory in the filesystem where repository files are to be stored.</dd><dt><code>fsencoding</code></dt><dd>This
2.24 +optional parameter specifies the character encoding employed by the
2.25 +filesystem to represent filenames. If left unspecified, the
2.26 +implementation will attempt to guess the correct encoding or, where
2.27 +supported, to use Unicode filenames.</dd><dt><code>delay</code></dt><dd>This
2.28 +optional parameter specifies a delay period for which a program will be
2.29 +made to wait if a repository file is found to be locked by another
2.30 +process.</dd></dl></div><h2>Initialisation Strategies</h2><p>One might choose to initialise a repository in the initialisation method of a resource:</p><pre># Inside a module defining a resource...<br /><br />class MyResource:<br /> def __init__(self):<br /> repository_dir = os.path.join(os.path.split(__file__)[0], "repository")<br /> self.repository = DirectoryRepository(repository_dir, "iso-8859-1")</pre><p>Here, the repository will reside alongside the resource's module in the filesystem.</p><h2>Session-like Access</h2><p>One might use a repository with a session-like API as follows:</p><pre># Given a name and some data, possibly provided in user input, store the data in the repository.<br /><br />repository[name] = data </pre><p>Note that <code>DirectoryRepository</code>
2.31 +places some restrictions on the values that can be used as keys in the
2.32 +session-like API since each key must correspond to a filename within
2.33 +the designated directory.</p><h2>Advanced Access</h2><p>The <code>DirectoryRepository</code> class also provides various methods to support access to files in the repository using standard file objects and methods:</p><pre># Given a name and some data...<br /><br />repository.lock(name)<br />f = open(repository.full_path(name), "wb")<br />try:<br /> f.write(data)<br />finally:<br /> f.close()<br /> repository.unlock(name)</pre><p>The usage of <code>try</code> and <code>finally</code>
2.34 +clauses is important to ensure that files are not left locked and
2.35 +inaccessible due to unhandled exceptions being raised. See the <a href="../apidocs/public/WebStack.Repositories.Directory.DirectoryRepository-class.html">API documentation</a> for the <code>DirectoryRepository</code> class for more information about the available methods and their behaviour.</p></body></html>
2.36 \ No newline at end of file
3.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
3.2 +++ b/docs/directory-resource.html Sun Nov 20 02:37:06 2005 +0000
3.3 @@ -0,0 +1,39 @@
3.4 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3.5 +<html xmlns="http://www.w3.org/1999/xhtml"><head><meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
3.6 +
3.7 + <title>DirectoryResource - Serving Static Content</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
3.8 + <link href="styles.css" rel="stylesheet" type="text/css" /></head>
3.9 +<body>
3.10 +<h1>DirectoryResource - Serving Static Content</h1>
3.11 +<p>The <code>DirectoryResource</code> class provides a means to
3.12 +serve static files from within a particular directory in the
3.13 +filesystem. By inspecting the remainder of the path information
3.14 +supplied in an incoming request, instances of <code>DirectoryResource</code> may identify files and serve their contents as a response to such a request.</p><p>There are various situations where providing static content is virtually essential:</p><ul><li>Providing
3.15 +stylesheets, script files and images employed by Web pages which may
3.16 +themselves have been produced by WebStack resources.</li><li>Providing static documents for Web pages which are not "dynamic".</li></ul><p>By instantiating <code>DirectoryResource</code> classes and deploying them in conjunction with <code>MapResource</code> objects (see the <a href="resource-map.html">"ResourceMap - Simple Mappings from Names to Resources"</a>
3.17 +document), it should be possible to retain control of the serving of
3.18 +static content within a WebStack application. Note, however, that the
3.19 +performance of a system can be improved if the job of serving static
3.20 +content is delegated to a specialised Web server solution - one might,
3.21 +for example, set up an Apache Web server to serve things like
3.22 +stylesheets, script files and images, and then link to the locations of
3.23 +such things in the Web pages generated by the WebStack application.</p><div class="WebStack"><h3>WebStack API - The DirectoryResource Class</h3>
3.24 +<p>Given a directory from which files shall be served, <code>DirectoryResource</code> uses a simple method to identify files to serve. First, it examines the <a href="path-info.html">virtual "path info"</a> and takes the first component of that information. For example, consider the following path information:</p><pre>/styles.css</pre><p>Here, <code>DirectoryResource</code> identifies the file to be served as having the name <code>styles.css</code>. Note that any trailing path information would be ignored; for example:</p><pre>/styles/abc</pre><p>Here, the file to be served would be identified as having the name <code>styles</code>.</p><h4>Handling Missing Files</h4><p>Where
3.25 +no file exists in the specified directory with the identified
3.26 +name, a "file not found" response code is set by the resource and a
3.27 +message is emitted. To modify the simple behaviour of <code>DirectoryResource</code> in this regard, it is recommended that a subclass of <code>DirectoryResource</code> is defined with its own implementation of the <code>not_found</code> method.</p><h4>Types of Served Files</h4><p>Given
3.28 +that a file exists in the specified directory, it is usually critical
3.29 +that the file is served along with special file type information so
3.30 +that a user's Web browser may understand the nature of the file's
3.31 +content. For example, a file containing a Web page must be served with
3.32 +a file type indicating that the contents of the file are HTML (or some
3.33 +variant thereof). Instances of <code>DirectoryResource</code> employ
3.34 +a special registry mapping filename extensions to file types in order
3.35 +to automate the process of deciding what type a file might be.</p><p>Using the <code>media_types</code> parameter (see below), one might choose to serve all files whose names have the <code>.html</code> extension with the HTML file (or content) type. This would be expressed with the following dictionary:</p><pre>{"html" : "text/html"}</pre><p>Note that the <code>.</code>
3.36 +character is omitted from the filename extension and that the file type
3.37 +(or more correctly, the media type) does not include character set
3.38 +information.<br /></p><h4>Further Reading</h4><p>The <a href="../apidocs/public/WebStack.Resources.Static.DirectoryResource-class.html">API documentation</a> for the <code>DirectoryResource</code> class provides more information on the usage of the class.</p><h4>Initialisation</h4><p>The <span style="font-family: monospace;">Directory</span><code>Resource</code> class (found in the <code>WebStack.Resources.Static</code> module) accepts the following parameters when being initialised:</p>
3.39 +<dl><dt><code>directory</code></dt><dd>The directory from which static files shall be served.</dd><dt><code>media_types</code></dt><dd>A dictionary or dictionary-like object mapping filename extensions to MIME types.</dd><dt><code>unrecognised_media_type</code></dt><dd>An optional parameter setting the MIME type for files whose extensions do not map to any MIME type according to the <code>media_types</code> parameter.</dd><dt><code>urlencoding</code></dt><dd>When
3.40 +specified, this parameter forces a particular interpretation of "URL
3.41 +encoded" character values in the path. Otherwise, the default encoding
3.42 +is employed to interpret such values. (See <a href="paths.html">"URLs and Paths"</a> for an explanation of "URL encoded" values.)</dd></dl></div><h2>Combining MapResource with DirectoryResource</h2><p>One might combine <code>MapResource</code> with <code>DirectoryResource</code> to provide stylesheet and script file directories for an application as follows:</p><pre>from WebStack.Resources.ResourceMap import MapResource<br />from WebStack.Resources.Static import DirectoryResource<br /><br /># This is where the application's resources would be obtained.<br /><br />app_resource = ...<br /><br /># Here is where we combine MapResource and DirectoryResource.<br /># Note that one would not necessarily hard-code directory paths into the application.<br /><br />top_resource = MapResource({<br /> "styles" : DirectoryResource("/usr/share/apps/MyApp/styles", {"css" : "text/css"}),<br /> "scripts" : DirectoryResource("/usr/share/apps/MyApp/scripts", {"js" : "text/javascript"}),<br /> "" : app_resource<br /> })</pre><p>In the above example, any file in the <code>styles</code> directory whose name ends with <code>.css</code> is served as <code>text/css</code>. Similarly, any file in the <code>scripts</code> directory whose name ends with <code>.js</code> is served as <code>text/javascript</code>.</p></body></html>
3.43 \ No newline at end of file
4.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
4.2 +++ b/docs/resource-map.html Sun Nov 20 02:37:06 2005 +0000
4.3 @@ -0,0 +1,39 @@
4.4 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
4.5 +<html xmlns="http://www.w3.org/1999/xhtml"><head><meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
4.6 +
4.7 + <title>ResourceMap - Simple Mappings from Names to Resources</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
4.8 + <link href="styles.css" rel="stylesheet" type="text/css" /></head>
4.9 +
4.10 +<body>
4.11 +<h1>ResourceMap - Simple Mappings from Names to Resources</h1>
4.12 +<p>The <code>ResourceMap</code> module provides classes (although
4.13 +currently only one class is supplied) which act as standard WebStack
4.14 +resources, but which examine the path or URL from incoming requests and
4.15 +direct such requests to other resources based on the contents of the
4.16 +path or URL. In other words, such classes map names or patterns to
4.17 +WebStack resources and dispatch requests accordingly.</p><h2>Introducing MapResource</h2><p>The <a href="paths-filesystem.html">"Treating the Path Like a Filesystem"</a> document contains an example involving the <code>MapResource</code> class; this class is initialised with a dictionary mapping names to resources as described below.</p><div class="WebStack">
4.18 +<h3>WebStack API - The MapResource Class</h3>
4.19 +
4.20 +<p>The <code>MapResource</code>
4.21 +class (found in the
4.22 +<code>WebStack.Resources.ResourceMap</code> module) maps names to
4.23 +resource objects, where to select a resource the
4.24 +corresponding name must match the first component discovered
4.25 +in the <a href="path-info.html">virtual "path info"</a>. For example,
4.26 +consider the following virtual "path info" (where there may have been
4.27 +more information in the path, but this has already been processed):</p><pre>/documents/news/2005/article.html</pre><p>Here, the name <code>documents</code>
4.28 +would match the above virtual "path info". Meanwhile, after processing
4.29 +more of the information, we might have the following remains of the
4.30 +path:</p><pre>/2005/article.html</pre><p>Here, the name <code>2005</code> would match, leaving the following information unprocessed:</p><pre>/article.html</pre><p>Here, the name <code>article.html</code> would match. However, let us consider the following original virtual "path info" instead:</p><pre>/documents/news/2005/</pre><p>After processing the leading components, we may instead end up with this:</p><pre>/</pre><p>Here, only an empty string as the name will specifically match the above.</p><h4>Further Reading</h4><p>The <a href="../apidocs/public/WebStack.Resources.ResourceMap.MapResource-class.html">API documentation</a> for the <code>MapResource</code>
4.31 +class provides more detail on the subject of name matching, including
4.32 +the special "catch all" name and a discussion of the pass-through
4.33 +parameter.</p><h4>Initialisation</h4><p><code>MapResource</code> objects are initialised with the following parameters:</p><dl><dt><code>mapping</code></dt><dd>A dictionary or dictionary-like object mapping names to resource objects. See above and the <a href="../apidocs/public/WebStack.Resources.ResourceMap.MapResource-class.html">API documentation</a> for a description of names.</dd><dt><code>pass_through</code></dt><dd>Indicates
4.34 +whether a component should be removed from the virtual "path info" if
4.35 +no specific match was made with any of the names, but if the "catch
4.36 +all" name selected a resource. By default, this parameter is set to a
4.37 +false value.</dd><dt><code>directory_redirects</code></dt><dd>Indicates whether a trailing <code>/</code> character should be added to paths which do not end with such a character, causing a <a href="redirection.html">redirect</a> if such a character has to be added.</dd><dt><code>urlencoding</code></dt><dd>When
4.38 +specified, this parameter forces a particular interpretation of "URL
4.39 +encoded" character values in the path. Otherwise, the default encoding
4.40 +is employed to interpret such values. (See <a href="paths.html">"URLs and Paths"</a> for an explanation of "URL encoded" values.)</dd></dl>
4.41 +
4.42 +</div></body></html>
4.43 \ No newline at end of file
5.1 --- a/docs/sessions.html Sun Nov 20 02:36:31 2005 +0000
5.2 +++ b/docs/sessions.html Sun Nov 20 02:37:06 2005 +0000
5.3 @@ -1,12 +1,10 @@
5.4 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
5.5 -<html xmlns="http://www.w3.org/1999/xhtml">
5.6 -<head>
5.7 +<html xmlns="http://www.w3.org/1999/xhtml"><head>
5.8 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
5.9 - <title>Sessions and Persistent Information</title>
5.10 - <meta name="generator"
5.11 - content="amaya 8.1a, see http://www.w3.org/Amaya/" />
5.12 - <link href="styles.css" rel="stylesheet" type="text/css" />
5.13 -</head>
5.14 +
5.15 + <title>Sessions and Persistent Information</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
5.16 + <link href="styles.css" rel="stylesheet" type="text/css" /></head>
5.17 +
5.18 <body>
5.19 <h1>Sessions and Persistent Information</h1>
5.20 <p>The term "session" is a technical term describing information which
5.21 @@ -29,8 +27,7 @@
5.22 persistent information - data is addressed or accessed using each
5.23 user's identity, and the information is partitioned in such a way that
5.24 sessions cannot be shared between users.</p>
5.25 -<table style="text-align: left; width: 80%;" align="center" border="1"
5.26 - cellpadding="5" cellspacing="0" width="80%">
5.27 +<table style="text-align: left; width: 80%;" align="center" border="1" cellpadding="5" cellspacing="0" width="80%">
5.28 <tbody>
5.29 <tr>
5.30 <td></td>
5.31 @@ -54,8 +51,8 @@
5.32 </tr>
5.33 </tbody>
5.34 </table>
5.35 -<p>Access to persistent information in general can be done by using
5.36 -database access libraries, for example - see <a href="integrating.html">"Integrating
5.37 +<p>Access to persistent information in general can be done in a simple fashion by using
5.38 +repositories (see <a href="directory-repository.html">"DirectoryRepository - Simple Access to Files in a Directory"</a>) or, for example, by using database access libraries - see <a href="integrating.html">"Integrating
5.39 with Other Systems"</a> for more details. </p>
5.40 <h2>More About Sessions</h2>
5.41 <ul>
5.42 @@ -63,5 +60,4 @@
5.43 <li><a href="sessions-servers.html">Server Environment Support for
5.44 Sessions</a></li>
5.45 </ul>
5.46 -</body>
5.47 -</html>
5.48 +</body></html>
5.49 \ No newline at end of file
