paulb@654 | 1 | <?xml version="1.0" encoding="iso-8859-1"?> |
paulb@357 | 2 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
paulb@654 | 3 | <html xmlns="http://www.w3.org/1999/xhtml"><head> |
paulb@654 | 4 | <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /><title>Paths To and Within Applications</title> |
paulb@654 | 5 | <link href="styles.css" rel="stylesheet" type="text/css" /></head> |
paulb@654 | 6 | <body><h1>Paths To and Within Applications</h1> |
paulb@488 | 7 | <p>One thing to be aware of, in the |
paulb@488 | 8 | code of an application, is which part |
paulb@357 | 9 | of |
paulb@357 | 10 | a |
paulb@582 | 11 | path refers to the location of the application in a server environment, |
paulb@582 | 12 | and |
paulb@357 | 13 | which refers to some resource within the application itself. Consider |
paulb@357 | 14 | this |
paulb@357 | 15 | path:</p> |
paulb@582 | 16 | <pre>/folder/application/resource/operation</pre><p>Let us say |
paulb@582 | 17 | that the application |
paulb@357 | 18 | was deployed in a Zope server |
paulb@357 | 19 | instance |
paulb@357 | 20 | inside |
paulb@357 | 21 | <code>folder</code> |
paulb@357 | 22 | and with the name <code>application</code>. |
paulb@357 | 23 | We may |
paulb@357 | 24 | then |
paulb@357 | 25 | say that the path to the application is this: |
paulb@582 | 26 | </p><pre>/folder/application</pre><p>Meanwhile, |
paulb@582 | 27 | the path <span style="font-style: italic;">within</span> |
paulb@582 | 28 | the |
paulb@357 | 29 | application is just this: |
paulb@582 | 30 | </p><pre>/resource/operation</pre><p>In WebStack, we |
paulb@582 | 31 | refer to this latter case - the path within |
paulb@582 | 32 | the |
paulb@654 | 33 | application - as the "path info".</p> |
paulb@582 | 34 | <div class="WebStack"><h3>WebStack API - Paths To |
paulb@357 | 35 | Resources Within Applications</h3> |
paulb@357 | 36 | <p>On transaction objects, the |
paulb@357 | 37 | following methods exist to inspect paths |
paulb@357 | 38 | to |
paulb@357 | 39 | resources within applications.</p> |
paulb@582 | 40 | <dl> <dt><code>get_path_info</code></dt> |
paulb@582 | 41 | <dd>This gets the path of a |
paulb@357 | 42 | resource within an application. The path should always contain a |
paulb@654 | 43 | leading <code>/</code> character at the very least.<br /> |
paulb@654 | 44 | An optional <code>encoding</code> parameter may be |
paulb@582 | 45 | used to assist the process of converting the path to a Unicode object - |
paulb@582 | 46 | see <a href="encodings.html">"Character Encodings"</a> |
paulb@582 | 47 | for more information.</dd> <dt><code>get_virtual_path_info</code></dt> |
paulb@582 | 48 | <dd>This gets the path of a |
paulb@357 | 49 | resource within a part of an application |
paulb@357 | 50 | - the application itself decides the scope of the path and can set the |
paulb@357 | 51 | "virtual path info" using the <code>set_virtual_path_info</code> |
paulb@654 | 52 | method. The path should either contain a leading <code>/</code> |
paulb@446 | 53 | character optionally followed by other characters, or an empty string.<br /> |
paulb@654 | 54 | An optional <code>encoding</code> parameter may be |
paulb@582 | 55 | used to assist the process of converting the path to a Unicode object - |
paulb@582 | 56 | see <a href="encodings.html">"Character Encodings"</a> |
paulb@582 | 57 | for more information.</dd><dt><code>get_processed_virtual_path_info</code></dt> |
paulb@582 | 58 | <dd>This gets the virtual path information which is considered to |
paulb@448 | 59 | have been processed or traversed, and consists of the part of the path |
paulb@448 | 60 | info which does not appear in the virtual path info. In other words, |
paulb@448 | 61 | when components at the start of the virtual path info are removed, such |
paulb@448 | 62 | components will appear at the end of the processed virtual path info.<br /> |
paulb@654 | 63 | An optional <code>encoding</code> parameter may be |
paulb@582 | 64 | used to assist the process of converting the path to a Unicode object - |
paulb@582 | 65 | see <a href="encodings.html">"Character Encodings"</a> |
paulb@582 | 66 | for more information.</dd> |
paulb@582 | 67 | </dl></div><h2>Choosing the Right Path Value</h2> |
paulb@654 | 68 | <p>Given that the path may change depending on |
paulb@582 | 69 | where an |
paulb@357 | 70 | application is deployed in a server environment, it may not be very |
paulb@357 | 71 | easy to use when determining which resources are being requested or |
paulb@357 | 72 | accessed within your application. Conversely, given that the "path |
paulb@357 | 73 | info" does not mention the full path to where the resources are, |
paulb@357 | 74 | it may be difficult to use that to provide references or links to those |
paulb@357 | 75 | resources. Here is a summary of how you might use the different path |
paulb@357 | 76 | values:</p> |
paulb@582 | 77 | <table style="text-align: left; width: 80%;" align="center" border="1" cellpadding="5" cellspacing="0" width="80%"> <tbody> <tr> <th style="text-align: center;">Type of information</th> <th style="text-align: center;">Possible uses</th> </tr> |
paulb@582 | 78 | <tr> <td align="undefined" valign="undefined">Path</td> |
paulb@582 | 79 | <td align="undefined" valign="undefined">Building |
paulb@582 | 80 | links to |
paulb@582 | 81 | resources within an application.</td> </tr> <tr><td align="undefined" valign="undefined">Path without |
paulb@582 | 82 | path info</td><td align="undefined" valign="undefined">Finding |
paulb@582 | 83 | the location of the application in a server environment. (This is the |
paulb@654 | 84 | path with the "path info" subtracted from |
paulb@582 | 85 | the end.)</td></tr><tr> <td align="undefined" valign="undefined">Path info</td> <td align="undefined" valign="undefined">Determining |
paulb@582 | 86 | which |
paulb@582 | 87 | resources are being accessed within an application.</td> </tr> |
paulb@582 | 88 | <tr> <td align="undefined" valign="undefined">Virtual |
paulb@582 | 89 | path info</td> <td align="undefined" valign="undefined">This |
paulb@582 | 90 | is an |
paulb@357 | 91 | application-defined version of "path info" and is discussed below.</td> |
paulb@582 | 92 | </tr> </tbody></table><h2>Using the Virtual |
paulb@582 | 93 | Path</h2> |
paulb@654 | 94 | <p>Although WebStack sets the "path info" so that |
paulb@582 | 95 | applications |
paulb@654 | 96 | know which part of themselves are being accessed, you may |
paulb@582 | 97 | decide |
paulb@357 | 98 | that upon |
paulb@357 | 99 | processing the request, these different parts of your application |
paulb@357 | 100 | should be |
paulb@357 | 101 | presented with different path information. For example, in a |
paulb@357 | 102 | hierarchical |
paulb@357 | 103 | structure of resources, each resource might use the first part of the |
paulb@357 | 104 | "path info" as an input to some kind of processing, but then have the |
paulb@357 | 105 | need to remove the |
paulb@357 | 106 | part they used, passing on a modified path to the other resources. For |
paulb@357 | 107 | such approaches, the "virtual path info" may be used instead, since it |
paulb@357 | 108 | permits modification within an application.</p> |
paulb@582 | 109 | <p>So starting with a virtual path like this (which would be the |
paulb@582 | 110 | same |
paulb@357 | 111 | as the "path info")...</p> |
paulb@582 | 112 | <pre>/company/department/employee</pre><p>...a |
paulb@654 | 113 | resource might extract <code>company</code> from |
paulb@582 | 114 | the start |
paulb@357 | 115 | of the path as follows:</p> |
paulb@582 | 116 | <pre> # Inside a respond method...<br /> path = trans.get_virtual_path_info() # get the virtual path<br /> parts = path.split("/") # split the path into components - the first will be empty</pre><p>Then, |
paulb@582 | 117 | having processed the first non-empty part (remembering that |
paulb@357 | 118 | the first part will be an empty string)...</p> |
paulb@582 | 119 | <pre> if len(parts) > 1: # check to see how deep we are in the path<br /> process_something(parts[1]) # process the first non-empty part</pre><p>...it |
paulb@582 | 120 | will reconstruct the path, removing the processed part (but |
paulb@654 | 121 | remembering to preserve a leading <code>/</code> |
paulb@582 | 122 | character)...</p> |
paulb@582 | 123 | <pre> trans.set_virtual_path_info("/" + "/".join(parts[2:]))</pre><p>...and |
paulb@582 | 124 | hand over control to another resource which would do the same |
paulb@357 | 125 | thing with the first of the other path components (<code>department</code> |
paulb@654 | 126 | and <code>employee</code>), and so on.</p> |
paulb@357 | 127 | <p>The compelling thing about this strategy is the way that each |
paulb@357 | 128 | resource would only need to take the "virtual path info" into |
paulb@357 | 129 | consideration, and that each resource would believe that it is running |
paulb@357 | 130 | independently from any "parent" resource. Moreover, such resources |
paulb@357 | 131 | could be deployed independently and still operate in the same way |
paulb@357 | 132 | without being "hardcoded" into assuming that they always reside at a |
paulb@582 | 133 | particular level in a resource hierarchy.</p><div class="WebStack"> |
paulb@357 | 134 | <h3>WebStack API - Paths To |
paulb@357 | 135 | Resources Within Applications</h3> |
paulb@357 | 136 | <p>On transaction objects, the |
paulb@357 | 137 | following method exists to set virtual paths within applications.</p> |
paulb@582 | 138 | <dl><dt><code>set_virtual_path_info</code></dt><dd>This |
paulb@582 | 139 | sets the virtual path, affecting subsequent calls to the <code>get_virtual_path_info</code> |
paulb@654 | 140 | method. The path should either contain a leading <code>/</code> |
paulb@582 | 141 | character optionally followed by other characters, or an empty string.</dd></dl> |
paulb@654 | 142 | </div><h2>Summary</h2><p>The following illustration hopefully provides a more memorable way of representing the structure of paths:</p> |
paulb@582 | 143 | <table style="text-align: left; width: 80%;" align="center" border="1" cellpadding="5" cellspacing="0" width="80%"> |
paulb@582 | 144 | <tbody> |
paulb@582 | 145 | <tr> |
paulb@582 | 146 | <th colspan="6" rowspan="1">URL</th> |
paulb@582 | 147 | </tr> |
paulb@582 | 148 | <tr> |
paulb@582 | 149 | <th colspan="1" rowspan="4">Protocol, host, port</th> |
paulb@582 | 150 | <th colspan="5" rowspan="1">Path</th> |
paulb@582 | 151 | </tr> |
paulb@582 | 152 | <tr> |
paulb@582 | 153 | <th colspan="3" rowspan="1">Path without query</th> |
paulb@582 | 154 | <th rowspan="3"></th> |
paulb@582 | 155 | <th colspan="1" rowspan="3">Query</th> |
paulb@582 | 156 | </tr> |
paulb@582 | 157 | <tr> |
paulb@582 | 158 | <th colspan="1" rowspan="2">Path without path info</th> |
paulb@582 | 159 | <th colspan="2">Path info</th> |
paulb@582 | 160 | </tr> |
paulb@582 | 161 | <tr> |
paulb@582 | 162 | <th>Processed virtual path info</th> |
paulb@582 | 163 | <th>Virtual path info</th> |
paulb@582 | 164 | </tr> |
paulb@582 | 165 | <tr> |
paulb@582 | 166 | <td>http://www.python.org</td> |
paulb@582 | 167 | <td>/folder/application</td> |
paulb@582 | 168 | <td>/resource</td> |
paulb@582 | 169 | <td>/operation</td> |
paulb@582 | 170 | <td>?</td> |
paulb@582 | 171 | <td>a=1&b=2</td> |
paulb@582 | 172 | </tr> |
paulb@582 | 173 | </tbody> |
paulb@582 | 174 | </table> |
paulb@654 | 175 | </body></html> |