Revision as of 17:47, 15 November 2010

Dali JPA Tools – Internal/External Developer Documentation

Archive

• Dali Developer Documentation v0.5

CVS Connection info

Major Features

JPA Structure View

• Contains the elements of an Entity
• Visual representation
• Allows navigation of JPA Details view

JPA Details View

• Provides rich UI for the editing of persistence related metadata
• Unified editing for Java annotation and orm.xml
• Provides defaults values for JPA metadata

Validation

• Validation in the form of “Problems” are reported based on the state of the Persistence Unit

Entity Generation from Tables

• Generates spec compliant Entities from tables defined in the DTP database definition model

Architecture diagram

Coming soon...

Dali Terminology

Resource Model: A resource model directly reflects a given resource (Java source or XML source). Dali currently maintains three resource models, including one for persistence.xml, the XML mapping file(s), and one for JPA Annotations. For XML resources(Mapping File or persistence.xml) this is a generated EMF model that uses the WTP translator framework to read/write the XML source. On the Java side it is a non-EMF object model that represents the JPA Annotations on the Java Types and Attributes.

Context Model: A context model represents only the non-resource related JPA metadata. Dali currently maintains three context models, including one for persistence.xml, the XML mapping file(s), and one for JPA Annotations. It pulls together the persistence.xml, XML Mapping File and Java resource models and uses common API. As and example, it gives context to the Java Annotations so that a JavaResourcePersistentType in the resource model with Entity, Table, SecondaryTable annotations on it becomes a PersistentType with an Entity TypeMapping in the context model. The context model interfaces are used by the Dali UI and adopters.

Persistent Type: Any Java Type that will be persisted.

Persistent Attribute: Any Java Attribute that will be persisted.

Mapping: A collection of related JPA metadata that consists of a persistence strategy for a given Type or Attribute.

Type Mapping: A specific way of persisting a Persistent Type, for example, Enity, Mapped Superclass, or Embeddable. All JPA metadata specified at the Type level will be contained by this Type Mapping.

Attribute Mapping: A specific way of persisting a Persistent Attribute, for example, Basic, ManyToOne, or OneToMany. All JPA metadata specified at the Attribute level will be contained by this Attribute Mapping.

Model usage examples

Traversing the Context model for JPA metadata

