1 <?xml version="1.0" encoding="iso-8859-1"?> 2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3 <html xmlns="http://www.w3.org/1999/xhtml"><head><meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> 4 <title>Selectors - Components for Dispatching to Resources</title> 5 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 6 <body> 7 <h1>Selectors - Components for Dispatching to Resources</h1> 8 9 <p>The <code>Selectors</code> module provides classes (although currently only 10 one class is supplied) which act as standard WebStack resources, but which 11 attempt to "select" other resources, dispatch each request to those resources, 12 and to cause various side-effects, mostly on the attributes stored on the 13 transaction object. These "selector" classes behave those in the 14 <code>ResourceMap</code> module, but aspire to be more generally 15 applicable.</p> 16 17 <h2>Selecting Path Roots with PathSelector</h2> 18 19 <p>In non-trivial applications, it is often desirable to know the path or URL 20 to a particular resource, especially the "root" resource under which the 21 application or one of its components may reside. The <code>PathSelector</code> 22 class can be instantiated and be made to refer to a resource, recording such 23 path or URL details in an attribute for later inspection.</p> 24 25 <div class="WebStack"> 26 <h3>WebStack API - The PathSelector Class</h3> 27 28 <p>The <code>PathSelector</code> class (found in the 29 <code>WebStack.Resources.Selectors</code> module) wraps resource objects whose 30 location (as indicated by a path or URL) should be recorded as an attribute on 31 the current transaction. The most common use of the class is to record the 32 "root" resource's location, and this would be done as follows:</p> 33 34 <pre> 35 def get_site_map(): 36 return PathSelector(MyResource()) 37 </pre> 38 39 <p>Here, the <code>get_site_map</code> function (as described in the <a 40 href="deploying.html">"Deploying a WebStack Application"</a> document) would 41 provide a <code>PathSelector</code> object instead of an instance of the 42 <code>MyResource</code> class. However, the side-effect of combining these two 43 resources would be the availability of an attribute named <code>root</code> on 44 the transaction object. Thus, the "root" <code>MyResource</code> object and, 45 indeed, all resource objects visited after this side-effect has occurred will 46 have access to the "root" path or URL information.</p> 47 48 <h4>Further Reading</h4> 49 50 <p>The <a 51 href="../apidocs/public/WebStack.Resources.Selectors.PathSelector-class.html">API 52 documentation</a> for the <code>PathSelector</code> class provides additional 53 information.</p> 54 55 </div> 56 57 <h2>Defining Encodings using EncodingSelector</h2> 58 59 <p>One frequently bothersome aspect of writing Web applications involves the 60 processing and production of text in different encodings. Whilst the WebStack 61 API lets applications explicitly state the character encoding for various 62 operations, one often wants to be able to ignore such details since they start 63 to clutter up application code. The <code>EncodingSelector</code> class offers 64 a basic solution which is compatible with the mechanisms in transaction 65 objects: by wrapping WebStack resources with instances of 66 <code>EncodingSelector</code>, an application-wide default encoding (or 67 character set) will be defined; this will result in request information being 68 processed according to the stated encoding and response information being 69 produced according to that encoding (see below for more details of the latter 70 activity).</p> 71 72 <div class="WebStack"> 73 <h3>WebStack API - The EncodingSelector Class</h3> 74 75 <p>The <code>EncodingSelector</code> class (found in the 76 <code>WebStack.Resources.Selectors</code> module) wraps resource 77 objects whilst changing the default encoding of the current transaction 78 object. The class can be applied like this:</p> 79 80 <pre> 81 def get_site_map(): 82 return EncodingSelector(MyResource(), "utf-8") 83 </pre> 84 85 <p>Here, the <code>get_site_map</code> function (as described in the <a 86 href="deploying.html">"Deploying a WebStack Application"</a> document) would 87 provide a <code>EncodingSelector</code> object instead of an instance of the 88 <code>MyResource</code> class. However, the <code>EncodingSelector</code> will 89 forward requests on to <code>MyResource</code> (since it "selects" that 90 resource), whilst setting the default encoding to be <code>"utf-8"</code>.</p> 91 92 <h4>Request Streams and Encodings</h4> 93 94 <p>Although a default encoding affects the processing of request parameters, 95 direct access to the request stream using the <code>get_request_stream</code> 96 method will only produce plain strings. This behaviour is justified by the 97 observation that, if conversion from an encoding to Unicode were to take place, 98 the resulting character values may be unsuitable substitutes for the original 99 byte values in applications intending to make use of the raw incoming (possibly 100 binary) data. A recipe for making a Unicode stream is provided in the <a 101 href="encodings.html">"Character Encodings"</a> document.</p> 102 103 <h4>Response Encodings and Content Types</h4> 104 105 <p>Although <code>EncodingSelector</code> sets a default encoding, responses 106 will generally be written in that encoding, at least if textual data is written 107 to the response stream as Unicode objects. However, the content type must 108 typically be set either to match the encoding in use or to not specify an 109 encoding. It may become necessary to find out what the response stream encoding 110 is when creating a <code>ContentType</code> object. For this and other 111 purposes, the <code>get_response_stream_encoding</code> method is available on 112 the transaction object<code></code>:</p> 113 114 <pre> 115 from WebStack.Generic import ContentType 116 117 def respond(self, trans): 118 119 # Some code... 120 121 trans.set_content_type(ContentType("text/html", trans.get_response_stream_encoding())) 122 out = trans.get_response_stream() 123 out.write(some_unicode_object) 124 </pre> 125 126 <p>However, it is completely acceptable to omit the encoding information where 127 a default encoding has been set:</p> 128 129 <pre> 130 trans.set_content_type(ContentType("text/html")) # no encoding/charset specified 131 </pre> 132 133 <h4>Reading the Default Directly</h4> 134 135 <p>For some activities, such as making a Unicode stream from the request 136 stream, it is desirable to find out the encoding set by the selector. This 137 information is made available on transaction objects as the 138 <code>default_charset</code> attribute.</p> 139 140 <h4>Further Reading</h4> 141 142 <p>The <a 143 href="../apidocs/public/WebStack.Resources.Selectors.EncodingSelector-class.html">API 144 documentation</a> for the <code>EncodingSelector</code> class provides 145 additional information, along with the <a href="responses.html">"Responses and 146 Presentation"</a> document.</p> 147 148 </div> 149 150 <h2>Managing Database Resources</h2> 151 152 <p>Web applications must often employ external resources such as database 153 systems, leading developers to consider effective mechanisms to manage such 154 resources. Although an application can initially open a database connection 155 and make it available to resources, it is essential that such resources access 156 the connection in a way that does not cause problems over time. The 157 <code>StoreSelector</code> class offers an elementary solution for resources 158 employing database connections by storing a connection object in an attribute 159 on the transaction object, such that resources may obtain the connection 160 merely by accessing the appropriate attribute. Moreover, the 161 <code>StoreSelector</code> also ensures that database transactions are 162 terminated in a timely fashion by calling the <code>rollback</code> method on 163 the connection when a resource (or potentially many resources) have completed 164 their work.</p> 165 166 <div class="WebStack"> 167 <h3>WebStack API - The StoreSelector Class</h3> 168 169 <p>The <code>StoreSelector</code> class (found in the 170 <code>WebStack.Resources.Selectors</code> module) wraps resource 171 objects whilst maintaining a reference to a database connection or store 172 object as an attribute on a WebStack transaction object. The class can be 173 applied like this:</p> 174 175 <pre> 176 def get_site_map(connection): 177 return StoreSelector(MyResource(), connection) 178 </pre> 179 180 <p>Here, the <code>get_site_map</code> function (as described in the <a 181 href="deploying.html">"Deploying a WebStack Application"</a> document) would 182 provide a <code>StoreSelector</code> object instead of an instance of the 183 <code>MyResource</code> class. However, the <code>StoreSelector</code> will 184 forward requests on to <code>MyResource</code> (since it "selects" that 185 resource), whilst maintaining a reference to the <code>connection</code> 186 provided.</p> 187 188 <p>Resources wishing to access the database connection would use code like 189 the following:</p> 190 191 <pre> 192 def respond(self, trans): 193 194 # Some code... 195 196 connection = trans.get_attributes()["store"] 197 </pre> 198 199 <p>Should an alternative attribute name be required, such a name may be 200 provided as an additional argument when initialising the 201 <code>StoreSelector</code>; for example:</p> 202 203 <pre> 204 def get_site_map(connection): 205 return StoreSelector(MyResource(), connection, "connection") 206 </pre> 207 208 <h4>Further Reading</h4> 209 210 <p>The <a 211 href="../apidocs/public/WebStack.Resources.Selectors.StoreSelector-class.html">API 212 documentation</a> for the <code>StoreSelector</code> class provides 213 additional information, and the <a href="integrating.html">"Integrating with 214 Other Systems"</a> document describes related topics.</p> 215 216 </div> 217 218 </body></html>