Coffea Works

The Enterprise Java Open Source Architecture Template

A Beginners' Way to J2EE Application Development

by Blasius Lofi Dewanto

The Enterprise Java Open Source Architecture (EJOSA) Template was built to help computer science students, at the University of Munster, develop J2EE projects with a low learning curve. With little to no experience in J2EE, and a modest experience in Java, students were able to use the EJOSA template to create robust and production-ready J2EE projects. In the first part of this article, EJOSA architect Lofi Dewanto takes a close look at this magic template -- Enhydra (Web container), JOnAS (EJB container) and HypersonicSQL (data container for development) or Firebird DBMS (data container for production).

The bane of many a J2EE novice has been the complexity associated with developing J2EE applications, using servlets and EJBs. Many commercial J2EE products that tried to address this problem failed either because their products were cluttered with features that overwhelmed J2EE beginners or simply because they failed to contribute to the explanation of the underlying development process itself. This article presents a solution for J2EE beginners who wish to overcome the complexity of J2EE application development by using Open Source Software (OSS).

Complexity of J2EE Application Development
Before we delve into the EJOSA solution, it is important to take a closer look at what makes the development of J2EE applications so complicated and inconvenient. Here are some points to consider:

J2EE applications are based on a multi-tier architecture that separates the presentation, business and data tier. This separation is one of the factors that make the development of J2EE applications harder to understand than single-tier applications. However, multi-tier architecture represents the most flexible architecture and offers a high reuse factor, using the "separation of concerns" concept.
Developers who aren't familiar with the Java Application Programming Interface (API) often develop within an Integrated Development Environment (IDE) with wizards and assistants, without understanding the underlying development process or the technology itself. Whilst this "drag and drop" approach will help them create applications faster and learn as they go, things might get difficult when their drag & drop environment does something "wrong" or "different". To overcome this problem, students in basic programming courses are now directed to use a plain text editor and command shell, instead of the IDE, so they can learn and understand the main principles of the development process and the technology hidden behind the user interface.
There are no good starter kits or best practices kits available. The J2EE reference implementation has some easy examples, which are sometimes too easy. After all, a "Hello World" J2EE application cannot teach beginners to build J2EE applications. And, although the 'Pet Store' application from Sun Microsystems illustrates some common design patterns in J2EE, it is just too extensive for beginners. Also, beginners cannot reuse the Pet Store application, since it does not offer reusable artefacts.
Most commercial J2EE products are cluttered with tons of features, which may not be useful for most J2EE beginners. The availability of umpteen libraries can also be a source of confusion.

The EJOSA Template Architecture
The multi-tier architecture, shown in Fig.1, is the basic architecture for J2EE. It illustrates the logical separation of the application into presentation, business, and data layers to improve its reusability, scalability, and ease of control.

The infrastructure of the multi-tier architecture comprises of the operating system, the network, distributed protocols like Internet Inter-ORB Protocol (IIOP) or Remote Method Invocation (RMI), and the Java Virtual Machine as the main part. At the development stage there is a need for both a development and a communication platform (if more than one developer is deployed on the project). The development platform consists of an IDE and a Concurrent Versioning System (CVS). Forums, mailing lists, Wiki and chat rooms represent the tools for the communication platform. And, during runtime, we need runtime containers like the Web, EJB, and the data container.

Before we can begin with the development of a J2EE application, we need to instantiate this architecture. I have instantiated the J2EE architecture with Open Source products to create the Enterprise Java Open Source Architecture (EJOSA). EJOSA implies Enhydra and JOnAS Application, because it uses Enhydra and JOnAS as the main Open Source products. It also uses HypersonicSQL (data container for development) and Firebird DBMS (data container for production). See Fig. 1:

Fig. 1: Multi-tier Architecture for J2EE and EJOSA (simplified)

Further, to ease the J2EE application development, I designed a template based on EJOSA, called the EJOSA Template.

Advantages of using the EJOSA Template
The EJOSA Template offers the following advantages:

