<?xml version="1.0"?>

<document>

 <properties>
  <title>Overview</title>
  <author email="dev@commons.apache.org">Commons Documentation Team</author>
 </properties>

 <body>

<section name="The XMLIO Component">

<p>XMLIO is a low level library to assist you in the straight forward process of importing and exporting XML from and to your Java applications. 
All of this has been designed having performance and simplicity in
mind. No magic is involved. Additionally, it is very lightweight and has exactly no
dependencies on any other libraries.</p>

<p>XMLIO consists of three parts:</p>

<subsection name="Structured reading of XML">

<p>XMLIO's main part - <a
href="apidocs/org/apache/commons/xmlio/in/SimpleImporter.html">SimpleImporter</a>
- is a simple and fast importer for XML.</p> 
<p>It is based on SAX and can be considered an extension to it. This
means it is callback oriented and does not build an internal data
structure like the DOM. No data access objects (DAO) will be created
either. This means it is <b>no XML->Java Object
Mapper</b>, but rahter a XML->Generic Mehtod Mapper (if there was
anything like this). You could easily use the simply importer without a single dynamic
construction of a class. </p>
<p>Comparing it to <a href="http://commons.apache.org/digester/">Commons Digester</a> the simple importer is much more
low level and much more simplistic. Beside <a
href="apidocs/org/apache/commons/xmlio/in/SimpleImporter.html">SimpleImporter</a>
you will only need to know the <a
href="apidocs/org/apache/commons/xmlio/in/SimpleImportHandler.html">call
back interface </a>. </p>

<p>While preserving all benefits of SAX - among them performance,
simplicity and general usability - the simple importer adds more high
level means to SAX's rudimentary features. These are the main
extensions:
<ol>
<li><em>Every callback includes a full path to the XML element</em>: In many 
cases this will make maintaining local stacks for keeping track of element
histories obsolete.</li>
<li><em>Leading character data can be included into start element callback</em>: 
In many cases import files do not or only rarely contain mixed content. If so
it is convenient to have the full content of an element at hand with a 
single callback.</li>
<li><em>More than one listener can be registered</em>: Some XML files contain
different types/aspects of data that may be interesting to different listeners. E.g.
data to import from a server may contain error messages along with the real
content data. It may be convenient to
processes these blocks of data separately. Another example is a debug or
log listener.</li>
</ol></p>
</subsection>

<subsection name="Writing data to formatted XML">

<p>You can write your data into a <a
href="apidocs/org/apache/commons/xmlio/out/XMLWriter.html">formatted
XML writer</a>. Formatting and encoding is done as straight forward as possible. Everything you know 
better than this class must be done by you. In effect, no unexpected
so called intelligent behavior or magic is to be feared. Another effect is high
speed and simplicity.</p>    

</subsection>

<subsection name="XML encoding and decoding helpers on the character (not the byte) level">

<p><a href="apidocs/org/apache/commons/xmlio/out/XMLEncode.html">Set
of methods</a> to encode and decode characters special to XML like 
<![CDATA[(& and < and " and ')]]>.</p> 

</subsection>

</section>

<section name="Releases">
    <p>
       See the <a href="downloads.html">downloads</a> page for information on obtaining releases.
    </p>
</section>

<section name="Documentation">
  <p>
     The <a href="apidocs/index.html">JavaDoc API documents</a> are available online.
  </p>
</section>

<section name="Class diagrams">
  <p>
     For an easy overview there is a class diagram for the <a href="xmlio-in.pdf">input part</a> and one for the <a href="xmlio-out.pdf">output part</a> in PDF format.
  </p>
</section>

</body>
</document>
