Jump to: navigation, search

Difference between revisions of "EclipseLink/Building"

(Environment Setup)
(Environment Setup)
 
(23 intermediate revisions by 7 users not shown)
Line 1: Line 1:
== SVN Structure ==
+
== Git Structure ==
  
At the moment, all code can be found in the org.eclipse.persistence/trunk directory on the technology SVN server.
+
EclipseLink code has migrated from SVN to Git. The SVN repository has been split into several repositories. The repository list, descriptions, and urls can be found at: http://git.eclipse.org under the EclipseLink project list.
  
 
=== Runtime===
 
=== Runtime===
Line 9: Line 9:
 
==== Plugins ====
 
==== 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.
+
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 making the bundle jars (all the jars) in this directory available to Eclipse's target platform.  You can do that by adding a directory that contains those jars to your Target Platform under "Preferences -> Plug-in Development -> Target Platform", or by copying them to your Eclipse installation's plugin's directory.
  
 
The following dependencies can also be obtained from [http://wiki.eclipse.org/index.php/Orbit_Faq Orbit].
 
The following dependencies can also be obtained from [http://wiki.eclipse.org/index.php/Orbit_Faq Orbit].
Line 33: Line 33:
 
** The oracle bundle requires that you configure the oracle target within your Eclipse.  To do that, you will need to do the following:
 
** 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
 
*** 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 and put them into oracle.libs folder.  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
*** 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
+
*** Import the target.oracle directory and its contents into Eclipse as a Plug-in fragment
*** Put those jars in the oracle.libs directory you have copied to Eclipses
+
*** Restart Eclipse
+
  
 
==== JPA ====
 
==== JPA ====
Line 42: Line 40:
 
* org.eclipse.persistence.jpa - EclipseLink's JPA support
 
* org.eclipse.persistence.jpa - EclipseLink's JPA support
 
* plugins - The additional dependencies for 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 ====
 
==== MOXY ====
Line 64: Line 60:
 
Importing the projects into Eclipse will build the class files for the PDE projects. Most functionality will be accessible after those builds.  Ant files are also provided both for use in a non-Eclipse IDE, and for commandline use.  If you want to do a complete build of the EclipseLink artifacts, the steps are outlined In the "building with Ant"  section below.
 
Importing the projects into Eclipse will build the class files for the PDE projects. Most functionality will be accessible after those builds.  Ant files are also provided both for use in a non-Eclipse IDE, and for commandline use.  If you want to do a complete build of the EclipseLink artifacts, the steps are outlined In the "building with Ant"  section below.
  
=== Ant ===
+
==== Building with Ant ====
 
Ant is used to drive all builds for the EclipseLink Project. Furthermore, it is assumed that EclipseLink will be built (ant tested) in environments other than the Eclipse IDE (PDE build). Therefore, the Ant buildfiles are designed to be used from many entry points with varying configurations. However, starting with 2.4, we have moved to a manifest-first approach to build our OSGi bundles. Therefore, rather than using BND to generate the OSGi manifest post build we are using Tycho (a maven plugin) to generate our OSGi bundles.
 
Ant is used to drive all builds for the EclipseLink Project. Furthermore, it is assumed that EclipseLink will be built (ant tested) in environments other than the Eclipse IDE (PDE build). Therefore, the Ant buildfiles are designed to be used from many entry points with varying configurations. However, starting with 2.4, we have moved to a manifest-first approach to build our OSGi bundles. Therefore, rather than using BND to generate the OSGi manifest post build we are using Tycho (a maven plugin) to generate our OSGi bundles.
  
===== Building with Ant =====
 
 
Below are the steps to setup for and then run a basic build of EclipseLink using the Ant buildfiles from the trunk.
 
Below are the steps to setup for and then run a basic build of EclipseLink using the Ant buildfiles from the trunk.
  
====== Environment Setup ======
+
===== Environment Setup =====
 
Most of the required dependencies are already existent in one of the previously discussed plugin folders. However, there are some third-party files that are not supplied. Specifically:
 
Most of the required dependencies are already existent in one of the previously discussed plugin folders. However, there are some third-party files that are not supplied. Specifically:
* Ant '''1.7.x'''. Our build scripts don't work properly under 1.8. If not already installed, you will need to download and install it. Make sure you have an "ANT_HOME" env variable that points to the installation, and a "JAVA_HOME" variable that points to your Java installation.
+
* Ant 1.9.x for 2.6.0, Ant 1.7 for earlier versions.
* Junit
+
** Our build scripts don't work properly under 1.8.  
* Any library licensed under an agreement that is not EPL or Eclipse approved. (This includes Oracle libraries needed to compile oracle specific extensions)
+
** If not already installed, you will need to download and install it.
* Maven 3. Tycho requires Maven 3 functionality. So to build EclipseLink 2.4 and beyond you will need to download and install it if it is not already installed. <font color="red">'''***Important***</font> Make sure you set an "M2_HOME" env variable that points to the installation.'''
+
* Maven 3 for EclipseLink 2.4+ (Tycho requires Maven 3 functionality).
 +
** If not already installed, you will need to download and install it.
 +
* Make sure you have an "ANT_HOME", "M2_HOME" and "JAVA_HOME" environment variables pointing to appropriate folders.
 +
* Junit 4.11 (or higher)
 +
* JMockit 1.10
 +
* Any library licensed under an agreement that is not EPL or Eclipse approved. This includes Oracle libraries and 3rd party libraries needed to compile specific extensions
 
* [http://www.aqute.biz/Code/Download#bnd BND] tool '''(2.3.x and earlier only)'''- we use bnd to generate our OSGi plugins in EclipseLink 2.3.x and earlier. Version .366 or later should work fine if placed in the extension.depend.dir or the buildsystem dir. In addition, if bnd is not available the build will attempt to generate meaningful OSGi manifests, but there are known shortcomings and issues with this approach.  
 
* [http://www.aqute.biz/Code/Download#bnd BND] tool '''(2.3.x and earlier only)'''- we use bnd to generate our OSGi plugins in EclipseLink 2.3.x and earlier. Version .366 or later should work fine if placed in the extension.depend.dir or the buildsystem dir. In addition, if bnd is not available the build will attempt to generate meaningful OSGi manifests, but there are known shortcomings and issues with this approach.  
**Add the following entry to your '''user-dir/build.properties''' as of 20100513
+
**Add the following entry to your '''user-dir/build.properties'''  
***<font color="red">''bndtool.jar=bnd-0.0.384.jar''</font>
+
***<font color="red">''bndtool.jar=bnd-0.0.384.jar''</font> as of 20100513
 +
***<font color="red">''bndtool.lib=bnd-0.0.384.jar''</font> as of at least 2.4.2
  
The build provides mechanisms to incorporate these dependencies outside of SVN.
+
 
 +
The build provides mechanisms to incorporate these dependencies outside of Git.
 
build defaults: The build assumes certain defaults for dependencies. These can be overridden, but are provided to allow minimal configuration setup.
 
build defaults: The build assumes certain defaults for dependencies. These can be overridden, but are provided to allow minimal configuration setup.
* external dependency location: The build assumes that all dependant libraries external to SVN are store in one of two default locations.
+
* external dependency location: The build assumes that all dependant libraries external to Git are stored in one of two default locations.
 
* extensions.depend.dir: This property defines where external dependencies can be found. (default: .\trunk\..\extension.lib.external)
 
* extensions.depend.dir: This property defines where external dependencies can be found. (default: .\trunk\..\extension.lib.external)
 
* oracle.extensions.depend.dir: This is a legacy property for compatability with Oracle testing scripts. It is used to define the location of  Oracle specific jars. (default: .\trunk\..\extension.oracle.lib.external)
 
* oracle.extensions.depend.dir: This is a legacy property for compatability with Oracle testing scripts. It is used to define the location of  Oracle specific jars. (default: .\trunk\..\extension.oracle.lib.external)
 
* library properties: Most dependant libraries are defined using a property definition that can be overridden
 
* library properties: Most dependant libraries are defined using a property definition that can be overridden
  
====== Overriding Defaults ======
+
===== Overriding Defaults =====
  
 
Basic Setup
 
Basic Setup
 
* 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:
 
* 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:
 
** For build:
*** junit.lib=<full path of the [http://sourceforge.net/projects/junit/files/junit/4.5/junit-4.5.jar/download JUnit 4.5 (latest version)] jar>
+
*** junit.lib=[http://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22junit%22%20AND%20a%3A%22junit%22 $YOUR_JUNIT_DIR/junit.jar:$YOUR_JUNIT_DIR/hamcrest-core-1.3.jar]
 
** For Test
 
** For Test
*** tools.lib=<full path of tools jar in your JDK installation - usually in JAVA_HOME/lib>
 
 
*** jdbc.driver.jar=<full path to your JDBC driver>
 
*** jdbc.driver.jar=<full path to your JDBC driver>
 
*** db.driver=<classname of your JDBC driver>
 
*** db.driver=<classname of your JDBC driver>
Line 101: Line 102:
 
*** db.pwd=<db password>
 
*** 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
 
*** (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
 
* Open a command prompt in your checked out trunk directory
 
* Run "ant" '''(or "ant -f antbuild.xml" in 2.4 or later)''' for a full build of all core and test code
 
* Run "ant" '''(or "ant -f antbuild.xml" in 2.4 or later)''' for a full build of all core and test code
Line 110: Line 110:
  
 
Note: Several DBWS component's build files are dependant upon JDK 1.6 (JDK 5 can be used but these components won't build)
 
Note: Several DBWS component's build files are dependant upon JDK 1.6 (JDK 5 can be used but these components won't build)
 +
 +
== Updating dependencies ==
 +
In order to update EclipseLink's dependencies, take these steps:
 +
 +
# Prepare the dependency bundle. All product dependencies need to be OSGi bundles: so they need an OSGi manifest, and to be named appropriately: <bundleprefix>_<bundleversion>.<builddate>.jar.
 +
# Verify the bundle by building the EclipseLink with it:
 +
## Override the default remote compdeps setting to "local.compdeps=true" in your $home/build.properties file.
 +
## Add the new bundle to /plugins or /<module>/plugins (as appropriate).
 +
## Update antbuild.xml in buildsystem/compdeps.
 +
## Update features.xml in buildsystem/compdeps/org.eclipse.persistence.compdeps.
 +
## Update your module's MANIFEST.MF file to Import-Package your new dependency.
 +
# Once your plugin passes the build, you need to create a CQ (e.g. https://dev.eclipse.org/ipzilla/show_bug.cgi?id=8334). If you are on a tight schedule, I recommend doing this step ahead of the others, since it may take some time before the CQ is approved.
 +
# When the CQ is approved, create a bug on eclipse (e.g. https://bugs.eclipse.org/bugs/show_bug.cgi?id=438761) and submit a patch containing the changes.
 +
# After the patch is pushed, contact the EL Releng team and ask them to update the p2 index.
 +
 +
For more detailed description see:
 +
* [[/UpdatingDependencies |Updating Dependencies page]]
  
 
== Testing ==
 
== Testing ==
Line 116: Line 133:
  
 
=== From Ant ===
 
=== From Ant ===
Make sure you are using the latest (''at least v20090423'') version of [http://sourceforge.net/projects/junit/files/junit/4.5/junit-4.5.jar/download JUnit 4.5 ]
 
 
In the trunk directory, you can use the following targets to run tests:
 
In the trunk directory, you can use the following targets to run tests:
  
Line 139: Line 155:
  
 
* foundation/eclipselink.core.test - the core testing for EclipseLink
 
* 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.
+
** Testing Browser.launch - runs legacy test browser.  Requires definition of JDBC_LIB classpath variables.
 
** SRGTestModel.launch - runs the SRG.  Requires definition of JDBC_LIB classpath variable
 
** 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.
+
** LRGTestModel.launch - runs the LRG. Requires definition of JDBC_LIB classpath variables.
 
* foundation/eclipselink.extension.oracle.test - the testing for EclipseLink's Oracle-specific functionality.  
 
* 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
 
** Contains Testing Browser (Oracle).launch - Launches Legacy test browser in a manner that can run Legacy Oracle tests
Line 156: Line 172:
 
* sdo/eclipselink.sdo.test - SDO testing
 
* sdo/eclipselink.sdo.test - SDO testing
 
* dbws/eclipselink.dbws.test - DBWS Testing
 
* dbws/eclipselink.dbws.test - DBWS Testing
====Minimum SVN Trunk projects for JPA or Core Eclipse Development and Testing====
+
 
*The following import screen capture from Eclipse 3.5 for the SVN trunk details the minimum projects you will need on top of the ''10 Orbit'' projects in order to do JPA or Core development in Eclipse.
+
====Minimum GIT projects for JPA or Core EclipseLink project Development and Testing====
[[Image:Minimum_svn_trunk_projects_for_jpa_core_development.JPG]]
+
* The following import screen capture from Eclipse 4.4 details the minimum projects you will need in order to do JPA or Core development in Eclipse.
*Note: Also add the  
+
[[file:Eclipselink-projects-corejpa.png]]
**org.eclipse.persistence.moxy project (a requirement of eclipselink.jpa.test)
+
* Before importing any test project into Eclipse, make sure you run full Ant build in order to let Eclipse resolve local test related dependencies
**org.eclipse.persistence.moxy.dynamic (a requirement of moxy.test)
+
* The following screens details the minimum test projects related to JPA and/or Core development in Eclipse.
 +
[[file:Eclipselink-projects-corejpa-tests.png]]
 +
*Note: Also add the org.eclipse.persistence.moxy project (a requirement of eclipselink.jpa.test)
 +
*Note: Also define "ECLIPSELINK_HOME" classpath variable (Java | Build Path | Classpath Variables) pointing to your local Git clone root folder
  
 
== Projects and Dependencies ==
 
== 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 http://www.eclipse.org/downloads
+
When using the Eclipse IDE - a Luna or later EE version is required. See the Eclipse download site for information http://www.eclipse.org/downloads
 +
 
 +
All current dependencies can be found in the manifests for the PDE projects or in the bundles or in Problems view in Eclipse IDE.
 +
 
 +
== Alternative IDEs ==
 +
 
 +
=== IntelliJ IDEA ===
 +
 
 +
This guide has been built using IntelliJ IDEA version 13 on Windows.
 +
 
 +
==== Prerequisites ====
 +
 
 +
* [http://www.oracle.com/technetwork/java/javase/downloads/index-jsp-138363.html Java 7/8 SDK]
 +
* [http://git-scm.com/downloads Git client]
 +
* [http://search.maven.org/remotecontent?filepath=org/hamcrest/hamcrest-core/1.3/hamcrest-core-1.3.jar hamcrest-core-1.3.jar]
 +
* [http://search.maven.org/remotecontent?filepath=junit/junit/4.11/junit-4.11.jar junit.jar]
 +
* [http://search.maven.org/remotecontent?filepath=org/apache/ant/ant/1.9.4/ant-1.9.4.jar ant.jar]
 +
 
 +
==== Downloading eclipselink sources ====
 +
 
 +
Under '''VCS''' menu, select '''Checkout from Version Control''' and '''Git''' version control system. In the dialogue window that opens, enter '''git@orahub.oraclecorp.com:fmw-infra-toplink/eclipselink-runtime.git''' URL, fill in '''Parent Directory''' and '''Directory Name''' fields  and click the '''Clone''' button. This process may take a while to complete.
 +
 
 +
[[File:Git_clone_IDEA.jpg]]
 +
 
 +
- ''For Parent Directory and Directory Name combination it is advised to not enter a long path in case of importing the project in a Windows system. A Parent Directory of C:\dev and Directory Name of eclipselink is enough.''
 +
 
 +
- ''You should click Test to verify connection settings. In case of failure, check whether a proxy server should be used. It should be enough to select Auto-detect proxy settings under IDE Settings - File menu -> Settings -> IDE Settings -> HTTP Proxy -> Auto-detect proxy settings.''
 +
 
 +
==== Setting up IDEA project ====
 +
 
 +
After downloading sources, a dialogue appears to create an IntelliJ IDEA project from the source files downloaded. Select '''Import project from external model''' and '''Eclipse'''. Clicking '''Next''' will initiate a scan of source files and a list of available projects will be displayed. Click '''Unselect all''' and select the following projects:
 +
 
 +
* eclipselink.core.test
 +
* eclipselink.jpa.modelgen.test
 +
* eclipselink.jpa.test
 +
* eclipselink.moxy.test
 +
* org.eclipse.persistence.core
 +
* org.eclipse.persistence.jpa
 +
* org.eclipse.persistence.moxy
 +
* org.eclipse.persistence.moxy.dynamicxjc
 +
* org.eclipse.persistence.nosql
 +
 
 +
- ''You can import additional projects at any time selecting Import Module… dialogue under File menu''
 +
 
 +
You will then be asked to select the project SDK. Select a Java 7 or Java 8 SDK and click '''Finish'''. At this point IDEA will create an '''ECLIPSE''' library. You need to provide the '''path to the eclipse installation'''. For '''ECLIPSELINK_HOME''' and '''MAVEN_REPOSITORY''' path variables, enter the '''project root''' directory and '''path to .m2/repository (M2_HOME)''' respectively.
 +
 
 +
==== Configuring project ====
 +
 
 +
Under '''File''' menu, select '''Project Structure'''. Inside '''Project''' panel, '''Change Project language level''' to '''7.0'''.
 +
 
 +
[[File:Project_sdk.jpg]]
 +
 
 +
Inside '''Modules''' panel, for every project module you need to '''change Module SDK''' to '''Project SDK''' and click '''OK'''.
 +
 
 +
[[File:Module_dependencies.jpg]]
 +
 
 +
- ''(Language level change will require a project re-import to apply)''
 +
 
 +
At this point, we need to run an ant build for test dependencies to be created.
 +
 
 +
Initially, a folder needs to be created at the same level as the project root called '''extension.lib.external''' (<project root>/../extension.lib.external). Files '''hamcrest-core-1.3.jar''' and '''junit.jar''' (a file rename may be needed) will need to be copied to that location.
 +
 
 +
Then, a user specific properties file needs to be created in the user home directory. To do so, create a '''build.properties''' file in your '''user home directory''' (usually C:\Documents and Settings\<username> on Windows) adding the following line:
 +
 
 +
'''junit.lib=<path to extension.lib.external>/junit.jar:<path to extension.lib.external>/hamcrest-core-1.3.jar'''
 +
 
 +
Now, in '''Project''' panel, find '''antbuild.xml''' file and '''right click''', selecting '''Add as Ant Build File'''. Build targets will appear in Ant Build panel.
 +
 
 +
[[File:Ant_panel.jpg]]
 +
 
 +
Double click '''build''' target and wait for the build process to finish.
 +
 
 +
[[File:Build_messages.jpg]]
 +
 
 +
- ''(You can check the progress of the build in Messages panel)''
 +
 
 +
After build has finished successfully, open '''Project Structure''' dialogue again and correct broken jar paths for '''eclipselink.jpa.modelgen.test''' module. For every broken path, click '''Add''' button and find the applicable jar file under '''<project root>/jpa/eclipselink.jpa.test'''. After adding the correct file, you may '''Remove''' the broken link.
 +
 
 +
[[File:Jpa_test_dependency.jpg]]
 +
 
 +
For '''org.eclipse.persistence.core''' module, click '''Add''' and select '''Jars or directories'''. Under '''<project root>/plugins''', select the following files:
 +
 
 +
* javax.persistence_2.1.0.v201304241213.jar
 +
* org.eclipse.persistence.antlr_3.2.0.v201302191141.jar
 +
* org.eclipse.persistence.jpa.jpql_2.6.0.qualifier.jar
 +
 
 +
For '''org.eclipse.persistence.jpa''' module, click '''Add''' and select '''Jars or directories'''. Under '''<project root>/jpa/plugins''' select '''javax.persistence_2.1.0.v201304241213.jar''' and under '''extension.lib.external''' select '''ant.jar'''.
 +
 
 +
For '''org.eclipse.persistence.moxy''' module, click '''Add''' and select '''Jars or directories'''. Under '''<project root>/plugins''', select the following files:
 +
 
 +
* javax.validation_1.1.0.v201304101302.jar
 +
* jaxb-core_2.2.11.v201407311112.jar
 +
* jaxb-xjc_2.2.11.v201407311112.jar
 +
 
 +
For '''org.eclipse.persistence.nosql''' module, click '''Add''' and select '''Module Dependency'''. Select module '''org.eclipse.persistence.core''' and click '''OK'''.
 +
 
 +
For '''eclipselink.jpa.test''' module, click '''Add''', select '''Jars or directories''' and select the path to '''hamcrest-core-1.3.jar''' and click '''OK'''.
 +
 
 +
At this point you should be able to select '''Make Project''' under '''Build''' menu without errors.
 +
 
 +
==== Directly importing IDEA project ====
 +
 
 +
Instead of setting up eclipselink project from scratch, there is also the possibility of importing eclipselink IDEA project found within the project source files.
 +
 
 +
Under '''File menu''', click '''Open''' and select the '''project root directory'''. This will import a project structure similar to the one described in the steps above. Since additional project modules are configured in this case, as a prerequisite, there is needed an existing [https://www.oracle.com/database/index.html Oracle Database] installation. After installing the database, along with extension.lib.external folder, an additional '''extension.oracle.lib.external''' folder will need to be created. This folder will need to contain the following dependencies from the database installation:
 +
 
 +
* dms.jar ''(<database home>/oc4j/lib)''
 +
* ojdbc7.jar ''(<database home>/jdbc)''
 +
* sdoapi.jar ''(<database home>/md/jlib)''
 +
* ucp.jar ''(<database home>/ucp/lib)''
 +
* xdb.jar ''(<database home>/RDBMS/jlib)''
 +
* xmlparserv2.jar ''(<database home>/LIB)''
 +
 
 +
When loading up the project, IDEA will display a warning about '''ECLIPSELINK_HOME''', '''EXTENSION_LIB_EXTERNAL''' and '''EXTENSION_ORACLE_LIB_EXTERNAL''' variables. For fixing this, you may '''click on the error message''' or navigate to '''Settings''' under '''File''' menu and select '''Path Variables''' under '''IDE Settings'''. Enter the '''path to the project root''' and the paths to '''extension.lib.external''' and '''extension.oracle.lib.external''' folders respectively and click '''OK'''.
 +
 
 +
Under '''File''' menu, select '''Project Structure''' option. In '''Project''' section, you need to select an SDK as the '''Project SDK''' or setup one if none exists.
 +
 
 +
==== Running unit tests ====
 +
 
 +
You can either run unit tests using the applicable ant build script targets (test-srg, test-lrg) or creating run configurations for the test groups you wish to execute.
 +
 
 +
===== '''Test using ant targets''' =====
 +
 
 +
For running the unit test ant targets, you will need to provide the '''path to the test.properties file to use'''. Right click on the '''ant file to edit''' under '''Ant Build''' section and select '''Properties'''. Under '''Execution''' tab, you need to add the following entry to the '''Ant command line''' field: '''-Dtest.properties=<path_to_file>'''.
  
All current dependencies can be found in the manifests for the PDE projects or in the bundles.
+
[[File:Ant_properties.jpg]]
  
== PDE Conversion ==
+
- ''(The path is relevant to the project configuration file. This will be the project root.)''
  
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.
+
After setting up the test property file to use, clicking on any test target ('''test-srg''', '''test-lrg''' etc.) will start executing the unit tests for that target. You may follow the test output under '''Messages''' panel.
  
There is a new PDE structure being finalized that will require a rebuild of all existing EclipseLink projects in Eclipse.
+
===== '''Test using build configurations''' =====
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.
+
For creating test configurations, under '''Run''' menu, select '''Edit Configurations…''' option. Click on '''Add New Configuration''' (the green plus sign on the top left corner) and select '''JUnit''' from the drop down menu. In '''Configuration''' tab, select '''Class''' if you are planning to run a '''single''' test/test suite, otherwise '''Pattern''' if you are planning to execute '''multiple''' test/test suite classes at once.
  
*Migrating Eclipse Projects to PDE #2 as of 20080508 - currently editing
+
[[File:Run_configuration.jpg]]
*<font color="green">This section is for developers that did the initial PDE refresh after 20080430.</font>
+
**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
+
  
<font color="red">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>).</font>
+
In '''VM options''' section, you should add the following entries:
  
#Prerequisites
+
* -Xmx1024M
##Eclipse 3.3+ EE version required - you will need the EE version of eclipse
+
* -Djava.security.manager
###Internal: eclipse-jee-europa-winter-win32, eclipse-jee-europa-fall2-win32 or eclipse-jee-ganymede-M6-win32
+
* -Djava.security.policy=($MODULE_DIR$/)<path to permissions file>  
##Remove any existing eclipselink.* projects (delete project but not workspace contents)
+
* -Dtest.properties=($MODULE_DIR$/)<path to test.properties file>
##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)
+
###db.platform=org.eclipse.persistence.platform.database.oracle.Oracle11Platform
+
###Normally we do not set a dependecy on the platform though - this will be fixed shortly in our script.
+
###[junit] Tests run: 911, Failures: 0, Errors: 0, Time elapsed: 583.35 sec Total time: 10 minutes 4 Seconds
+
#Refresh eclipse workspace to optionally run the testing browser targets
+
#'''Pending:'''
+
#Launch Targets
+
  
== Port TODO List ==
+
- ''(It is advised to enter a path relative to the module directory, although an absolute path is acceptable as well.)''
  
List of task, items, issues, refactorig left to due from the initial port.
+
As the '''Working directory''', enter '''$MODULE_DIR$\<path_to_run_folder>''' and select the '''module you wish to execute tests on''' for '''Use classpath of module''' field. In '''Before launch''' section, you may add ant targets to execute prior to running the tests (clean, build, clear-db). Click '''OK''' to leave the dialogue.
* 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 ==
+
It is important at this point to setup the classpath for running unit tests. Under '''File''' menu, select '''Project Structure''' option. In '''Modules''' section, for every module the tests of which you need to execute, you need to enter the '''jdbc''' client jar to use with a '''Runtime''' scope. You then need to setup the rest of the classpath. For module '''eclipselink.core.test''' for example, you need to include paths to '''/run''' folder, '''eclipselink-coretest-framework.jar''' and '''eclipselink-core-tests.jar''' within the module directory, as well as the path to '''tools.jar''' JDK library (JAVA_HOME/lib).
* [[EclipseLink/Building/64bit| EclipseLink 64 Bit Development]]
+
* [[EclipseLink/Source|Get EclipseLink Source]]
+
* [[EclipseLink/Development/Testing/Prereq| General prerequisites for building & running EclipseLink tests]]
+
* [[EclipseLink/Build/Antlr| Make changes to ANTLR generated JPA code]]
+
* [[EclipseLink/Test/LRG| Run the legacy LRG]]
+
* [[EclipseLink/Test/JPA| Run the JPA Junit tests]]
+
* [[EclipseLink/Development/TestStatus/MOXy-Instructions| Run the MOXy Junit tests]]
+
* [[EclipseLink/Development/TestStatus/SDO-Instructions| Run the SDO Junit tests]]
+
* [[EclipseLink/Building/Automate| Automated/Scripted SVN checkout ]]
+
* [[EclipseLink/Building/Optimize| Optimize SVN ]]
+
  
 +
[[File:Eclipselink.core.test_classpath.jpg]]
  
 +
At this point, you should be able to '''select the configuration to execute''' and click on '''Run''' or '''Debug'''. If you have selected to run some ant targets prior to the tests, you may monitor their progress in the '''Messages''' panel. When the tests start executing, the Run or Debug panel will automatically expand to display the tests progress.
  
[[Category:EclipseLink|Building]]
+
For being able to '''run tests simply by right clicking on the test target''', you may alter the default JUnit configuration. Under '''Run''' menu, select '''Edit Configurations…''' option. Expand '''Defaults''' and select '''JUnit'''. Enter '''VM options''', '''Working directory''' and '''Before launch''' configurations as advised above and click '''OK'''. Provided that the module classpath is correctly setup as advised above, you should now be able to '''right click a test target''' and select '''Run <target_name>'''.

Latest revision as of 04:20, 8 December 2014

Git Structure

EclipseLink code has migrated from SVN to Git. The SVN repository has been split into several repositories. The repository list, descriptions, and urls can be found at: http://git.eclipse.org under the EclipseLink project list.

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 making the bundle jars (all the jars) in this directory available to Eclipse's target platform. You can do that by adding a directory that contains those jars to your Target Platform under "Preferences -> Plug-in Development -> Target Platform", or by copying them to your Eclipse installation's plugin's directory.

The following dependencies can also be obtained from Orbit.

  • commonj.sdo 2.1.1
  • javax.activation 1.1.0
  • javax.mail 1.4.0
  • javax.persistence 1.0.0
  • javax.servlet 2.4.0
  • javax.wsdl 1.6.2
  • javax.xml.bind 2.0.0
  • javax.xml.rpc 1.1.0
  • javax.xml.stream 1.0.1
  • javax.xml.ws 2.1.0
  • org.apache.ant 1.7.0

Instructions about getting bundles from Orbit

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
      • Obtain the Oracle dependency jars and put them into oracle.libs folder. 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
      • Import the target.oracle directory and its contents into Eclipse as a Plug-in fragment

JPA

  • org.eclipse.persistence.jpa - EclipseLink's JPA support
  • plugins - The additional dependencies for JPA support

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 PDE projects. Most functionality will be accessible after those builds. Ant files are also provided both for use in a non-Eclipse IDE, and for commandline use. If you want to do a complete build of the EclipseLink artifacts, the steps are outlined In the "building with Ant" section below.

Building with Ant

Ant is used to drive all builds for the EclipseLink Project. Furthermore, it is assumed that EclipseLink will be built (ant tested) in environments other than the Eclipse IDE (PDE build). Therefore, the Ant buildfiles are designed to be used from many entry points with varying configurations. However, starting with 2.4, we have moved to a manifest-first approach to build our OSGi bundles. Therefore, rather than using BND to generate the OSGi manifest post build we are using Tycho (a maven plugin) to generate our OSGi bundles.

Below are the steps to setup for and then run a basic build of EclipseLink using the Ant buildfiles from the trunk.

Environment Setup

Most of the required dependencies are already existent in one of the previously discussed plugin folders. However, there are some third-party files that are not supplied. Specifically:

  • Ant 1.9.x for 2.6.0, Ant 1.7 for earlier versions.
    • Our build scripts don't work properly under 1.8.
    • If not already installed, you will need to download and install it.
  • Maven 3 for EclipseLink 2.4+ (Tycho requires Maven 3 functionality).
    • If not already installed, you will need to download and install it.
  • Make sure you have an "ANT_HOME", "M2_HOME" and "JAVA_HOME" environment variables pointing to appropriate folders.
  • Junit 4.11 (or higher)
  • JMockit 1.10
  • Any library licensed under an agreement that is not EPL or Eclipse approved. This includes Oracle libraries and 3rd party libraries needed to compile specific extensions
  • BND tool (2.3.x and earlier only)- we use bnd to generate our OSGi plugins in EclipseLink 2.3.x and earlier. Version .366 or later should work fine if placed in the extension.depend.dir or the buildsystem dir. In addition, if bnd is not available the build will attempt to generate meaningful OSGi manifests, but there are known shortcomings and issues with this approach.
    • Add the following entry to your user-dir/build.properties
      • bndtool.jar=bnd-0.0.384.jar as of 20100513
      • bndtool.lib=bnd-0.0.384.jar as of at least 2.4.2


The build provides mechanisms to incorporate these dependencies outside of Git. build defaults: The build assumes certain defaults for dependencies. These can be overridden, but are provided to allow minimal configuration setup.

  • external dependency location: The build assumes that all dependant libraries external to Git are stored in one of two default locations.
  • extensions.depend.dir: This property defines where external dependencies can be found. (default: .\trunk\..\extension.lib.external)
  • oracle.extensions.depend.dir: This is a legacy property for compatability with Oracle testing scripts. It is used to define the location of Oracle specific jars. (default: .\trunk\..\extension.oracle.lib.external)
  • library properties: Most dependant libraries are defined using a property definition that can be overridden
Overriding Defaults

Basic Setup

  • 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:
    • For Test
      • jdbc.driver.jar=<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
  • Open a command prompt in your checked out trunk directory
  • Run "ant" (or "ant -f antbuild.xml" in 2.4 or later) for a full build of all core and test code
  • or
  • use the "build-eclipselink-jar" task 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)

Updating dependencies

In order to update EclipseLink's dependencies, take these steps:

  1. Prepare the dependency bundle. All product dependencies need to be OSGi bundles: so they need an OSGi manifest, and to be named appropriately: <bundleprefix>_<bundleversion>.<builddate>.jar.
  2. Verify the bundle by building the EclipseLink with it:
    1. Override the default remote compdeps setting to "local.compdeps=true" in your $home/build.properties file.
    2. Add the new bundle to /plugins or /<module>/plugins (as appropriate).
    3. Update antbuild.xml in buildsystem/compdeps.
    4. Update features.xml in buildsystem/compdeps/org.eclipse.persistence.compdeps.
    5. Update your module's MANIFEST.MF file to Import-Package your new dependency.
  3. Once your plugin passes the build, you need to create a CQ (e.g. https://dev.eclipse.org/ipzilla/show_bug.cgi?id=8334). If you are on a tight schedule, I recommend doing this step ahead of the others, since it may take some time before the CQ is approved.
  4. When the CQ is approved, create a bug on eclipse (e.g. https://bugs.eclipse.org/bugs/show_bug.cgi?id=438761) and submit a patch containing the changes.
  5. After the patch is pushed, contact the EL Releng team and ask them to update the p2 index.

For more detailed description see:

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-wdf - runs the "WDF" JPA test suite (JPA tests contributed by SAP (Walldorf, Germany)).
  • 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 classpath variables.
    • SRGTestModel.launch - runs the SRG. Requires definition of JDBC_LIB classpath variable
    • LRGTestModel.launch - runs the LRG. Requires definition of JDBC_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
    • See the description of the test-jpa target above for a prerequisite.
    • FullRegressionTestSuite.launch - runs JPA tests
      • Needs DB properties to run. either of the following can be done to give the DB properties:
        • Add a JVM argument: -Dtest.properties=<full path to build.properties in your user home>
        • 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
      • Note: Recompilation of eclipselink.jpa.test test jars are required only if new classes were added/deleted since the last build.
  • 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

Minimum GIT projects for JPA or Core EclipseLink project Development and Testing

  • The following import screen capture from Eclipse 4.4 details the minimum projects you will need in order to do JPA or Core development in Eclipse.

Eclipselink-projects-corejpa.png

  • Before importing any test project into Eclipse, make sure you run full Ant build in order to let Eclipse resolve local test related dependencies
  • The following screens details the minimum test projects related to JPA and/or Core development in Eclipse.

Eclipselink-projects-corejpa-tests.png

  • Note: Also add the org.eclipse.persistence.moxy project (a requirement of eclipselink.jpa.test)
  • Note: Also define "ECLIPSELINK_HOME" classpath variable (Java | Build Path | Classpath Variables) pointing to your local Git clone root folder

Projects and Dependencies

When using the Eclipse IDE - a Luna or later EE version is required. See the Eclipse download site for information http://www.eclipse.org/downloads

All current dependencies can be found in the manifests for the PDE projects or in the bundles or in Problems view in Eclipse IDE.

Alternative IDEs

IntelliJ IDEA

This guide has been built using IntelliJ IDEA version 13 on Windows.

Prerequisites

Downloading eclipselink sources

Under VCS menu, select Checkout from Version Control and Git version control system. In the dialogue window that opens, enter git@orahub.oraclecorp.com:fmw-infra-toplink/eclipselink-runtime.git URL, fill in Parent Directory and Directory Name fields and click the Clone button. This process may take a while to complete.

Git clone IDEA.jpg

- For Parent Directory and Directory Name combination it is advised to not enter a long path in case of importing the project in a Windows system. A Parent Directory of C:\dev and Directory Name of eclipselink is enough.

- You should click Test to verify connection settings. In case of failure, check whether a proxy server should be used. It should be enough to select Auto-detect proxy settings under IDE Settings - File menu -> Settings -> IDE Settings -> HTTP Proxy -> Auto-detect proxy settings.

Setting up IDEA project

After downloading sources, a dialogue appears to create an IntelliJ IDEA project from the source files downloaded. Select Import project from external model and Eclipse. Clicking Next will initiate a scan of source files and a list of available projects will be displayed. Click Unselect all and select the following projects:

  • eclipselink.core.test
  • eclipselink.jpa.modelgen.test
  • eclipselink.jpa.test
  • eclipselink.moxy.test
  • org.eclipse.persistence.core
  • org.eclipse.persistence.jpa
  • org.eclipse.persistence.moxy
  • org.eclipse.persistence.moxy.dynamicxjc
  • org.eclipse.persistence.nosql

- You can import additional projects at any time selecting Import Module… dialogue under File menu

You will then be asked to select the project SDK. Select a Java 7 or Java 8 SDK and click Finish. At this point IDEA will create an ECLIPSE library. You need to provide the path to the eclipse installation. For ECLIPSELINK_HOME and MAVEN_REPOSITORY path variables, enter the project root directory and path to .m2/repository (M2_HOME) respectively.

Configuring project

Under File menu, select Project Structure. Inside Project panel, Change Project language level to 7.0.

Project sdk.jpg

Inside Modules panel, for every project module you need to change Module SDK to Project SDK and click OK.

Module dependencies.jpg

- (Language level change will require a project re-import to apply)

At this point, we need to run an ant build for test dependencies to be created.

Initially, a folder needs to be created at the same level as the project root called extension.lib.external (<project root>/../extension.lib.external). Files hamcrest-core-1.3.jar and junit.jar (a file rename may be needed) will need to be copied to that location.

Then, a user specific properties file needs to be created in the user home directory. To do so, create a build.properties file in your user home directory (usually C:\Documents and Settings\<username> on Windows) adding the following line:

junit.lib=<path to extension.lib.external>/junit.jar:<path to extension.lib.external>/hamcrest-core-1.3.jar

Now, in Project panel, find antbuild.xml file and right click, selecting Add as Ant Build File. Build targets will appear in Ant Build panel.

Ant panel.jpg

Double click build target and wait for the build process to finish.

Build messages.jpg

- (You can check the progress of the build in Messages panel)

After build has finished successfully, open Project Structure dialogue again and correct broken jar paths for eclipselink.jpa.modelgen.test module. For every broken path, click Add button and find the applicable jar file under <project root>/jpa/eclipselink.jpa.test. After adding the correct file, you may Remove the broken link.

Jpa test dependency.jpg

For org.eclipse.persistence.core module, click Add and select Jars or directories. Under <project root>/plugins, select the following files:

  • javax.persistence_2.1.0.v201304241213.jar
  • org.eclipse.persistence.antlr_3.2.0.v201302191141.jar
  • org.eclipse.persistence.jpa.jpql_2.6.0.qualifier.jar

For org.eclipse.persistence.jpa module, click Add and select Jars or directories. Under <project root>/jpa/plugins select javax.persistence_2.1.0.v201304241213.jar and under extension.lib.external select ant.jar.

For org.eclipse.persistence.moxy module, click Add and select Jars or directories. Under <project root>/plugins, select the following files:

  • javax.validation_1.1.0.v201304101302.jar
  • jaxb-core_2.2.11.v201407311112.jar
  • jaxb-xjc_2.2.11.v201407311112.jar

For org.eclipse.persistence.nosql module, click Add and select Module Dependency. Select module org.eclipse.persistence.core and click OK.

For eclipselink.jpa.test module, click Add, select Jars or directories and select the path to hamcrest-core-1.3.jar and click OK.

At this point you should be able to select Make Project under Build menu without errors.

Directly importing IDEA project

Instead of setting up eclipselink project from scratch, there is also the possibility of importing eclipselink IDEA project found within the project source files.

Under File menu, click Open and select the project root directory. This will import a project structure similar to the one described in the steps above. Since additional project modules are configured in this case, as a prerequisite, there is needed an existing Oracle Database installation. After installing the database, along with extension.lib.external folder, an additional extension.oracle.lib.external folder will need to be created. This folder will need to contain the following dependencies from the database installation:

  • dms.jar (<database home>/oc4j/lib)
  • ojdbc7.jar (<database home>/jdbc)
  • sdoapi.jar (<database home>/md/jlib)
  • ucp.jar (<database home>/ucp/lib)
  • xdb.jar (<database home>/RDBMS/jlib)
  • xmlparserv2.jar (<database home>/LIB)

When loading up the project, IDEA will display a warning about ECLIPSELINK_HOME, EXTENSION_LIB_EXTERNAL and EXTENSION_ORACLE_LIB_EXTERNAL variables. For fixing this, you may click on the error message or navigate to Settings under File menu and select Path Variables under IDE Settings. Enter the path to the project root and the paths to extension.lib.external and extension.oracle.lib.external folders respectively and click OK.

Under File menu, select Project Structure option. In Project section, you need to select an SDK as the Project SDK or setup one if none exists.

Running unit tests

You can either run unit tests using the applicable ant build script targets (test-srg, test-lrg) or creating run configurations for the test groups you wish to execute.

Test using ant targets

For running the unit test ant targets, you will need to provide the path to the test.properties file to use. Right click on the ant file to edit under Ant Build section and select Properties. Under Execution tab, you need to add the following entry to the Ant command line field: -Dtest.properties=<path_to_file>.

Ant properties.jpg

- (The path is relevant to the project configuration file. This will be the project root.)

After setting up the test property file to use, clicking on any test target (test-srg, test-lrg etc.) will start executing the unit tests for that target. You may follow the test output under Messages panel.

Test using build configurations

For creating test configurations, under Run menu, select Edit Configurations… option. Click on Add New Configuration (the green plus sign on the top left corner) and select JUnit from the drop down menu. In Configuration tab, select Class if you are planning to run a single test/test suite, otherwise Pattern if you are planning to execute multiple test/test suite classes at once.

Run configuration.jpg

In VM options section, you should add the following entries:

  • -Xmx1024M
  • -Djava.security.manager
  • -Djava.security.policy=($MODULE_DIR$/)<path to permissions file>
  • -Dtest.properties=($MODULE_DIR$/)<path to test.properties file>

- (It is advised to enter a path relative to the module directory, although an absolute path is acceptable as well.)

As the Working directory, enter $MODULE_DIR$\<path_to_run_folder> and select the module you wish to execute tests on for Use classpath of module field. In Before launch section, you may add ant targets to execute prior to running the tests (clean, build, clear-db). Click OK to leave the dialogue.

It is important at this point to setup the classpath for running unit tests. Under File menu, select Project Structure option. In Modules section, for every module the tests of which you need to execute, you need to enter the jdbc client jar to use with a Runtime scope. You then need to setup the rest of the classpath. For module eclipselink.core.test for example, you need to include paths to /run folder, eclipselink-coretest-framework.jar and eclipselink-core-tests.jar within the module directory, as well as the path to tools.jar JDK library (JAVA_HOME/lib).

Eclipselink.core.test classpath.jpg

At this point, you should be able to select the configuration to execute and click on Run or Debug. If you have selected to run some ant targets prior to the tests, you may monitor their progress in the Messages panel. When the tests start executing, the Run or Debug panel will automatically expand to display the tests progress.

For being able to run tests simply by right clicking on the test target, you may alter the default JUnit configuration. Under Run menu, select Edit Configurations… option. Expand Defaults and select JUnit. Enter VM options, Working directory and Before launch configurations as advised above and click OK. Provided that the module classpath is correctly setup as advised above, you should now be able to right click a test target and select Run <target_name>.