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

Dali Developer Documentation

Revision as of 13:01, 16 September 2013 by Brian.vosburgh.oracle.com (Talk | contribs) (Terminology)

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:

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. Installing and using a 1.5 JRE/JDK reduces the possibility of any errors slipping through (e.g. using classes or methods added in later versions of Java). The host platform can be run on a later version of Java; but the Dali plug-ins must be compiled against and capable of executing on Java 1.5. Each Dali project's build path and project-specific Java compiler settings ensure Dali is compiled with Java 1.5 compliance; but there must be a Java 1.5 installation present for the compiler to compile against the correct Java jars.
    • NB: As of the Luna release, parts of the Eclipse Platform needed by Dali require a Java 1.6 Execution Environment. As a result, Dali requires a Java 1.6 Execution Environment to execute. Despite this requirement, Dali will continue to be compiled against and require only a Java 1.5 Execution Environment, until an irresistable Java feature compels Dali to move to a higher version of Java.
  • 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)
  • 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 Repository Exploring 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 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.

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.

Entity generation from tables

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

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.

Design

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 Structure

UI Structure

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.

Core Dali Plug-ins

org.eclipse.jpt.*.core

Description: Resource model and Context model interfaces and implementations

org.eclipse.jpt.jpa.db

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

org.eclipse.jpt.jpa.db.ui

Description: Dali UI for DTP Connection Wizard

org.eclipse.jpt.doc.isv

Description: Javadoc plugin

org.eclipse.jpt.doc.user

Description: User docs and infopop for Dali

org.eclipse.jpt.jpa.gen

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

org.eclipse.jpt.*.ui

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

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-ins.

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

EMF

DTP

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

WTP

  • Facets
  • EMF-XML Translator Framework
  • Validation Framework

Platform

  • Project Explorer

Extension

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

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

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

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.

API

Provisional API is available as of the 2.0 release.

Miscellaneous

Archives

Back to the top