Difference between revisions of "EclipseLink/Building"

Revision as of 11:49, 31 July 2008

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.

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

• org.eclipse.persistence.dbws - EclipseLink's Database Webservice support
• plugins - The additional dependencies for DBWS support

Build

Importing the projects into Eclipse will build the class files for the components, but you may also want to do a full build of EclipseLink. The build runs in Ant. Here are the steps:

• Define a build.properties file in your user home directory. Define the following variables in it:
  • 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"

This will build the Runtime, the Utilities in the tests.

Testing

Tests can be run through Ant or in Eclipse

Note: Before running any tests that use JPA, you will have to run the build at least once. This creates some directories needed for testing and the jars that contain the JPA models. Please refresh your eclipselink.jpa.test project to pick these up before running the Testing Browser eclipse launch target.

= 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"
• 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"

From Eclipse

The following directories contain projects with tests

• foundation/eclipselink.core.test - the core testing for EclipseLink
  • Testing Browser.launch - runs legacy test browser. Requires definition of JDBC_LIB and TOOLS_LIB classpath variables.
  • SRGTestModel.launch - runs the SRG. Requires definition of JDBC_LIB classpath variable
  • LRGTestModel.launch - runs the LRG. Requires definition of JDBC_LIB and TOOLS_LIB classpath variables.
• foundation/eclipselink.extension.oracle.test - the testing for EclipseLink's Oracle-specific functionality.
  • Contains Testing Browser (Oracle).launch - Launches Legacy test browser in a manner that can run Legacy Oracle tests
• jpa/eclipselink.jpa.test - the JPA tests for EclipseLink
  • FullRegressionTestSuite.launch - runs JPA tests - requires updating the test.properties file in same 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.

The following is an slightly outdated overview:

1. org.eclipse.persistence.core depends on the following:
   1. moxy/plugins/javax.xml.bind
   2. plugins/javax.activation
   3. plugins/javax.ejb
   4. plugins/javax.jms
   5. plugins/javax.persistence
   6. plugins/javax.resource
   7. plugins/javax.transaction
   8. plugins/javax.xml.rpc
   9. plugins/javax.xml.soap
   10. plugins/javax.xml.stream
   11. plugins/org.eclipse.persistence.antlr
   12. plugins/org.eclipse.persistence.asm

1. org.eclipse.persistence.jpa depends on the following:
   1. org.eclipse.persistence.core - The Eclipse project defined in this folder
2. eclipselink.core.test should have all its dependencies already set but provides an ant build that sets up some xml files to run
3. eclipselink.jpa.test should have all its dependencies already set but provides an ant build to build persistence units for testing
4. eclipselink.extension.oracle depends on a selection of jars from Oracle products. In order to build this project you will need to obtain all these jars. As a result the class files from this project are checked in so they can be used by people that do not have those jars
   1. Jars:
      1. aqapi.jar - Oracle Advanced Queue
      2. sdoapi.jar - Oracle Spatial API
      3. An oracle JDBC driver
      4. xdb.jar - XDB
      5. xml.jar - Oracle XML support
      6. xmlparserv2.jar - Oracle XML parser
   2. Projects
      1. eclipselink.core depends on the same jars as foundation/extension.oracle and as a result, it has also had class files checked in
5. eclipselink.extension.oracle.test depends on
   1. eclipselink.extension.oracle
   2. eclipselink.core.test
   3. org.eclipse.persistence.jpa
6. org.eclipse.persistence.moxy depends on the following:
   1. org.eclipse.persistence.core
7. eclipselink.moxy.test depends on the following:
   1. org.eclipse.persistence.moxy
   2. org.eclipse.persistence.core
   3. Eclipse Library JUnit 3 - this is already configured, but there have been issues with Eclipse version 3.2 where the library needs to be reselected in order for JUnit to be picked up properly.
8. eclipselink.sdo depends on the following:
   1. org.eclipse.persistence.core
