Axis2 Databinding Framework

Deep into Generated Code

When the schema compiler is invoked (one-way or another) it generates code depending on the following rules:

1. All named complex types become bean classes. Any attribute or element encapsulated in this complex type will become a field in the generated class. Note that the support for constructs other than xsd:sequence and xsd:all is not yet implemented.
2. All top level elements become classes. This is a rather obvious feature since unless classes are generated for the top level elements the handling of elements becomes difficult and messy!
3. SimpleType restrictions are handled by replacing the relevant type with the basetype

Once the code is generated according to the rules it looks like the following. Consider the following schema:

<schema xmlns="http://www.w3.org/2001/XMLSchema" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:tns="http://soapinterop.org/types" targetNamespace="http://soapinterop.org/types" 
elementFormDefault="qualified" >
<import namespace="http://schemas.xmlsoap.org/soap/encoding/"/>
 <complexType name="SOAPStruct">
  <sequence>
   <element name="varString" type="xsd:string"/>
   <element name="varInt" type="xsd:int"/>
   <element name="varFloat" type="xsd:float"/>
  </sequence>
 </complexType>
<element name="myElement" type="tns:SOAPStruct"/>
</schema>

For comprehension let us consider the expanded mode for the code generator. Unless specifically mentioned, the rest of this document assumes that the expanded mode of the code generation is used. This particular schema will generate the following two classes in the designated package, which in this case would be org.soapinterop.types. The package name is derived from the target namespace of the schema.

1. MyElement.java
2. SOAPStruct.java

As explained earlier, SOAPStruct refers to the complexType. MyElement is the class that refers to the element. Just as expected, the SOAPStruct bean has getters and setters for varString, varInt and varFloat which are String, int and float respectively. MyElement on the other hand has a single field representing the SOAPStruct object that it encapsulates.

The most important aspect of the generated code is that it encapsulates two methods for creating and serializing the beans. Note that to make this work, the generated beans implement the org.apache.axis2.databinding.ADBBean interface

The creator and serializer methods look like the following:

• public javax.xml.stream.XMLStreamReader
      getPullParser(javax.xml.namespace.QName qName)
  

  This method returns a pull parser that throws the right events for this particular object. However there is a subtle difference between element based classes and complexType based classes

  1. An element based bean class (like MyElement.java in the example) will ignore the passed in QName. Instead of using the passed in QName it'll utilize its own QName which is embedded in the class under the constant MY_QNAME, during the code generation. Hence it is usual to call getPullparser() with a null parameter for elements.
  2. A ComplexType based bean class (like SOAPStruct.java in the example) will use the passed-in QName to return an instance of the ADBpullparser. This will effectively wrap the elements inside with an element having the passed QName

•  public org.apache.axiom.om.OMElement getOMElement(
              final javax.xml.namespace.QName parentQName,
              final org.apache.axiom.om.OMFactory factory){
  

  This method returns an OMElement representing the ADB bean object.

  1. Inside the getOMElement method an anonymous ADBDataSource class is created. This anonymous class implements a serialize() method where the serialization logic for that particular bean class is handled. Finally an OMSourcedElementImpl object with the above anonymous class type object as the data source is returned.

•  public static [Object].Factory. 
               parse(javax.xml.stream.XMLStreamReader reader) 
               throws java.lang.Exception 
  

  This method returns a populated instance of the class in question. Note that

  [Object]
  

  will be replaced by the actual class that contains this method. Say for SOAPStruct the method looks like

  public static SOAPStruct.Factory. 
                  parse(javax.xml.stream.XMLStreamReader reader) 
                  throws java.lang.Exception
  

  Also note that the above parse method is available in the Factory nested class within the relevant top level class. Hence one will have to get the static Factory instance before calling the parse method.

<myElement xmlns="http://soapinterop.org/types">
  <varInt>5</varInt>
  <varString>Hello</varString>
  <varFloat>3.3</varFloat>
</myElement>

XMLStreamReader reader = XMLInputFactory.newInstance().
                                createXMLStreamReader(
                                        new ByteArrayInputStream(xmlString.getBytes()));
MyElement elt = MyElement.Factory.parse(reader);

OMElement omElement = myElement.getOMElement
                (MyElement.MY_QNAME, OMAbstractFactory.getSOAP12Factory());
String xmlString = omElement.toStringWithConsume();

XMLStreamReader reader = elt.getPullParser(null);
OMElement omElt =  new StAXOMBuilder(reader).getDocumentElement();