[Zope3-checkins] SVN: Zope3/branches/3.2/src/zope/ Added a text file describing the new IResult mechanism and registered

[Jim Fulton]

Log message for revision 40924:
  Added a text file describing the new IResult mechanism and registered
  it with apidoc.
  
  I need someone to review this.
  
  This probably should be written as a test, but that requires too much
  effort for now.
  

Changed:
  U   Zope3/branches/3.2/src/zope/app/publisher/configure.zcml
  A   Zope3/branches/3.2/src/zope/publisher/httpresults.txt

-=-
Modified: Zope3/branches/3.2/src/zope/app/publisher/configure.zcml
===================================================================
--- Zope3/branches/3.2/src/zope/app/publisher/configure.zcml	2005-12-20 22:39:56 UTC (rev 40923)
+++ Zope3/branches/3.2/src/zope/app/publisher/configure.zcml	2005-12-20 22:39:59 UTC (rev 40924)
@@ -1,10 +1,27 @@
-<configure xmlns="http://namespaces.zope.org/zope">
+<configure 
+    xmlns="http://namespaces.zope.org/zope"
+    xmlns:apidoc="http://namespaces.zope.org/apidoc"
+    >
+
   <include package=".browser" />
   <include package=".xmlrpc" />
   <include file="http.zcml" />
 
-  <interface
-     interface="zope.publisher.interfaces.xmlrpc.IXMLRPCRequest"
-     />
+  <interface interface="zope.publisher.interfaces.xmlrpc.IXMLRPCRequest" />
 
+  <configure 
+      xmlns:zcml="http://namespaces.zope.org/zcml"
+      zcml:condition="have apidoc" 
+      xmlns="http://namespaces.zope.org/apidoc"
+      >
+
+    <bookchapter
+        id="zopepublisherhttpresults.txt"
+        title="Creating HTTP Results"
+        doc_path="../../publisher/httpresults.txt"
+        />
+
+  </configure>
+
 </configure>
+

Added: Zope3/branches/3.2/src/zope/publisher/httpresults.txt
===================================================================
--- Zope3/branches/3.2/src/zope/publisher/httpresults.txt	2005-12-20 22:39:56 UTC (rev 40923)
+++ Zope3/branches/3.2/src/zope/publisher/httpresults.txt	2005-12-20 22:39:59 UTC (rev 40924)
@@ -0,0 +1,96 @@
+Creating HTTP Results
+=====================
+
+This document describes the state of creating HTTP results for Zope
+3.2.  This is different than it was in the past and likely to be
+different from how it will be in the future. Please bear with us.
+
+Traditionally in Zope, HTTP results are created by simply returning
+strings.  Strings are inspected to deduce their content type, which is
+usually HTML.  Applications can override this by setting a response
+headers (calling request.respoonce.setHeader).
+
+In Zope 2, applications could also call response.write.  This allows 
+both:
+
+- Effecient handling of large output
+
+- HTTP chucked output for streaming
+
+Before release 3.1, Zope 3 has a response write method that did
+neither of these things.  Developers coming from Zope 2 might use the
+write method, expecting it to have the same bahavior as it does in
+Zope 2.  At least until we can satisfy those expectations, we have
+disabled the response write method for now.  Maybe we'll reinstate it
+in the future.
+
+There is currently no support for streaming, but there is now support
+for returning large amounts of data.
+
+Returning large amounts of data without storing the data in memory
+------------------------------------------------------------------
+
+Starting in Zope 3.2, a published object (e.g. a view or view method)
+can return any object as long as it is is adaptable to
+zope.publisher.interfaces.http.IResult::
+
+  class IResult(Interface):
+      """HTTP result.
+
+      The result provides the result in a form suitable for delivery to HTTP
+      clients.
+
+      IMPORTANT: The result object may be held indefinitely by a server and may
+      be accessed by arbitrary threads. For that reason the result should not
+      hold on to any application resources and should be prepared to be invoked
+      from any thread.
+      """
+
+      headers = Attribute('A sequence of tuples of result headers, such as'
+                          '"Content-Type" and "Content-Length", etc.')
+
+      body = Attribute('An iterable that provides the body data of the'
+                       'response.')
+
+The result object has headers and an iterable body.  The ability to
+supply headers in a result is useful for adapters that compute headers
+by inspecting a the object being adapted.
+
+There is a helper class, zope.publisher.http.DirectResult that can be
+used to compute result objects.
+
+When an published object returns a string. the string is inspected to
+determine response headers (like content type and content length) and
+a result is created using DirectResult.
+
+If you want to return a large amont of data, you can create a result
+object yourself.  A good way to do this is to copy the data to a 
+temporary file and return an iterator to that::
+
+   import tempfile
+   file = tempfile.TemporaryFile()
+
+   # ... write data to the file ...
+
+   def fileiterator(file, bufsize=8192):
+       while 1:
+           data = file.read(bufsize)
+           if data:
+               yield data
+           else:
+               break
+
+       file.close()
+
+   return DirectResult(fileiterator(file), 
+                       [('Content-Length', mydatalength),
+                        ('Content-Type', mydatatype),
+                       ])
+
+We should provide some helper objects that automate more of this, and
+we probably will in later revisions.
+
+IMPORTANT NOTE: the iterator that you pass to DirectResult must *not*
+use any application resources.  When the iterator is called,
+application resoures may have been released or be in use by another
+thread. 


Property changes on: Zope3/branches/3.2/src/zope/publisher/httpresults.txt
___________________________________________________________________
Name: svn:eol-style
   + native