9. eclipselink.sdo.test depends on the following:
   1. org.eclipse.persistence.sdo
   2. org.eclipse.persistence.core
   3. TOOLS_LIB variable has been mapped to your JDK tools.jar for a runtime dependency
   4. Eclipse Library JUnit 3 - this is already configured, but there have been issues with Eclipse version 3.2 where the library needs to be reselected in order for JUnit to be picked up properly.

Migrating Eclipse Projects to PDE as of 20080430

There is a new PDE structure being finalized that will require a rebuild of all existing EclipseLink projects in Eclipse. See [EclipseLink/Development/EclipseLinkPDEConversionPlan http://wiki.eclipse.org/EclipseLink/Development/EclipseLinkPDEConversionPlan]

These notes will be incorporated into the main doc and formalized when this process is complete.

• Migrating Eclipse Projects to PDE #2 as of 20080508 - currently editing
• This section is for developers that did the initial PDE refresh after 20080430.
  • Remove existing lib projects and reimport as plugin projects (delete project but not workspace contents)
    • All javax.*, org.apache.*, org.*antlr, org.*.asm
  • Perform actions below

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

1. Prerequisites
   1. Eclipse 3.3+ EE version required - you will need the EE version of eclipse
      1. Internal: eclipse-jee-europa-winter-win32, eclipse-jee-europa-fall2-win32 or eclipse-jee-ganymede-M6-win32
   2. Remove any existing eclipselink.* projects (delete project but not workspace contents)
   3. Note: eclipselink.*.test projects are not migrated yet, these can be retained
   4. Keep existing classpath variables
2. Update SVN at the <trunk> root
3. Importing Projects
   1. Import | General | Existing projects into Workspace
      1. root directory = <trunk>/plugins
      2. Leave "Copy projects into workspace" unselected
      3. select all of javax.* and org.*
   2. Import jpa/plugins/javax.persistence
   3. Import foundation projects in the same way
   4. Import jpa projects in the same way
   5. Import moxy/plugins projects so jpa test project compiles
   6. Import sdo/plugins
   7. Refresh/Rebuild
      1. If automatic build is not checked - check it and clean all projects
   8. core dependency on jpa lib project
      1. see javax.persistence;bundle-version="1.99.0";visibility:=reexport in the core project
      2. 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.
4. Building
   1. Run ant at the <trunk> root so that all the test project jars are updated and built
   2. BUILD SUCCESSFUL Total time: 8 minutes 4 seconds
5. Running
   1. Test the build by running test.jpa
   2. <trunk>/ant test-jpa
   3. 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)
      1. db.platform=org.eclipse.persistence.platform.database.oracle.Oracle11Platform
      2. Normally we do not set a dependecy on the platform though - this will be fixed shortly in our script.
      3. [junit] Tests run: 911, Failures: 0, Errors: 1, Time elapsed: 583.35 sec Total time: 10 minutes 4 Seconds
6. See the following (I get 1 error locally that can be ignored)
   1. C:\view_w34\jpa\eclipselink.jpa.test\reports\junit-noframes.html
7. Refresh eclipse workspace to optionally run the testing browser targets
8. Pending:
9. Launch Targets

Port TODO List

List of task, items, issues, refactorig left to due from the initial port.

• Get all tests passing. - JPA JUnit tests and legacy LRG model currently pass
• Move left-over internal classes to internal packages.
• Internationalization.
• Server tests.
• Sun Corba and RMI-IIOP - are these elements still required in EclipseLink. If so, make sure tests work. Else, remove.
• Make all server platforms work. i.e. address the fact that they all need to be reflective to compile

How To

• General prerequisites for building & running EclipseLink tests
• Make changes to ANTLR generated JPA code
• Run the legacy LRG
• Run the JPA Junit tests
• Run the MOXy Junit tests
• Run the SDO Junit tests
• Automated/Scripted SVN checkout
• Optimize SVN