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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
![http://www.apache.org/images/asf-logo.gif"](http://www.apache.org/images/asf-logo.gif"){kind=link}