NB: This Java installation must be version 1.5. Installing and using a 1.5 JRE/JDK reduces the possibility of any errors slipping through (e.g. using classes or methods added in later versions of Java). The host platform can be run on a later version of Java; but the Dali plug-ins must be compiled against and capable of executing on Java 1.5. Each Dali project's build path and project-specific Java compiler settings ensure Dali is compiled with Java 1.5 compliance; but there must be a Java 1.5 installation present for the compiler to compile against the correct Java jars.

NB: As of the Luna release, parts of the Eclipse Platform needed by Dali require a Java 1.6 Execution Environment. As a result, Dali requires a Java 1.6 Execution Environment to execute. Despite this requirement, Dali will continue to be compiled against and require only a Java 1.5 Execution Environment, until an irresistable Java feature compels Dali to move to a higher version of Java.

Other Tests

There are a number of other test suites that should be reasonably straightforward to configure:

Common UI

Generic JPA UI

Generic JPA Generation

JPA Diagram Editor

Major User Features

JPA

JPA Structure View

The JPA Structure View is much like the standard Eclipse Outline View; it is associated with the current editor's file and is an outline of the JPA model corresponding to the file's JPA content. The JPA Structure View is active only for files in JPA projects (i.e. projects with a JPA Facet). Typical files:

the project's META-INF/persistence.xml file

any mapping (typically orm.xml) files referenced by the persistence.xml file

any Java files with JPA annotations

JPA Details View

The JPA Details View provides a rich UI for the editing of JPA-related metadata. It provides the user with all the settings appropriate for the current state of the current selection. It also displays all the JPA spec-defined defaults for each setting. The JPA Details View also attempts to provide a similar set of settings for both Java and orm.xml mappings.

JPA Validation

Like the Java compiler, every time the user saves a file Dali will validate the file's JPA project. In particular, Dali validates the project's JPA settings against a user-specified database and generates Eclipse "Problems" for any settings that do not match the database's metadata. The severity of these errors can be configured by the user in the workspace and/or project-specific preferences.

JPQL content assistance

JPA Entity generation from tables

Dali can generate JPA spec-compliant Entities from tables defined in a DTP-accessible database.

JPA Canonical metamodel generation

As of JPA 2.0, Dali can be configured to dynamically generate JPA spec-compliant Canonical Metamodel classes based on the current state of a JPA project. This happens continuously, as the user edits JPA Entities etc. This allows the user to immediately use the current Entities etc. in the Criteria API, without waiting for the invocation of an external Annotation Processor. (In particular, Dali will re-generate the Canonical Metamodel with changes to the various JPA XML files; while, typically, annotation processors will not detect changes to XML files.) This generation will also reveal, immediately, as the Entities etc. are changed, any errors in existing usages of the Criteria API.

JAXB

Under construction...

Design

JPA

Terminology

Resource Model: A resource model is a direct representation of a particular Eclipse resource (typically a Java or XML source file). Dali currently maintains three resource models:

persistence.xml file

XML mapping file(s) (orm.xml)

Java source files

For XML resources (persistence.xml and orm.xml), the model is an EMF-generated model that uses the WTP translator framework to read/write the XML source file. For Java resources, the model is a hand-coded, non-EMF model that uses the JDT AST framework and various Dali utility classes to read/write the JPA annotations in the Java source file.

Context Model: A context model typically corresponds to a resource model but adds context by determining default values and the relationships among all the context models. As with resource models, Dali maintains three context models:

persistence.xml file

XML mapping file(s) (orm.xml)

Java source files

The context model also provides and uses common API, when possible, across the Java and XML persistent types and attributes. The context model is the model used directly by the Dali UI and clients.

