Hewlett-Packard Bluestone Cocoon Project

                               @version@


  What is being added?
  --------------------

·	StreamGenerator
·	PostInputStream
   
StreamGenerator
The StreamGenerator is a class that reads XML from an HttpRequest InputStream and generates SAX Events. StreamGenerator expects XML data coming as POST message. 

For POST requests with mimetype of application/x-www-form-urlencoded, the xml data expects to be associated with the name specified in the sitemap parameter.

For POST requests with mimetypes: text/plain, text/xml, application/xml the xml data is in the body of the POST request and its length is specified by the value returned by getContentLength() method.
  
PostInputStream
The StreamGenerator uses helper class org.apache.cocoon.util.PostInputStream for InputStream reading operations. At the time that Parser reads the data out of InputStream - Parser has no knowledge about the length of data to be    read. The only way to signal to the Parser that all data was read from the InputStream is to control reading   operation - PostInputStream- and to return to the requestor -1 when the number of bytes read is equal to the getContentLength() value.
  

Installation Instructions
----------------------------
TO VIEW ABOVE COCOON ELEMENTS "IN ACTION":
  
Unzip the attached file. The necessary elements will "fall into place" within the Cocoon code. Compile it using instruction in Cocoon install file. Since the generator is a generic object, i.e. it can process any stream out of the POST message there are two ways to see StreamGenerator in action:
  1. To invoke URL http://localhost:8080/cocoon/Order
  2. To use telnet program to generate POST request
   
The first option is not a "pure" stream invocation, but it is quick way to observe desired effects. The result of this invocation is a form containing the XML document embedded in the textarea of the form. Submission of this form will invoke StreamGenerator. The testarea name/value par is specified as a parameter in the sitemap definition for the StreamGenerator. The expected result is the submitted xml document send back to the browser.
  
The second or "pure" option of testing StreamGenerator "in action," requires the use of Telnet program or any other process able to generate correct POST message. The procedure is:
·	To invoke telnet, connect to localhost 8080 and to use content of telnet.txt file as a post message. 
·	Here, the Copy-Paste method should be used.
·	Remember to hit the enter button twice enter after the contents of the post are set in telnet.

It is important because Content-len is calculated assuming two "enter" in the end of http message. Once again, the performed task results in the mirror of the original document being sent back to the requestor. 

The "pure" stream generation can be observed using the telnet utility where you can invoke a message targeting my processing. Any other method is good (URL object connection) as long the message is well formed.


Compatibility Issues
------------------------

The attached code was tested and is compatible with the Cocoon codebase ver.2.0a7 taken from CVS Repository 5/26/2001. 
The code was tested  on  Windows 2000 and  NT 4.0  using Tomcatt 4.0-b5 and newest Bluestone HP  application server.