The basic concept of EJOSA Template is "Keep It Short and Simple" (KISS)! This template defines a clear structure (architecture, that is) and a step-by-step development process, which can be easily understood and executed by J2EE novices. Since the separation of presentation, business, and data layer is a significant part of the J2EE architecture, the EJOSA Template follows this structure.
EJOSA Template offers easy to use templates, and is a good starting point for J2EE development based on Enhydra and JOnAS. It is a collection of pre-configured Open Source libraries. So, just unpack the EJOSA Template file and you have everything you need to start with your own J2EE application development. Enhydra and JOnAS are not a must - you can exchange Enhydra with Tomcat and JOnAS with JBoss, but they have been chosen for their simplicity.
EJOSA Template does not use IDE, wizards, or assistants. So you need to understand the whole process before beginning to develop your own J2EE application. In addition, you have the freedom to choose your own IDE since the EJOSA Template is based purely on reusable Ant scripts, which manage the build and execution system of your J2EE application.
J2EE beginners can use EJOSA Template to easily make a prototype, without having to throw the result at the end. One important idea is that all J2EE applications based on EJOSA Template can be directly deployed into your production environment. Since EJOSA Template chooses Open Source products that are mature and ready to deploy into a real production environment, projects built using EJOSA Template can scale.
EJOSA Template combines Model Driven Architecture (MDA) and Sourcecode Centric Development (SCD) model. It allows you to integrate both models in one environment to get the best of both worlds. It is very important to integrate the modelling part of the components directly into the developer's compile, run, and test cycle. EJOSA Template uses best practices from:
Component-based software engineering [Ref. 1] [Ref. 2] [Ref. 3] [Ref. 4]
Common J2EE design patterns [Ref. 5] [Ref. 6]
Model Driven Architecture concept from Object Management Group (OMG) [Ref. 9] [Ref. 10]
Development and deployment of Open University Support System (OpenUSS)

For in-depth information on each of these topics, please refer to the mentioned references; EJOSA Template demonstrates only the most important aspects for developing J2EE applications, to retain the simplicity.
Architecture and Development Process using EJOSA Template
It is recommended to download and unpack the EJOSA Template into your working directory (see the EJOSA information at the end of this article) before delving into the following indepther.

Introduction
The directory structure for a J2EE application is one important step to building a reusable template. A good structured directory gives you the general idea quickly. EJOSA Template offers a standardized directory structure. At the top of the structure (see Fig. 2) it gives a J2EE application a name like "ejosa-revo". EJOSA Template separates internal (dev-framework) and external (ext-libs) frameworks or libraries. Although reuse from external libraries is the way of component-based software development, in certain situation it is not possible to find suitable libraries. To avoid such a scenario, EJOSA Template puts all self developed internal libraries centralized in one directory. Due to the instability of the internal libraries it is always wise to separate internal from external libraries.

The dev-cartridges directory contains all the MDA cartridges, which EJOSA provides to transform and generate the models into another models or source codes. We shall discuss this directory further, in the Model section, later in the article.

Since J2EE applications may consist of one or more components, it is recommended to separate those components into different subdirectories. EJOSA Template defines dev-templates directory for each component, which should be seen as dev-your-own-component or dev-xxx. Replace this directory with your own components directory. To see all the template files that can be used as an example, go to the directory: ejosa-revo/dev-cartridges/cartridges/ejosa-component-structure/src/templates, where you will see all template files that build the structure of one component.

For the purposes of this article, the term "component" has to meet following requirements:

