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/12 19:37:21 UTC
svn commit: r528060 [2/2] - /webservices/commons/site/XmlSchema/
Added: webservices/commons/site/XmlSchema/writingExtensions.html
URL: http://svn.apache.org/viewvc/webservices/commons/site/XmlSchema/writingExtensions.html?view=auto&rev=528060
==============================================================================
--- webservices/commons/site/XmlSchema/writingExtensions.html (added)
+++ webservices/commons/site/XmlSchema/writingExtensions.html Thu Apr 12 10:37:20 2007
@@ -0,0 +1,458 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+
+
+
+
+
+
+
+
+<html>
+ <head>
+ <title>Apache XmlSchema -
+ :: Apache XmlSchema Extension Tutorial ::</title>
+ <style type="text/css" media="all">
+ @import url("./css/maven-base.css");
+ @import url("./css/maven-theme.css");
+ @import url("./css/site.css");
+ </style>
+ <link rel="stylesheet" href="./css/print.css" type="text/css" media="print" />
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
+ </head>
+ <body class="composite">
+ <div id="banner">
+ <a href="../../" id="bannerLeft">
+
+ <img src="http://www.apache.org/images/asf-logo.gif" alt="" />
+
+ </a>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="breadcrumbs">
+
+
+
+
+
+
+
+ <div class="xleft">
+ Last Published: 04/12/2007
+ </div>
+ <div class="xright"> <a href="http://www.apache.org/">Apache</a>
+ |
+ <a href="../../">WebServices</a>
+ |
+ <a href="../">WS Commons</a>
+ |
+ <a href="">XmlSchema</a>
+
+
+
+
+
+
+
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="leftColumn">
+ <div id="navcolumn">
+
+
+
+
+
+
+
+ <h5>XML Schema</h5>
+ <ul>
+
+ <li class="none">
+ <a href="index.html">Home</a>
+ </li>
+
+
+
+
+
+
+
+ <li class="expanded">
+ <a href="">Downloads</a>
+ <ul>
+
+ <li class="none">
+ <a href="download.cgi">Releases</a>
+ </li>
+
+ <li class="none">
+ <a href="source-repository.html">Source Code</a>
+ </li>
+ </ul>
+ </li>
+
+
+
+
+
+
+
+
+
+
+
+ <li class="expanded">
+ <a href="">Documentation</a>
+ <ul>
+
+ <li class="none">
+ <a href="schematutorial.html">Tutorial</a>
+ </li>
+
+ <li class="none">
+ <strong>Extensions</strong>
+ </li>
+
+ <li class="none">
+ <a href="apidocs/index.html">Javadocs</a>
+ </li>
+
+ <li class="none">
+ <a href="http://svn.apache.org/viewvc/webservices/commons/trunk/modules/XmlSchema/?root=Apache-SVN">View Source</a>
+ </li>
+ </ul>
+ </li>
+
+
+
+
+
+
+
+
+
+ <li class="expanded">
+ <a href="">Project Information</a>
+ <ul>
+
+ <li class="none">
+ <a href="mail-lists.html">Mailing Lists</a>
+ </li>
+
+ <li class="none">
+ <a href="team-list.html">Project Team</a>
+ </li>
+
+ <li class="none">
+ <a href="issue-tracking.html">Issue Tracking</a>
+ </li>
+ </ul>
+ </li>
+
+ <li class="none">
+ <a href="license.html">License</a>
+ </li>
+ </ul>
+ <a href="http://maven.apache.org/" title="Built by Maven" id="poweredBy">
+ <img alt="Built by Maven" src="./images/logos/maven-feather.png"></img>
+ </a>
+
+
+
+
+
+
+
+ </div>
+ </div>
+ <div id="bodyColumn">
+ <div id="contentBox">
+
+
+
+ <head>
+ <meta http-equiv="content-type" content="text/html; charset=iso-8859-1"></meta>
+ <meta content="text/html; charset=iso-8859-1"></meta>
+ </head>
+
+
+ <a name="Contents"></a><div class="section"><h2>Contents</h2>
+ <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="#conclusion">Conclusion</a></li>
+ </ul>
+ </div>
+
+
+ <a name="intro"></a>
+ <a name="Introduction"></a><div class="section"><h2>Introduction</h2>
+ 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.
+ </div>
+
+
+ <a name="example"></a>
+ <a name="Example Extension"></a><div class="section"><h2>Example Extension</h2>
+ Following are two example schema documents that contain external attributes/elements
+ 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>
+
+
+ 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>
+
+
+ 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.
+ </div>
+
+ <a name="iclasses"></a>
+ <a name="Important classes"></a><div class="section"><h2>Important classes</h2>
+ Following are the important classes in writing an extension
+ <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>
+ Last two classes are interfaces that should be implemented by the respective
+ implementations.
+
+ </div>
+
+ <a name="deser"></a>
+ <a name="Code for a Deserializer"></a><div class="section"><h2>Code for a Deserializer</h2>
+ 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
+
+
+ <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>
+
+ 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> 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>
+ </div>
+
+ <a name="ser"></a>
+ <a name="Code for a Serializer"></a><div class="section"><h2>Code for a Serializer</h2>
+ <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>
+ </div>
+
+ <a name="reg"></a>
+ <a name="Registering Types and Using a Custom Extension Registry"></a><div class="section"><h2>Registering Types and Using a Custom Extension Registry</h2>
+ <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>
+ </div>
+
+ <a name="conclusion"></a>
+ <a name="Conclusion"></a><div class="section"><h2>Conclusion</h2>
+ The extension mechanism of the XMLSchema object model allows the users to add their custom
+ objects to the standard XMLSchema objects.
+ </div>
+
+
+
+ </div>
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ <div id="footer">
+ <div class="xright">©
+ 2004-2007
+
+ Apache Software Foundation
+
+
+
+
+
+
+
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ </body>
+</html>
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: commons-dev-help@ws.apache.org