On June 26, 2006 the Eclipse Foundation announced the availability of new releases of 10 Open Source projects. This simultaneous release event, named Callisto, garnered a lot of attention for the 10 projects involved. But, meanwhile, on the same day and without much fanfare, not even a press release, the Dali JPA Tools project shipped its first formal release numbered 0.5. With the release of Dali 0.5, developers now have a solid set of tools for developing applications for the new Java Persistence API (JPA) in Eclipse.

The Java Persistence API
The Java Persistence API is part of the new Java EE 5 EJB 3.0 specification and defines a vendor-neutral standard for object-relational mapping. But don't be fooled by the term "EJB." The JPA specification was certainly developed under the umbrella EJB 3.0 specification, but that doesn't mean it's just for Java EE. JPA is designed to work in Java SE as well as EE, and will likely be split off into its own specification in the future.

JPA defines a way to map plain old Java objects (POJOs), not Entity Beans, to relational databases. This means you can use JPA to store the Java objects you write without having to subclass a JPA-provided class or implement any JPA interfaces. One of the driving goals of the JPA specification was ease of use and it shows.

JPA in Eclipse
One of the most striking features of JPA is the use of Java 5 annotations to define object-relational mappings. By adding annotations to your classes you can make instances persistent. JPA uses the term "Entity" for persistent objects and uses the @Entity annotation to identify them. This means that you can use a simple text editor or the Eclipse Java editor to work with JPA. (see Figure 1)

Unfortunately the Java editor doesn't understand what the annotations mean. As far as it's concerned annotations are just metadata markup. It can validate the syntax but not the semantics. For example, in Figure 2 the Phone Entity's number field is mapped to a column named "NUM." That column may or may not exist in the database but without JPA-aware validation you won't find out until runtime - a very bad time to find out. This is essentially what Dali provides: JPA-aware tooling and validation to ensure that what developers build at design time will run at deployment time.

Dali Overview
Dali provides tools to develop JPA applications targeted at either Java SE or Java EE and supports top-down, bottom-up, and meet-in-the-middle development approaches. Regardless of whether you want to persist an existing Java object model, manipulate data in an existing database, or connect your existing Java classes with an existing database, Dali can improve your productivity and help ensure that you don't spend your time in an endless edit, deploy, run, debug cycle.

For example, Figure 3 shows the same Phone Entity as Figure 2. But when using Dali, a problem is found in the JPA mapping for the number field. Dali has validated the column name specified in the @Column annotation against the Phone table and found that there's no such column.

JPA Defaults
One of the most useful features of the JPA is its defaulting rules. For example, if an Entity is not explicitly mapped to a table then the table name defaults to that of the Entity. Defaulting rules let developers "program by exception." That is, they only need to add annotations for things that don't match the defaults. In the case of our Phone example, Dali has confirmed that a table exists in the database with the name "Phone" - the same name as the Entity. Since there's no problem, no errors are displayed.

Dali Views
Dali contributes two views to the Eclipse user interface along with a perspective that defines a layout suitable for performing object-relational mapping. Those two views are the Persistence Outline and Persistence Properties.

Persistence Outline
The Persistence Outline view is similar to the Eclipse Java Outline but offers a JPA view of your object. In Figure 4 the Persistence Outline shows the Phone Entity and its mapped attributes. In JPA you can either put your mapping annotations on a Class's fields or properties (JavaBean style getters). The Persistence Outline displays the mappings the same way regardless of which of the two approaches you choose. Using the outline you can get a quick thumbnail sketch of the mappings for an Entity, even if those mappings are spread throughout the Java source file. For Phone you can see the id holds the primary key of the Entity and is a Basic mapping - mapped directly to the database column. The number attribute is also a Basic mapping while the custs attribute is a collection of objects mapped as a ManyToMany.

By default, the Persistence Outline selection is linked with the Java editor so you can navigate quickly around a Class to individual mappings. The linking is reciprocal - selection of attributes in the Java editor will also update the selection in the Persistence Outline. This quick navigation to mappings is useful if you want to jump to them in the Java source editor, but is more useful when paired with the Persistence Properties view.

Persistence Properties
The Persistence Outline gives you a brief summary of your mappings and lets you navigate between them, but doesn't offer any help in editing your mappings. That's the function of the second view contributed by Dali: the Persistence Properties view. In Figure 3, we saw how Dali validated mappings and put error markers in the Java editor and errors into the problems view. But as the saying goes, acknowledging you have a problem is just the first step. The Persistence Properties provides tools for understanding and resolving mapping problems.