A component has to map the structure of multi-tier architecture for simplicity. It should have a presentation directory that handles all the presentation code. Between the presentation layer and the business layer, we need a specification directory. The specification directory contains interface definitions for the business logic, which will be implemented within a business directory. The presentation layer should never touch the business layer directly; it will only use the interfaces as specified in the specification directory. So the implementation of the business logic can be changed and extended without breaking the presentation layer. A component can have a data directory for saving all the data needed for the business layer.
On the top, a component may also need a model directory. The model directory contains all the UML models that describe the component in higher abstraction level than the source code view. The higher abstraction level of the model makes it possible to have a short glance at the component easily. In most cases, the model is the "centre" of the development, since any codes in specification, business, and presentation can be easily generated or transformed from the model.
An application directory subsumes all the component directories, like specification, business and presentation, to build a single deployable component. This is only needed if you have to distribute the component, and not in the development phase. Additionally, a component can offer documentation and test for each layer. Fig. 2 (the first part) illustrates the structure of the EJOSA Template. While the second part of the figure, illustrates the dependencies between the directories in one component.
Each layer (presentation, specification, business, etc.) defines some standard directories: The bin directory stands for binary. You will find all the executable files inside this directory. If you can execute a layer, then you will find this directory. I call this as an execution management directory.
Inside the build directory you will find all Ant build scripts to build the whole layer. I call this directory a build management directory.
Java code should be put into the src directory.
Inside the resource directory you should collect any resource files (HTML, XML descriptors, text files, etc.).
All directories, which are drawn with dashed lines, will be generated through some of the build processes. It is very important to separate generated and non-generated codes, since developers will never edit the generated codes. Also, all generated codes will never be imported into the CVS, because they will be generated automatically every time the build process starts.

Fig. 2: Structure of EJOSA Template and Dependencies between Directories

Model
The model directory contains the model element of the component. As a standard, Unified Modelling Language (UML) should be used to model the component. You can also check out MDA (Model Driven Architecture), MOF (Meta Object Facility), XMI (XML Metadata Interchange), and JMI (Java Metadata Interchange) to understand the model directory in more detail.

The implementation of the model part is based on AndroMDA 3.x. Use PoseidonUML Community Edition to model your component and export the result into an XMI file, which will be read by the AndroMDA tool to generate codes or transform into another models. AndroMDA uses the concept of cartridge to componentize generators and transformers. Fig. 3 shows the development process using AndroMDA and the importance of the cartridge concept within the AndroMDA 3.x architecture.

Fig. 3: Architecture of AndroMDA

AndroMDA 3.x delivers built-in cartridges such as EJB 2.x, EJB 2.x-Hibernate, BPM4Struts, WebService, POJO (Plain Old Java Object) cartridges and some experimental cartridges for Data Definition Language (Database DDL) and SpringFramework. I customized some of them to meet the structure of EJOSA Template. You can use the built-in cartridges from AndroMDA 3.x without customizing within EJOSA as well (see ext-libs/readme-external-libs.txt for detailed information on AndroMDA 3.x distribution; for AndroMDA 3.x documentation, click here). All EJOSA cartridges are located in the directory dev-cartridges. To develop your own cartridges you need to understand the idea of metamodels (especially for UML). AndroMDA delivers a Metafacade cartridge, which can be used to develop your own cartridges (Note: use an available cartridge to develop a new cartridge). The process of developing cartridges must be included into the developer's compile-build-run-test cycle iteratively as it is almost impossible to create these cartridges perfectly in the first attempt.

EJOSA Template offers the following customized and extended cartridges:

EJOSA Template cartridges are categorized into different types: component, model, specification (Application Programming Interface - API) and different layer of implementation like business layer implementation and presentation layer implementation. It is also important to know the standard stereotypes and tagged values from AndroMDA Metafacade UML, as they are needed to mark the model. All cartridges will use the same standard UML profile from the Metafacade UML (see Table 2). To see the most up-to-date stereotypes and tagged values, refer the following files:

