Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Dali Developer Documentation"

(Development Workspace)
(Development Workspace)
 
(88 intermediate revisions by 4 users not shown)
Line 1: Line 1:
=Dali Java Persistence Tools – Developer Documentation=
+
= Repository =
Archive
+
*[[Dali Developer Documentation v0.5]]
+
  
 +
http://git.eclipse.org/c/dali/webtools.dali.git
  
==CVS Connection Settings==
+
'''NB:''' Ensure the Eclipse network proxy is configured, if applicable (Preferences > General > Network Connections)
  
{| style="width:40%;" border="0" cellpadding="2"
+
= Development Workspace =
|-
+
| '''Host''' || dev.eclipse.org
+
|-
+
| '''Repository Paths''' || /cvsroot/webtools
+
|-
+
| '''User''' || anonymous
+
|-
+
| '''Password''' || (leave blank)
+
|-
+
| '''Connection Type''' || pserver
+
|-
+
|}
+
The Dali modules are under <code>HEAD/org.eclipse.jpa</code>.
+
  
==Development Workspace==
+
To set up an Eclipse IDE workspace for working on Dali, perform the following steps:
  
The following is the recommended default Eclipse config for Dali development (and most any WTP development)
+
* 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 Eclipse IDE for Eclipse Committers (https://www.eclipse.org/downloads/packages/eclipse-ide-eclipse-committers/neonr)
 +
*** [Optional] The Eclipse Modeling Framework (http://www.eclipse.org/modeling/emf/downloads/)
  
* Set up your host platform (or use your current Eclipse install, assuming it is reasonable up-to-date)
+
* Add the appropriate Execution Environment to the ''host'' platform
** Download and unzip the latest major Eclipse release (latest service release if available) to use as your Java development environment
+
** Like the base Eclipse platform, Dali requires JavaSE-1.8
* Next you need your "Target Platform".  This is what you will compile against in your dev workspace.
+
** 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/
+
** For reference the current stream is 3.3.0
+
** Unzip the WTP SDK I-Build and all prerequisite zips into the same directory (but a different directory than your host platform)
+
* Configure your target platform in the host
+
** Start your Eclipse host dev environment
+
** Go to Windows->Preferences->Plug-in Development->Target Platform
+
** "Add" a new target
+
** Initialize the target with "Nothing"
+
** "Add" a location, the directory where you unzipped your target contents
+
** "Finish" the wizard
+
* Check out the Dali code from the Eclipse CVS repository
+
** Ensure proxy is set if applicable
+
** Open the CVS Repository Exploring perspective
+
** Create a new Repository Location using the CVS connection settings [[Dali Developer Documentation#CVS Connection Settings|above]]
+
** 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==
+
* Set up a ''target'' platform
Once your workspace has been successfully configured, you are ready to run the tests.
+
** Download the latest WTP Integration Build and all of its dependencies (http://download.eclipse.org/webtools/downloads/)
 +
*** Eclipse SDK
 +
*** EMF and XSD SDK
 +
*** GEF3 SDK ('''NB:''' ''not'' GEF4)
 +
*** DTP SDK
 +
*** EMF Transaction
 +
*** EMF Validation
 +
*** Graphiti
 +
*** Orbit
 +
*** WTP
 +
** Unzip all the downloaded files that are not update repositories:
 +
*** '''Mac:''' Extract the Eclipse SDK Mac application bundle tar first; then unzip the non-repository files into the subdirectory <code>Eclipse.app/Contents</code>.
 +
*** Eclipse SDK
 +
*** EMF and XSD SDK
 +
*** EMF Transaction
 +
*** EMF Validation
  
===JptCoreTests===
+
* 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 files)
 +
***** '''Mac:''' Select the subdirectory <code>Eclipse.app/Contents/Eclipse</code>.
 +
**** '''NB:''' The new location should indicate it has over 500 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 over 20 plug-ins available
 +
*** <Add...> another location for the DTP repository
 +
**** <Software Site>
 +
**** <Add...> a new repository
 +
***** <Archive...>
 +
***** Select the just-downloaded DTP zip file
 +
**** <Work with:> the just-added DTP repository
 +
**** '''NB:'''  Make sure <Group by Category> is checked.
 +
**** Click on <Select All>
 +
**** '''NB:''' The new location should indicate it has over 200 plug-ins available
 +
*** <Add...> another location for the GEF repository
 +
**** <Software Site>
 +
**** <Add...> a new repository
 +
***** <Archive...>
 +
***** Select the just-downloaded GEF3 zip file
 +
**** <Work with:> the just-added GEF3 repository
 +
**** '''NB:'''  Make sure <Group by Category> is checked.
 +
**** Click on <Select All>
 +
**** '''NB:''' The new location should indicate it has 20 plug-ins available
 +
*** <Add...> another location for the WTP repository
 +
**** <Software Site>
 +
**** <Add...> a new repository
 +
***** <Archive...>
 +
***** Select the just-downloaded WTP zip file
 +
**** <Work with:> the just-added WTP repository
 +
**** '''NB:'''  Make sure <Group by Category> is checked.
 +
**** Click on <Select All>
 +
**** '''NB:''' The new location should indicate it has over 500 plug-ins available
 +
*** <Finish> the wizard to create the new ''target'' platform
  
* In the Java perspective, select the Run->Run Configurations... menu item
+
* 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)
* Select the JUnit Plug-in Test node, right-click and New
+
* Run a single test
+
** Project: org.eclipse.jpt.core.tests
+
** Test Class: org.eclipse.jpt.core.tests.internal.JptCoreTests
+
* 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:
+
  
<pre>-Xmx512M -XX:MaxPermSize=128M -Dhttp.proxyHost=www-proxy.us.oracle.com -Dhttp.proxyPort=80
+
* Clone the Eclipse Foundation-hosted Dali Git repository and import the Dali projects
-Dorg.eclipse.jpt.jpa.jar="C:\[pathTo]\javax.persistence_2.[qualifier].jar"</pre>
+
** Ensure the Eclipse network proxy is configured, if applicable (Preferences > General > Network Connections)
 +
** Open the Git perspective
 +
** Clone the Dali repository using the appropriate URL from http://git.eclipse.org/c/dali/webtools.dali.git
 +
** Import the plug-in and test plug-in projects in the repository's working directory (The projects are named <code>org.eclipse.jpt.*</code>.):
 +
***<code>common/plugins</code> - the <code>*.branding</code> projects are optional
 +
***<code>common/tests</code>
 +
***<code>jaxb/plugins</code> - the <code>*.branding</code> projects are optional
 +
***<code>jaxb/tests</code>
 +
***<code>jpa/plugins</code> - the <code>*.branding</code> projects are optional
 +
***<code>jpa/tests</code>
 +
***<code>jpa_diagram_editor/plugins</code>
 +
***<code>jpa_diagram_editor/tests</code>
  
Apply and run.  After you are able to successfully run the JptCoreTests you can move on to...
+
= JUnit Tests =
 +
Once the development workspace is configured and the Dali plug-ins built, it is possible to execute the Dali tests.
  
===JptEclipseLinkCoreTests===
+
== Generic JPA Core Tests ==
  
* In the Java perspective, select the Run->Run Configurations... menu item
+
* Add a run configuration (Run > Run Configurations... > JUnit Plug-in Test > New)
* Make a duplicate of your JptCoreTests run configuration
+
** <Test> tab
* Change the following
+
*** <Run a single test>
** Project: org.eclipse.jpt.eclipselink.core.tests
+
**** Project: <code>org.eclipse.jpt.jpa.core.tests</code>
** Test Class: org.eclipse.jpt.eclipselink.core.tests.internal.JptEclipseLinkCoreTests
+
**** Test Class: <code>org.eclipse.jpt.jpa.core.tests.internal.JptJpaCoreTests</code>
* On the Arguments tab
+
*** Test Runner: JUnit 3 or 4
** Make sure the following VM arguments are specified:
+
** <Main> tab
 +
*** <Program to run>
 +
**** Run an application: [No Application] - Headless mode
 +
** <Arguments> tab
 +
*** VM arguments:
  
<pre>-Xmx512M -Dhttp.proxyHost=www-proxy.us.oracle.com -Dhttp.proxyPort=80
+
<pre>
-Dorg.eclipse.jpt.jpa.jar="C:\[pathTo]\javax.persistence_2.[qualifier].jar"
+
-Xmx768M
-Dorg.eclipse.jpt.eclipselink.jar="C:\[pathTo]\eclipselink.jar"</pre>
+
-XX:MaxPermSize=256M
 +
-Dorg.eclipse.jpt.jpa.jar=<path to jar containing javax.persistence packages>
 +
</pre>
  
===JaxbCoreTests===
+
* <Run>
  
* Same basic setup as JptCore and EcliseLinkCore tests
+
'''NB:''' These tests may take on the order of 30 minutes to complete.
** 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:
+
  
<pre>-Xmx512M -Dhttp.proxyHost=www-proxy.us.oracle.com -Dhttp.proxyPort=80</pre>
+
== EclipseLink JPA Core Tests ==
  
===JptUtilityTests===
+
Duplicate the Generic JPA Core Tests configuration described above and make the following modifications:
 +
* <Test> tab
 +
** Project: <code>org.eclipse.jpt.jpa.eclipselink.core.tests</code>
 +
** Test class: <code>org.eclipse.jpt.jpa.eclipselink.core.tests.internal.JptJpaEclipseLinkCoreTests</code>
 +
* <Arguments> tab
 +
** Add the following VM argument:
  
*Create a new Launch Config under the "JUnit" category
+
<pre>
*Run a single test
+
-Dorg.eclipse.jpt.eclipselink.jar=<path to eclipselink.jar>
** Project: org.eclipse.jpt.utility.tests
+
</pre>
** Test Class: org.eclipse.jpt.utility.tests.internal.JptUtilityTests
+
* 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...
+
  
 +
== Generic JAXB Core Tests ==
  
==Dali Terminology==
+
Duplicate the Generic JPA Core Tests configuration described above and make the following modifications:
 
+
* <Test> tab
'''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.
+
** Project: <code>org.eclipse.jpt.jaxb.core.tests</code>
 
+
** Test class: <code>org.eclipse.jpt.jaxb.core.tests.internal.JaxbCoreTests</code>
'''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.
+
* <Arguments> tab
 
+
** Add the following VM argument:
'''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===
+
  
 
<pre>
 
<pre>
JpaProject.getRootContext() : JpaRootContextNode
+
-Dorg.eclipse.jpt.jaxb.jar=<path to eclipselink.jar>
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>
+
 
</pre>
 
</pre>
  
 +
== EclipseLink JAXB Core Tests ==
  
===Retrieving Java Entities in a given persistence unit===
+
Duplicate the Generic JAXB Core Tests configuration described above and make the following modifications:
 +
* <Test> tab
 +
** Project: <code>org.eclipse.jpt.jaxb.eclipselink.core.tests</code>
 +
** Test class: <code>org.eclipse.jpt.jaxb.eclipselink.core.tests.internal.ELJaxbCoreTests</code>
 +
* <Arguments> tab
 +
** Add the following VM argument:
  
 
<pre>
 
<pre>
 +
-Dorg.eclipse.jpt.jaxb.jar=<path to eclipselink.jar>
 +
-Dorg.eclipse.jpt.eclipselink.jar=<path to eclipselink.jar>
 +
</pre>
  
public static List<PersistentType> entities(JpaProject jpaProject) {
+
== Common Core Tests ==
List<PersistentType> entities = new ArrayList<PersistentType>();
+
JpaRootContextNode rootContext = jpaProject.getRootContext();
+
  
// You'll want null checks in here in cases of the persistence.xml
+
Duplicate the Generic JPA Core Tests configuration described above and make the following modifications:
// file not being complete.
+
* <Test> tab
// Also, we only support 1 persistenceUnit in the implementation,
+
** Project: <code>org.eclipse.jpt.common.core.tests</code>
// you should verify there is at least one.
+
** Test class: <code>org.eclipse.jpt.common.core.tests.internal.JptCommonCoreTests</code>
PersistenceUnit persistenceUnit = rootContext.getPersistenceXml()
+
.getPersistence().persistenceUnits().next();
+
  
for (Iterator<ClassRef> classRefs = persistenceUnit.classRefs(); classRefs
+
== Common Utility Tests ==
.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();
+
                MappingFile mappingFile = mappingFileRef.getMappingFile();
+
// null checks needed here for EntityMappings
+
EntityMappings entityMappings = (EntityMappings) mappingFile.getRoot();
+
for (Iterator<OrmPersistentType> persistentTypes = entityMappings
+
.getPersistentTypes().iterator(); persistentTypes.hasNext();) {
+
OrmPersistentType ormPersistentType = persistentTypes.next();
+
if (ormPersistentType.getMappingKey() == MappingKeys.ENTITY_TYPE_MAPPING_KEY){
+
entities.add(ormPersistentType);
+
}
+
}
+
}
+
  
return entities;
+
* Add a run configuration (Run > Run Configurations... > JUnit > New)
}
+
** <Test> tab
 +
*** <Run a single test>
 +
**** Project: <code>org.eclipse.jpt.common.utility.tests</code>
 +
**** Test Class: <code>org.eclipse.jpt.common.utility.tests.internal.JptCommonUtilityTests</code>
  
</pre>
+
== Other Tests ==
  
===Changing the Context model programatically===
+
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 =
  
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).
+
== JPA ==
  
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.
+
=== 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 <code>META-INF/persistence.xml</code> file
 +
* any mapping (typically <code>orm.xml</code>) files referenced by the <code>persistence.xml</code> file
 +
* any Java files with JPA annotations
  
==Dali Plug-ins==
+
=== 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 <code>orm.xml</code> mappings.
  
===org.eclipse.jpt.core===
+
=== JPA Validation ===
Description:  Resource model and Context model interfaces and implementations
+
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.
  
Dependency on (see plugin Manifest for details):
+
=== JPQL content assistance ===
 +
Dali provides content assistance for JPQL queries edited in a Java source file, an <code>orm.xml</code> file, or the JPA Details View.
  
*org.eclipse.jpt.db
+
=== JPA Entity generation from tables ===
*org.eclipse.jpt.utility
+
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.
  
*org.eclipse.core
+
== JAXB ==
*org.eclipse.emf
+
Under construction...
*org.eclipse.jdt
+
*org.eclipse.jem
+
*org.eclipse.jst
+
*org.eclipse.text
+
*org.eclipse.wst
+
*org.eclipse.xsd
+
  
 +
= Design =
  
===org.eclipse.jpt.db===
+
== JPA ==
Description:  DTP wrapper model, serves as Dali’s interface to the DTP DB model.
+
  
Dependency on (see plugin Manifest for details):
+
=== Terminology ===
  
*org.eclipse.jpt.utility
+
'''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:
 +
* <code>persistence.xml</code> file
 +
* XML mapping file(s) (<code>orm.xml</code>)
 +
* Java source files
 +
For XML resources (<code>persistence.xml</code> and <code>orm.xml</code>), 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:
 +
* <code>persistence.xml</code> file
 +
* XML mapping file(s) (<code>orm.xml</code>)
 +
* 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.
  
*org.eclipse.core
+
'''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.
*org.eclipse.datatools.sqltools.editor.core
+
  
 +
'''Persistent Attribute''': Any Java attribute (field or property) to be persisted.
  
===org.eclipse.jpt.db.ui===
+
'''Mapping'''A collection of related JPA metadata that consists of a persistence strategy for a type or attribute (field or property).
DescriptionDali UI for DTP Connection Wizard
+
  
Dependency on (see plugin Manifest for details):
+
'''Type Mapping''': A specific way of persisting a ''persistent type''. For example: <code>Entity</code>, <code>MappedSuperclass</code>, <code>Embeddable</code>.  All JPA metadata specified at the type level will be contained by a ''type mapping''.
  
*org.eclipse.jpt.db
+
'''Attribute Mapping''': A specific way of persisting a ''persistent attribute''. For example: <code>Basic</code>, <code>ManyToOne</code>, <code>OneToMany</code>. All JPA metadata specified at the attribute (field or property) level will be contained by an ''attribute mapping''.
  
 +
=== Model ===
  
*org.eclipse.ui
+
The main entry point for the Dali model is the <code>JpaWorkspace</code>, which corresponds to the Eclipse workspace (i.e. <code>org.eclipse.core.resources.IWorkspace</code>). The <code>JpaWorkspace</code> can be obtained by ''adapting'' the Eclipse workspace:
*org.eclipse.datatools.connectivity.ui
+
<pre>
*org.eclipse.datatools.sqltools.editor.core
+
IWorkspace workspace = ResourcesPlugin.getWorkspace();
 +
JpaWorkspace jpaWorkspace = (JpaWorkspace) workspace.getAdapter(JpaWorkspace.class);
 +
</pre>
 +
The primary use of the <code>JpaWorkspace</code> is gaining access to the <code>JpaProjectManager</code>. The <code>JpaProjectManager</code> holds the current set of <code>JpaProject</code>s. Dali builds a <code>JpaProject</code> for each Eclipse project that has a JPA ''facet''. (Refer to the [http://www.eclipse.org/articles/Article-BuildingProjectFacets/tutorial.html WTP Faceted Project Framework] for more information.) A <code>JpaProject</code> holds the ''resource model'' corresponding to the project's <code>persistence.xml</code> file, mapping (<code>orm.xml</code>) files, and Java source files. The <code>JpaProject</code> also holds the ''context model'' that represents the JPA metadata, as derived from spec-defined defaults, Java source code annotations, and XML descriptors. A <code>JpaProject</code> can be obtained directly by ''adapting'' the corresponding Eclipse project:
 +
<pre>
 +
IProject project = ResourcesPlugin.getWorkspace().getRoot().getProject("Foo Project");
 +
JpaProject jpaProject = (JpaProject) project.getAdapter(JpaProject.class);
 +
</pre>
 +
The <code>JpaProject</code>'s context model is used to:
 +
* 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 <code>org.eclipse.jpt.common.utility.model.Model</code> interface.
 +
The "root" of the context model is the <code>JpaProject</code>'s <code>JpaContextRoot</code>. This root provides access to the project's single <code>PersistenceXml</code>, whose root XML element is a <code>Persistence</code>. 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 ''single'' <code>PersistenceUnit</code>.
  
 +
The <code>PersistenceUnit</code> holds the significant JPA mapping data:
 +
* mapping files (typicall <code>orm.xml</code> files)
 +
* JAR files
 +
* mapped Java classes
 +
* database connection settings
 +
* transaction settings
 +
In the case of a Java annotation-only project, the <code>PersistenceUnit</code> directly holds all the resolved <code>JavaManagedType</code>s (which are typically <code>JavaPersistentType</code>s). These are held by the <code>PersistenceUnit</code>'s <code>ClassRef</code>s, which each hold the corresponding  <code>JavaPersistentType</code> if the ref's class name can be resolved. Predictably, the <code>JavaPersistentType</code>s hold the <code>JavaPersistentAttribute</code>s.
  
===org.eclipse.jpt.doc.isv===
+
In the case of a project that maps Java types via mapping files (either exclusively or in addition to Java annotations), the <code>PersistenceUnit</code> directly holds all the resolved mapping files. These are held by the <code>PersistenceUnit</code>'s <code>MappingFileRef</code>s, which each hold the corresponding  <code>MappingFile</code> if the ref's file name can be resolved. Each mapping file holds a set of <code>PersistentType</code>s (typically <code>OrmPersistentType</code>s). Again, the <code>PersistentType</code>s hold the <code>PersistentAttribute</code>s. In addition, an <code>OrmPersistentType</code> holds a reference to its corresponding <code>JavaPersistentType</code>.
Description:  Javadoc plugin
+
  
No dependencies.
+
==== Examples ====
  
 +
* Traverse the ''context model'' for JPA metadata:
  
===org.eclipse.jpt.doc.user===
+
To access the JPA metadata for a type listed in the <code>persistence.xml</code> file:
Description: User docs and infopop for Dali
+
<pre>
 +
IProject.getAdapter(JpaProject.class) : JpaProject
 +
  JpaProject.getContextRoot() : JpaContextRoot
 +
    JpaContextRoot.getPersistenceXml() : PersistenceXml
 +
      PersistenceXml.getRoot() : 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<JavaSpecifiedPersistentAttribute>
 +
                JavaSpecifiedPersistentAttribute.getMapping() : JavaAttributeMapping
 +
</pre>
  
Dependency on (see plugin Manifest for details):
+
To access the JPA metadata for a type listed in an <code>orm.xml</code> file:
*org.eclipse.help
+
*org.eclipse.ui.cheatsheets
+
  
 +
<pre>
 +
...
 +
PersistenceUnit.getMappingFileRefs() : Iterable<MappingFileRef>
 +
  MappingFileRef.getMappingFile() : MappingFile
 +
    MappingFile.getPersistentTypes() : Iterable<PersistentType>
 +
...
 +
</pre>
  
===org.eclipse.jpt.gen===
+
* Retrieve the JPA Entities for a Project
Description:  Contains model and generator code for generating Entities from tables
+
  
Dependency on (see plugin Manifest for details):
+
<pre>
*eclipse.jpt.db
+
public static Iterable<PersistentType> getEntities(IProject project) {
*eclipse.jpt.core
+
    JpaProject jpaProject = (JpaProject) project.getAdapter(JpaProject.class);
*eclipse.jpt.utility
+
    if (jpaProject == null) {
 +
        return Collections.emptySet();
 +
    }
  
 +
    JpaContextRoot root = jpaProject.getContextRoot();
 +
    PersistenceXml persistenceXml = root.getPersistenceXml();
 +
    if (persistenceXml == null) {
 +
        return Collections.emptySet();
 +
    }
  
*eclipse.core
+
    Persistence persistence = persistenceXml.getRoot();
*eclipse.jdt.core
+
    if (persistence == null) {
 +
        return Collections.emptySet();
 +
    }
  
 +
    if (persistence.getPersistenceUnitsSize() == 0) {
 +
        return Collections.emptySet();
 +
    }
  
===org.eclipse.jpt.ui===
+
    PersistenceUnit persistenceUnit = persistence.getPersistenceUnit(0);
Description:  Contains the actions, composites, data models, wizards, views, and perspective that make up the Dali UI.
+
    ArrayList<PersistentType> entities = new ArrayList<PersistentType>();
 +
    for (PersistentType persistentType : persistenceUnit.getPersistentTypes()) {
 +
        if (persistentType.getMappingKey() == MappingKeys.ENTITY_TYPE_MAPPING_KEY) {
 +
            entities.add(persistentType);
 +
        }
 +
    }
 +
    return entities;
 +
}
 +
</pre>
  
Dependency on (see plugin Manifest for details):
+
* Modify the ''context model'' programatically
  
*org.eclipse.jpt.core
+
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 <code>JpaProjectManager.execute(Command, ExtendedCommandContext)</code>. 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 <code>SynchronousUiCommandContext.instance()</code>). (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).
*org.eclipse.jpt.db
+
*org.eclipse.jpt.db.ui
+
*org.eclipse.jpt.gen
+
*org.eclipse.jpt.utility
+
  
 +
=== UI ===
  
*org.eclipse.core
+
The main entry point for the Dali UI is the <code>JpaWorkbench</code>, which corresponds to the Eclipse workbench (i.e. <code>org.eclipse.ui.IWorkbench</code>). The <code>JpaWorkbench</code> can be obtained by ''adapting'' the Eclipse workbench:
*org.eclipse.draw2d
+
<pre>
*org.eclipse.emf
+
IWorkbench workbench = PlatformUI.getWorkbench();
*org.eclipse.jdt
+
JpaWorkbench jpaWorkbench = (JpaWorkbench) Platform.getAdapterManager().getAdapter(workbench, JpaWorkbench.class);
*org.eclipse.jem
+
</pre>
*org.eclipse.jface
+
'''NB:''' Even though <code>IWorkbench</code> extends <code>IAdaptable</code>, it does not delegate to the <code>Platform</code> adapter manager; so registered adapter factories are ''not'' used, and clients must directly use the <code>Platform</code> adapter manager.
*org.eclipse.jst
+
*org.eclipse.ui
+
*org.eclipse.wst
+
  
 +
The primary use of the <code>JpaWorkbench</code> is gaining access to the <code>JpaPlatformUiManager</code>. The <code>JpaPlatformUiManager</code> holds the current set of <code>JpaPlatformUi</code>s. Each <code>JpaPlatformUi</code> corresponds to a specific <code>JpaPlatform</code> and provides the UI components necessary to support the models derived from that <code>JpaPlatform</code>. The UI also provides behavior the various Dali menu commands and wizards.
  
===org.eclipse.jpt.utility===
+
== JAXB ==
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.
+
Under construction...
  
No Dependencies.
+
= Plug-ins =
  
 +
* <code>org.eclipse.jpt.*.core</code> - ''resource model'' and ''context model'' interfaces and implementations
 +
* <code>org.eclipse.jpt.jpa.db</code> - DTP wrapper model, Dali’s interface to the DTP database metadata model
 +
* <code>org.eclipse.jpt.jpa.db.ui</code> - Dali UI for DTP Connection Wizard
 +
* <code>org.eclipse.jpt.jpa.gen</code> - model and generator code for generating Entities from database tables
 +
* <code>org.eclipse.jpt.*.ui</code> - Dali UI actions, composites, data models, wizards, views, and perspectives
 +
* <code>org.eclipse.jpt.utility</code> - Dali utility classes: model/event/listener sets, iterables, closures, commands, transformers, predicates, factories, references, collections, value models, etc.
 +
* <code>org.eclipse.jpt.*.eclipselink.core</code> - EclipseLink extension, including an EclipseLink <code>JpaPlatform</code> and associated EclipseLink ''resource model'' and ''context model''.
 +
* <code>org.eclipse.jpt.*.eclipselink.ui</code> - EclipseLink UI extension, including an EclipseLink <code>JpaPlatformUI</code> and associated EclipseLink UI composites
 +
* <code>org.eclipse.jpt.*.core.tests</code> - headless JUnit plug-in test suites for the core plug-ins
 +
* <code>org.eclipse.jpt.utility.tests</code> - JUnit test suites for the utility plug-in
 +
* <code>org.eclipse.jpt.doc.isv</code> - Javadoc plug-in
 +
* <code>org.eclipse.jpt.doc.user</code> - Dali user docs and infopop
  
===org.eclipse.jpt.eclipselink.core===
+
= Major Integration points =
Description:  EclipseLink extension, including an EclipseLinkPlatform and the EclipseLink context model.
+
  
 +
== JPA ==
  
===org.eclipse.jpt.eclipselink.ui===
+
=== Eclipse Platform ===
Description:  EclipseLink UI extension, including an EclipseLinkPlatformUI and associated EclipseLink UI composites.
+
* Content types
 +
** <code>persistence.xml</code>
 +
** Mapping file/<code>orm.xml</code>
 +
* Markers (errors/warnings)
 +
* Refactoring participants
 +
* At startup, Dali adds a resource change listener to the Eclipse workspace:
 +
** detect the presence of JPA Facet on any workspace project
 +
** files added or removed from any workspace project
 +
** "clean" builds will trigger the rebuilding of the appropriate JPA projects
 +
=== JDT ===
 +
* At startup, Dali adds a Java element change listener to the Java model manager:
 +
** detect the presence of the JPA annotations in any Java source files
 +
** classpath changes will trigger the rebuilding of the appropriate JPA project
 +
* The Dali ''resource model'' makes extensive use of the JDT core model and utilities to manipulate Java source code.
 +
=== EMF ===
 +
* The Dali XML ''resource model'' is generated from an EMF model defined to correspond to the JPA XML files:
 +
** <code>persistence.xml</code>
 +
** <code>orm.xml</code>
 +
=== DTP ===
 +
* Manage database connections
 +
* Database metadata is used for validation and to populate drop-down list-boxes
 +
* Entity generation uses database metadata and the data definitino model
 +
* The Datasource Explorer view is part of the Dali Persistence Perspective
 +
=== WTP ===
 +
* Faceted Project Framework
 +
* EMF-XML Translator Framework
 +
* Validation Framework
 +
* Library providers
 +
=== Eclipse Platform UI ===
 +
* "New" wizards
 +
* JPA Perspective
 +
* Views
 +
** JPA Structure
 +
** JPA Details
 +
* JPA Project Properties
 +
* Project Explorer (Common Navigator)
 +
* Completion proposals (content assist, Intellisense)
 +
** Database metadata
 +
** JPQL
 +
* Commands/Handlers/Menus
 +
* Editors
 +
** <code>persistence.xml</code>
 +
** Mapping file/<code>orm.xml</code>
  
 +
== JAXB ==
 +
Under construction...
  
===org.eclipse.jpt.core.tests===
+
= Extension =
Description:  Contains a suite of headless JUnit tests for the core plug-in.
+
  
 +
== JPA ==
  
===org.eclipse.jpt.utility.tests===
+
=== JpaPlatform ===
Description:  Contains a comprehensive set of tests for the Utility classes.
+
  
==Major Integration points==
+
Dali's main extension mechanism is the JPA Platforms (<code>org.eclipse.jpt.jpa.core.jpaPlatforms</code>) extension point, which adopters can use to specify implementations of the <code>JpaPlatformFactory</code> interface.
  
===JDT===
+
The <code>JpaPlatformFactory</code> interface is to be implemented by a JPA adopter to provide extensions to the core JPA model. Dali supplies a JPA Platform that supports JPA spec-defined Java annotations, <code>persistence.xml</code> and mapping (<code>orm.xml</code>) files.  The <code>org.eclipse.jpt.jpa.core.generic</code> extension supplies ''resource models'' for those file types.
  
*The Dali Core makes extensive use of the JDT Core model and utilities for the purpose of reading and writing Java class metadata.
+
Example:
*Code Completion
+
  
===DTP===
+
<pre>
 +
<extension
 +
    point="org.eclipse.jpt.jpa.core.jpaPlatforms">
  
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.
+
    <jpaPlatform
 +
        id="generic"
 +
        label="%GENERIC_1_0_PLATFORM_LABEL"
 +
        factoryClass="org.eclipse.jpt.jpa.core.internal.GenericJpaPlatformFactory"
 +
        group="generic"
 +
        jpaFacetVersion="1.0"
 +
        default="false"/>
  
===WTP===
+
</extension>
*Facets
+
</pre>
*EMF-XML Translator Framework
+
  
===Platform===
+
Dali also provides an exemplary impelementation for EclipseLink which provides support for EclipseLink-specific Java annotations, <code>persistence.xml</code> settings and mapping file settings. See the <code>org.eclipse.jpt.jpa.eclipselink.core</code>) plug-in.
*Project Explorer
+
  
 +
=== JpaPlatformUi ===
  
==Extension Mechanism==
+
Similar to the JPA Platform, the Dali UI can be extended via the JPA Platform UIs (<code>org.eclipse.jpt.jpa.ui.jpaPlatformUis</code>) extension point, which adopters can use to specify implementations of the <code>JpaPlatformUiFactory</code> interface. This interface must be implemented for any models defined in a JPA Platform extension to be correctly displayed in the UI.
  
Dali's main extension mechanism is the JpaPlatform Interface and extension point.
+
<pre>
 +
<extension
 +
    point="org.eclipse.jpt.jpa.ui.jpaPlatformUis">
  
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.
+
    <jpaPlatformUi
 +
        id="generic.ui"
 +
        jpaPlatform="generic"
 +
        factoryClass="org.eclipse.jpt.jpa.ui.internal.platform.generic.GenericJpaPlatformUiFactory"/>
  
The extension designates a Platform ID, Label, Class (implemenation of JpaPlatform), and an option to set the platform as a "Default" platform.
+
</extension>
 +
</pre>
  
Extension Example:
+
== JAXB ==
  
<pre>
+
Under construction....
  <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>
+
</pre>
+
  
See the EclipseLinkPlatform included in Dali as an exemplary implementation.
+
= API =
  
==Statement on API==
+
''Provisional'' API is available as of the 2.0 release.
  
Provisional API is available as of the 2.0 release.
+
= Miscellaneous =
 +
Archives
 +
*[[Dali Developer Documentation v0.5]]

Latest revision as of 23:31, 22 June 2016

Repository

http://git.eclipse.org/c/dali/webtools.dali.git

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:

  • Add the appropriate Execution Environment to the host platform
    • Like the base Eclipse platform, Dali requires JavaSE-1.8
  • 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
      • GEF3 SDK (NB: not GEF4)
      • DTP SDK
      • EMF Transaction
      • EMF Validation
      • Graphiti
      • Orbit
      • WTP
    • Unzip all the downloaded files that are not update repositories:
      • Mac: Extract the Eclipse SDK Mac application bundle tar first; then unzip the non-repository files into the subdirectory Eclipse.app/Contents.
      • Eclipse SDK
      • EMF and XSD SDK
      • EMF Transaction
      • EMF Validation
  • 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 files)
          • Mac: Select the subdirectory Eclipse.app/Contents/Eclipse.
        • NB: The new location should indicate it has over 500 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 over 20 plug-ins available
      • <Add...> another location for the DTP repository
        • <Software Site>
        • <Add...> a new repository
          • <Archive...>
          • Select the just-downloaded DTP zip file
        • <Work with:> the just-added DTP repository
        • NB: Make sure <Group by Category> is checked.
        • Click on <Select All>
        • NB: The new location should indicate it has over 200 plug-ins available
      • <Add...> another location for the GEF repository
        • <Software Site>
        • <Add...> a new repository
          • <Archive...>
          • Select the just-downloaded GEF3 zip file
        • <Work with:> the just-added GEF3 repository
        • NB: Make sure <Group by Category> is checked.
        • Click on <Select All>
        • NB: The new location should indicate it has 20 plug-ins available
      • <Add...> another location for the WTP repository
        • <Software Site>
        • <Add...> a new repository
          • <Archive...>
          • Select the just-downloaded WTP zip file
        • <Work with:> the just-added WTP repository
        • NB: Make sure <Group by Category> is checked.
        • Click on <Select All>
        • NB: The new location should indicate it has over 500 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)
  • Clone the Eclipse Foundation-hosted Dali Git repository and import the Dali projects
    • Ensure the Eclipse network proxy is configured, if applicable (Preferences > General > Network Connections)
    • Open the Git perspective
    • Clone the Dali repository using the appropriate URL from http://git.eclipse.org/c/dali/webtools.dali.git
    • Import the plug-in and test plug-in projects in the repository's working directory (The projects are named org.eclipse.jpt.*.):
      • common/plugins - the *.branding projects are optional
      • common/tests
      • jaxb/plugins - the *.branding projects are optional
      • jaxb/tests
      • jpa/plugins - the *.branding projects are optional
      • jpa/tests
      • jpa_diagram_editor/plugins
      • jpa_diagram_editor/tests

JUnit Tests

Once the development workspace is configured and the Dali plug-ins built, it is possible to execute the Dali tests.

Generic JPA Core Tests

  • Add a run configuration (Run > Run Configurations... > JUnit Plug-in Test > New)
    • <Test> tab
      • <Run a single test>
        • Project: org.eclipse.jpt.jpa.core.tests
        • Test Class: org.eclipse.jpt.jpa.core.tests.internal.JptJpaCoreTests
      • Test Runner: JUnit 3 or 4
    • <Main> tab
      • <Program to run>
        • Run an application: [No Application] - Headless mode
    • <Arguments> tab
      • VM arguments:
-Xmx768M
-XX:MaxPermSize=256M
-Dorg.eclipse.jpt.jpa.jar=<path to jar containing javax.persistence packages>
  • <Run>

NB: These tests may take on the order of 30 minutes to complete.

EclipseLink JPA Core Tests

Duplicate the Generic JPA Core Tests configuration described above and make the following modifications:

  • <Test> tab
    • Project: org.eclipse.jpt.jpa.eclipselink.core.tests
    • Test class: org.eclipse.jpt.jpa.eclipselink.core.tests.internal.JptJpaEclipseLinkCoreTests
  • <Arguments> tab
    • Add the following VM argument:
-Dorg.eclipse.jpt.eclipselink.jar=<path to eclipselink.jar>

Generic JAXB Core Tests

Duplicate the Generic JPA Core Tests configuration described above and make the following modifications:

  • <Test> tab
    • Project: org.eclipse.jpt.jaxb.core.tests
    • Test class: org.eclipse.jpt.jaxb.core.tests.internal.JaxbCoreTests
  • <Arguments> tab
    • Add the following VM argument:
-Dorg.eclipse.jpt.jaxb.jar=<path to eclipselink.jar>

EclipseLink JAXB Core Tests

Duplicate the Generic JAXB Core Tests configuration described above and make the following modifications:

  • <Test> tab
    • Project: org.eclipse.jpt.jaxb.eclipselink.core.tests
    • Test class: org.eclipse.jpt.jaxb.eclipselink.core.tests.internal.ELJaxbCoreTests
  • <Arguments> tab
    • Add the following VM argument:
-Dorg.eclipse.jpt.jaxb.jar=<path to eclipselink.jar>
-Dorg.eclipse.jpt.eclipselink.jar=<path to eclipselink.jar>

Common Core Tests

Duplicate the Generic JPA Core Tests configuration described above and make the following modifications:

  • <Test> tab
    • Project: org.eclipse.jpt.common.core.tests
    • Test class: org.eclipse.jpt.common.core.tests.internal.JptCommonCoreTests

Common Utility Tests

  • Add a run configuration (Run > Run Configurations... > JUnit > New)
    • <Test> tab
      • <Run a single test>
        • Project: org.eclipse.jpt.common.utility.tests
        • Test Class: org.eclipse.jpt.common.utility.tests.internal.JptCommonUtilityTests

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

Dali provides content assistance for JPQL queries edited in a Java source file, an orm.xml file, or the JPA Details View.

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:

IWorkspace workspace = ResourcesPlugin.getWorkspace();
JpaWorkspace jpaWorkspace = (JpaWorkspace) workspace.getAdapter(JpaWorkspace.class);

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:

IProject project = ResourcesPlugin.getWorkspace().getRoot().getProject("Foo Project");
JpaProject jpaProject = (JpaProject) project.getAdapter(JpaProject.class);

The JpaProject's context model is used to:

  • 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 single PersistenceUnit.

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:

IProject.getAdapter(JpaProject.class) : JpaProject
  JpaProject.getContextRoot() : JpaContextRoot
    JpaContextRoot.getPersistenceXml() : PersistenceXml
      PersistenceXml.getRoot() : 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<JavaSpecifiedPersistentAttribute>
                JavaSpecifiedPersistentAttribute.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>
...
  • Retrieve 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();
    }

    JpaContextRoot root = jpaProject.getContextRoot();
    PersistenceXml persistenceXml = root.getPersistenceXml();
    if (persistenceXml == null) {
        return Collections.emptySet();
    }

    Persistence persistence = persistenceXml.getRoot();
    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 persistentType : persistenceUnit.getPersistentTypes()) {
        if (persistentType.getMappingKey() == MappingKeys.ENTITY_TYPE_MAPPING_KEY) {
            entities.add(persistentType);
        }
    }
    return entities;
}
  • Modify the context model programatically

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:

IWorkbench workbench = PlatformUI.getWorkbench();
JpaWorkbench jpaWorkbench = (JpaWorkbench) Platform.getAdapterManager().getAdapter(workbench, JpaWorkbench.class);

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.

JAXB

Under construction...

Plug-ins

  • org.eclipse.jpt.*.core - resource model and context model interfaces and implementations
  • org.eclipse.jpt.jpa.db - DTP wrapper model, Dali’s interface to the DTP database metadata model
  • org.eclipse.jpt.jpa.db.ui - Dali UI for DTP Connection Wizard
  • org.eclipse.jpt.jpa.gen - model and generator code for generating Entities from database tables
  • org.eclipse.jpt.*.ui - Dali UI actions, composites, data models, wizards, views, and perspectives
  • org.eclipse.jpt.utility - Dali utility classes: model/event/listener sets, iterables, closures, commands, transformers, predicates, factories, references, collections, value models, etc.
  • org.eclipse.jpt.*.eclipselink.core - EclipseLink extension, including an EclipseLink JpaPlatform and associated EclipseLink resource model and context model.
  • org.eclipse.jpt.*.eclipselink.ui - EclipseLink UI extension, including an EclipseLink JpaPlatformUI and associated EclipseLink UI composites
  • org.eclipse.jpt.*.core.tests - headless JUnit plug-in test suites for the core plug-ins
  • org.eclipse.jpt.utility.tests - JUnit test suites for the utility plug-in
  • org.eclipse.jpt.doc.isv - Javadoc plug-in
  • org.eclipse.jpt.doc.user - Dali user docs and infopop

Major Integration points

JPA

Eclipse Platform

  • Content types
    • persistence.xml
    • Mapping file/orm.xml
  • Markers (errors/warnings)
  • Refactoring participants
  • At startup, Dali adds a resource change listener to the Eclipse workspace:
    • detect the presence of JPA Facet on any workspace project
    • files added or removed from any workspace project
    • "clean" builds will trigger the rebuilding of the appropriate JPA projects

JDT

  • At startup, Dali adds a Java element change listener to the Java model manager:
    • detect the presence of the JPA annotations in any Java source files
    • classpath changes will trigger the rebuilding of the appropriate JPA project
  • The Dali resource model makes extensive use of the JDT core model and utilities to manipulate Java source code.

EMF

  • The Dali XML resource model is generated from an EMF model defined to correspond to the JPA XML files:
    • persistence.xml
    • orm.xml

DTP

  • Manage database connections
  • Database metadata is used for validation and to populate drop-down list-boxes
  • Entity generation uses database metadata and the data definitino model
  • The Datasource Explorer view is part of the Dali Persistence Perspective

WTP

  • Faceted Project Framework
  • EMF-XML Translator Framework
  • Validation Framework
  • Library providers

Eclipse Platform UI

  • "New" wizards
  • JPA Perspective
  • Views
    • JPA Structure
    • JPA Details
  • JPA Project Properties
  • Project Explorer (Common Navigator)
  • Completion proposals (content assist, Intellisense)
    • Database metadata
    • JPQL
  • Commands/Handlers/Menus
  • Editors
    • persistence.xml
    • Mapping file/orm.xml

JAXB

Under construction...

Extension

JPA

JpaPlatform

Dali's main extension mechanism is the JPA Platforms (org.eclipse.jpt.jpa.core.jpaPlatforms) extension point, which adopters can use to specify implementations of the JpaPlatformFactory interface.

The JpaPlatformFactory interface is to be implemented by a JPA adopter to provide extensions to the core JPA model. Dali supplies a JPA Platform that supports JPA spec-defined Java annotations, persistence.xml and mapping (orm.xml) files. The org.eclipse.jpt.jpa.core.generic extension supplies resource models for those file types.

Example:

<extension
    point="org.eclipse.jpt.jpa.core.jpaPlatforms">

    <jpaPlatform
        id="generic"
        label="%GENERIC_1_0_PLATFORM_LABEL"
        factoryClass="org.eclipse.jpt.jpa.core.internal.GenericJpaPlatformFactory"
        group="generic"
        jpaFacetVersion="1.0"
        default="false"/>

</extension>

Dali also provides an exemplary impelementation for EclipseLink which provides support for EclipseLink-specific Java annotations, persistence.xml settings and mapping file settings. See the org.eclipse.jpt.jpa.eclipselink.core) plug-in.

JpaPlatformUi

Similar to the JPA Platform, the Dali UI can be extended via the JPA Platform UIs (org.eclipse.jpt.jpa.ui.jpaPlatformUis) extension point, which adopters can use to specify implementations of the JpaPlatformUiFactory interface. This interface must be implemented for any models defined in a JPA Platform extension to be correctly displayed in the UI.

<extension
    point="org.eclipse.jpt.jpa.ui.jpaPlatformUis">

    <jpaPlatformUi
        id="generic.ui"
        jpaPlatform="generic"
        factoryClass="org.eclipse.jpt.jpa.ui.internal.platform.generic.GenericJpaPlatformUiFactory"/>

</extension>

JAXB

Under construction....

API

Provisional API is available as of the 2.0 release.

Miscellaneous

Archives

Back to the top