Automated documentation and ODFDOM

Published Tuesday, July 7th, 2009 by AN

Everyone hates out-of-date documentation. Unfortunately most people hate keeping documentation updated even more. So Paul Duvall has written a nice piece on developerWorks about automatically generated documentation.

The tools used in Pauls piece don’t exactly fit my project however. I use Guice, and since that can be a bit confusing it would be nice to have some overview of how Guice binds the app together. With Guice 2.0 however there is a nice Guice plugin to generate diagrams. The only problem is that the Seam/Guice integration is not updated to Guice 2.0 yet. So I guess I’ll postpone this.

An important part of any application is the data model. So I would like to have entity diagrams generated. Since I use hibernate/JPA I thought that there would be an ant task to have entity diagram generated directly. However, lots of searching on google brought me nowhere. Linguine maps would have been a solution back in the days when one used “.hbm.xml” files to configure entity classes. But noone does that anymore. So I asked a question on Stackoverflow but that didn’t help. Finally I tried a workaround that involves starting a database deploying the entities and then letting SchemaSpy generate diagrams from the database. This could definitely be more elegant.

I usually don’t program with deep or advanced class hierachies so I don’t see the point in doing inheritance graphs. Others do, however, and the tool API viz does a nice and easy job of creating them, so I might as well include that. I could presumably also have used UMLJGraph or UMLGraph (like in the developerworks article).

The really fun part begins if I were to write a small ant task that could process an ODF document with ODFDOM and automatically insert the graphs in the right place. I attended the ODFDOM hands-on-lab at JavaOne, and while the api is a bit rough now, it should actually not be too much work I think (especially if I use Groovy). I guess the first version would just replace some placeholder string in the document with the appropriate diagram. This way it should not be too difficult to use with the different documentation template documents one encounters. Poor mans LaTeX, yay! I’ll blog it when I get it running.

+++++++++++++++++++++++++++++++++++++

The AntTask for ApiViz just requires the apiviz jar file which I put in a folder “buildlib”:

<target name="javadoc">
 <javadoc destdir="docs/api"
 author="true"
 version="true"
 use="true"
 windowtitle="TACS API"
 classpathref="class.build.path"
 doclet="org.jboss.apiviz.APIviz"
 docletpath="buildlib/apiviz-1.3.0.GA.jar"
 additionalparam="-author -version">
 <fileset dir="src"/>
 </javadoc>
 </target>

The not very elegant integration of SchemaSpy involves the buildtarget below which starts two tasks in parallel. The top one just executes a class that programatically start an HSQLDB and then loads a datasource which points to that database. This then causes Hibernate to create the tables specified by the entity classes. When the database is started and the datasource loaded it sleeps 20 secs to allow the schemaspy task to connect. The bottom parallel task then sleeps 10 secs (to allow the datasource to load) and then runs schemaspy.

<target name="db-diagram" depends="db-start">
<parallel>
 <daemons>
 <java dir="build/classes/test" classname="TestEntityManagerProvider" fork="true">
 <classpath>
<pathelement location="build/classes/test"/>
<path refid="class.test.path"/>
 </classpath>
 </java>
 </daemons>
 <sequential>
 <sleep seconds="10"/>
 <java jar="buildlib/schemaSpy_4.1.1.jar"
 output="docs/output.log"
 error="docs/error.log"
 fork="true">
 <arg line="-t hsqldb"/>
 <arg line="-host localhost"/>
 <arg line="-db tacs"/>
 <arg line="-u sa"/>
 <arg line="-s PUBLIC"/>
 <arg line="-cp buildlib/hsqldb.jar"/>
 <arg line="-o docs/api"/>
 </java>
 </sequential>
 </parallel>
 </target>

public class TestEntityManagerProvider {

 public static void main(String[] args) throws InterruptedException {
 System.out.println("Starting hsqldb");

 new Thread(new Runnable(){
 public void run() {
 Server s = new Server();
 s.setDatabaseName(0, "tacs");
 s.setDatabasePath(0, "mem:test;sql.enforce_strict_size=true");
 s.start();
 }
 }).start();

 Thread.sleep(2000);

 final Map props = new HashMap();
 props.put("javax.persistence.jtaDataSource", "");
 final EntityManagerFactory entityManagerFactory = Persistence.createEntityManagerFactory("tacs-diagram", props);

 final EntityManager entityManager = entityManagerFactory.createEntityManager();

 entityManager.getTransaction().begin();
 entityManager.persist(new Cpe());
 Query q = entityManager.createQuery("from Cpe");
 System.out.println("Results from cpe" + q.getResultList());

 System.out.println("Sleeping 20 sec");
 Thread.sleep(200000    );
 System.out.println("Done sleeping");
 }
}

Tags: Documentation, ODFDOM
Posted in Techchat

This entry was posted on Tuesday, July 7th, 2009 at 2:14 pm and is filed under Techchat. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.