1.1 --- a/docs/responses.html Sat Apr 30 21:47:58 2005 +0000
1.2 +++ b/docs/responses.html Sat Apr 30 21:48:08 2005 +0000
1.3 @@ -29,8 +29,7 @@
1.4 <li>Setting a response code to
1.5 signal whether the application performed the requested operation
1.6 successfully.</li>
1.7 - <li>Setting a content type and a
1.8 - <a>character encoding</a>.</li>
1.9 + <li>Setting a content type and a <a>character encoding</a>.</li>
1.10 <li>Producing content and
1.11 sending it to the user.</li>
1.12 </ol>
1.13 @@ -70,6 +69,26 @@
1.14 stream through which data may be sent to the user.</dd>
1.15 </dl>
1.16 </div>
1.17 +<h2>Ending the Response Explicitly</h2>
1.18 +<p>Although it is possible to produce some output and then to let
1.19 +the <code>respond</code> function complete normally, sometimes it
1.20 +is appropriate to terminate the response and to hand control straight
1.21 +back to the server environment; in other words, to decide that no more
1.22 +activity will be performed within the application and to send the
1.23 +response immediately. Whilst just using a <code>return</code>
1.24 +statement might be adequate in many applications...</p>
1.25 +<pre> # In the respond method...<br /> if some_condition:<br /> [Produce a response.]<br /> return<br /> [Produce a different response.]</pre>
1.26 +<p>...sometimes a resource's <code>respond</code> method is being
1.27 +called from another resource, and it may be the case that this other
1.28 +resource may produce additional output if control is returned to it.</p>
1.29 +<p>To provide a definitive end of response signal, a special exception
1.30 +is available:</p>
1.31 +<pre>from WebStack.Generic import EndOfResponse<br /><br />[The usual declarations for the resource and the respond method...]<br /><br /> # In the respond method (possibly called by another resource)...<br /> if some_condition:<br /> [Produce a response.]<br /> raise EndOfResponse</pre>
1.32 +<p>This exception, when raised, ensures that the response is sent
1.33 +exactly as the resource intended upon raising the exception. Note that
1.34 +although <code>WebStack.Generic.EndOfResponse</code> is an exception,
1.35 +it will not cause an error condition or change the response code in any
1.36 +way.</p>
1.37 <h2>Integrating with Content Generators</h2>
1.38 <p>Just as applications might need to integrate with other systems in
1.39 order to fetch information or to perform operations on behalf of the