JpaProject.getRootContext() : JpaRootContextNode
JpaRootContextNode.getPersistenceXml(): PersistenceXml
PersistenceXml.getPersistence() : Persistence
Persistence.persistenceUnits() : ListIterator<PersistenceUnit> (will contain 0 or 1 PersistenceUnits, we don't support multiple yet)
PersistenceUnit.classRefs() : ListIterator<ClassRef> (mappingFileRefs() if you want the orm.xml entities)
ClassRef.getJavaPersistentType() : JavaPersistentType
JavaPersistentType.attributes() : ListIterator<JavaPersistentAttribute>

Retrieving Java Entities in a given persistence unit

public static List<PersistentType> entities(JpaProject jpaProject) {
	List<PersistentType> entities = new ArrayList<PersistentType>();
	JpaRootContextNode rootContext = jpaProject.getRootContext();

	// You'll want null checks in here in cases of the persistence.xml
	// file not being complete.
	// Also, we only support 1 persistenceUnit in the implementation,
	// you should verify there is at least one.
	PersistenceUnit persistenceUnit = rootContext.getPersistenceXml()
			.getPersistence().persistenceUnits().next();

	for (Iterator<ClassRef> classRefs = persistenceUnit.classRefs(); classRefs
			.hasNext();) {
		ClassRef classRef = classRefs.next();
		if (classRef.getJavaPersistentType() != null) { // null if
			// there is no java class with this name)
			if (classRef.getJavaPersistentType().getMappingKey() == MappingKeys.ENTITY_TYPE_MAPPING_KEY) {
				entities.add(classRef.getJavaPersistentType());
			}
		}
	}
	// to get entities from orm.xml files
	for (Iterator<MappingFileRef> mappingFiles = persistenceUnit
			.mappingFileRefs(); mappingFiles.hasNext();) {
		MappingFileRef mappingFileRef = mappingFiles.next();
		// null checks needed here for OrmXml as well as EntityMappings
		EntityMappings entityMappings = mappingFileRef.getOrmXml().getEntityMappings();
		for (Iterator<OrmPersistentType> persistentTypes = entityMappings
				.ormPersistentTypes(); persistentTypes.hasNext();) {
			OrmPersistentType ormPersistentType = persistentTypes.next();
			if (ormPersistentType.getMappingKey() == MappingKeys.ENTITY_TYPE_MAPPING_KEY){
				entities.add(ormPersistentType);
			}
		}
	}

	return entities;
}

Changing the Context model programatically

If you are changing the model outside the UI thread you will need to configure the JPA project to make modifications on the UI thread as necessary. See JpaProject#setThreadLocalModifySharedDocumentCommandExecutor(CommandExecutor).

Also note the model is "updated" asynchronously with every change. If you want these updates to happen synchronously, you will need to set the JPA project's "updater". See JpaProject#setUpdater(Updater). Note the comments in SynchronousJpaProjectUpdater.

Dali Plug-ins

org.eclipse.jpt.core

Description: Resource model and Context model interfaces and implementations

Dependency on (see plugin Manifest for details):

• org.eclipse.jpt.db
• org.eclipse.jpt.utility

• org.eclipse.core
• org.eclipse.emf
• org.eclipse.jdt
• org.eclipse.jem
• org.eclipse.jst
• org.eclipse.text
• org.eclipse.wst
• org.eclipse.xsd

org.eclipse.jpt.db

Description: DTP wrapper model, serves as Dali’s interface to the DTP DB model.

Dependency on (see plugin Manifest for details):

• org.eclipse.jpt.utility

• org.eclipse.core
• org.eclipse.datatools.sqltools.editor.core

org.eclipse.jpt.db.ui

Description: Dali UI for DTP Connection Wizard

Dependency on (see plugin Manifest for details):

• org.eclipse.jpt.db

• org.eclipse.ui
• org.eclipse.datatools.connectivity.ui
• org.eclipse.datatools.sqltools.editor.core

org.eclipse.jpt.doc.isv

Description: Javadoc plugin

No dependencies.

org.eclipse.jpt.doc.user

Description: User docs and infopop for Dali

Dependency on (see plugin Manifest for details):

• org.eclipse.help
• org.eclipse.ui.cheatsheets

org.eclipse.jpt.gen

Description: Contains model and generator code for generating Entities from tables

Dependency on (see plugin Manifest for details):

• eclipse.jpt.db
• eclipse.jpt.core
• eclipse.jpt.utility

• eclipse.core
• eclipse.jdt.core

org.eclipse.jpt.ui

Description: Contains the actions, composites, data models, wizards, views, and perspective that make up the Dali UI.

Dependency on (see plugin Manifest for details):

• org.eclipse.jpt.core
• org.eclipse.jpt.db
• org.eclipse.jpt.db.ui
• org.eclipse.jpt.gen
• org.eclipse.jpt.utility

• org.eclipse.core
• org.eclipse.draw2d
• org.eclipse.emf
• org.eclipse.jdt
• org.eclipse.jem
• org.eclipse.jface
• org.eclipse.jst
• org.eclipse.ui
• org.eclipse.wst

org.eclipse.jpt.utility

Description: A set of utility classes for the Dali plug-in. Contains a set of advanced iterators, change support, SWT Value Models, plus utilities for dealing with Files, Strings, Collections, etc.

No Dependencies.

org.eclipse.jpt.eclipselink.core

Description: EclipseLink extension, including an EclipseLinkPlatform and the EclipseLink context model.

org.eclipse.jpt.eclipselink.ui

Description: EclipseLink UI extension, including an EclipseLinkPlatformUI and associated EclipseLink UI composites.

org.eclipse.jpt.core.tests

Description: Contains a suite of headless JUnit tests for the core plug-in.

org.eclipse.jpt.utility.tests

Description: Contains a comprehensive set of tests for the Utility classes.

Major Integration points

JDT

• 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

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

Platform

• Project Explorer

Extension Mechanism

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.

Extension Example:

  <extension
         point="org.eclipse.jpt.core.jpaPlatform">
      <jpaPlatform
            class="org.eclipse.jpt.eclipselink.core.internal.EclipseLinkPlatform"
            id="org.eclipse.eclipselink.platform"
            label="EclipseLink">
      </jpaPlatform>
   </extension>

See the EclipseLinkPlatform included in Dali as an exemplary implementation.

Statement on API

Provisional API is available as of the 2.0 release.