IT-eye

Writing a documentation about the software that is made is important. But why should we document the code in a separate document. We know Javadoc standard to document java code and pldoc for generating documentation from PL/SQL code. In those cases you need to document your code in a pre defined way to let the tool generate correct documentation pages.

BPEL stores the documentation in the code using the annotation tags. This makes it easy to find the documentation area’s in the code. The next step is extracting this information from the BPEL. With xslt we can transform the bpel.xml file into a HTML file. Below you find a sample of a xslt file.

<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:tns="http://schemas.xmlsoap.org/ws/2003/03/business-process/"
xmlns:bpelx="http://schemas.oracle.com/bpel/extension"
xmlns:bre="http://xmlns.oracle.com/BPELDocSample">
<xsl:template match="/tns:process">
<xsl:element name="html">
<xsl:element name="head">
<xsl:element name="link">
<xsl:attribute name="rel">stylesheet</xsl:attribute>
<xsl:attribute name="type">text/css</xsl:attribute>
<xsl:attribute name="href">bpel-flow-doc.css</xsl:attribute>
</xsl:element>
</xsl:element>
<xsl:element name="body">
<xsl:element name="div">
<xsl:attribute name="class">process</xsl:attribute>
<xsl:value-of select="@name"/>
<xsl:apply-templates />
</xsl:element>
</xsl:element>
</xsl:element>
</xsl:template>
<xsl:template match="tns:sequence">
<xsl:variable name="sequenceID"><xsl:value-of select="generate-id(.)"/></xsl:variable>
<xsl:element name="div">
<xsl:attribute name="id"><xsl:value-of select="$sequenceID"/></xsl:attribute>
<xsl:attribute name="class">sequence</xsl:attribute>
<xsl:element name="p">
<xsl:value-of select="@name"/>
</xsl:element>
<xsl:apply-templates />
</xsl:element>
</xsl:template>
<xsl:template match="tns:scope">
<xsl:variable name="scopeID"><xsl:value-of select="generate-id(.)"/></xsl:variable>
<xsl:element name="div">
<xsl:attribute name="class">scope</xsl:attribute>
<xsl:attribute name="id"><xsl:value-of select="$scopeID"/></xsl:attribute>
<xsl:element name="p">
<xsl:attribute name="class">scope</xsl:attribute>
<xsl:value-of select="@name"/>
</xsl:element>
<xsl:apply-templates />
</xsl:element>
</xsl:template>
</xsl:stylesheet>


In this example the sequences and scopes in the BPEL file are transformed into a html file. Expand the xslt file to get the information that you want to see in your HTML. For example: used partner links, Variables etc. Style the html file using CSS and you have a nice html page displaying what you want to see of the BPEL process.

To process the xslt file I made a ANT target. Connecting this to our nightly build the documentation of the process is generated on the moment that the code is compiled.

<!--
===========================================================
== doc-gen
===========================================================
-->
<target name="doc-gen">
<xslt force="true"
in="${basedir}/bpel/${process.name}.bpel"
style="${bpel.documentatie.flow.xsl}"
out="${process.name}.html"/>
<echo level="info">
doc-gen for ${basedir}/bpel/${process.name}.bpel
</echo>
</target>


Useful links:

• Javadoc
• Pldoc