Well prepared documentation presents important aspect of further XML facade integration. Suppose we only receive the JAR package containing XML facade. It is virtually impossible to use XML facade if we don't know what the purpose of each data type is and how we can utilize it. With documentation, we receive a well-defined XML facade capable of integrating XML and Java worlds together. This recipe explains how to document the XML facade generated Java classes.
To complete this recipe, we only need the XML schema defined. We already have the XML schema in the Banking_BPEL project (Derivative_Cashflow.xsd).
Here are the steps we need to take in order to generate Java documents for XML facade:
- We open the
Derivative_Cashflow.xsdXML schema file. - Initially, we need to add an additional schema definition to the XML schema file:
<xsd:schema attributeFormDefault="unqualified" elementFormDefault="qualified" targetNamespace="http://xmlns.oracle.com/BPELFacade/Banking_BPEL/Derivative_Cashflow" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:prc="http://xmlns.oracle.com/BPELFacade/Banking_BPEL/Derivative_Cashflow" xmlns:jxb="http://java.sun.com/xml/ns/jaxb" jxb:version="2.1"> </xsd:schema> - In order to put documentation at the package level, we put the following code immediately after the
<xsd:schema>tag in the XML schema file:<xsd:annotation> <xsd:appinfo> <jxb:schemaBindings> <jxb:package name="org.packt.cashflow.facade"> <jxb:javadoc>This package represents the XML facade of the cashflows in the financial derivatives structure.</jxb:javadoc> </jxb:package> </jxb:schemaBindings> </xsd:appinfo> </xsd:annotation> - In order to add documentation at the
complexTypelevel, we need to put the following lines into the XML schema file. The code goes immediately after thecomplexTypedefinition:<xsd:annotation> <xsd:appinfo> <jxb:class> <jxb:javadoc>This class defines the data for the events, when principal exchange occurs.</jxb:javadoc> </jxb:class> </xsd:appinfo> </xsd:annotation> - The elements of the
complexTypedefinition are annotated in a similar way. We put the annotation data immediately after the element definition in the XML schema file:<xsd:annotation> <xsd:appinfo> <jxb:property> <jxb:javadoc>Raw principal exchange date.</jxb:javadoc> </jxb:property> </xsd:appinfo> </xsd:annotation> - In JDeveloper, we are now ready to build the
javadocdocumentation. So, select the project CashflowFacade root node. Then, from the main menu, select the Build and Javadoc CashflowFacade.jpr option. Thejavadoccontent will be built in thejavadocdirectory of the project.
During the conversion from XML schema to Java classes, JAXB is also processing possible annotations inside the XML schema file. When the conversion utility (xjc or execution through JDeveloper) finds the annotation in the XML schema file, it decorates the generated Java classes according to the specification.
The XML schema file must contain the following declarations. In the <xsd:schema> element, the following declaration of the JAXB schema namespace must exist:
xmlns:jxb="http://java.sun.com/xml/ns/jaxb" jxb:version="2.1"
Note that the xjb:version attribute is where the Version of the JAXB specification is defined. The most common Version declarations are 1.0, 2.0, and 2.1.
The actual definition of javadoc resides within the <xsd:annotation> and <xsd:appinfo> blocks. To annotate at package level, we use the following:
<jxb:schemaBindings> <jxb:package name="PKG_NAME"> <jxb:javadoc>TEXT</jxb:javadoc> </jxb:package> </jxb:schemaBindings>
We define the package name to annotate and a javadoc text containing the documentation for the package level.
The annotation of javadoc at class or attribute level is similar to the following:
<jxb:class|property> <jxb:javadoc>TEXT</jxb:javadoc> </jxb:class|property>
If we want to annotate the XML schema at complexType level, we use the <jaxb:class> element. To annotate the XML schema at element level, we use the <jaxb:property> element.
In many cases, we need to annotate the XML schema file directly for various reasons. The XML schema defined by different vendors is automatically generated. In such cases, we would need to annotate the XML schema each time we want to generate Java classes out of it. This would require additional work just for annotation decoration tasks.
In such situations, we can separate the annotation part of the XML schema to a separate file. With such an approach, we separate the annotating part from the XML schema content itself, over which we usually don't have control. For that purpose, we create a binding file in our CashflowFacade project and name it extBinding.xjb. We put the annotation documentation into this file and remove it from the original XML schema. We start by defining the binding file header declaration:
<jxb:bindings version="1.0"
xmlns:jxb="http://java.sun.com/xml/ns/jaxb"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<jxb:bindings schemaLocation="file:/D:/delo/source_code/Banking_BPEL/xsd/Derivative_Cashflow.xsd" node="/xs:schema">We need to specify the name of the schema file location and the root node of the XML schema which corresponds to our mapping. We continue by declaring the package level annotation:
<jxb:schemaBindings>
<jxb:package name="org.packt.cashflow.facade">
<jxb:javadoc><![CDATA[<body>This package represents the XML facade of the cashflows in the financial derivatives structure.</body>]]>
</jxb:javadoc>
</jxb:package>
<jxb:nameXmlTransform>
<jxb:elementName suffix="Element"/>
</jxb:nameXmlTransform>
</jxb:schemaBindings> We notice that the structure of the package level annotation is identical to those in the inline XML schema annotation. To annotate the class and its attribute, we use the following declaration:
<jxb:bindings node="//xs:complexType[@name='CashflowsType']">
<jxb:class>
<jxb:javadoc>
<![CDATA[This class defines the data for the events, when principal exchange occurs.]]>
</jxb:javadoc>
</jxb:class>
<jxb:bindings node=".//xs:element[@name='principalExchange']">
<jxb:property>
<jxb:javadoc>TEST prop</jxb:javadoc>
</jxb:property>
</jxb:bindings>
</jxb:bindings>Notice the indent annotation of attributes inside the class annotation that naturally correlates to the object programming paradigm.
Now that we have the external binding file, we can regenerate the XML facade.
In JDeveloper, if we are building XML facade for the first time, we follow either the Creating XML facade from XSD or the Creating XML facade from WSDL recipe. To rebuild XML facade, we use the following procedure:
- Select the XML schema file (
Cashflow_Facade.xsd) in the CashflowFacade project. Right-click on it and select the Generate JAXB 2.0 Content Model option.
- The configuration dialog opens with some already pre-filled fields. We enter the location of the JAXB Customization File (in our case, the location of the
extBinding.xjbfile) and click on the OK button.
- Next, we build the
javadocpart to get the documentation. Now, if we open the generated documentation in the web browser, we can see our documentation lines inside.