non-releases/trunk_before_flattening/src/documentation/src/content/xdocs/c21-stream-generator/content_en.html - cocoon - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
 <html>
 <head>
 <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
 <title>Stream Generator</title>
 <link href="http://purl.org/DC/elements/1.0/" rel="schema.DC">
 <meta content="Kinga Dziembowska" name="DC.Creator">
 <meta content="Davanum Srinivas" name="DC.Creator">
 <meta content="This document describes the stream generator of Cocoon." name="DC.Description">
 </head>
 <body>

 <h1>Stream Generator</h1>

 <p>
               The StreamGenerator is a class that reads XML from an HttpRequest
               InputStream and generates SAX Events. StreamGenerator expects
               XML data coming as HTTP request message.
               </p>

 <ul>

 <li>Name : stream</li>

 <li>Class: org.apache.cocoon.generation.StreamGenerator</li>

 <li>Cacheable: no.</li>

 </ul>

 <p>
              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.
               </p>


 <p>
               For HTTP requests with mimetypes: text/plain, text/xml, application/xml
               the xml data is in the body of the HTTP request and its length is
               specified by the value returned by getContentLength() method.
               </p>

 <h2>PostInputStream</h2>
 <p>
               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.
               </p>


 <h2>See it in Action</h2>
 <p>
               The Generator is a generic object, i.e. it can process any stream out of the
               HTTP message. There are two ways to see StreamGenerator in action:
               </p>
 <ul>

 <li>To invoke URL http://localhost:8080/cocoon/Order</li>

 <li>To use telnet program to generate POST request</li>

 </ul>
 <p>
               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.
               </p>
 <p>
               The second or "pure" option of testing StreamGenerator "in action," requires the
               use of Telnet program or any other process able to generate correct HTTP message.
               The procedure is:
               </p>
 <ul>

 <li>To invoke telnet, connect to localhost 8080 and to use content of
                       <a href="telnet.txt">telnet.txt</a> file as a post message.
                   </li>

 <li>Here, the Copy-Paste method should be used.</li>

 <li>Remember to hit the enter button twice enter after the contents of the post are set in telnet.</li>

 </ul>
 <p>
               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.
               </p>
 <p>
               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.
               </p>
 <pre class="code">

   &lt;map:generate type="stream"/&gt;

 </pre>
 <p>
               If you want to process XML streams sent by clients that don't set the Content-Type HTTP header
               just use the defaultContentType parameter.

             </p>
 <pre class="code">

   &lt;map:generate type="stream"&gt;
     &lt;map:parameter name="defaultContentType" value="text/xml"/&gt;
   &lt;/map:generate&gt;

 </pre>


 </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
	<html>
	<head>
	<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
	<title>Stream Generator</title>
	<link href="http://purl.org/DC/elements/1.0/" rel="schema.DC">
	<meta content="Kinga Dziembowska" name="DC.Creator">
	<meta content="Davanum Srinivas" name="DC.Creator">
	<meta content="This document describes the stream generator of Cocoon." name="DC.Description">
	</head>
	<body>

	<h1>Stream Generator</h1>

	<p>
	The StreamGenerator is a class that reads XML from an HttpRequest
	InputStream and generates SAX Events. StreamGenerator expects
	XML data coming as HTTP request message.
	</p>

	<ul>

	<li>Name : stream</li>

	<li>Class: org.apache.cocoon.generation.StreamGenerator</li>

	<li>Cacheable: no.</li>

	</ul>

	<p>
	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.
	</p>


	<p>
	For HTTP requests with mimetypes: text/plain, text/xml, application/xml
	the xml data is in the body of the HTTP request and its length is
	specified by the value returned by getContentLength() method.
	</p>

	<h2>PostInputStream</h2>
	<p>
	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.
	</p>


	<h2>See it in Action</h2>
	<p>
	The Generator is a generic object, i.e. it can process any stream out of the
	HTTP message. There are two ways to see StreamGenerator in action:
	</p>
	<ul>

	<li>To invoke URL http://localhost:8080/cocoon/Order</li>

	<li>To use telnet program to generate POST request</li>

	</ul>
	<p>
	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.
	</p>
	<p>
	The second or "pure" option of testing StreamGenerator "in action," requires the
	use of Telnet program or any other process able to generate correct HTTP message.
	The procedure is:
	</p>
	<ul>

	<li>To invoke telnet, connect to localhost 8080 and to use content of
	<a href="telnet.txt">telnet.txt</a> file as a post message.
	</li>

	<li>Here, the Copy-Paste method should be used.</li>

	<li>Remember to hit the enter button twice enter after the contents of the post are set in telnet.</li>

	</ul>
	<p>
	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.
	</p>
	<p>
	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.
	</p>
	<pre class="code">

	<map:generate type="stream"/>

	</pre>
	<p>
	If you want to process XML streams sent by clients that don't set the Content-Type HTTP header
	just use the defaultContentType parameter.

	</p>
	<pre class="code">

	<map:generate type="stream">
	<map:parameter name="defaultContentType" value="text/xml"/>
	</map:generate>

	</pre>


	</body>
	</html>