JavaGen UML-to-EJB Tutorials

This page contains two tutorials using code examples that ship with XDoclet and JBoss, respectively. These examples demonstrate how various UML classes, attributes and associations are transformed into EJB CMP 2.0 entity beans with persistent properties and relationships. A recommended prerequisite is the JAMing EJBs tutorial, which is an introduction to using JAM to build and test EJBs.

Note: A few changes were made to the original code to demonstrate features of JavaGen.

XDoclet CMR EJB Example

This code snippet ships with the XDoclet distribution and is meant to demonstrate how to add XDoclet attributes to create CMRs (container managed relationships) for your EJBs. The advantage of using a code generator like JavaGen is that most of these XDoclet attributes can be inferred from the UML relationships. JavaGen looks for stereotypes in the UML to determine what type of code to generate for a given design element. Stereotypes are a simple UML extension mechanism, three of which are required for this example: <<cmp>>, <<cmp-field>>, and <<cmp-pk>>. The <<cmp>> stereotype tells JavaGen to generate a CMP EJB (Container Managed Persistence entity bean mapped to a database table), the <<cmp-field>> stereotype generates a persistent property (mapped to a database column) and the <<cmp-field>> stereotype generates a primary key property (mapped to a primary key column). JavaGen also looks for UML associations between <<cmp>> marked classes and generates corresponding relationship navigation code. These relations can be one-to-one, one-to-many, many-to-many, both unidirectional and bi-directional, as well as self-referencing (like the owner-colonies relation on the Country class).

Ultimately, the CMP EJBs do all kinds of SQL joins, selects, updates, inserts, cascading deletes and foreign key-primary key transactions, of which you can remain blissfully unaware! Diagram 1 shows the high level view of the UML Class Diagram as rendered in Poseidon.

DIAGRAM 1 - JBoss CMR EJB UML Class Diagram

Rather than try to explain UML in detail here, we suggest you load the UML file into Poseidon (available from www.gentleware.com) and compare the design details with the generated code. Notice how the names at either end of relations are utilized in the generated code. Locate instances of <<cmp>>, <<cmp-field>> and <<cmp-pk>> stereotypes and notice how they effect the code.

The following steps show you how to build and deploy this example. The source distribution contains the generated code and we recommend you get this working before you regenerate; correspondingly the code generation step is explained last.

Go through the setup page first, verifying that you have a Java, JBoss, ANT, Maven and JAM properly installed.
Get the XDoclet CMR source distribution from the download page and extract the contents somehwere on your hard drive.
Test your environment by typing ant setup and make sure the displayed settings make sense. To see a listing of the commands with which we will be working, type and -p.
Now you are ready to compile your code into EJBs. Open a console and go to the directory that contains the build.xml file. Type: ant dist. If all goes as expected, this will invoke XDoclet to generate the remaining EJB files, compile the results and package the whole lot into a jar file. If this did not work, go back to the setup page and verify your installation.
Now you are ready to deploy. Make sure Application Server is running. To start JBoss, open a second console and type run from JBoss's bin sub-directory. Now type ant deploy from the in the first console, while keeping an eye on the JBoss console. JBoss will indicate its progress as it verifies the deployment descriptors, installs the EJBs, and creates the database tables. If you made it this far, congratulate yourself; you've accomplished what used to take months of hard work.
You can uninstall the EJBs by typing: ant undeploy and erase all the build files by typing ant clean.
Now that you know the shipped source works, let's run the UML file through JavaGen to regenerate the EJB code. First, rename or delete the old src-gen directory. Next, open a second browser and point it at the JavaGen UML Upload page. Browse to the UML file, located in the src/uml directory of the example source distribution, and press Upload. In a few moments you should be looking at the JavaGen Code Generator page. Check JBoss for the application server and select the database you're using (JBoss ships with Hypersonic SQL database). Don't select the unit test or build file options. Press Generate Source and Download. You may be presented with the software license agreement page, press Agree. Unzip the contents so the src-gen directory replaces the original source distribution directory. Type ant clean deploy to verify that everything is working again. Don't forget to type ant undeploy when you're done.

This exercise may seem trivial, but reflect upon what you have done. From a simple UML diagram, you've created an entity tier and a database tier (see architecture), including all the O-R (object to relational) mapping functionality and database definitions. (Still think this is trivial? I consulted at a Swiss bank that spent $200 million to do basically the same thing!)

You can use the generated SQL (located under src-gen/sql) to create your database tables or if you're using JBoss's default installation, the tables are automatically created and removed when you deploy and undeploy. To see the SQL JBoss generates, you can configure Log4J to send it to a log file as follows by adding the following entry to the JBoss Log4J config file: jboss-3.x/server/default/conf/log4j.xml:

 <appender name="SQL" class="org.apache.log4j.FileAppender">
    <param name="Append" value="false"/>
    <param name="Threshold" value="DEBUG"/>
    <param name="File" value="${jboss.server.home.dir}/log/sql.log"/>
    <layout class="org.apache.log4j.PatternLayout">
      <param name="ConversionPattern" value="%d{ABSOLUTE} %-5p [%c{1}] %m%n"/>
    </layout>
  </appender>
  <category name="org.jboss.ejb.plugins.cmp">
    <appender-ref ref="SQL"/>
    <priority value="DEBUG"/>
  </category>

Restart JBoss and redeploy/undeploy your EJB and look in the resulting log file jboss-3.x/server/default/log/sql.log.

Gangsters Example

This example comes with the JBoss documentation. It is slightly more complex, illustrating an aggregation relation and a richer set of properties. It also comes with unit tests for verifying the code works as expected. Diagram 2 shows the Gangsters UML Class Diagram as rendered in Poseidon 1.6.

DIAGRAM 2 - Gangsters UML Class Diagram

This tutorial is terser than the previous example. If you don't understand something, refer to the first tutorial for more explanation.

Make sure your setup is completed.
Download and extract the javagen-gangster-ejb source distribution found on the download page.
Next, compile and package the distribution file by typing ant dist. If you compare this build.xml file with the one from the previous example, you'll see that the dist target is overridden to include the Cactus test war file.
Start JBoss in a second console as above, type ant deploy followed by ant itest, look at the HTML test results in target/reports and clean up when you're finished by typing ant undeploy. You can also do everything using the single command, testcycle, see JAMing EJBs for an explanation.
Now let's regenerate the EJB code using JavaGen. First, rename or delete the old src-gen directory. Next, open a second browser and point it at the JavaGen UML Upload page. Browse to the UML file, located in the src/uml directory, and press Upload. In a few moments, you should be looking at the JavaGen Code Generator page. Check JBoss for the application server and select the database you're using (JBoss ships with Hypersonic SQL database). Don't select the unit test or build file options. Press Generate Source and Download. You may be presented with the software license agreement page, press Agree. Unzip the contents so the src-gen directory replaces the original source distribution directory. Type ant clean deploy to verify that everything is working again. Don't forget to type ant undeploy when you're done.

Only the GangsterITest class has any valid tests, the other integration test classes have a single generated test that fails. You can try your hand at EJB programming by writing some unit tests in these classes.

Congratulations, you've graduated to J2EE gurudom. To see a more advanced EJB example, look at the ejb-module directory of the JavaGen Petstore.