1.1 --- a/docs/selectors.html Thu Dec 06 23:38:37 2007 +0000
1.2 +++ b/docs/selectors.html Thu Dec 06 23:40:18 2007 +0000
1.3 @@ -5,60 +5,214 @@
1.4 <link href="styles.css" rel="stylesheet" type="text/css" /></head>
1.5 <body>
1.6 <h1>Selectors - Components for Dispatching to Resources</h1>
1.7 -<p>The <code>Selectors</code> module provides classes (although
1.8 -currently only one class is supplied) which act as standard WebStack
1.9 -resources, but which attempt to "select" other resources, dispatch each
1.10 -request to those resources, and to cause various side-effects, mostly
1.11 -on the attributes stored on the transaction object. These "selector"
1.12 -classes behave those in the <code>ResourceMap</code> module, but aspire to be more generally applicable.</p><h2>Selecting Path Roots with PathSelector</h2><p>In
1.13 -non-trivial applications, it is often desirable to know the path or URL
1.14 -to a particular resource, especially the "root" resource under which
1.15 -the application or one of its components may reside. The <code>PathSelector</code>
1.16 -class can be instantiated and be made to refer to a resource, recording
1.17 -such path or URL details in an attribute for later inspection.</p><div class="WebStack">
1.18 -<h3>WebStack API - The PathSelector Class</h3>
1.19 +
1.20 +<p>The <code>Selectors</code> module provides classes (although currently only
1.21 +one class is supplied) which act as standard WebStack resources, but which
1.22 +attempt to "select" other resources, dispatch each request to those resources,
1.23 +and to cause various side-effects, mostly on the attributes stored on the
1.24 +transaction object. These "selector" classes behave those in the
1.25 +<code>ResourceMap</code> module, but aspire to be more generally
1.26 +applicable.</p>
1.27 +
1.28 +<h2>Selecting Path Roots with PathSelector</h2>
1.29 +
1.30 +<p>In non-trivial applications, it is often desirable to know the path or URL
1.31 +to a particular resource, especially the "root" resource under which the
1.32 +application or one of its components may reside. The <code>PathSelector</code>
1.33 +class can be instantiated and be made to refer to a resource, recording such
1.34 +path or URL details in an attribute for later inspection.</p>
1.35 +
1.36 +<div class="WebStack">
1.37 + <h3>WebStack API - The PathSelector Class</h3>
1.38 +
1.39 + <p>The <code>PathSelector</code> class (found in the
1.40 + <code>WebStack.Resources.Selectors</code> module) wraps resource objects whose
1.41 + location (as indicated by a path or URL) should be recorded as an attribute on
1.42 + the current transaction. The most common use of the class is to record the
1.43 + "root" resource's location, and this would be done as follows:</p>
1.44 +
1.45 +<pre>
1.46 +def get_site_map():
1.47 + return PathSelector(MyResource())
1.48 +</pre>
1.49 +
1.50 + <p>Here, the <code>get_site_map</code> function (as described in the <a
1.51 + href="deploying.html">"Deploying a WebStack Application"</a> document) would
1.52 + provide a <code>PathSelector</code> object instead of an instance of the
1.53 + <code>MyResource</code> class. However, the side-effect of combining these two
1.54 + resources would be the availability of an attribute named <code>root</code> on
1.55 + the transaction object. Thus, the "root" <code>MyResource</code> object and,
1.56 + indeed, all resource objects visited after this side-effect has occurred will
1.57 + have access to the "root" path or URL information.</p>
1.58 +
1.59 + <h4>Further Reading</h4>
1.60 +
1.61 + <p>The <a
1.62 + href="../apidocs/public/WebStack.Resources.Selectors.PathSelector-class.html">API
1.63 + documentation</a> for the <code>PathSelector</code> class provides additional
1.64 + information.</p>
1.65 +
1.66 +</div>
1.67 +
1.68 +<h2>Defining Encodings using EncodingSelector</h2>
1.69 +
1.70 +<p>One frequently bothersome aspect of writing Web applications involves the
1.71 +processing and production of text in different encodings. Whilst the WebStack
1.72 +API lets applications explicitly state the character encoding for various
1.73 +operations, one often wants to be able to ignore such details since they start
1.74 +to clutter up application code. The <code>EncodingSelector</code> class offers
1.75 +a basic solution which is compatible with the mechanisms in transaction
1.76 +objects: by wrapping WebStack resources with instances of
1.77 +<code>EncodingSelector</code>, an application-wide default encoding (or
1.78 +character set) will be defined; this will result in request information being
1.79 +processed according to the stated encoding and response information being
1.80 +produced according to that encoding (see below for more details of the latter
1.81 +activity).</p>
1.82 +
1.83 +<div class="WebStack">
1.84 + <h3>WebStack API - The EncodingSelector Class</h3>
1.85 +
1.86 + <p>The <code>EncodingSelector</code> class (found in the
1.87 + <code>WebStack.Resources.Selectors</code> module) wraps resource
1.88 + objects whilst changing the default encoding of the current transaction
1.89 + object. The class can be applied like this:</p>
1.90 +
1.91 +<pre>
1.92 +def get_site_map():
1.93 + return EncodingSelector(MyResource(), "utf-8")
1.94 +</pre>
1.95 +
1.96 + <p>Here, the <code>get_site_map</code> function (as described in the <a
1.97 + href="deploying.html">"Deploying a WebStack Application"</a> document) would
1.98 + provide a <code>EncodingSelector</code> object instead of an instance of the
1.99 + <code>MyResource</code> class. However, the <code>EncodingSelector</code> will
1.100 + forward requests on to <code>MyResource</code> (since it "selects" that
1.101 + resource), whilst setting the default encoding to be <code>"utf-8"</code>.</p>
1.102 +
1.103 + <h4>Request Streams and Encodings</h4>
1.104 +
1.105 + <p>Although a default encoding affects the processing of request parameters,
1.106 + direct access to the request stream using the <code>get_request_stream</code>
1.107 + method will only produce plain strings. This behaviour is justified by the
1.108 + observation that, if conversion from an encoding to Unicode were to take place,
1.109 + the resulting character values may be unsuitable substitutes for the original
1.110 + byte values in applications intending to make use of the raw incoming (possibly
1.111 + binary) data. A recipe for making a Unicode stream is provided in the <a
1.112 + href="encodings.html">"Character Encodings"</a> document.</p>
1.113 +
1.114 + <h4>Response Encodings and Content Types</h4>
1.115 +
1.116 + <p>Although <code>EncodingSelector</code> sets a default encoding, responses
1.117 + will generally be written in that encoding, at least if textual data is written
1.118 + to the response stream as Unicode objects. However, the content type must
1.119 + typically be set either to match the encoding in use or to not specify an
1.120 + encoding. It may become necessary to find out what the response stream encoding
1.121 + is when creating a <code>ContentType</code> object. For this and other
1.122 + purposes, the <code>get_response_stream_encoding</code> method is available on
1.123 + the transaction object<code></code>:</p>
1.124
1.125 -<p>The <code>PathSelector</code>
1.126 -class (found in the
1.127 -<code>WebStack.Resources.Selectors</code> module) wraps resource
1.128 -objects whose location (as indicated by a path or URL) should be
1.129 -recorded as an attribute on the current transaction. The most common
1.130 -use of the class is to record the "root" resource's location,
1.131 -and this would be done as follows:</p><pre>def get_site_map():<br /> return PathSelector(MyResource())</pre><p>Here, the <code>get_site_map</code>
1.132 -function (as described in the <a href="deploying.html">"Deploying a WebStack Application"</a> document) would provide a <code>PathSelector</code> object instead of an instance of the <code>MyResource</code> class. However, the side-effect of combining these two resources would be the availability of an attribute named <code>root</code> on the transaction object. Thus, the "root" <code>MyResource</code>
1.133 -object and, indeed, all resource objects visited after this side-effect
1.134 -has occurred will have access to the "root" path or URL information.</p><h4>Further Reading</h4><p>The <a href="../apidocs/public/WebStack.Resources.Selectors.PathSelector-class.html">API documentation</a> for the <code>PathSelector</code>
1.135 -class provides additional information.</p></div><h2>Defining Encodings using EncodingSelector</h2><p>One
1.136 -frequently bothersome aspect of writing Web applications involves the
1.137 -processing and production of text in different encodings. Whilst the
1.138 -WebStack API lets applications explicitly state the character encoding
1.139 -for various operations, one often wants to be able to ignore such
1.140 -details since they start to clutter up application code. The <code>EncodingSelector</code> class offers a basic solution which is compatible with the mechanisms in transaction objects: by wrapping WebStack resources with instances of <code>EncodingSelector</code>,
1.141 -an application-wide default encoding (or character set) will be
1.142 -defined; this will result in request information being processed
1.143 -according to the stated encoding and response information being
1.144 -produced according to that encoding (see below for more details of the
1.145 -latter activity).</p><div class="WebStack">
1.146 -<h3>WebStack API - The EncodingSelector Class</h3>
1.147 +<pre>
1.148 +from WebStack.Generic import ContentType
1.149 +
1.150 +def respond(self, trans):
1.151 +
1.152 + # Some code...
1.153 +
1.154 + trans.set_content_type(ContentType("text/html", trans.get_response_stream_encoding()))
1.155 + out = trans.get_response_stream()
1.156 + out.write(some_unicode_object)
1.157 +</pre>
1.158 +
1.159 + <p>However, it is completely acceptable to omit the encoding information where
1.160 + a default encoding has been set:</p>
1.161 +
1.162 +<pre>
1.163 + trans.set_content_type(ContentType("text/html")) # no encoding/charset specified
1.164 +</pre>
1.165 +
1.166 + <h4>Reading the Default Directly</h4>
1.167 +
1.168 + <p>For some activities, such as making a Unicode stream from the request
1.169 + stream, it is desirable to find out the encoding set by the selector. This
1.170 + information is made available on transaction objects as the
1.171 + <code>default_charset</code> attribute.</p>
1.172 +
1.173 + <h4>Further Reading</h4>
1.174 +
1.175 + <p>The <a
1.176 + href="../apidocs/public/WebStack.Resources.Selectors.EncodingSelector-class.html">API
1.177 + documentation</a> for the <code>EncodingSelector</code> class provides
1.178 + additional information, along with the <a href="responses.html">"Responses and
1.179 + Presentation"</a> document.</p>
1.180 +
1.181 +</div>
1.182 +
1.183 +<h2>Managing Database Resources</h2>
1.184 +
1.185 +<p>Web applications must often employ external resources such as database
1.186 +systems, leading developers to consider effective mechanisms to manage such
1.187 +resources. Although an application can initially open a database connection
1.188 +and make it available to resources, it is essential that such resources access
1.189 +the connection in a way that does not cause problems over time. The
1.190 +<code>StoreSelector</code> class offers an elementary solution for resources
1.191 +employing database connections by storing a connection object in an attribute
1.192 +on the transaction object, such that resources may obtain the connection
1.193 +merely by accessing the appropriate attribute. Moreover, the
1.194 +<code>StoreSelector</code> also ensures that database transactions are
1.195 +terminated in a timely fashion by calling the <code>rollback</code> method on
1.196 +the connection when a resource (or potentially many resources) have completed
1.197 +their work.</p>
1.198
1.199 -<p>The <code>EncodingSelector</code>
1.200 -class (found in the
1.201 -<code>WebStack.Resources.Selectors</code> module) wraps resource
1.202 -objects whilst changing the default encoding of the current transaction object. The class can be applied like this:</p><pre>def get_site_map():<br /> return EncodingSelector(MyResource(), "utf-8")</pre><p>Here, the <code>get_site_map</code>
1.203 -function (as described in the <a href="deploying.html">"Deploying a WebStack Application"</a> document) would provide a <code>EncodingSelector</code> object instead of an instance of the <code>MyResource</code> class. However, the <code>EncodingSelector</code> will forward requests on to <code>MyResource</code> (since it "selects" that resource), whilst setting the default encoding to be <code>"utf-8"</code>.</p><h4>Request Streams and Encodings</h4><p>Although a default encoding affects the processing of request parameters, direct access to the request stream using the <code>get_request_stream</code>
1.204 -method will only produce plain strings. This behaviour is justified by
1.205 -the observation that, if conversion from an encoding to Unicode were to
1.206 -take place, the resulting character values may be unsuitable
1.207 -substitutes for the original byte values in applications intending to
1.208 -make use of the raw incoming (possibly binary) data. A recipe for
1.209 -making a Unicode stream is provided in the <a href="encodings.html">"Character Encodings"</a> document.</p><h4>Response Encodings and Content Types</h4><p>Although <code>EncodingSelector</code> sets
1.210 -a default encoding, responses will generally be written in that
1.211 -encoding, at least if textual data is written to the response stream as
1.212 -Unicode objects. However, the content type must typically be set either
1.213 -to match the encoding in use or to not specify an encoding. It may
1.214 -become necessary to find out what the response stream encoding is when
1.215 -creating a <code>ContentType</code> object. For this and other purposes, the <code>get_response_stream_encoding</code> method is available on the transaction object<code></code>:</p><pre>from WebStack.Generic import ContentType<br /><br />def respond(self, trans):<br /><br /> # Some code...<br /><br /> trans.set_content_type(ContentType("text/html", trans.get_response_stream_encoding()))<br /> out = trans.get_response_stream()<br /> out.write(some_unicode_object)</pre><p>However, it is completely acceptable to omit the encoding information where a default encoding has been set:</p><pre> trans.set_content_type(ContentType("text/html")) # no encoding/charset specified<br /></pre><h4>Reading the Default Directly</h4><p>For
1.216 -some activities, such as making a Unicode stream from the request
1.217 -stream, it is desirable to find out the encoding set by the selector.
1.218 -This information is made available on transaction objects as the <code>default_charset</code> attribute.</p><h4>Further Reading</h4><p>The <a href="../apidocs/public/WebStack.Resources.Selectors.EncodingSelector-class.html">API documentation</a> for the <code>EncodingSelector</code>
1.219 -class provides additional information, along with the <a href="responses.html">"Responses and Presentation"</a> document.</p></div><p></p><br /></body></html>
1.220 +<div class="WebStack">
1.221 + <h3>WebStack API - The StoreSelector Class</h3>
1.222 +
1.223 + <p>The <code>StoreSelector</code> class (found in the
1.224 + <code>WebStack.Resources.Selectors</code> module) wraps resource
1.225 + objects whilst maintaining a reference to a database connection or store
1.226 + object as an attribute on a WebStack transaction object. The class can be
1.227 + applied like this:</p>
1.228 +
1.229 +<pre>
1.230 +def get_site_map(connection):
1.231 + return StoreSelector(MyResource(), connection)
1.232 +</pre>
1.233 +
1.234 + <p>Here, the <code>get_site_map</code> function (as described in the <a
1.235 + href="deploying.html">"Deploying a WebStack Application"</a> document) would
1.236 + provide a <code>StoreSelector</code> object instead of an instance of the
1.237 + <code>MyResource</code> class. However, the <code>StoreSelector</code> will
1.238 + forward requests on to <code>MyResource</code> (since it "selects" that
1.239 + resource), whilst maintaining a reference to the <code>connection</code>
1.240 + provided.</p>
1.241 +
1.242 + <p>Resources wishing to access the database connection would use code like
1.243 + the following:</p>
1.244 +
1.245 +<pre>
1.246 +def respond(self, trans):
1.247 +
1.248 + # Some code...
1.249 +
1.250 + connection = trans.get_attributes()["store"]
1.251 +</pre>
1.252 +
1.253 + <p>Should an alternative attribute name be required, such a name may be
1.254 + provided as an additional argument when initialising the
1.255 + <code>StoreSelector</code>; for example:</p>
1.256 +
1.257 +<pre>
1.258 +def get_site_map(connection):
1.259 + return StoreSelector(MyResource(), connection, "connection")
1.260 +</pre>
1.261 +
1.262 + <h4>Further Reading</h4>
1.263 +
1.264 + <p>The <a
1.265 + href="../apidocs/public/WebStack.Resources.Selectors.StoreSelector-class.html">API
1.266 + documentation</a> for the <code>StoreSelector</code> class provides
1.267 + additional information, and the <a href="integrating.html">"Integrating with
1.268 + Other Systems"</a> document describes related topics.</p>
1.269 +
1.270 +</div>
1.271 +
1.272 +</body></html>