cocoon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From reinh...@apache.org
Subject svn commit: r806356 - in /cocoon/cocoon3/trunk/cocoon-docs/src/docbkx: index.xml reference/pipelines.xml
Date Thu, 20 Aug 2009 20:56:40 GMT
Author: reinhard
Date: Thu Aug 20 20:56:39 2009
New Revision: 806356

URL: http://svn.apache.org/viewvc?rev=806356&view=rev
Log:
COCOON3-28
Stax documenation
update package names of SAX components

Modified:
    cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/index.xml
    cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/pipelines.xml

Modified: cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/index.xml
URL: http://svn.apache.org/viewvc/cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/index.xml?rev=806356&r1=806355&r2=806356&view=diff
==============================================================================
--- cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/index.xml (original)
+++ cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/index.xml Thu Aug 20 20:56:39 2009
@@ -22,7 +22,7 @@
   <bookinfo>
     <title>Cocoon 3.0 ALPHA - Reference Documentation</title>
 
-    <releaseinfo>Cocoon 3.0 ALPHA</releaseinfo>
+    <releaseinfo>Apache Cocoon 3.0 ALPHA</releaseinfo>
 
     <authorgroup>
       <author>

Modified: cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/pipelines.xml
URL: http://svn.apache.org/viewvc/cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/pipelines.xml?rev=806356&r1=806355&r2=806356&view=diff
==============================================================================
--- cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/pipelines.xml (original)
+++ cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/pipelines.xml Thu Aug 20 20:56:39
2009
@@ -90,7 +90,7 @@
           <area id="pipelines.definition.setup" coords="7"/>
           <area id="pipelines.definition.execute" coords="8"/>
         </areaspec>      
