You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commons-dev@ws.apache.org by aj...@apache.org on 2007/04/06 21:08:19 UTC
svn commit: r526252 - in
/webservices/commons/trunk/modules/XmlSchema/src/site: apt/index.apt
site.xml xdoc/schematutorial.xml xdoc/writingExtensions.xml
Author: ajith
Date: Fri Apr 6 12:08:18 2007
New Revision: 526252
URL: http://svn.apache.org/viewvc?view=rev&rev=526252
Log:
1. Adding the documentation for extensions
Added:
webservices/commons/trunk/modules/XmlSchema/src/site/xdoc/writingExtensions.xml
Modified:
webservices/commons/trunk/modules/XmlSchema/src/site/apt/index.apt
webservices/commons/trunk/modules/XmlSchema/src/site/site.xml
webservices/commons/trunk/modules/XmlSchema/src/site/xdoc/schematutorial.xml
Modified: webservices/commons/trunk/modules/XmlSchema/src/site/apt/index.apt
URL: http://svn.apache.org/viewvc/webservices/commons/trunk/modules/XmlSchema/src/site/apt/index.apt?view=diff&rev=526252&r1=526251&r2=526252
==============================================================================
--- webservices/commons/trunk/modules/XmlSchema/src/site/apt/index.apt (original)
+++ webservices/commons/trunk/modules/XmlSchema/src/site/apt/index.apt Fri Apr 6 12:08:18 2007
@@ -15,7 +15,7 @@
Downloads
- The latest release is 1.2 and can be found
+ The latest release is 1.3 and can be found
{{{http://ws.apache.org/commons/XmlSchema/download.cgi}here}}.
Modified: webservices/commons/trunk/modules/XmlSchema/src/site/site.xml
URL: http://svn.apache.org/viewvc/webservices/commons/trunk/modules/XmlSchema/src/site/site.xml?view=diff&rev=526252&r1=526251&r2=526252
==============================================================================
--- webservices/commons/trunk/modules/XmlSchema/src/site/site.xml (original)
+++ webservices/commons/trunk/modules/XmlSchema/src/site/site.xml Fri Apr 6 12:08:18 2007
@@ -20,6 +20,7 @@
</item>
<item name="Documentation">
<item name="Tutorial" href="schematutorial.html"/>
+ <item name="Extensions" href="writingExtensions.html"/>
<item name="Javadocs" href="/apidocs/index.html"/>
<item name="View Source"
href="http://svn.apache.org/viewvc/webservices/commons/trunk/modules/XmlSchema/?root=Apache-SVN"/>
Modified: webservices/commons/trunk/modules/XmlSchema/src/site/xdoc/schematutorial.xml
URL: http://svn.apache.org/viewvc/webservices/commons/trunk/modules/XmlSchema/src/site/xdoc/schematutorial.xml?view=diff&rev=526252&r1=526251&r2=526252
==============================================================================
--- webservices/commons/trunk/modules/XmlSchema/src/site/xdoc/schematutorial.xml (original)
+++ webservices/commons/trunk/modules/XmlSchema/src/site/xdoc/schematutorial.xml Fri Apr 6 12:08:18 2007
@@ -1,6 +1,6 @@
-<xdoc>
- <properties>
- <title>XML Schema Tutorial</title>
+<xdoc>
+ <properties>
+ <title>:: Apache XmlSchema Tutorial ::</title>
</properties>
<body>
<section name="Contents">
@@ -11,8 +11,8 @@
<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>
+</ul>
+</section>
<a name="intro"></a>
<section name="Introduction">
@@ -20,8 +20,8 @@
<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>
+<a name="dependencies"></a>
+</section>
<section name="Structure and Dependencies">
<p>The core commons XML Schema classes have <strong>no</strong> third party
@@ -38,8 +38,8 @@
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>
+
<section name="Reading a Schema">
<a name="reading"></a>
<p>The reader for the XML Schema model is called the SchemaCollection
@@ -60,10 +60,10 @@
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>
+yet.</p>
+</section>
-<a name="navigating"></a>
+<a name="navigating"></a>
<section name="Navigating the Schema Model">
@@ -89,15 +89,15 @@
<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>
+<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>
+used inside another project with ease.</p>
</section>
-</body>
+</body>
</xdoc>
Added: webservices/commons/trunk/modules/XmlSchema/src/site/xdoc/writingExtensions.xml
URL: http://svn.apache.org/viewvc/webservices/commons/trunk/modules/XmlSchema/src/site/xdoc/writingExtensions.xml?view=auto&rev=526252
==============================================================================
--- webservices/commons/trunk/modules/XmlSchema/src/site/xdoc/writingExtensions.xml (added)
+++ webservices/commons/trunk/modules/XmlSchema/src/site/xdoc/writingExtensions.xml Fri Apr 6 12:08:18 2007
@@ -0,0 +1,262 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<document>
+ <properties>
+ <title>:: Apache XmlSchema Extension Tutorial ::</title>
+ </properties>
+
+ <head>
+ <meta http-equiv="content-type" content="text/html; charset=iso-8859-1"/>
+ <meta content="text/html; charset=iso-8859-1"/>
+ </head>
+
+ <body>
+ <section name="Contents">
+ <ul>
+ <li><a href="#intro">Introduction</a></li>
+ <li><a href="#example">Example Extension</a></li>
+ <li><a href="#iclasses">Important classes</a></li>
+ <li><a href="#deser">Code for a Deserializer</a></li>
+ <li><a href="#ser">Code for a Serializer</a></li>
+ <li><a href="#reg">Registering types and using a custom extension registry</a></li>
+ <!--<li><a href="#default">Default Behavior</a></li>-->
+ <li><a href="#conclusion">Conclusion</a></li>
+ </ul>
+ </section>
+
+
+ <a name="intro"></a>
+ <section name="Introduction">
+ <p>Usually when parsing a schema document, developers will prefer to make custom
+ objects for attribute and element extensions. XMLSchema supports this through
+ an extension registry mechanism. This document explains how this extension mechanism works by going through
+ two complete examples. These two examples are included as test cases with the source release.</p>
+ </section>
+
+
+ <a name="example"></a>
+ <section name="Example Extension">
+ <p>Following are two example schema documents that contain external attributes/elements</p>
+ <p>This schema demonstrates the use of an extension attribute
+ <pre>
+ <schema
+ xmlns="http://www.w3.org/2001/XMLSchema"
+ xmlns:xsd="http://www.w3.org/2001/XMLSchema"
+ xmlns:tns="http://soapinterop.org/types"
+ xmlns:ext="http://customattrib.org"
+ targetNamespace="http://soapinterop.org/types">
+
+ <complexType name="Struct" ext:customAttrib="toplevel:type">
+ <sequence>
+ <element name="varString" type="xsd:string" ext:customAttrib="inner:element"/>
+ <element name="varInt" type="xsd:int" ext:customAttrib="inner:element"/>
+ <element name="varFloat" type="xsd:float" ext:customAttrib="inner:element"/>
+ <element name="varStruct" type="tns:Struct" ext:customAttrib="inner:element"/>
+ </sequence>
+ </complexType>
+
+ <element name="attrTest" type="tns:Struct" ext:customAttrib="toplevel:element"/>
+
+ </schema>
+
+ </pre>
+ </p>
+
+ <p>This schema demonstrates the use of an extension element
+ <pre>
+ <schema
+ xmlns="http://www.w3.org/2001/XMLSchema"
+ xmlns:xsd="http://www.w3.org/2001/XMLSchema"
+ xmlns:tns="http://soapinterop.org/types"
+ xmlns:ext="http://customattrib.org"
+ targetNamespace="http://soapinterop.org/types">
+
+ <complexType name="Struct">
+ <ext:customElt prefix="ext" suffix="type"/>
+ <sequence>
+ <element name="varString" type="xsd:string"/>
+ <element name="varInt" type="xsd:int" />
+ <element name="varFloat" type="xsd:float" />
+ <element name="varStruct" type="tns:Struct" />
+ </sequence>
+ </complexType>
+
+ <element name="attrTest" type="tns:Struct" >
+ <ext:customElt prefix="ext" suffix="elt"/>
+ </element>
+
+ </schema>
+ </pre>
+ </p>
+
+ <p>A developer would like the parser to make custom objects when it encounters customAttrib
+ or customElt. This can be achieved by writing a custom extension deserializer and serializer and
+ registering them with the extension registry. The next section briefly explains the important classes
+ involved in this process.</p>
+ </section>
+
+ <a name="iclasses"></a>
+ <section name="Important classes">
+ <p>Following are the important classes in writing an extension</p>
+ <ul>
+ <li><code>org.apache.ws.commons.schema.extensions.ExtensionRegistry</code></li>
+ <li><code>org.apache.ws.commons.schema.extensions.ExtensionDeserializer</code></li>
+ <li><code>org.apache.ws.commons.schema.extensions.ExtensionSerializer</code></li>
+ </ul>
+ <p>Last two classes are interfaces that should be implemented by the respective
+ implementations.</p>
+
+ </section>
+
+ <a name="deser"></a>
+ <section name="Code for a Deserializer">
+ <p>The deserializer needs to implement the
+ <code>org.apache.ws.commons.schema.extensions.ExtensionDeserializer</code> interface.
+ Following is a code fragment of the Extension deserializer that deserializes the extension
+ attribute into a custom object. Note that once the custom object is made it is attached
+ to the meta info map of the relevant XMLSchema object with the QName as the key</p>
+
+ <p>
+ <pre>
+ <code>
+ public void deserialize(XmlSchemaObject schemaObject, QName name, Node domNode) {
+ if (CustomAttribute.CUSTOM_ATTRIBUTE_QNAME.equals(name)){
+ Attr attrib = (Attr)domNode;
+ String value = attrib.getValue();
+ //break the attrib into
+ CustomAttribute customAttrib = new CustomAttribute();
+ String[] strings = value.split(":");
+ customAttrib.setPrefix(strings[0]);
+ customAttrib.setSuffix(strings[1]);
+
+ //put this in the schema object meta info map
+ schemaObject.addMetaInfo(CustomAttribute.CUSTOM_ATTRIBUTE_QNAME,customAttrib);
+ }
+ }
+ </code>
+ </pre>
+ </p>
+ <p>Note that prior knowledge is required about the format of the string of the attribute value.
+ The complete custom attribute deserializer is available in
+ <code>tests.customext.attrib.CustomAttributeDeserializer</code></p>
+
+ <p> Following is a code fragment of the Extension deserializer that deserializes the extension
+ element into a custom object. This is similar to the attribute case but now the node
+ passed is the actual extension element itself.</p>
+
+ <p>
+ <pre>
+ <code>
+ public void deserialize(XmlSchemaObject schemaObject, QName name, Node domNode) {
+ if (CustomElement.CUSTOM_ELT_QNAME.equals(name)){
+ Element elt = (Element)domNode;
+
+ CustomElement customElement = new CustomElement();
+ customElement.setPrefix(elt.getAttribute("prefix"));
+ customElement.setSuffix(elt.getAttribute("suffix"));
+
+ //put this in the schema object meta info map
+ schemaObject.addMetaInfo(CustomElement.CUSTOM_ELT_QNAME,customElement);
+ }
+ }
+ </code>
+ </pre>
+ </p>
+ <p>The complete custom attribute deserializer is available in
+ <code>tests.customext.elt.CustomElementDeserializer</code></p>
+ </section>
+
+ <a name="ser"></a>
+ <section name="Code for a Serializer">
+ <p>The serializer needs to implement the
+ <code>org.apache.ws.commons.schema.extensions.ExtensionSerializer</code> interface.
+ Following is a code fragment of the Extension serializer that serializes a given custom
+ object into an attributeObject. Note that XMLSchema serialization mechanism is to create
+ a DOM tree and serialize it. Hence the custom serializers needs to create the
+ appropriate DOM node and attach it.</p>
+
+ <p>
+ <pre>
+ <code>
+ public void serialize(XmlSchemaObject schemaObject, Class classOfType, Node domNode) {
+ Map metaInfoMap = schemaObject.getMetaInfoMap();
+ CustomAttribute att = (CustomAttribute)metaInfoMap.get(CustomAttribute.CUSTOM_ATTRIBUTE_QNAME);
+
+ Element elt = (Element)domNode;
+ Attr att1 = elt.getOwnerDocument().createAttributeNS(CustomAttribute.CUSTOM_ATTRIBUTE_QNAME.getNamespaceURI(),
+ CustomAttribute.CUSTOM_ATTRIBUTE_QNAME.getLocalPart());
+ att1.setValue(att.getPrefix() + ":" + att.getSuffix());
+ elt.setAttributeNodeNS(att1);
+ }
+ </code>
+ </pre>
+ </p>
+ <p>Note that prior knowledge is required about the format of the string of the attribute value. DomNode
+ passed in would be the parent node of the serialized DOM tree.The complete custom attribute serializer is available in
+ <code>tests.customext.attrib.CustomAttributeSerializer</code></p>
+
+ <p> Following is a code fragment of the Extension serializer that serializes the custom object into
+ an extension element. This is similar to the attribute case.</p>
+
+ <p>
+ <pre>
+ <code>
+ public void serialize(XmlSchemaObject schemaObject, Class classOfType, Node domNode) {
+ Map metaInfoMap = schemaObject.getMetaInfoMap();
+ CustomElement customElt = (CustomElement)metaInfoMap.get(CustomElement.CUSTOM_ELT_QNAME);
+
+ Element elt = (Element)domNode;
+ Element extElt = elt.getOwnerDocument().createElementNS(CustomElement.CUSTOM_ELT_QNAME.getNamespaceURI(),
+ CustomElement.CUSTOM_ELT_QNAME.getLocalPart());
+ extElt.setAttribute("prefix",customElt.getPrefix());
+ extElt.setAttribute("suffix",customElt.getSuffix());
+
+ elt.appendChild(extElt);
+
+ }
+ </code>
+ </pre>
+ </p>
+ <p>The complete custom element serializer is available in
+ <code>tests.customext.elt.CustomElementSerializer</code></p>
+ </section>
+
+ <a name="reg"></a>
+ <section name="Registering Types and Using a Custom Extension Registry">
+ <p>Once the serilizers are made they need to be registered with the registry.
+ This can be done by the following way.</p>
+ <p>
+ <pre>
+ <code>
+ //register our custom type
+ registerDeserializer(CustomElement.CUSTOM_ELT_QNAME,new CustomElementDeserializer());
+ registerSerializer(CustomElement.class,new CustomElementSerializer());
+ </code>
+ </pre>
+ </p>
+ <p>It can be a more convenient if the extension types are registered inside a subclass
+ of the <code>org.apache.ws.commons.schema.extensions.ExtensionRegistry</code> to
+ avoid any confusions.</p>
+ <p>If the system property<code>"org.apache.ws.commons.extensions.ExtensionRegistry"</code> is present
+ the extension registry will be instantiated with the class specified. Following is an example of
+ how this can be done</p>
+ <p>
+ <pre>
+ <code>
+ System.setProperty(Constants.SystemConstants.EXTENSION_REGISTRY_KEY,
+ CustomExtensionRegistry.class.getName());
+ </code>
+ </pre>
+ </p>
+ <p>This behavior is quite useful when the XMlSchema object models are used internally with
+ no direct access to the extension registry.</p>
+ </section>
+
+ <a name="conclusion"></a>
+ <section name="Conclusion">
+ The extension mechanism of the XMLSchema object model allows the users to add their custom
+ objects to the standard XMLSchema objects.
+ </section>
+ </body>
+
+</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: commons-dev-help@ws.apache.org