Difference between revisions of "Dali Developer Documentation"

From Eclipsepedia

Jump to: navigation, search
(JptUtilityTests=)
(Development Workspace)
(39 intermediate revisions by 4 users not shown)
Line 1: Line 1:
=Dali JPA Tools – Internal/External Developer Documentation=
+
=Dali Java Persistence Tools – Developer Documentation=
 
Archive
 
Archive
 
*[[Dali Developer Documentation v0.5]]
 
*[[Dali Developer Documentation v0.5]]
  
  
==CVS Connection info==
+
==CVS Connection Settings==
  
{| style="width:60%;" border="0" cellpadding="2"  
+
{| style="width:40%;" border="0" cellpadding="2"  
 
|-
 
|-
 
| '''Host''' || dev.eclipse.org  
 
| '''Host''' || dev.eclipse.org  
Line 17: Line 17:
 
|-
 
|-
 
| '''Connection Type''' || pserver
 
| '''Connection Type''' || pserver
|-
 
| '''Plugin Directory''' || org.eclipse.jpa
 
 
|-
 
|-
 
|}
 
|}
 +
The Dali modules are under <code>HEAD/org.eclipse.jpa</code>.
 +
 +
'''NB:''' Ensure the Eclipse network proxy is configured, if applicable (Preferences > General > Network Connections)
 +
 +
==Development Workspace==
 +
 +
To set up an Eclipse IDE workspace for working on Dali, perform the following steps:
 +
 +
* Set up a ''host'' platform (or use a current Eclipse install, assuming it is reasonably up-to-date)
 +
** Download and unzip the latest major Eclipse release
 +
