Revision as of 15:20, 12 August 2009

Contents

SVN Structure

At the moment, all code can be found in the org.eclipse.persistence/trunk directory on the technology SVN server.

Runtime

The below is a description of the content of the directories. Note: All projects are Eclipse PDE projects and therefore classpath dependencies are defined in the manifest rather than the project metadata.

Plugins

The plugins directory contains all the common dependencies needed by all the projects. You can make use of them by either importing the Eclipse projects for all the depenencies or by copying the bundle jars (all the jars) in this directory in your Eclipse installation's plugin's directory. Note: The org.eclipse.persistence.asm and org.eclipse.persistence.antlr jars are not checked in and must be either be built by running the EclipseLink build or imported as projects.

Foundation

org.eclipse.persistence.core - All other EclipseLink components depend on this bundle. You will need to import this project to work on other EclipseLink components. All other components can be imported separately.

org.eclipse.persistence.oracle - extensions that require Oracle-specific libraries for compilation. If you do not have the required oracle libraries, you can get the compiled classes since they are checked in. This bundle is only used for advanced Oracle-specific functionality and not required unless you are using that functionality.

The oracle bundle requires that you configure the oracle target within your Eclipse. To do that, you will need to do the following:

Find the target.oracle directory in foundation/targets

Import the oracle.libs directory and its contents into Eclipse (In Ganymede, that means copying oracle.libs and its contents into your Eclipse dropins directory)

Obtain the Oracle dependency jars. There is a list of them in the manifest found in oracle.libs. Note: These are not currently available in open-source format and you will have to obtain them from Oracle

Put those jars in the oracle.libs directory you have copied to Eclipses

Restart Eclipse

JPA

org.eclipse.persistence.jpa - EclipseLink's JPA support

plugins - The additional dependencies for JPA support

org.eclipse.persistence.equinox - fragment for OSGi weaving on Equinox that plugs into org.eclispe.persistence.jpa. Only required for people doing weaving on Equinox

org.eclipse.persistence.equinox.weaving - fragment for OSGi weaving on Equinox that plugs into Equinox itself. Only required for people doing weaving on Equinox

MOXY

org.eclipse.persistence.moxy - EclipseLink's Object-XML support

plugins - The additional dependencies for Object-XML support

SDO

org.eclipse.persistence.sdo - EclipseLink's SDO support

plugins - The additional dependencies for SDO support

DBWS

Build

Importing the projects into Eclipse will build the class files for the PDE projects. Most functionality will be accessible after those builds. If you want to do a complete build of EclipseLink, here are the steps:

It may be necessary to create a user specific properties file to override the default values in <trunk>/build.properties. To do so, create a build.properties file in your user home directory (usually C:\Documents and Settings\<username> on windows). Variables commonly needing redefinition in it are:

For build:

junit.lib=<full path of junit 4 jar>

For Test

tools.lib=<full path of tools jar in your JDK installation - usually in JAVA_HOME/lib>

jdbc.driver=<full path to your JDBC driver>

db.driver=<classname of your JDBC driver>

db.url=<JDBC url of your DB>

db.user=<db username>

db.pwd=<db password>

(optional) db.platform=<EclipseLink Database Platform to use> - this is only necessary if EclipseLink does not properly dectect you DB with its database detection

Ensure you have ant 1.7 set up to run

Open a command prompt in your checked out trunk directory

Run "ant" for a full build of all core and test code

or

Run "ant build-eclipselink-jar" for a full build of only core code

These commands will build the Runtime and/or the tests. Tests can also be run by adding a test execution target (like test-srg).

Note: Several DBWS component's build files are dependant upon JDK 1.6 (JDK 5 can be used but these components won't build)

Testing

Tests can be run through Ant or in Eclipse

From Ant

In the trunk directory, you can use the following targets to run tests:

test-srg - Basic "smoke tests"

test-lrg - Full test model - must be run sucessfully on either MySQL or Oracle before checking in any changes to core classes

test-core - subset of tests just for the core

test-core-srg - smoke tess for the core

test-jpa - runs JPA tests - required prior to check-in for any changes to JPA included in "test-lrg"

JPA tests require some artifacts from the build in order to be able to run. There are two ways to get them.

Run the full build as indicated above

From the org.eclipse.persistence.jpa directory, run "ant"

This will create a directory required by the tests and the jars that contain the models. You only need to rebuild if you are adding or subtracting from the models (Package org.eclipse.persistence.testing.models.jpa and its subpackages).

test-moxy - runs MOXY tests - required prior to check-in for any changes to MOXY included in "test-lrg"

test-jaxb - required prior to check-in for any changes to JAXB included in "test-moxy"

test-oxm - required prior to check-in for any changes to OXM included in "test-moxy"

test-sdo - required prior to check-in for any changes to SDO included in "test-lrg"

update the test.properties file in jpa/eclipselink.jpa.test directory to point at correct DB

Testing Browser (JPA).launch - Launches Legacy test browser in a manner that can run JPA tests through that browser

jpa/eclipselink.spring.test - Spring specific JPA testing

moxy/eclipselink.moxy.test - MOXY testing

sdo/eclipselink.sdo.test - SDO testing

dbws/eclipselink.dbws.test - DBWS Testing

Projects and Dependencies

When using the Eclipse IDE - a Europa or later EE version is required. If you are using OSGi, a Ganymede EE version is required. See the Eclipse download site for information [www.eclipse.org/downloads]

All current dependencies can be found in the manifests for the PDE projects or in the bundles.

PDE Conversion

The following is inforation about our work to convert to PDE projects and is still here for people that had EclipseLink projects before our conversion. All other developers should be able to ignore it.

Note: If you are getting compilation errors that are due to a missing plugin like javax.resource or javax.jms - and you have these projects in your workspace. The fix seems to be to delete these projects (not the filesystem) and reimport the project with the problem as well as the plugin that it is complaining it cannot find - together in a single import (from the <root>).

Prerequisites

Eclipse 3.3+ EE version required - you will need the EE version of eclipse

Note: eclipselink.*.test projects are not migrated yet, these can be retained

Keep existing classpath variables

Update SVN at the <trunk> root

Importing Projects

Import | General | Existing projects into Workspace

root directory = <trunk>/plugins

Leave "Copy projects into workspace" unselected

select all of javax.* and org.*

Import jpa/plugins/javax.persistence

Import foundation projects in the same way

Import jpa projects in the same way

Import moxy/plugins projects so jpa test project compiles

Import sdo/plugins

Refresh/Rebuild

If automatic build is not checked - check it and clean all projects

core dependency on jpa lib project

see javax.persistence;bundle-version="1.99.0";visibility:=reexport in the core project

If you get a compile error on javax.persistence it is because we are referencing the 1.99 version instead of 1.0 in the manifest of org.eclipse.persistence.core - make sure the jpa project javax.persistence.1.99 is loaded in your workspace.

Building

Run ant at the <trunk> root so that all the test project jars are updated and built

BUILD SUCCESSFUL Total time: 8 minutes 4 seconds

Or run ant build-eclipselink-jar at the <trunk> root so that all the non-test projects are compiled and eclipselink.jar is built in under 60 seconds.

BUILD SUCCESSFUL Total time: 8 minutes 4 seconds

Running

Test the build by running test.jpa

<trunk>/ant test-jpa

Note: if db.platform is not set in your <user-home>/test.properties then you may get a "ClassNotFoundException: ${db.platform}" - set this variable as follows (using your own platform)