1.1 --- a/docs/integrating.html Thu Dec 06 23:38:37 2007 +0000
1.2 +++ b/docs/integrating.html Thu Dec 06 23:40:18 2007 +0000
1.3 @@ -8,33 +8,52 @@
1.4 </head>
1.5 <body>
1.6 <h1>Integrating with Other Systems</h1>
1.7 -<p>Most Web applications are not self-contained - instead of
1.8 -providing information which is written into the application
1.9 -code itself, they may often access data from other places or even
1.10 -communicate with other systems. Since applications may be very
1.11 -different in the way that they access external systems or the way
1.12 -in which they obtain external information, WebStack does not mandate
1.13 -rigid mechanisms for hooking into such systems or loading such
1.14 -information. Instead, it is recommended that applications import
1.15 -packages and modules which provide the functionality necessary to carry
1.16 -out such integration.</p>
1.17 +
1.18 +<p>Most Web applications are not self-contained - instead of providing
1.19 +information which is written into the application code itself, they may often
1.20 +access data from other places or even communicate with other systems. Since
1.21 +applications may be very different in the way that they access external systems
1.22 +or the way in which they obtain external information, WebStack does not mandate
1.23 +a single mechanism for hooking into such systems or loading such information.
1.24 +Instead, it is recommended that applications import packages and modules which
1.25 +provide the functionality necessary to carry out such integration, using the
1.26 +appropriate conveniences (such as <a href="selectors.html">selector
1.27 +resources</a>) to manage that functionality where appropriate.</p>
1.28 +
1.29 <h2>Examples of Packages</h2>
1.30 -<p>Examples of packages and modules that might be used for integration
1.31 -purposes include the following:</p>
1.32 +
1.33 +<p>Examples of packages and modules that might be used for integration purposes
1.34 +include the following:</p>
1.35 +
1.36 <ul>
1.37 <li>Database access packages, including object-relational mappers.</li>
1.38 - <li>Communications libraries - for connecting to Web services or
1.39 -other remote services, for example.</li>
1.40 - <li>Templating or reporting systems. (Note that templating systems
1.41 -are also very useful when generating <a href="responses.html">responses</a>.)</li>
1.42 + <li>Communications libraries - for connecting to Web services or other remote
1.43 + services, for example.</li>
1.44 + <li>Templating or reporting systems. (Note that templating systems are also
1.45 + very useful when generating <a href="responses.html">responses</a>.)</li>
1.46 </ul>
1.47 -<h2> Using External Packages</h2>
1.48 -<p>In the simplest of cases, the use of external packages is as
1.49 -straightforward as importing a Python module (or package) and then
1.50 -using that module's contents. This can often be done in the <a
1.51 - href="resources.html">resource</a> code; for example:</p>
1.52 -<pre>import urllib<br /><br />class MyResource:<br /> def respond(self, trans):<br /> [Examine the transaction, decide what the user wants to do.]<br /><br /> f = urllib.urlopen("http://www.boddie.org.uk/rss/feed.xml")<br /><br /> [Produce some kind of response which tells the user what happened.]</pre>
1.53 +
1.54 +<h2>Using External Packages in General</h2>
1.55 +
1.56 +<p>In the simplest of cases, the use of external packages is as straightforward
1.57 +as importing a Python module (or package) and then using that module's
1.58 +contents. This can often be done in the <a href="resources.html">resource</a>
1.59 +code; for example:</p>
1.60 +
1.61 +<pre>
1.62 +import urllib
1.63 +
1.64 +class MyResource:
1.65 + def respond(self, trans):
1.66 + [Examine the transaction, decide what the user wants to do.]
1.67 +
1.68 + f = urllib.urlopen("http://www.boddie.org.uk/rss/feed.xml")
1.69 +
1.70 + [Produce some kind of response which tells the user what happened.]
1.71 +</pre>
1.72 +
1.73 <p>In the above example, here is what happens:</p>
1.74 +
1.75 <table style="text-align: left; width: 80%;" align="center" border="1"
1.76 cellpadding="5" cellspacing="0">
1.77 <tbody>
1.78 @@ -43,28 +62,68 @@
1.79 <th>Where it happens and how often</th>
1.80 </tr>
1.81 <tr>
1.82 - <td align="undefined" valign="undefined"> Import <code>urllib</code>
1.83 -to gain access to functionality which we can then use to access a
1.84 -remote service.</td>
1.85 - <td align="undefined" valign="undefined">This happens once - when
1.86 -the above code is itself imported into Python.</td>
1.87 + <td>Import <code>urllib</code> to gain access to functionality which we
1.88 + can then use to access a remote service.</td>
1.89 + <td>This happens once - when the above code is itself imported into
1.90 + Python.</td>
1.91 </tr>
1.92 <tr>
1.93 - <td align="undefined" valign="undefined">Use the <code>urlopen</code>
1.94 -function of <code>urllib</code> to actually access a remote service.</td>
1.95 - <td align="undefined" valign="undefined">This happens in the
1.96 -resource code each time the resource decides to access the service.</td>
1.97 + <td>Use the <code>urlopen</code> function of <code>urllib</code> to
1.98 + actually access a remote service.</td>
1.99 + <td>This happens in the resource code each time the resource decides to
1.100 + access the service.</td>
1.101 </tr>
1.102 </tbody>
1.103 </table>
1.104 -<p>In this case, the functionality is relatively easy to acquire and
1.105 -does not require any initialisation. But what if we were connecting to
1.106 -a database? There might be a need to specially initialise the database
1.107 -module - only once, though - and then repeatedly use it. Consider this
1.108 -highly artificial example:</p>
1.109 -<pre>import mydb<br /><br />connection = mydb.connect("me", "myPassword")<br /><br />class MyResource:<br /> def respond(self, trans):<br /> [Examine the transaction, decide what the user wants to do.]<br /><br /> results = connection.query("feed", owner="boddie.org.uk")<br /><br /> [Produce some kind of response which tells the user what happened.]
1.110 +
1.111 +<h2>Using Database Connections</h2>
1.112 +
1.113 +<p>In the above case, the functionality is relatively easy to acquire and does not
1.114 +require any initialisation. But what if we were connecting to a database? There
1.115 +might be a need to specially initialise the database module - only once, though
1.116 +- and then repeatedly use it. Moreover, we may want to ensure that any
1.117 +transactions created as our resources run are terminated when the resources
1.118 +have themselves completed their work. At this point, it is worth considering
1.119 +the <code>StoreSelector</code> class, as described in the <a
1.120 +href="selectors.html">"Selectors - Components for Dispatching to
1.121 +Resources"</a> document. Consider this example:</p>
1.122 +
1.123 +<pre>
1.124 +from WebStack.Resources.Selectors import StoreSelector
1.125 +
1.126 +class MyResource:
1.127 + def respond(self, trans):
1.128 + [Examine the transaction, decide what the user wants to do.]
1.129 +
1.130 + connection = trans.get_attributes()["store"]
1.131 + cursor = connection.cursor()
1.132 + try:
1.133 + cursor.execute("select url from feeds where owner=?", ["boddie.org.uk"])
1.134 + results = cursor.fetchall()
1.135 + finally:
1.136 + cursor.close()
1.137 +
1.138 + [Produce some kind of response which tells the user what happened.]
1.139 +
1.140 +def get_site_map(connection):
1.141 + return StoreSelector(MyResource(), connection)
1.142 </pre>
1.143 +
1.144 +<p>The initialisation would be done elsewhere, perhaps in the same module:</p>
1.145 +
1.146 +<pre>
1.147 +import mydb
1.148 +
1.149 +connection = mydb.connect("me", "myPassword")
1.150 +try:
1.151 + site = get_site_map(connection)
1.152 + deploy(site)
1.153 +finally:
1.154 + connection.close()
1.155 +</pre>
1.156 +
1.157 <p>In the above example, here is what happens:</p>
1.158 +
1.159 <table style="text-align: left; width: 80%;" align="center" border="1"
1.160 cellpadding="5" cellspacing="0">
1.161 <tbody>
1.162 @@ -73,54 +132,54 @@
1.163 <th>Where it happens and how often</th>
1.164 </tr>
1.165 <tr>
1.166 - <td align="undefined" valign="undefined">Import the <code>mydb</code>
1.167 -module to gain access to database access functionality.</td>
1.168 - <td align="undefined" valign="undefined">This happens once - when
1.169 -the above code is itself imported into Python.</td>
1.170 + <td>Import the <code>mydb</code> module to gain access to database access functionality.</td>
1.171 + <td>This happens once - when the above code is itself imported into Python.</td>
1.172 + </tr>
1.173 + <tr>
1.174 + <td>Initialise a database connection using the <code>connect</code> function from the <code>mydb</code> module.</td>
1.175 + <td>This also happens only once - when the above code is itself imported into Python.</td>
1.176 + </tr>
1.177 + <tr>
1.178 + <td>Wrap the application in a <code>StoreSelector</code> which manages
1.179 + the database connection.</td>
1.180 + <td>This happens in the <code>get_site_map</code> function which
1.181 + prepares the application before deployment.</td>
1.182 </tr>
1.183 <tr>
1.184 - <td align="undefined" valign="undefined">Initialise a database
1.185 -connection using the <code>connect</code> function from the <code>mydb</code>
1.186 -module.</td>
1.187 - <td align="undefined" valign="undefined">This also happens only
1.188 -once - when the above code is itself imported into Python.</td>
1.189 + <td>Make the connection available in a transaction object.</td>
1.190 + <td>This happens <strong>automatically</strong> for every incoming transaction or request to access the
1.191 + application - it is managed by the <code>StoreSelector</code> object.</td>
1.192 </tr>
1.193 <tr>
1.194 - <td align="undefined" valign="undefined">Use the <code>query</code>
1.195 -method on the connection object to access a database.</td>
1.196 - <td align="undefined" valign="undefined">This happens in the
1.197 -resource code each time the resource decides to access the database.</td>
1.198 + <td>Obtain the connection from the attributes on the transaction object;
1.199 + use the <code>cursor</code> method on the connection object to access
1.200 + the database; use the methods on the cursor object.</td>
1.201 + <td>This happens in the resource code each time the resource decides to
1.202 + access the database.</td>
1.203 + </tr>
1.204 + <tr>
1.205 + <td>Terminate the active transaction on the connection object.</td>
1.206 + <td>This happens <strong>automatically</strong> for every completed transaction or request to access the
1.207 + application - it is managed by the <code>StoreSelector</code> object.</td>
1.208 + </tr>
1.209 + <tr>
1.210 + <td>Close the database connection using the <code>close</code> method on
1.211 + the connection object.</td>
1.212 + <td>This also happens only once - when the application is
1.213 + terminating.</td>
1.214 </tr>
1.215 </tbody>
1.216 </table>
1.217 -<p>The choice of initialising the connection may seem arbitrary - why
1.218 -not just obtain a connection in the resource? Usually, such decisions
1.219 -are made on the basis of efficiency and on constraints outside the
1.220 -control of the application - some database systems limit the number of
1.221 -connections, for example, and if a large number of resources suddenly
1.222 -became active, some of them would fail to obtain connections if the
1.223 -connection initialisation code were in the <code>respond</code>
1.224 -method of the resource.</p>
1.225 -<h2>Configuring Packages Globally</h2>
1.226 -<p>Of course, the above resource might not be the only resource to use
1.227 -database connections. It might then be tempting to initialise a
1.228 -connection for each module whose resource needs (or, since as normal
1.229 -Python classes we can put many resources in a single module, whose
1.230 -resources need) to access a database. But it would surely be more
1.231 -convenient to define a single, central place to hold such global
1.232 -resources.</p>
1.233 -<p>One approach is to define a module which can be accessed by all
1.234 -modules, and thus by all resources. Let us create such a module in the
1.235 -file <code>Properties.py</code> which will reside alongside <code>MyApplication.py</code>
1.236 -(or whatever the application module is called). Inside the <code>Properties</code>
1.237 -module we can write the following code:</p>
1.238 -<pre>import mydb<br /><br />connection = mydb.connect("me", "myPassword")</pre>
1.239 -<p>Now, in each module containing resources which need to access the
1.240 -database, all we need to do now is to import the <code>Properties</code>
1.241 -module and to use the connection as defined in that module:</p>
1.242 -<pre>import Properties<br /><br />class MyResource:<br /> def respond(self, trans):<br /> [Examine the transaction, decide what the user wants to do.]<br /><br /> results = Properties.connection.query("feed", owner="boddie.org.uk")<br /><br /> [Produce some kind of response which tells the user what happened.]</pre>
1.243 -<p>This is a very simple approach that is technically outclassed by the
1.244 -mechanisms available in some frameworks. Currently, WebStack does not
1.245 -provide access to those more sophisticated mechanisms, however.</p>
1.246 +
1.247 +<p>The choice of initialising the connection may seem arbitrary - why not just
1.248 +obtain a connection in the resource? Usually, such decisions are made on the
1.249 +basis of efficiency and on constraints outside the control of the application -
1.250 +some database systems limit the number of connections, for example, and if a
1.251 +large number of resources suddenly became active, some of them would fail to
1.252 +obtain connections if the connection initialisation code were in the
1.253 +<code>respond</code> method of the resource. Moreover, by using the
1.254 +<code>StoreSelector</code>, a certain amount of "boilerplate" code can be
1.255 +hidden away and not written within each resource.</p>
1.256 +
1.257 </body>
1.258 </html>
2.1 --- a/docs/selectors.html Thu Dec 06 23:38:37 2007 +0000
2.2 +++ b/docs/selectors.html Thu Dec 06 23:40:18 2007 +0000
2.3 @@ -5,60 +5,214 @@
2.4 <link href="styles.css" rel="stylesheet" type="text/css" /></head>
2.5 <body>
2.6 <h1>Selectors - Components for Dispatching to Resources</h1>
2.7 -<p>The <code>Selectors</code> module provides classes (although
2.8 -currently only one class is supplied) which act as standard WebStack
2.9 -resources, but which attempt to "select" other resources, dispatch each
2.10 -request to those resources, and to cause various side-effects, mostly
2.11 -on the attributes stored on the transaction object. These "selector"
2.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
2.13 -non-trivial applications, it is often desirable to know the path or URL
2.14 -to a particular resource, especially the "root" resource under which
2.15 -the application or one of its components may reside. The <code>PathSelector</code>
2.16 -class can be instantiated and be made to refer to a resource, recording
2.17 -such path or URL details in an attribute for later inspection.</p><div class="WebStack">
2.18 -<h3>WebStack API - The PathSelector Class</h3>
2.19 +
2.20 +<p>The <code>Selectors</code> module provides classes (although currently only
2.21 +one class is supplied) which act as standard WebStack resources, but which
2.22 +attempt to "select" other resources, dispatch each request to those resources,
2.23 +and to cause various side-effects, mostly on the attributes stored on the
2.24 +transaction object. These "selector" classes behave those in the
2.25 +<code>ResourceMap</code> module, but aspire to be more generally
2.26 +applicable.</p>
2.27 +
2.28 +<h2>Selecting Path Roots with PathSelector</h2>
2.29 +
2.30 +<p>In non-trivial applications, it is often desirable to know the path or URL
2.31 +to a particular resource, especially the "root" resource under which the
2.32 +application or one of its components may reside. The <code>PathSelector</code>
2.33 +class can be instantiated and be made to refer to a resource, recording such
2.34 +path or URL details in an attribute for later inspection.</p>
2.35 +
2.36 +<div class="WebStack">
2.37 + <h3>WebStack API - The PathSelector Class</h3>
2.38 +
2.39 + <p>The <code>PathSelector</code> class (found in the
2.40 + <code>WebStack.Resources.Selectors</code> module) wraps resource objects whose
2.41 + location (as indicated by a path or URL) should be recorded as an attribute on
2.42 + the current transaction. The most common use of the class is to record the
2.43 + "root" resource's location, and this would be done as follows:</p>
2.44 +
2.45 +<pre>
2.46 +def get_site_map():
2.47 + return PathSelector(MyResource())
2.48 +</pre>
2.49 +
2.50 + <p>Here, the <code>get_site_map</code> function (as described in the <a
2.51 + href="deploying.html">"Deploying a WebStack Application"</a> document) would
2.52 + provide a <code>PathSelector</code> object instead of an instance of the
2.53 + <code>MyResource</code> class. However, the side-effect of combining these two
2.54 + resources would be the availability of an attribute named <code>root</code> on
2.55 + the transaction object. Thus, the "root" <code>MyResource</code> object and,
2.56 + indeed, all resource objects visited after this side-effect has occurred will
2.57 + have access to the "root" path or URL information.</p>
2.58 +
2.59 + <h4>Further Reading</h4>
2.60 +
2.61 + <p>The <a
2.62 + href="../apidocs/public/WebStack.Resources.Selectors.PathSelector-class.html">API
2.63 + documentation</a> for the <code>PathSelector</code> class provides additional
2.64 + information.</p>
2.65 +
2.66 +</div>
2.67 +
2.68 +<h2>Defining Encodings using EncodingSelector</h2>
2.69 +
2.70 +<p>One frequently bothersome aspect of writing Web applications involves the
2.71 +processing and production of text in different encodings. Whilst the WebStack
2.72 +API lets applications explicitly state the character encoding for various
2.73 +operations, one often wants to be able to ignore such details since they start
2.74 +to clutter up application code. The <code>EncodingSelector</code> class offers
2.75 +a basic solution which is compatible with the mechanisms in transaction
2.76 +objects: by wrapping WebStack resources with instances of
2.77 +<code>EncodingSelector</code>, an application-wide default encoding (or
2.78 +character set) will be defined; this will result in request information being
2.79 +processed according to the stated encoding and response information being
2.80 +produced according to that encoding (see below for more details of the latter
2.81 +activity).</p>
2.82 +
2.83 +<div class="WebStack">
2.84 + <h3>WebStack API - The EncodingSelector Class</h3>
2.85 +
2.86 + <p>The <code>EncodingSelector</code> class (found in the
2.87 + <code>WebStack.Resources.Selectors</code> module) wraps resource
2.88 + objects whilst changing the default encoding of the current transaction
2.89 + object. The class can be applied like this:</p>
2.90 +
2.91 +<pre>
2.92 +def get_site_map():
2.93 + return EncodingSelector(MyResource(), "utf-8")
2.94 +</pre>
2.95 +
2.96 + <p>Here, the <code>get_site_map</code> function (as described in the <a
2.97 + href="deploying.html">"Deploying a WebStack Application"</a> document) would
2.98 + provide a <code>EncodingSelector</code> object instead of an instance of the
2.99 + <code>MyResource</code> class. However, the <code>EncodingSelector</code> will
2.100 + forward requests on to <code>MyResource</code> (since it "selects" that
2.101 + resource), whilst setting the default encoding to be <code>"utf-8"</code>.</p>
2.102 +
2.103 + <h4>Request Streams and Encodings</h4>
2.104 +
2.105 + <p>Although a default encoding affects the processing of request parameters,
2.106 + direct access to the request stream using the <code>get_request_stream</code>
2.107 + method will only produce plain strings. This behaviour is justified by the
2.108 + observation that, if conversion from an encoding to Unicode were to take place,
2.109 + the resulting character values may be unsuitable substitutes for the original
2.110 + byte values in applications intending to make use of the raw incoming (possibly
2.111 + binary) data. A recipe for making a Unicode stream is provided in the <a
2.112 + href="encodings.html">"Character Encodings"</a> document.</p>
2.113 +
2.114 + <h4>Response Encodings and Content Types</h4>
2.115 +
2.116 + <p>Although <code>EncodingSelector</code> sets a default encoding, responses
2.117 + will generally be written in that encoding, at least if textual data is written
2.118 + to the response stream as Unicode objects. However, the content type must
2.119 + typically be set either to match the encoding in use or to not specify an
2.120 + encoding. It may become necessary to find out what the response stream encoding
2.121 + is when creating a <code>ContentType</code> object. For this and other
2.122 + purposes, the <code>get_response_stream_encoding</code> method is available on
2.123 + the transaction object<code></code>:</p>
2.124
2.125 -<p>The <code>PathSelector</code>
2.126 -class (found in the
2.127 -<code>WebStack.Resources.Selectors</code> module) wraps resource
2.128 -objects whose location (as indicated by a path or URL) should be
2.129 -recorded as an attribute on the current transaction. The most common
2.130 -use of the class is to record the "root" resource's location,
2.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>
2.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>
2.133 -object and, indeed, all resource objects visited after this side-effect
2.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>
2.135 -class provides additional information.</p></div><h2>Defining Encodings using EncodingSelector</h2><p>One
2.136 -frequently bothersome aspect of writing Web applications involves the
2.137 -processing and production of text in different encodings. Whilst the
2.138 -WebStack API lets applications explicitly state the character encoding
2.139 -for various operations, one often wants to be able to ignore such
2.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>,
2.141 -an application-wide default encoding (or character set) will be
2.142 -defined; this will result in request information being processed
2.143 -according to the stated encoding and response information being
2.144 -produced according to that encoding (see below for more details of the
2.145 -latter activity).</p><div class="WebStack">
2.146 -<h3>WebStack API - The EncodingSelector Class</h3>
2.147 +<pre>
2.148 +from WebStack.Generic import ContentType
2.149 +
2.150 +def respond(self, trans):
2.151 +
2.152 + # Some code...
2.153 +
2.154 + trans.set_content_type(ContentType("text/html", trans.get_response_stream_encoding()))
2.155 + out = trans.get_response_stream()
2.156 + out.write(some_unicode_object)
2.157 +</pre>
2.158 +
2.159 + <p>However, it is completely acceptable to omit the encoding information where
2.160 + a default encoding has been set:</p>
2.161 +
2.162 +<pre>
2.163 + trans.set_content_type(ContentType("text/html")) # no encoding/charset specified
2.164 +</pre>
2.165 +
2.166 + <h4>Reading the Default Directly</h4>
2.167 +
2.168 + <p>For some activities, such as making a Unicode stream from the request
2.169 + stream, it is desirable to find out the encoding set by the selector. This
2.170 + information is made available on transaction objects as the
2.171 + <code>default_charset</code> attribute.</p>
2.172 +
2.173 + <h4>Further Reading</h4>
2.174 +
2.175 + <p>The <a
2.176 + href="../apidocs/public/WebStack.Resources.Selectors.EncodingSelector-class.html">API
2.177 + documentation</a> for the <code>EncodingSelector</code> class provides
2.178 + additional information, along with the <a href="responses.html">"Responses and
2.179 + Presentation"</a> document.</p>
2.180 +
2.181 +</div>
2.182 +
2.183 +<h2>Managing Database Resources</h2>
2.184 +
2.185 +<p>Web applications must often employ external resources such as database
2.186 +systems, leading developers to consider effective mechanisms to manage such
2.187 +resources. Although an application can initially open a database connection
2.188 +and make it available to resources, it is essential that such resources access
2.189 +the connection in a way that does not cause problems over time. The
2.190 +<code>StoreSelector</code> class offers an elementary solution for resources
2.191 +employing database connections by storing a connection object in an attribute
2.192 +on the transaction object, such that resources may obtain the connection
2.193 +merely by accessing the appropriate attribute. Moreover, the
2.194 +<code>StoreSelector</code> also ensures that database transactions are
2.195 +terminated in a timely fashion by calling the <code>rollback</code> method on
2.196 +the connection when a resource (or potentially many resources) have completed
2.197 +their work.</p>
2.198
2.199 -<p>The <code>EncodingSelector</code>
2.200 -class (found in the
2.201 -<code>WebStack.Resources.Selectors</code> module) wraps resource
2.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>
2.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>
2.204 -method will only produce plain strings. This behaviour is justified by
2.205 -the observation that, if conversion from an encoding to Unicode were to
2.206 -take place, the resulting character values may be unsuitable
2.207 -substitutes for the original byte values in applications intending to
2.208 -make use of the raw incoming (possibly binary) data. A recipe for
2.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
2.210 -a default encoding, responses will generally be written in that
2.211 -encoding, at least if textual data is written to the response stream as
2.212 -Unicode objects. However, the content type must typically be set either
2.213 -to match the encoding in use or to not specify an encoding. It may
2.214 -become necessary to find out what the response stream encoding is when
2.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
2.216 -some activities, such as making a Unicode stream from the request
2.217 -stream, it is desirable to find out the encoding set by the selector.
2.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>
2.219 -class provides additional information, along with the <a href="responses.html">"Responses and Presentation"</a> document.</p></div><p></p><br /></body></html>
2.220 +<div class="WebStack">
2.221 + <h3>WebStack API - The StoreSelector Class</h3>
2.222 +
2.223 + <p>The <code>StoreSelector</code> class (found in the
2.224 + <code>WebStack.Resources.Selectors</code> module) wraps resource
2.225 + objects whilst maintaining a reference to a database connection or store
2.226 + object as an attribute on a WebStack transaction object. The class can be
2.227 + applied like this:</p>
2.228 +
2.229 +<pre>
2.230 +def get_site_map(connection):
2.231 + return StoreSelector(MyResource(), connection)
2.232 +</pre>
2.233 +
2.234 + <p>Here, the <code>get_site_map</code> function (as described in the <a
2.235 + href="deploying.html">"Deploying a WebStack Application"</a> document) would
2.236 + provide a <code>StoreSelector</code> object instead of an instance of the
2.237 + <code>MyResource</code> class. However, the <code>StoreSelector</code> will
2.238 + forward requests on to <code>MyResource</code> (since it "selects" that
2.239 + resource), whilst maintaining a reference to the <code>connection</code>
2.240 + provided.</p>
2.241 +
2.242 + <p>Resources wishing to access the database connection would use code like
2.243 + the following:</p>
2.244 +
2.245 +<pre>
2.246 +def respond(self, trans):
2.247 +
2.248 + # Some code...
2.249 +
2.250 + connection = trans.get_attributes()["store"]
2.251 +</pre>
2.252 +
2.253 + <p>Should an alternative attribute name be required, such a name may be
2.254 + provided as an additional argument when initialising the
2.255 + <code>StoreSelector</code>; for example:</p>
2.256 +
2.257 +<pre>
2.258 +def get_site_map(connection):
2.259 + return StoreSelector(MyResource(), connection, "connection")
2.260 +</pre>
2.261 +
2.262 + <h4>Further Reading</h4>
2.263 +
2.264 + <p>The <a
2.265 + href="../apidocs/public/WebStack.Resources.Selectors.StoreSelector-class.html">API
2.266 + documentation</a> for the <code>StoreSelector</code> class provides
2.267 + additional information, and the <a href="integrating.html">"Integrating with
2.268 + Other Systems"</a> document describes related topics.</p>
2.269 +
2.270 +</div>
2.271 +
2.272 +</body></html>