# HG changeset patch
# User paulb
# Date 1114897688 0
# Node ID 4afabafdf5cace3f5f880c38a71a0138e451d536
# Parent  a6cc8e5f642d002d32820375e224d1375123b2f6
[project @ 2005-04-30 21:48:08 by paulb]
Added notes about EndOfResponse.

diff -r a6cc8e5f642d -r 4afabafdf5ca docs/responses.html
--- a/docs/responses.html	Sat Apr 30 21:47:58 2005 +0000
+++ b/docs/responses.html	Sat Apr 30 21:48:08 2005 +0000
@@ -29,8 +29,7 @@
   <li>Setting a response code to
 signal whether the application performed the requested operation
 successfully.</li>
-  <li>Setting a content type and a
-    <a>character encoding</a>.</li>
+  <li>Setting a content type and a <a>character encoding</a>.</li>
   <li>Producing content and
 sending it to the user.</li>
 </ol>
@@ -70,6 +69,26 @@
 stream through which data may be sent to the user.</dd>
 </dl>
 </div>
+<h2>Ending the Response Explicitly</h2>
+<p>Although it is possible to produce some output and then to let
+the&nbsp;<code>respond</code> function complete normally, sometimes it
+is appropriate to terminate the response and to hand control straight
+back to the server environment; in other words, to decide that no more
+activity will be performed within the application and to send the
+response immediately. Whilst just using a&nbsp;<code>return</code>
+statement might be adequate in many applications...</p>
+<pre>        # In the respond method...<br />        if some_condition:<br />            [Produce a response.]<br />            return<br />        [Produce a different response.]</pre>
+<p>...sometimes a resource's&nbsp;<code>respond</code> method is being
+called from another resource, and it may be the case that this other
+resource may produce additional output if control is returned to it.</p>
+<p>To provide a definitive end of response signal, a special exception
+is available:</p>
+<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>
+<p>This exception, when raised, ensures that the response is sent
+exactly as the resource intended upon raising the exception. Note that
+although <code>WebStack.Generic.EndOfResponse</code> is an exception,
+it will not cause an error condition or change the response code in any
+way.</p>
 <h2>Integrating with Content Generators</h2>
 <p>Just as applications might need to integrate with other systems in
 order to fetch information or to perform operations on behalf of the