The Persistence Properties view performs a couple of very useful functions. It shows how a mapping is configured and, perhaps even more importantly, it shows the defaults that will be applied by a JPA runtime when the Entity is deployed.

For example, in Figure 5 the column mapping for the number attribute is defaulting to True for insertable and True for updatable. Defaulted values are clearly visible through the use of the word "Default." Notice that the column name isn't marked as a default value because the developer has explicitly specified it in an annotation.

But let's return to the problem Dali identified with the number attribute - there's no such column as NUM in the Phone table. A valid column name has to be selected, and the Persistence Properties view can help. It offers valid options for all mapping settings including settings that require access to the data model.

In Figure 6 the column name dropdown contains all the Phone table columns. It also displays what the default column name would be if nothing were specified. Since the default is correct, the default may as well be used. With the entire mapping using default values Dali removes the mapping annotation from the Java source to keep it uncluttered by unnecessary annotations.

Figure 7 and Figure 8 show that with no column specified, in fact no mapping specified at all, the defaults validate against the data model and there are no problems.

Top Down and Bottom Up
We've seen how Dali can help with the "meet-in-the-middle" approach of mapping an object model to an existing database but two other approaches are supported. Using Dali, it's possible to start with a set of Java classes annotated as Entities and generate the database tables they map to. Generation of Entities from tables is also supported. The algorithm Dali uses for both Entity and table generation is defined by the JPA default mapping rules with a few extra heuristics to deal with differences in Java/database naming styles like underscores versus camel case.

Dali's support for generation offers a quick way to bootstrap a new JPA application. You can generate Entities or tables to get a starter configuration and then refactor either knowing that Dali will flag any breakage in your mappings with problem markers.

Deployment
Deploying a JPA application is straightforward whether you're using Java SE or EE. Dali doesn't offer any specific packaging and deployment support beyond some assistance with maintaining the persistence.xml file (more on this below), however, deploying JPA Entities is just like deploying POJO applications. You can jar them up using the standard Eclipse support for exporting jars or include them in an Enterprise Archive (EAR) as a utility jar using the Web Tools Platform (WTP).

Persistence.xml
The one XML configuration file required in the JPA specification is the persistence.xml file. This file defines important runtime settings including database connection information and transaction type. When you add persistence support to a Java project, Dali creates a basic persistence.xml file and places in the src\META-INF folder. Typically you'll hand-edit this XML file to reflect your deployment configuration. (Figure 9)

As mentioned, JPA applications can be deployed to both Java SE and EE environments. However, when running outside an EJB 3.0 container, JPA requires an additional piece of information in the persistence.xml: a list of all the persistent Entities. In the 0.5 release Dali provides support for keeping the persistence.xml in sync with your defined Entities.

Right-clicking on the persistence.xml file in the Package Explorer and selecting Java Persistence>Synchronize Classes will update its list of classes (Figure 10).

Future Directions
The focus of the Dali 0.5 release was annotation-based mapping and support for the core JPA mapping types. Dali 1.0 will offer editing and validation support for both annotation and XML-based mapping as well as the use of XML mappings to override annotations as defined in the JPA specification.

Smoother integration of the Dali tools with WTP is also a high priority for 1.0. The Dali project is now incubating inside WTP as one of the new Java EE 5 technologies that will be incorporated into WTP 2.0.

In 1.0, Dali will also leverage the enhanced database support provided by the Data Tools Project (DTP). The combination of WTP with Dali and the DTP will provide a comprehensive toolset for the development of Java applications that rely on relational data.

Getting Started
The best place to begin with Dali is to visit the project home page, check out the online demos, download the plug-ins, and go through the tutorial. The Dali newsgroup is monitored by the development team and is a great place to ask a question or get help.

And finally, like every Open Source Eclipse project, contributors are welcome. Contributors meet on the dali-dev@eclipse.org mailing list to discuss technical issues and make decisions.

Resources

• Dali home page with links to downloads, documentation, project roadmap, and tutorials: www.eclipse.org/dali
• TopLink Essentials JPA Reference Implementation: http://otn.oracle.com/jpa
• JSR 220: Enterprise JavaBeans 3.0 specification: www.jcp.org/en/jsr/detail?id=220