*** The basic Eclipse Java IDE (http://download.eclipse.org/eclipse/downloads/)
 +
*** [Optional] The Eclipse Modeling Framework (http://www.eclipse.org/modeling/emf/downloads/)
 +
** A reasonable command-line for executing the ''host'' platform might look like this:<br>
 +
 +
<pre>eclipse.exe -vm C:\jdk\1.6.0_23\bin\javaw.exe -data C:\dev\dali -vmargs -Xmx768M -XX:MaxPermSize=256M</pre>
 +
 +
* Add the appropriate Execution Environment to the ''host'' platform
 +
** If necessary, download and install the final J2SE 1.5 JRE or JDK (http://www.oracle.com/technetwork/java/javase/downloads/index.html)
 +
** Start the ''host'' platform
 +
** Add an Installed JRE (Preferences > Java > Installed JREs)
 +
*** <Standard VM>
 +
*** Select the directory holding the just-installed JRE/JDK
 +
**'''NB:''' This Java installation ''must'' be version '''1.5'''. WTP requires Dali to execute on a 1.5 JVM. 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:''' The JPA Diagram Editor compiles against Java 1.5; but it requires a Java 1.6 Execution Environment. This is because its prerequisite Graphiti requires a Java 1.6 Execution Environment.
 +
**'''NB:''' The JAXB test plug-ins compile against Java 1.5; but they require a Java 1.6 Execution Environment. This is because the <code>javax.xml.bind</code> annotations ship with the Java 1.6 Execution Environment.
 +
 +
* Set up a ''target'' platform
 +
** Download the latest WTP Integration Build and all of its dependencies (http://download.eclipse.org/webtools/downloads/)
 +
*** Eclipse SDK
 +
*** EMF and XSD SDK
 +
*** GEF SDK
 +
*** DTP SDK
 +
*** EMF Transaction
 +
*** EMF Validation
 +
*** Graphiti
 +
*** Orbit
 +
*** WTP SDK
 +
** Unzip all the downloaded files (except the Graphiti and Orbit files) into the same directory (This directory is different than the directory holding the ''host'' platform created above.)
  
==Configuring your workspace for development==
+
* Configure the ''host'' platform to use the ''target'' platform for building plug-ins
 +
** Start the ''host'' platform
 +
** Add a ''target'' platform (Preferences > Plug-in Development > Target Platform)
 +
*** <Add...> a new Target definition
 +
*** Initialize the target definition with <Nothing>
 +
*** <Add...> a new location for the ''target'' platform
 +
**** <Directory>
 +
**** Select the directory holding the ''target'' platform (i.e. the directory holding the just-unzipped WTP files and pre-requisites)
 +
**** NB: The new location should indicate it has over 1000 plug-ins available
 +
*** <Add...> another location for the Orbit repository
 +
**** <Software Site>
 +
**** <Add...> a new repository
 +
***** <Archive...>
 +
***** Select the just-downloaded Orbit zip file
 +
**** <Work with:> the just-added Orbit repository
 +
**** '''NB:'''  Make sure <Group by Category> is checked.
 +
**** Select "All Orbit Bundles" => "EasyMock"
 +
**** NB: The new location should indicate it has 2 plug-ins available
 +
*** <Add...> another location for the Graphiti repository
 +
**** <Software Site>
 +
**** <Add...> a new repository
 +
***** <Archive...>
 +
***** Select the just-downloaded Graphiti zip file
 +
**** <Work with:> the just-added Graphiti repository
 +
**** '''NB:''' Make sure <Include required software> is unchecked. (Graphiti requires the EMF Transaction plug-in, which is already part of the target platform location added above.)
 +
**** Select "Graphiti SDK"  (or "Graphiti" => "Graphiti SDK" if grouped by categories.)
 +
**** NB: The new location should indicate it has 20 plug-ins available
 +
*** <Finish> the wizard to create the new ''target'' platform
  
The following is the recommended default Eclipse config for Dali development (and most any WTP development)
+
* Optional (but very helpful): Configure the ''host'' platform to include the classes from the ''target'' platform (Preferences > Plug-in Development > Include all plug-ins from target in Java search)
  
* Set up your host platform (or use your current Eclipse install, assuming it is reasonable up-to-date)
+
* Check out the Dali code from the Eclipse Foundation-hosted CVS repository
** Download and unzip the latest major Eclipse release (latest service release if available) to use as your Java development environment
+
** Ensure the Eclipse network proxy is configured, if applicable (Preferences > General > Network Connections)
* Next you need your "Target Platform".  This is what you will compile against in your dev workspace.
+
** Open the CVS Repository Exploring perspective
** Download the latest WTP SDK I-Build and all of its dependencies for the stream you need from here - http://download.eclipse.org/webtools/downloads/
+
** Create a new Repository Location using the Dali CVS connection settings documented [[Dali Developer Documentation#CVS Connection Settings|above]]
** For reference the current stream is 3.3.0
+
** Download all the plug-in and test plug-in projects in the following directories under <code>HEAD/org.eclipse.jpa/components</code> (The projects are named <code>org.eclipse.jpt.*</code>.):
** Unzip the WTP SDK I-Build and all prerequisite zips into the same directory (but a different directory than your host platform)
+
***<code>common</code>
* Configure your target platform in the host
+
***<code>jaxb</code>
** Start your Eclipse host dev environment
+
***<code>jpa</code>
** Go to Windows->Preferences->Plug-in Development->Target Platform
+
***<code>jpa_diagram_editor</code>
** "Add" a new target
+
** '''NB:''' The various plug-in projects must be checked out individually. Do not check out a parent directory; use multi-select to check out multiple projects.
** Initialize the target with "Nothing"
+
** "Add" a location, the directory where you unzipped your target contents
+
** "Finish" the wizard
+
* Fetch the Dali code in CVS
+
** Ensure proxy is set if applicable
+
** Go to the CVS Repository Exploring Perspective
+
** Create a location using the above CVS connection info
+
** Download all plugins and test plugins under HEAD/org.eclipse.jpa/components/jpa and jaxb
+
*** These plugins must be checked out by selecting the actual plugins, not a parent directory.  Multi-select plugins to bring down more than one at a time.
+
  
 
==Running JUnit Tests==
 
==Running JUnit Tests==
Line 54: Line 108:
 
* Select the JUnit Plug-in Test node, right-click and New
 
* Select the JUnit Plug-in Test node, right-click and New
 
* Run a single test
 
* Run a single test
** Project: org.eclipse.jpt.core.tests
+
** Project: org.eclipse.jpt.jpa.core.tests
** Test Class: org.eclipse.jpt.core.tests.internal.JptCoreTests
+
** Test Class: org.eclipse.jpt.jpa.core.tests.internal.JptJpaCoreTests
 
* Test Runner can be JUnit 3 or 4
 
* Test Runner can be JUnit 3 or 4
 
* On the Main tab
 
* On the Main tab
Line 72: Line 126:
 
* Make a duplicate of your JptCoreTests run configuration
 
* Make a duplicate of your JptCoreTests run configuration
 
* Change the following
 
* Change the following
** Project: org.eclipse.jpt.eclipselink.core.tests
+
** Project: org.eclipse.jpt.jpa.eclipselink.core.tests
** Test Class: org.eclipse.jpt.eclipselink.core.tests.internal.JptEclipseLinkCoreTests
+
** Test Class: org.eclipse.jpt.jpa.eclipselink.core.tests.internal.JptJpaEclipseLinkCoreTests
 
* On the Arguments tab
 
* On the Arguments tab
 
** Make sure the following VM arguments are specified:
 
** Make sure the following VM arguments are specified:
Line 95: Line 149:
 
*Create a new Launch Config under the "JUnit" category
 
*Create a new Launch Config under the "JUnit" category
 
*Run a single test
 
*Run a single test
** Project: org.eclipse.jpt.utility.tests
+
** Project: org.eclipse.jpt.common.utility.tests
** Test Class: org.eclipse.jpt.utility.tests.internal.JptUtilityTests
+
** Test Class: org.eclipse.jpt.common.utility.tests.internal.JptCommonUtilityTests
 
* No other configuration is needed
 
* No other configuration is needed
  
Line 144: Line 198:
 
===Traversing the Context model for JPA metadata===
 
===Traversing the Context model for JPA metadata===
  
 +
To access the JPA metadata for a type listed in the <code>persistence.xml</code> file:
 
<pre>
 
<pre>
JpaProject.getRootContext() : JpaRootContextNode
+
IProject.getAdapter(JpaProject.class) : JpaProject
JpaRootContextNode.getPersistenceXml(): PersistenceXml
+
  JpaProject.getRootContextNode() : JpaRootContextNode
PersistenceXml.getPersistence() : Persistence
+
    JpaRootContextNode.getPersistenceXml(): PersistenceXml
Persistence.persistenceUnits() : ListIterator<PersistenceUnit> (will contain 0 or 1 PersistenceUnits, we don't support multiple yet)
+
      PersistenceXml.getPersistence() : Persistence
PersistenceUnit.classRefs() : ListIterator<ClassRef> (mappingFileRefs() if you want the orm.xml entities)
+
        Persistence.getPersistenceUnits() : Iterable<PersistenceUnit>
ClassRef.getJavaPersistentType() : JavaPersistentType
+
              (this will contain 0 or 1 PersistenceUnits as Dali does not support multiple persistence units)
JavaPersistentType.attributes() : ListIterator<JavaPersistentAttribute>
+
          PersistenceUnit.getClassRefs() : Iterable<ClassRef>
 +
            ClassRef.getJavaPersistentType() : JavaPersistentType
 +
              JavaPersistentType.getMapping() : JavaTypeMapping
 +
              JavaPersistentType.getAttributes() : Iterable<JavaPersistentAttribute>
 +
                JavaPersistentAttribute.getMapping() : JavaAttributeMapping
 
</pre>
 
</pre>
  
 +
To access the JPA metadata for a type listed in an <code>orm.xml</code> file:
  
===Retrieving Java Entities in a given persistence unit===
+
<pre>
 +
...
 +
PersistenceUnit.getMappingFileRefs() : Iterable<MappingFileRef>
 +
  MappingFileRef.getMappingFile() : MappingFile
 +
    MappingFile.getPersistentTypes() : Iterable<PersistentType>
 +
...
 +
</pre>
 +
 
 +
===Retrieving the JPA Entities for a Project===
  
 
<pre>
 
<pre>
 +
public static Iterable<PersistentType> getEntities(IProject project) {
 +
    JpaProject jpaProject = (JpaProject) project.getAdapter(JpaProject.class);
 +
    if (jpaProject == null) {
 +
        return Collections.emptySet();
 +
    }
  
public static List<PersistentType> entities(JpaProject jpaProject) {
+
    JpaRootContextNode rootContextNode = jpaProject.getRootContextNode();
List<PersistentType> entities = new ArrayList<PersistentType>();
+
    PersistenceXml persistenceXml = rootContextNode.getPersistenceXml();
JpaRootContextNode rootContext = jpaProject.getRootContext();
+
    if (persistenceXml == null) {
 +
        return Collections.emptySet();
 +
    }
  
// You'll want null checks in here in cases of the persistence.xml
+
    Persistence persistence = persistenceXml.getPersistence();
// file not being complete.
+
    if (persistence == null) {
// Also, we only support 1 persistenceUnit in the implementation,
+
        return Collections.emptySet();
// you should verify there is at least one.
+
    }
PersistenceUnit persistenceUnit = rootContext.getPersistenceXml()
+
.getPersistence().persistenceUnits().next();
+
  
for (Iterator<ClassRef> classRefs = persistenceUnit.classRefs(); classRefs
+
    if (persistence.getPersistenceUnitsSize() == 0) {
.hasNext();) {
+
        return Collections.emptySet();
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;
+
    PersistenceUnit persistenceUnit = persistence.getPersistenceUnit(0);
 +
    ArrayList<PersistentType> entities = new ArrayList<PersistentType>();
 +
    for (PersistentType persistentTypes : persistenceUnit.getPersistentTypes()) {
 +
        if (persistentTypes.getMappingKey() == MappingKeys.ENTITY_TYPE_MAPPING_KEY) {
 +
            entities.add(persistentTypes);
 +
        }
 +
    }
 +
    return entities;
 
}
 
}
 
 
</pre>
 
</pre>
  
Line 207: Line 265:
 
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.
 
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==
+
==Dali Plug-ins (Needs to be updated)==
  
 
===org.eclipse.jpt.core===
 
===org.eclipse.jpt.core===

Revision as of 15:51, 4 June 2013

Contents

Dali Java Persistence Tools – Developer Documentation

Archive


CVS Connection Settings

Host dev.eclipse.org
Repository Paths /cvsroot/webtools
User anonymous
Password (leave blank)
Connection Type pserver

The Dali modules are under HEAD/org.eclipse.jpa.

NB: Ensure the Eclipse network proxy is configured, if applicable (Preferences > General > Network Connections)

Development Workspace

To set up an Eclipse IDE workspace for working on Dali, perform the following steps:

eclipse.exe -vm C:\jdk\1.6.0_23\bin\javaw.exe -data C:\dev\dali -vmargs -Xmx768M -XX:MaxPermSize=256M
  • Add the appropriate Execution Environment to the host platform
    • If necessary, download and install the final J2SE 1.5 JRE or JDK (http://www.oracle.com/technetwork/java/javase/downloads/index.html)
    • Start the host platform
    • Add an Installed JRE (Preferences > Java > Installed JREs)
      • <Standard VM>
      • Select the directory holding the just-installed JRE/JDK
    • NB: This Java installation must be version 1.5. WTP requires Dali to execute on a 1.5 JVM. 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: The JPA Diagram Editor compiles against Java 1.5; but it requires a Java 1.6 Execution Environment. This is because its prerequisite Graphiti requires a Java 1.6 Execution Environment.
    • NB: The JAXB test plug-ins compile against Java 1.5; but they require a Java 1.6 Execution Environment. This is because the javax.xml.bind annotations ship with the Java 1.6 Execution Environment.
  • Set up a target platform
    • Download the latest WTP Integration Build and all of its dependencies (http://download.eclipse.org/webtools/downloads/)
      • Eclipse SDK
      • EMF and XSD SDK
      • GEF SDK
      • DTP SDK
      • EMF Transaction
      • EMF Validation
      • Graphiti
      • Orbit
      • WTP SDK
    • Unzip all the downloaded files (except the Graphiti and Orbit files) into the same directory (This directory is different than the directory holding the host platform created above.)
  • Configure the host platform to use the target platform for building plug-ins
    • Start the host platform
    • Add a target platform (Preferences > Plug-in Development > Target Platform)
      • <Add...> a new Target definition
      • Initialize the target definition with <Nothing>
      • <Add...> a new location for the target platform
        • <Directory>
        • Select the directory holding the target platform (i.e. the directory holding the just-unzipped WTP files and pre-requisites)
        • NB: The new location should indicate it has over 1000 plug-ins available
      • <Add...> another location for the Orbit repository
        • <Software Site>
        • <Add...> a new repository
          • <Archive...>
          • Select the just-downloaded Orbit zip file
        • <Work with:> the just-added Orbit repository
        • NB: Make sure <Group by Category> is checked.
        • Select "All Orbit Bundles" => "EasyMock"
        • NB: The new location should indicate it has 2 plug-ins available
      • <Add...> another location for the Graphiti repository
        • <Software Site>
        • <Add...> a new repository
          • <Archive...>
          • Select the just-downloaded Graphiti zip file
        • <Work with:> the just-added Graphiti repository
        • NB: Make sure <Include required software> is unchecked. (Graphiti requires the EMF Transaction plug-in, which is already part of the target platform location added above.)
        • Select "Graphiti SDK" (or "Graphiti" => "Graphiti SDK" if grouped by categories.)
        • NB: The new location should indicate it has 20 plug-ins available
      • <Finish> the wizard to create the new target platform
  • Optional (but very helpful): Configure the host platform to include the classes from the target platform (Preferences > Plug-in Development > Include all plug-ins from target in Java search)
  • Check out the Dali code from the Eclipse Foundation-hosted CVS repository
    • Ensure the Eclipse network proxy is configured, if applicable (Preferences > General > Network Connections)
    • Open the CVS Repository Exploring perspective
    • Create a new Repository Location using the Dali CVS connection settings documented above
    • Download all the plug-in and test plug-in projects in the following directories under HEAD/org.eclipse.jpa/components (The projects are named org.eclipse.jpt.*.):
      • common
      • jaxb
      • jpa
      • jpa_diagram_editor
    • NB: The various plug-in projects must be checked out individually. Do not check out a parent directory; use multi-select to check out multiple projects.

Running JUnit Tests

Once your workspace has been successfully configured, you are ready to run the tests.

JptCoreTests

  • In the Java perspective, select the Run->Run Configurations... menu item
  • Select the JUnit Plug-in Test node, right-click and New
  • Run a single test
    • Project: org.eclipse.jpt.jpa.core.tests
    • Test Class: org.eclipse.jpt.jpa.core.tests.internal.JptJpaCoreTests
  • Test Runner can be JUnit 3 or 4
  • On the Main tab
    • Program to run -> Run an application: [No Application] Headless mode
  • On the Arguments tab
    • Insert the following VM arguments:
-Xmx512M -XX:MaxPermSize=128M -Dhttp.proxyHost=www-proxy.us.oracle.com -Dhttp.proxyPort=80 
-Dorg.eclipse.jpt.jpa.jar="C:\[pathTo]\javax.persistence_2.[qualifier].jar"

Apply and run. After you are able to successfully run the JptCoreTests you can move on to...

JptEclipseLinkCoreTests

  • In the Java perspective, select the Run->Run Configurations... menu item
  • Make a duplicate of your JptCoreTests run configuration
  • Change the following
    • Project: org.eclipse.jpt.jpa.eclipselink.core.tests
    • Test Class: org.eclipse.jpt.jpa.eclipselink.core.tests.internal.JptJpaEclipseLinkCoreTests
  • On the Arguments tab
    • Make sure the following VM arguments are specified:
-Xmx512M -Dhttp.proxyHost=www-proxy.us.oracle.com -Dhttp.proxyPort=80
-Dorg.eclipse.jpt.jpa.jar="C:\[pathTo]\javax.persistence_2.[qualifier].jar"
-Dorg.eclipse.jpt.eclipselink.jar="C:\[pathTo]\eclipselink.jar"

JaxbCoreTests

  • Same basic setup as JptCore and EcliseLinkCore tests
    • Project: org.eclipse.jpt.jaxb.core.tests
    • Test Class: org.eclipse.jpt.jaxb.core.tests.internal.JaxbCoreTests
  • On the Arguments tab
    • Make sure the following VM arguments are specified:
-Xmx512M -Dhttp.proxyHost=www-proxy.us.oracle.com -Dhttp.proxyPort=80

JptUtilityTests

  • Create a new Launch Config under the "JUnit" category
  • Run a single test
    • Project: org.eclipse.jpt.common.utility.tests
    • Test Class: org.eclipse.jpt.common.utility.tests.internal.JptCommonUtilityTests
  • No other configuration is needed

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

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

IProject.getAdapter(JpaProject.class) : JpaProject
  JpaProject.getRootContextNode() : JpaRootContextNode
    JpaRootContextNode.getPersistenceXml(): PersistenceXml
      PersistenceXml.getPersistence() : Persistence
        Persistence.getPersistenceUnits() : Iterable<PersistenceUnit>
              (this will contain 0 or 1 PersistenceUnits as Dali does not support multiple persistence units)
          PersistenceUnit.getClassRefs() : Iterable<ClassRef>
            ClassRef.getJavaPersistentType() : JavaPersistentType
              JavaPersistentType.getMapping() : JavaTypeMapping
              JavaPersistentType.getAttributes() : Iterable<JavaPersistentAttribute>
                JavaPersistentAttribute.getMapping() : JavaAttributeMapping

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

...
PersistenceUnit.getMappingFileRefs() : Iterable<MappingFileRef>
  MappingFileRef.getMappingFile() : MappingFile
    MappingFile.getPersistentTypes() : Iterable<PersistentType>
...

Retrieving the JPA Entities for a Project

public static Iterable<PersistentType> getEntities(IProject project) {
    JpaProject jpaProject = (JpaProject) project.getAdapter(JpaProject.class);
    if (jpaProject == null) {
        return Collections.emptySet();
    }

    JpaRootContextNode rootContextNode = jpaProject.getRootContextNode();
    PersistenceXml persistenceXml = rootContextNode.getPersistenceXml();
    if (persistenceXml == null) {
        return Collections.emptySet();
    }

    Persistence persistence = persistenceXml.getPersistence();
    if (persistence == null) {
        return Collections.emptySet();
    }

    if (persistence.getPersistenceUnitsSize() == 0) {
        return Collections.emptySet();
    }

    PersistenceUnit persistenceUnit = persistence.getPersistenceUnit(0);
    ArrayList<PersistentType> entities = new ArrayList<PersistentType>();
    for (PersistentType persistentTypes : persistenceUnit.getPersistentTypes()) {
        if (persistentTypes.getMappingKey() == MappingKeys.ENTITY_TYPE_MAPPING_KEY) {
            entities.add(persistentTypes);
        }
    }
    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 (Needs to be updated)

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.