XmlSchema/src/site/xdoc/schematutorial.xml - webservices-commons-xmlschema - Git at Google

 <xdoc>
   <properties>
     <title>:: Apache XmlSchema Tutorial ::</title>
   </properties>
 <body>
 <section name="Contents">
 <ul>
   <li><a href="#intro">Introduction</a></li>
   <li><a href="#dependencies">Structure and Dependencies</a></li>
   <li><a href="#reading">Reading a Schema</a></li>
   <li><a href="#navigating">Navigating the Schema Model</a></li>
   <li><a href="#printing">Printing the Schema Model</a></li>
   <li><a href="#conclusion">Conclusion</a></li>
 </ul>
 </section>

 <a name="intro"></a>
 <section name="Introduction">

 <p>Commons XML Schema model is a general purpose schema model that can be
 used when a Java object tree representation of an Xml schema is required.
 This short tutorial explains how the Commons XML Schema can be utilized.</p>
 <a name="dependencies"></a>
 </section>
 <section name="Structure and Dependencies">

 <p>The core commons XML Schema classes have <strong>no</strong> third party
 dependencies. However it depends on the XMLUnit and JUnit libraries for unit
 testing, and the maven build uses the StAX API libraries to access the
 javax.xml.namespace.QName class (which is not part of the JDK). Also the
 serialization mechanism uses the DOM serialization mechanism, hence the JDK
 has to be 1.4 and upwards.</p>

 <p>The structure of the commons XMLSchema model is quite straightforward. It
 has a strict specification bound hierarchy of classes that represents each
 and every schema component. It is not based on an interface-implementation
 model which allows extensions and different implementations. However, the
 schema specification is quite stable and complete, hence a change is
 unlikelyl, which makes the commons XmlSchema sufficient for almost all needs
 of schema handling.</p>
 </section>

 <section name="Reading a Schema">
 <a name="reading"></a>
 <p>The reader for the XML Schema model is called the SchemaCollection
 (org.apache.ws.commons.schema.XmlSchemaCollection). It has a
 <em>read</em> method that returns a XmlSchema object which represents the
 whole schema. The XmlSchema instance returned can be used to access types and
 elements of the relevant schema by their qualified name.</p>

 <p>The <em>read</em> method has a parameter to pass in a validating event
 handler. The validating event handler can be used to pass in the custom
 validating procedures. However, this particular handler has no effect on the
 reading of the schema yet, and it is not a feature in this release of Commons
 XML Schema. The following code fragment shows how a file can be read through
 the SchemaCollection.</p>
 <source><pre>
 InputStream is = new FileInputStream(fileName);
 XmlSchemaCollection schemaCol = new XmlSchemaCollection();
 XmlSchema schema = schemaCol.read(new StreamSource(is), null);</pre></source>

 <p>Note that null is passed for the validating handler since it has no effect
 yet.</p>
 </section>

 <a name="navigating"></a>

 <section name="Navigating the Schema Model">

 <p>Navigation of the model once the XmlSchema model is obtained is also quite
 straight forward. All top level elements and types are available through the
 schema object as either
 <code>org.apache.ws.commons.schema.XmlSchemaObjectTable</code> instances or
 can be accessed directly if it can have a QName reference. For example, if
 the qualified name of an element is known, then getElementByName method can
 be used to extract the XmlSchemaElement object directly from the schema
 object. The following code sample shows how such direct methods can be used
 to extract schema objects</p>
 <source><pre>XmlSchemaType schemaType = schema.getTypeByName(TYPE_QNAME);
 XmlSchemaElement elem = schema.getElementByName(ELEMENT_QNAME);</pre></source>

 <p>Note that the TYPE_QNAME and ELEMENT_QNAME represents QName objects.</p>
 <a name="printing"></a>
 <h2>Printing the Schema Model</h2>

 <p>Printing of the model once the XmlSchema model has been modified or
 constructed in-memory, is also quite straightforward. Schema object has a
 <em>write</em> method that can use an output stream.</p>

 <p>The following code fragment shows how to write the schema into the System
 output stream.</p>
 <source><pre>schema.write(System.out);</pre></source>
 </section>

 <!--<h2>Advanced Topics</h2>-->
 <a name="conclusion"></a>
 <section name="Conclusion">
 <p>Commons XmlSchema is quite a versatile piece of code that can be used to
 manipulate and generate XML Schemas. It has minimum dependencies and can be
 used inside another project with ease.</p>
 </section>
 </body>
 </xdoc>
	<xdoc>
	<properties>
	<title>:: Apache XmlSchema Tutorial ::</title>
	</properties>
	<body>
	<section name="Contents">
	<ul>
	<li><a href="#intro">Introduction</a></li>
	<li><a href="#dependencies">Structure and Dependencies</a></li>
	<li><a href="#reading">Reading a Schema</a></li>
	<li><a href="#navigating">Navigating the Schema Model</a></li>
	<li><a href="#printing">Printing the Schema Model</a></li>
	<li><a href="#conclusion">Conclusion</a></li>
	</ul>
	</section>

	<a name="intro"></a>
	<section name="Introduction">

	<p>Commons XML Schema model is a general purpose schema model that can be
	used when a Java object tree representation of an Xml schema is required.
	This short tutorial explains how the Commons XML Schema can be utilized.</p>
	<a name="dependencies"></a>
	</section>
	<section name="Structure and Dependencies">

	<p>The core commons XML Schema classes have <strong>no</strong> third party
	dependencies. However it depends on the XMLUnit and JUnit libraries for unit
	testing, and the maven build uses the StAX API libraries to access the
	javax.xml.namespace.QName class (which is not part of the JDK). Also the
	serialization mechanism uses the DOM serialization mechanism, hence the JDK
	has to be 1.4 and upwards.</p>

	<p>The structure of the commons XMLSchema model is quite straightforward. It
	has a strict specification bound hierarchy of classes that represents each
	and every schema component. It is not based on an interface-implementation
	model which allows extensions and different implementations. However, the
	schema specification is quite stable and complete, hence a change is
	unlikelyl, which makes the commons XmlSchema sufficient for almost all needs
	of schema handling.</p>
	</section>

	<section name="Reading a Schema">
	<a name="reading"></a>
	<p>The reader for the XML Schema model is called the SchemaCollection
	(org.apache.ws.commons.schema.XmlSchemaCollection). It has a
	<em>read</em> method that returns a XmlSchema object which represents the
	whole schema. The XmlSchema instance returned can be used to access types and
	elements of the relevant schema by their qualified name.</p>

	<p>The <em>read</em> method has a parameter to pass in a validating event
	handler. The validating event handler can be used to pass in the custom
	validating procedures. However, this particular handler has no effect on the
	reading of the schema yet, and it is not a feature in this release of Commons
	XML Schema. The following code fragment shows how a file can be read through
	the SchemaCollection.</p>
	<source><pre>
	InputStream is = new FileInputStream(fileName);
	XmlSchemaCollection schemaCol = new XmlSchemaCollection();
	XmlSchema schema = schemaCol.read(new StreamSource(is), null);</pre></source>

	<p>Note that null is passed for the validating handler since it has no effect
	yet.</p>
	</section>

	<a name="navigating"></a>

	<section name="Navigating the Schema Model">

	<p>Navigation of the model once the XmlSchema model is obtained is also quite
	straight forward. All top level elements and types are available through the
	schema object as either
	<code>org.apache.ws.commons.schema.XmlSchemaObjectTable</code> instances or
	can be accessed directly if it can have a QName reference. For example, if
	the qualified name of an element is known, then getElementByName method can
	be used to extract the XmlSchemaElement object directly from the schema
	object. The following code sample shows how such direct methods can be used
	to extract schema objects</p>
	<source><pre>XmlSchemaType schemaType = schema.getTypeByName(TYPE_QNAME);
	XmlSchemaElement elem = schema.getElementByName(ELEMENT_QNAME);</pre></source>

	<p>Note that the TYPE_QNAME and ELEMENT_QNAME represents QName objects.</p>
	<a name="printing"></a>
	<h2>Printing the Schema Model</h2>

	<p>Printing of the model once the XmlSchema model has been modified or
	constructed in-memory, is also quite straightforward. Schema object has a
	<em>write</em> method that can use an output stream.</p>

	<p>The following code fragment shows how to write the schema into the System
	output stream.</p>
	<source><pre>schema.write(System.out);</pre></source>
	</section>

	<!--<h2>Advanced Topics</h2>-->
	<a name="conclusion"></a>
	<section name="Conclusion">
	<p>Commons XmlSchema is quite a versatile piece of code that can be used to
	manipulate and generate XML Schemas. It has minimum dependencies and can be
	used inside another project with ease.</p>
	</section>
	</body>
	</xdoc>