ejosa-revo/ext-libs/andromda/andromda/jars/
andromda-metafacades-uml-3.0M2.jar.
Open the jar file and search for UMLProfile.properties file. Table 2 shows the content of this file.
In each cartridge you need to look at the META-INF files for the cartridge description.
For ejosa-specification-independent cartridge, see ejosa-revo/dev-cartridges/cartridges/ejosa-
specification-independent/src/META-INF/*.*
In each cartridge you need to look for the UMLProfile file. In this file you will find all the constants to describe the stereotypes and tagged values within the cartridge.
For ejosa-specification-independent cartridge, see ejosa-revo/dev-cartridges/cartridges/ejosa-
specification-independent/src/java/org/andromda/
cartridges/ejosa/specificationindependent/SpecificationIndependentProfile.java
Sometimes you also need to look through all the template files and search for the constant definition like: #set ($finderMethod = "FinderMethod") For ejosa-specification-independent cartridge, see ejosa-revo/dev-cartridges/cartridges/ejosa-
specification-independent/src/templates/*.*

This drawback, of not being able to see all the stereotypes and tagged values in one place, needs to be solved in a future version of AndroMDA. Fig. 4 shows all the sources you need to look for, to know the up to-date UML profile (stereotypes and tagged values) of each cartridge.

Fig. 4: Sources for the UML Profile

Example Model: I use a very simple example "PiggyBank" (PoseidonUML file: dev-piggybank-swing-enhydra-ejb-hibernate/model/src/piggybank.zuml) to go through the directories in EJOSA Template. Fig. 5 shows a simple use case diagram, activity diagram, and class diagrams that explain the functions and structure of the PiggyBank application. Here are the steps to develop the example:

Create a model in UML using use case and class diagrams (see Fig. 5), and use the English language to model the application (e.g. UserActivity, date, amount).
Use the model transformation cartridge "language" to translate the model language from English into German (for instance, BenutzerAktivit�t, datum, betrag). We will also generate a short report to see the cost of building this J2EE application approximately, by using the model transformation cartridge "cost calculator".
Create an independent specification type. (Note: We will look into more details of specification types in the Specification section, in the next part of this article.)
Implement the specification as SessionBean (stateless) in combination with Hibernate for the business implementation.
Use Enhydra - XMLC and Swing for the presentation layer implementation.

Fig. 5: Model: use case, activity, and class diagrams of PiggyBank

In the concept of AndroMDA, it is necessary to mark the model element in the PIM you want to work with, with stereotypes (<>) and tagged values (@xxx). Each cartridge can define its own stereotypes and tagged values. AndroMDA will then read and process the model depending on the cartridge it uses. (Note: For more information on how to model your component, please read the section on Specification, in the next part of this series.) You need to execute following steps:

The model file, piggybank.zuml, is located in the model/src directory. Here you will find a PoseidonUML specific file (.zuml) and the exported XMI file (.xmi) that will be used as an input file for the AndroMDA tool.
Compile the model to generate all the codes and other models. Ant build files are located in the model/build directory.
To get a translated (German, for instance) model, run the build file, transform-bin.xml. The example model already sets the German translation for each model elements (go to tagged value for each element and you will find something like @language.german = ). You will get the translated model at translation-generated/piggybank_de.xmi. The model transformation language cartridge uses Java Metadata Interface (JMI) directly to process the input XMI file and create a new output XMI file because Query View Transformation (QVT) standard from OMG is not available yet.
To get the short report of the cost for building the PiggyBank application (the report will be created in directory model/report-generated) and to generate the codes for specification, business and presentation (all the result will be created at the src-generated directory in each layer), run the build file, build-andromda.xml. The specification can be generated 100% as you only have interfaces (API) in the specification. A lot of code can also be generated within the business and presentation implementation, and the result can be viewed in each src-generated directory.
The build file, build-andromda-structure.xml, should only be executed if you need to update the build (build management) and bin (execution management) files; for instance, if you want to upgrade the J2EE application server with a newer version, the build and execution files need to be updated as well.

Depending on the cartridge you can transform your model into another one, and generate the source codes automatically. Also, more importantly, everybody in your team (including your business analyst and chief) can understand the functions of your application easily (thanks to the diagrams) and be updated regularly, since you will always have to change the model to modify your component implementation. Reverse Engineering Out, Forward Engineering In!

In the next part of this series, we will move further into the workings of EJOSA Template and look at the specification directory, which is the most important part of EJOSA Template; the business layer, where you implement the specification with available Java technologies; the presentation layer that represents the view of the business logics; and the roadmap for EJOSA Template.
Blasius Lofi Dewanto is a Professor Assistant at the Institute for Business Informatics and Controlling, at the University of M�nster, Germany. Reach him via e-mail: dewanto@uni-muenster.de

References
[Ref. 1] G. T. Heineman and W. T. Council, Component-Based Software Engineering - Putting the Pieces Together, Addison-Wesley, 2001.
[Ref. 2] J. Cheesman, and J. Daniels, UML Components: A Simple Process for Specifying Component-Based Software, Addison-Wesley, 2001.
[Ref. 3] P. Allen, Realizing e-Business with Components, Addison-Wesley, 2001.
[Ref. 4] R. Sharp, Component Oriented Software: Java Perspectives, http://www.softwarereality.com/programming/component_oriented.jsp.
[Ref. 5] F. Marinescu, EJB Design Patterns, Advance Patterns, Processes and Idioms, John Wiley & Sons Inc., 2002.
[Ref. 6] The Middleware Company, J2EE Best Practices, http://www.theserverside.com/resources/article.jsp?l=TMCBestPractices.
[Ref. 7] E. Cecchet, J. Marguerite and W. Zwaenepoel, Performance and Scalability of EJB Applications, http://rubis.objectweb.org/download/perf_scalability_ejb.pdf.
[Ref. 8] D. H. Young, XMLC vs. JSP, http://www.theserverside.com/resources/article.jsp?l=XMLCvsJSP.
[Ref. 9] Kleppe, A., Warmer, J., Bast, W., MDA Explained, Addison-Wesley, 2003.
[Ref. 10] Frankel, D. S., Model Driven Architecture, Wiley, 2003

EJOSA Template Links
Project site: http://ejosa.sourceforge.net/
Download Revolutions 2.2: http://sourceforge.net/project/showfiles.php?group_id=69075&package_id=83592&release_id=272948
Documentation PDF Revolutions 2.2: http://prdownloads.sourceforge.net/ejosa/ejosa-revo2.2-doc.pdf?download
HOW-TO Installation and Release Document Revolutions 2.2: http://sourceforge.net/project/shownotes.php?release_id=272948

Open Source Products Links
OpenUSS (Open University Support System) eLearning Platform: http://www.openuss.org/
Wafer Comparison of presentation layers: http://www.waferproject.org/

1. Development
SourceForge: http://www.sourceforge.net/
NetBeans IDE: http://www.netbeans.org/
Eclipse IDE http://www.eclipse.org/
ArgoUML UML diagrams: http://www.argouml.org/
AndroMDA MDA development: http://www.andromda.org/
Jalopy Source Code Formatter for Ant: http://sourceforge.net/projects/jalopy
JUnit unit testing: http://www.junit.org/
JUnitEE unit testing for J2EE: http://www.junitee.org/
Grinder stress testing: http://sourceforge.net/projects/grinder
XDoclet Attribute Oriented Programming: http://sourceforge.net/projects/xdoclet
AspectJ Aspect Oriented Programming: http://www.aspectj.org/
MTL MDA development: http://modelware.inria.fr/rubrique.php3?id_rubrique=8

2. Development and Runtime
ObjectWeb Enhydra Servlet container: http://www.enhydra.org/
ObjectWeb JOnAS EJB container: http://www.objectweb.org/jonas
HSQLDB database container: http://sourceforge.net/projects/hsqldb
Jakarta Ant Build and Execution library: http://ant.apache.org/
Jakarta ORO Regular Expressions: http://jakarta.apache.org/oro/index.html
Jakarta Lucene Search Engine: http://jakarta.apache.org/lucene/index.html
JDom for building XML files and data: http://www.jdom.org/
OSCore OpenSymphony J2EE libraries: http://www.opensymphony.com/
Quartz Scheduler: http://sourceforge.net/projects/quartz
SkinLF Swing Skin Look and Feel: http://www.l2fprod.com/

Free, yet not Open Source, Products mentioned in this Article
PoseidonUML Community Edition: http://www.gentleware.com/