-      <programlisting language="java"><![CDATA[Pipeline pipeline = new NonCachingPipeline();
+      <programlisting language="java"><![CDATA[Pipeline<SAXPipelineComponent>
pipeline = new NonCachingPipeline<SAXPipelineComponent>();
 pipeline.addComponent(new StringGenerator("<x></x>"));
 pipeline.addComponent(new XSLTTransformer(this.getClass().getResource("/test1.xslt")));
 pipeline.addComponent(new XSLTTransformer(this.getClass().getResource("/test2.xslt")));
@@ -114,13 +114,13 @@
             </para>
             <para>
               The <literal>StringGenerator</literal> expects a <literal>java.lang.String</literal>
object and produces SAX events by using a SAX parser.
-              Hence it has to implement the <literal>org.apache.cocoon.pipeline.component.sax.SAXProducer</literal>
interface.
+              Hence it has to implement the <literal>org.apache.cocoon.sax.component.SAXProducer</literal>
interface.
             </para>
             <para>
               The <literal>SAXProducer</literal> interface extends the <literal>org.apache.cocoon.pipeline.component.Producer</literal>
interface. This
               means that it expects the next (or the same!) component to implement the <literal>org.apache.cocoon.pipeline.component.Consumer</literal>
-              interface. The check that the next pipeline component is of type <literal>org.apache.cocoon.pipeline.component.sax.SAXConsumer</literal>
-              isn't done at interface level but by the implementation (see the <literal>org.apache.cocoon.pipeline.component.sax.AbstractXMLProducer</literal>
+              interface. The check that the next pipeline component is of type <literal>org.apache.cocoon.sax.component.SAXConsumer</literal>
+              isn't done at interface level but by the implementation (see the <literal>org.apache.cocoon.sax.component.AbstractXMLProducer</literal>
               for details which the <literal>StringGenerator</literal> is inherited
from).
             </para>
             <para>
@@ -129,8 +129,8 @@
          </callout>
          <callout arearefs="pipelines.definition.transformer1">
             <para>
-              Add a transformer, that implements the <literal>org.apache.cocoon.pipeline.component.PipelineComponent</literal>
interface to the
-              pipeline by using the pipeline's <literal>addComponent(pipelineComponent)</literal>
interface.
+              Add a transformer, that implements the <literal>org.apache.cocoon.pipeline.component.PipelineComponent</literal>
interface, to the
+              pipeline by using the pipeline's <literal>addComponent(pipelineComponent)</literal>
method.
             </para>
             <para>
               This <literal>XSLTTransformer</literal> expects the <literal>java.net.URL</literal>
of an XSLT stylesheet. It uses the rules of the stylesheet
@@ -138,15 +138,15 @@
             </para>
             <para>
               Since it implements the <literal>org.apache.cocoon.pipeline.component.Consumer</literal>
interface, it fulfills the general contract that a <literal>Consumer</literal>
-              is linked with a <literal>Producer</literal>. By implementing the
<literal>org.apache.cocoon.pipeline.component.sax.SAXConsumer</literal> interface,
+              is linked with a <literal>Producer</literal>. By implementing the
<literal>org.apache.cocoon.sax.component.SAXConsumer</literal> interface,
               it fulfills the specific requirement of the previous <literal>StringGenerator</literal>
that expects a next pipeline component of that type. 
             </para>
             <para>
-              This transformer also implements the <literal>org.apache.cocoon.pipeline.component.sax.SAXProducer</literal>
interface. This interface extends the
+              This transformer also implements the <literal>org.apache.cocoon.sax.component.SAXProducer</literal>
interface. This interface extends the
               <literal>org.apache.cocoon.pipeline.component.Producer</literal>
interface which means that the next component has to be a 
               <literal>org.apache.cocoon.pipeline.component.Consumer</literal>.
Like the previous <literal>StringGenerator</literal>, the <literal>XSLTTransformer</literal>
-              inherits from the <literal>org.apache.cocoon.pipeline.component.sax.AbstractXMLProducer</literal>
which contains the check that the next component
-              is of type <literal>org.apache.cocoon.pipeline.component.sax.SAXConsumer</literal>.

+              inherits from the <literal>org.apache.cocoon.sax.component.AbstractXMLProducer</literal>
which contains the check that the next component
+              is of type <literal>org.apache.cocoon.sax.component.SAXConsumer</literal>.

             </para>
          </callout>
          <callout arearefs="pipelines.definition.transformer2">
@@ -265,40 +265,390 @@
   
   <section id="pipeline.stax">
     <title>StAX components</title>
-    <para>explain StAX in general, advantages (ease of writing fast transformers),
links to external sources</para>
+    <para>StAX pipelines provide an alternative API for writing pipeline components.
Altough they are not as fast as SAX, they provide easier state handling as the component can
control when to pull the next events. This allows an implicit state rather than have to manage
the state in the various content handler methods of SAX.</para>
+    <para>The most visible difference of StAX components in contrast to SAX is that
the component itself has controls the parsing of the input whereas in SAX the parser controls
the pipeline by calling the component.
+    Our implementation of StAX pipelines uses just StAX interfaces for retrieving events
- the writing interface is proprietary in order to avoid multihreading or continuations.
+    So it is really a hybrid process - the StAX component is called to generate the next
events, but it is also allowed to read as much data from the previous pipeline component as
it wants. But as the produced events are kept in-memory until a later component pulls for
them, the components should not emit large amounts of events during one invocation.
+    </para>
 
     <section>
       <title>Available components</title>
-      <para>Link to Javadocs</para>
+      <para><itemizedlist>
+        <listitem><para><literal>StAXGenerator</literal> is a Starter
and normally parses a XML from an InputStream.</para></listitem>
+        <listitem><para><literal>StAXSerializer</literal> is a Finisher
and writes the StAX Events to an OutputStream.</para></listitem>
+        <listitem><para><literal>AbstractStAXTransformer</literal>
is the abstract base class for new transformers. It simplifies the task by providing a template
method for generating the new events.</para></listitem>
+        <listitem><para><literal>StAXCleaningTransformer</literal>
is an transformer, which cleans the document from whitespaces and comments.</para></listitem>
+        <listitem><para><literal>IncludeTransformer</literal> includes
the contents of another document.</para></listitem>
+      </itemizedlist></para>
+      <para>For further information refer to the <ulink url="http://cocoon.apache.org/3.0/apidocs/org/apache/cocoon/stax/package-summary.html">javadoc</ulink></para>
     </section>
     
     <section>
       <title>Writing custom components</title>
       <section>
         <title>StAX generator</title>
-        <para>explain from a user's point of view, what she needs to do to implement
one
-              (available abstract classes)
-        </para>
+	<para>The <literal>StAXGenerator</literal> is a <literal>Starter</literal>
component and produces XMLEvents.
+	<programlistingco>
+        <areaspec>
+          <area id="stax.generator.example.classdecl" coords="12"/>
+          <area id="stax.generator.example.ctor" coords="18"/>
+          <area id="stax.generator.example.execute" coords="27"/>
+          <area id="stax.generator.example.hasNext" coords="31"/>
+          <area id="stax.generator.example.nextEvent" coords="35"/>
+          <area id="stax.generator.example.peek" coords="39"/>
+        </areaspec>    
+	<programlisting language="java"><![CDATA[import java.io.InputStream;
+import java.net.URL;
+
+import javax.xml.stream.FactoryConfigurationError;
+import javax.xml.stream.XMLEventReader;
+import javax.xml.stream.XMLInputFactory;
+import javax.xml.stream.XMLStreamException;
+import javax.xml.stream.events.XMLEvent;
+
+import org.apache.cocoon.pipeline.SetupException;
+import org.apache.cocoon.pipeline.component.Starter;
+public class MyStAXGenerator extends AbstractStAXProducer implements Starter {
+
+   private XMLEventReader reader;
+    
+   public MyStAXGenerator(InputStream inputStream) {
+      try {
+         this.reader = XMLInputFactory.newInstance().createXMLEventReader(inputStream);
+      } catch (XMLStreamException e) {
+         throw new SetupException("Error during setup an XMLEventReader on the inputStream",
e);
+      } catch (FactoryConfigurationError e) {
+         throw new SetupException("Error during setup the XMLInputFactory for creating an
XMLEventReader", e);
+      }
+   }
+    
+   public void execute() {
+      this.getConsumer().initiatePullProcessing();
+   }
+
+   public boolean hasNext() {
+      return this.reader.hasNext();
+   }
+
+   public XMLEvent nextEvent() throws XMLStreamException {
+      return this.reader.nextEvent();
+   }
+    
+   public XMLEvent peek() throws XMLStreamException {
+      return this.reader.peek();
+   }
+	
+}]]>	</programlisting>
+	<calloutlist>
+         <callout arearefs="stax.generator.example.classdecl">
+            <para>
+	      In order to implement an own <literal>StAXGenerator</literal> the easiest
approach is to inherit from <literal>AbstractStAXProducer</literal>.
+            </para>
+         </callout>
+	<callout arearefs="stax.generator.example.ctor">
+            <para>
+	      The constructor creates a new XMLEventReader for reading from the inputstream.
+            </para>
+         </callout>
+	<callout arearefs="stax.generator.example.execute">
+            <para>
+	      The pipeline is started using the <literal>execute</literal> method. As
StAX is a pull based approach the last component has to start pulling.
+            </para>
+         </callout>
+	 <callout arearefs="stax.generator.example.hasNext">
+            <para>This method should return true if the generator has a next Event.
</para>
+         </callout>
+ 	 <callout arearefs="stax.generator.example.nextEvent">
+            <para>Returns the next event from the generator.</para>
+         </callout>
+ 	 <callout arearefs="stax.generator.example.peek">
+            <para>Returns the next event from the generator, without moving actually
to the next event.</para>
+         </callout>
+       </calloutlist>
+      </programlistingco>
+	</para>
       </section>
       <section>
         <title>StAX transformer</title>
-        <para>explain from a user's point of view, what she needs to do to implement
one</para>
-        <para>explain navigators by example</para>
+        <para>Implementing a StAX Transformer should be the most common use case. The
<literal>AbstractStAXTransformer</literal> provides a foundation for new transformers.
But in order to write new transformers even simpler, let's describe another feature first:</para>
+	
+	<section>
+	<title>Navigator</title>
+        <para>Navigators allow an easier navigation in the XML document. They also
simplify transformers, as usually transformers need only process some parts of the input document
and the navigator helps to identify the interesting parts. There are several implementations
already included:
+	<itemizedlist>
+	  <listitem><para><literal>FindStartElementNavigator</literal> finds
the start tag with certain properties(name,attribute)</para></listitem>
+	  <listitem><para><literal>FindEndElementNavigator</literal> finds
the end tag with certain properties(name,attribute)</para></listitem>
+	  <listitem><para><literal>FindCorrespondingStartEndElementPairNavigator</literal>
finds both the start and the corresponding end tag.</para></listitem>
+	  <listitem><para><literal>InSubtreeNavigator</literal> finds whole
subtrees, by specifying the properties of the "root" element.</para></listitem>
+	</itemizedlist>
+	For further information refer to the <ulink url="http://cocoon.apache.org/3.0/apidocs/org/apache/cocoon/stax/navigation/package-summary.html">navigator
javadoc</ulink>
+	</para>
+	<section>
+	  <title>Using navigators</title>
+	  <para>
+	  Using a navigator is a rather simple task. The transformer peeks or gets the next event
and calls <literal>Navigator.fulfillsCriteria</literal> - if true is returned
the transformer should be process that event somehow. 
+	  </para>
+	</section>
+	<section>
+	  <title>Implementing a navigator</title>
+	  <para>Creating a new navigator is a rather simple task and just means implementing
two methods:</para>
+	  <programlistingco>
+	  <areaspec>
+	    <area id="stax.navigator.example.fulfillsCriteria" coords="4"/>
+	    <area id="stax.navigator.example.isActive" coords="8"/>
+	  </areaspec>    
+	  <programlisting language="java"><![CDATA[import javax.xml.stream.events.XMLEvent;
+
+public class MyNavigator implements Navigator {
+   public boolean fulfillsCriteria(XMLEvent event) {
+      return false;
+   }
+    
+   public boolean isActive() {
+      return false;
+   }
+}
+]]>	</programlisting>
+	<calloutlist>
+         <callout arearefs="stax.navigator.example.fulfillsCriteria">
+            <para>
+	      This method returns true if the event matches the criteria of the navigator.
+            </para>
+         </callout>
+	<callout arearefs="stax.navigator.example.isActive">
+            <para>
+	      Returns the result of the last invocation of fulfillsCriteria.
+	    </para>
+         </callout>
+       </calloutlist>
+      </programlistingco>
+	</section>
+	</section>
+
+	<section>
+	  <title>Implementing a transformer</title>
+	  <para>The next example should show you an transformer featuring navigators and implicit
state handling through function calls.</para>
+	  <programlistingco>
+	      <areaspec>
+		<area id="stax.transformer.example.navigatorFulfillsCriteria" coords="6"/>
+		<area id="stax.transformer.example.collectLinkInfoInvocation" coords="8"/>
+		<area id="stax.transformer.example.rewriteAndEmit" coords="10"/>
+		<area id="stax.transformer.example.flushAdditionalEvents" coords="13"/>
+		<area id="stax.transformer.example.collectLinkInfoInvocationNavigator" coords="26"/>
+		<area id="stax.transformer.example.collectLinkInfoInvocationPeek" coords="31"/>
+	      </areaspec>    
+	      <programlisting language="java"><![CDATA[public class DaisyLinkRewriteTransformer
extends AbstractStAXTransformer {
+  @Override
+   protected void produceEvents() throws XMLStreamException {
+      while (this.getParent().hasNext()) {
+         XMLEvent event = this.getParent().nextEvent();
+         if (this.anchorNavigator.fulfillsCriteria(event)) {
+            ArrayList<XMLEvent> innerContent = new ArrayList<XMLEvent>();
+            LinkInfo linkInfo = this.collectLinkInfo(innerContent);
+            if(linkInfo != null) {
+               linkInfo.setNavigationPath(this.getAttributeValue(event.asStartElement(),

+                  PUBLISHER_NS,"navigationPath"));
+
+               this.rewriteAttributesAndEmitEvent(event.asStartElement(),linkInfo);
+
+               if(innerContent.size() != 0) {
+                  this.addAllEventsToQueue(innerContent);
+               }
+            } 
+            /* ... */
+         } 
+         /* ... */
+      }
+   }
+
+   private LinkInfo collectLinkInfo(List<XMLEvent> events) throws XMLStreamException
{
+      Navigator linkInfoNavigator = new InSubtreeNavigator(LINK_INFO_EL);
+      Navigator linkInfoPartNavigator = new FindStartElementNavigator(LINK_PART_INFO_EL);
+      LinkInfo linkInfo = null;
+
+      while (this.getParent().hasNext()) {
+         XMLEvent event = this.getParent().peek();
+
+         if (linkInfoNavigator.fulfillsCriteria(event)) {
+            event = this.getParent().nextEvent();
+            if (linkInfoPartNavigator.fulfillsCriteria(event)) {
+               /* ... */
+               String fileName = this.getAttributeValue(event.asStartElement(),"fileName");
+               if (!"".equals(fileName)) {
+                  linkInfo.setFileName(fileName);
+               }
+            } /* ... */
+         } else if (event.isCharacters()) {
+            events.add(this.getParent().nextEvent());
+         } else {
+            return linkInfo;
+         }
+      }
+      return linkInfo;
+   }
+
+   private void rewriteAttributesAndEmitEvent(StartElement event, LinkInfo linkInfo) ;
+
+}]]></programlisting>
+	    <calloutlist>
+	    <callout arearefs="stax.transformer.example.navigatorFulfillsCriteria">
+		<para>The transformer checks for anchors in the XML.</para>
+	    </callout>
+	    <callout arearefs="stax.transformer.example.collectLinkInfoInvocation">
+		<para>If an anchor is found, it invokes a method which parses the link info if there
is any. The additional array is for returning any events, which were read but do not belong
to the linkinfo.</para>
+	    </callout>
+	    <callout arearefs="stax.transformer.example.rewriteAndEmit">
+		<para>This method finally writes the start tag with the correct attributes taken
from the parsed LinkInfo.</para>
+	    </callout>
+	    <callout arearefs="stax.transformer.example.flushAdditionalEvents">
+		<para>The events, which were read but not parsed, are finally added to the output
of the transformer.</para>
+	    </callout>
+	    <callout arearefs="stax.transformer.example.collectLinkInfoInvocationNavigator">
+		<para>The parser for the linkInfo object uses itself also navigators ...</para>
+	    </callout>
+	    <callout arearefs="stax.transformer.example.collectLinkInfoInvocationPeek">
+		<para>... and reads more events from the parent.</para>
+	    </callout>
+	  </calloutlist>
+	  </programlistingco>
+      
+	</section>
       </section>
       <section>
         <title>StAX serializer</title>
-        <para>explain from a user's point of view, what she needs to do to implement
one</para>
+        <para>The <literal>StAXSerializer</literal> pulls and serializes
the StAX events from the pipeline.</para>
+		  <programlistingco>
+	  <areaspec>
+	    <area id="stax.serializer.example.parent" coords="4"/>
+	    <area id="stax.serializer.example.initiatePull" coords="6"/>
+	    <area id="stax.serializer.example.nextEvent" coords="9"/>
+	    <area id="stax.serializer.example.setParent" coords="17"/>
+	    <area id="stax.serializer.example.getContentType" coords="21"/>
+	  </areaspec>    
+	  <programlisting language="java"><![CDATA[public class NullSerializer extends
AbstractStAXPipelineComponent 
+   implements StAXConsumer, Finisher {
+   
+   private StAXProducer parent;
+
+   public void initiatePullProcessing() {
+      try {
+         while (this.parent.hasNext()) {
+            XMLEvent event = this.parent.nextEvent();
+            /* serialize Event */
+         }
+      } catch (XMLStreamException e) {
+         throw new ProcessingException("Error during writing output elements.", e);
+      }
+   }
+
+   public void setParent(StAXProducer parent) {
+      this.parent = parent;
+   }
+
+   public String getContentType()  ;
+   public void setOutputStream(OutputStream outputStream) ;
+}]]></programlisting>
+	<calloutlist>
+        <callout arearefs="stax.serializer.example.parent">
+            <para>The Finisher has to pull from the previous pipeline component..</para>
+         </callout>
+         <callout arearefs="stax.serializer.example.initiatePull">
+            <para>In case of StAX the last pipeline component has to start pulling
for Events.</para>
+         </callout>
+         <callout arearefs="stax.serializer.example.nextEvent">
+            <para>The serializer pulls the next Event from the previous component and
should as next step serialize it.</para>
+         </callout>
+         <callout arearefs="stax.serializer.example.setParent">
+            <para>During the pipeline construction the setParent is called to set the
previous component of the pipeline.</para>
+         </callout>
+         <callout arearefs="stax.serializer.example.getContentType">
+            <para>These two methods are defined in the Finisher and allow to set the
OutputStream (if the Serializer needs any) and to retrieve the content-type of the result..</para>
+         </callout>
+
+       </calloutlist>
+      </programlistingco>
       </section>
     </section>
     
     <section>
       <title>Using StAX and SAX components in the same pipeline</title>
-      <para></para>
+      <para>The StAX pipeline offers interoperability to SAX components to a certain
degree. However due their different paradigms only two use cases are currently implemented:
Wrapping a SAX component in a StAX pipeline and a StAX-to-SAX pipeline, which starts with
StAX components and finishes with SAX.</para>
+        <section>
+	<title>Wrapping a SAX component in a StAX pipeline</title>
+	  <para>This allows to use existing SAX components in a StAX pipeline. Beware the
overhead of the conversion of StAX->SAX->StAX - so no performance gains from a SAX component
can be expected.</para>
+	  <programlistingco>
+	    <areaspec>
+	      <area id="stax.converter.sax-in-stax.generator" coords="2"/>
+	      <area id="stax.converter.sax-in-stax.wrapper" coords="3"/>
+	      <area id="stax.converter.sax-in-stax.serializer" coords="4"/>
+	    </areaspec>    
+	    <programlisting language="java">
+<![CDATA[Pipeline<StAXPipelineComponent> pipeStAX = new NonCachingPipeline<StAXPipelineComponent>();
+pipeStAX.addComponent(new StAXGenerator(input));
+pipeStAX.addComponent(new SAXForStAXPipelineWrapper(new CleaningTransformer()));
+pipeStAX.addComponent(new StAXSerializer());
+pipeStAX.setup(System.out);
+pipeStAX.execute();]]></programlisting>
+	  <calloutlist>
+	    <callout arearefs="stax.converter.sax-in-stax.generator">
+	      <para>The pipeline uses a <literal>StAXGenerator</literal> - which
produces StAX events.</para>
+	    </callout>
+	    <callout arearefs="stax.converter.sax-in-stax.wrapper">
+	      <para>In order to embed a single SAX component in a StAX pipeline, the <literal>SAXForStAXPipelineWrapper</literal>
is needed. The constructor argument is the SAX component.</para>
+	    </callout>
+	    <callout arearefs="stax.converter.sax-in-stax.serializer">
+	      <para>Altough the <literal>CleaningTransformer</literal> would emit
SAX calls - the wrapper converts them back to the appropriate StAX events the <literal>StAXSerializer</literal>
can write..</para>
+	    </callout>
+	  </calloutlist>
+	</programlistingco>
+	</section>
+        <section>
+	<title>StAX-to-SAX pipeline</title>
+	  <para>This converter allows to mix StAX and SAX components - but is limited to starting
with StAX and then switching to SAX. </para>
+	  <programlistingco>
+	    <areaspec>
+	      <area id="stax.converter.stax-to-sax.generator" coords="2"/>
+	      <area id="stax.converter.stax-to-sax.adapter" coords="3"/>
+	      <area id="stax.converter.stax-to-sax.transformer" coords="4"/>
+	      <area id="stax.converter.stax-to-sax.serializer" coords="5"/>
+	    </areaspec>    
+	    <programlisting language="java"><![CDATA[Pipeline<PipelineComponent>
pipeStAX = new NonCachingPipeline<StAXPipelineComponent>();
+pipeStAX.addComponent(new StAXGenerator(input));
+pipeStAX.addComponent(new StAXToSAXPipelineAdapter());
+pipeStAX.addComponent(new CleaningTransformer());
+pipeStAX.addComponent(new XMLSerializer());
+pipeStAX.setup(System.out);
+pipeStAX.execute();]]></programlisting>
+	  <calloutlist>
+	    <callout arearefs="stax.converter.stax-to-sax.generator">
+	      <para>The pipeline starts with a <literal>StAXGenerator</literal>.</para>
+	    </callout>
+	    <callout arearefs="stax.converter.stax-to-sax.adapter">
+	      <para>The adapter converts the StAX events to SAX method calls.</para>
+	    </callout>
+	    <callout arearefs="stax.converter.stax-to-sax.transformer">
+	      <para>The <literal>CleaningTransformer</literal> is a SAX component.</para>
+	    </callout>
+	    <callout arearefs="stax.converter.stax-to-sax.serializer">
+	      <para>The <literal>XMLSerializer</literal> writes the SAX method
calls to a file.</para>
+	    </callout>
+	  </calloutlist>
+	</programlistingco>
+	</section>
     </section>
-    
+
+
     <section>
       <title>Java 1.5 support</title>
-      <para>What do you have to do to use StAX components, in a Java 1.5 environment</para>
+      <para>In order to use StAX with Java 1.5 an additional dependency is needed in
the project's <literal>pom.xml</literal>. 
+      <programlisting language="xml"><![CDATA[<dependency>
+  <groupId>org.codehaus.woodstox</groupId>
+  <artifactId>wstx-asl</artifactId>
+  <version>3.2.7</version>
+</dependency>]]>
+</programlisting>
+      Using woodstox is simpler, as the reference implementation depends on JAXP 1.4, which
is not part of Java 1.5.
+      </para>
     </section>
   </section>
 



Mime
View raw message