Persistent Type: Any Java type to be persisted (i.e. a Java type that has JPA annotations or has been listed explicitly in a mapping file.

Persistent Attribute: Any Java attribute (field or property) to be persisted.

Mapping: A collection of related JPA metadata that consists of a persistence strategy for a type or attribute (field or property).

Type Mapping: A specific way of persisting a persistent type. For example: Entity, MappedSuperclass, Embeddable. All JPA metadata specified at the type level will be contained by a type mapping.

Attribute Mapping: A specific way of persisting a persistent attribute. For example: Basic, ManyToOne, OneToMany. All JPA metadata specified at the attribute (field or property) level will be contained by an attribute mapping.

Model

The main entry point for the Dali model is the JpaWorkspace, which corresponds to the Eclipse workspace (i.e. org.eclipse.core.resources.IWorkspace). The JpaWorkspace can be obtained by adapting the Eclipse workspace:

The primary use of the JpaWorkspace is gaining access to the JpaProjectManager. The JpaProjectManager holds the current set of JpaProjects. Dali builds a JpaProject for each Eclipse project that has a JPA facet. (Refer to the WTP Faceted Project Framework for more information.) A JpaProject holds the resource model corresponding to the project's persistence.xml file, mapping (orm.xml) files, and Java source files. The JpaProject also holds the context model that represents the JPA metadata, as derived from spec-defined defaults, Java source code annotations, and XML descriptors. A JpaProject can be obtained directly by adapting the corresponding Eclipse project:

validate the Java annotations and mapping files against the user-specified database metadata; any errors are reported as Eclipse problems and/or warnings (i.e. markers)

populate the Dali UI; the UI keeps in sync with the model via the event/listener mechanism defined by the Dali org.eclipse.jpt.common.utility.model.Model interface.

The "root" of the context model is the JpaProject's JpaContextRoot. This root provides access to the project's single PersistenceXml, whose root XML element is a Persistence. Although the JPA spec provides for the existence of multiple Persistence Units in the Persistence element, to simplify the user interface, Dali only supports the Persistence element containing a singlePersistenceUnit.

The PersistenceUnit holds the significant JPA mapping data:

mapping files (typicall orm.xml files)

JAR files

mapped Java classes

database connection settings

transaction settings

In the case of a Java annotation-only project, the PersistenceUnit directly holds all the resolved JavaManagedTypes (which are typically JavaPersistentTypes). These are held by the PersistenceUnit's ClassRefs, which each hold the corresponding JavaPersistentType if the ref's class name can be resolved. Predictably, the JavaPersistentTypes hold the JavaPersistentAttributes.

In the case of a project that maps Java types via mapping files (either exclusively or in addition to Java annotations), the PersistenceUnit directly holds all the resolved mapping files. These are held by the PersistenceUnit's MappingFileRefs, which each hold the corresponding MappingFile if the ref's file name can be resolved. Each mapping file holds a set of PersistentTypes (typically OrmPersistentTypes). Again, the PersistentTypes hold the PersistentAttributes. In addition, an OrmPersistentType holds a reference to its corresponding JavaPersistentType.

Examples

Traverse the context model for JPA metadata:

To access the JPA metadata for a type listed in the persistence.xml file:

The Dali context model can be modified directly on the UI thread; but any cascading changes to the context model happen in a background job. As a result, simple, write-only modifications can be performed on the UI thread without much hassle; but any code that changes the context model and wants any cascading changes to be immediately accessible (i.e. with the next line of code) must use a special API. To force these background, cascading changes to occur synchronously, use the method JpaProjectManager.execute(Command, ExtendedCommandContext). The command is a client-defined command that will execute the model-modifying code; while the context allows the modification of any documents that are open in the UI (typically the context can be the SynchronousUiCommandContext.instance()). (This context is most likely necessary because of an Eclpse platform bug....) Dali has several internal examples of using this method (e.g. the code that synchronizes the Persistence Unit's list of classes with the currently JPA annotated Java classes in the project).

UI

The main entry point for the Dali UI is the JpaWorkbench, which corresponds to the Eclipse workbench (i.e. org.eclipse.ui.IWorkbench). The JpaWorkbench can be obtained by adapting the Eclipse workbench:

NB: Even though IWorkbench extends IAdaptable, it does not delegate to the Platform adapter manager; so registered adapter factories are not used, and clients must directly use the Platform adapter manager.

The primary use of the JpaWorkbench is gaining access to the JpaPlatformUiManager. The JpaPlatformUiManager holds the current set of JpaPlatformUis. Each JpaPlatformUi corresponds to a specific JpaPlatform and provides the UI components necessary to support the models derived from that JpaPlatform. The UI also provides behavior the various Dali menu commands and wizards.

Major Integration points

The Dali Core makes extensive use of the JDT Core model and utilities for the purpose of reading and writing Java class metadata.

Code Completion

EMF

DTP

The Dali DB and DDL plug-ins make use of the data definition mode and the New Connection Wizard. The Datasource Explorer view is an integral part of the Dali Persistence Perspective.

WTP

Facets

EMF-XML Translator Framework

Validation Framework

Extension

Dali's main extension mechanism is the JpaPlatform Interface and extension point.

This interface is to be implemented by a JPA vendor to provide extensions to the core JPA model. The core JPA model will provide functionality for JPA spec annotations in java, persistence.xml and (orm.xml) mapping files. The org.eclipse.jpt.core.genericPlatform extension supplies resource models for those file types. As another vendor option you will have to supply those resource models as well or different ones as necessary.

The extension designates a Platform ID, Label, Class (implemenation of JpaPlatform), and an option to set the platform as a "Default" platform.