Skip to main content

Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

EclipseLink/Development/Testing/JPA

Running the JPA tests

The JPA tests can be run in J2SE and JEE, using several ways. Following section 1.1, 1.2 and 1.3 demonstrate how to run J2SE tests with following three different ways, section 1.4 "Server testing" demonstrates how to run JPA tests in JEE with ANT.

Ant

The eclipselink.jpa.test/antbuild.xml contains several ant targets for testing. The "test" target will run the JPA LRG. Ensure that the eclipselink.jpa.test/test.properties file has been configured for your database and environment. You may overwrite this file in {user.home}/test.properties. 

 ant -f antbuild.xml test

This will run the JPA LRG, the results will be output into the eclipselink.jpa.test/reports directory as html.

The following ant test targets are defined:

  • test (runs FullRegressionTestSuite using agent)
  • test-no-weave (runs FullRegressionTestSuite without any weaving)
  • test-static-weave (runs FullRegressionTestSuite with static weaving)
  • test-srg (runs the JPA SRG)
  • test-lrg (runs the JPA LRG)

Eclipse JUnit

The JPA test suite is written using JUnit. It consists of a set of jars that contain various persistence units and a number of tests. The JPA tests are contained in the eclipselink.jpa.test project. The current minimum version level is JUnit 4.5 (Which ships in Galileo).

  1. Ensure you have an eclipselink jar available in your local Git clone root folder. This jar is created by running the ant build located in your local Git clone root folder (ant -f antbuild.xml).
  2. Run the antbuild.xml in base directory of eclipselink.jpa.test. This will create a set of jar files containing the persistence units.
  3. Edit eclipselink.jpa.test/test.properties to include information necessary to connect to your database
  4. Use the JUnit run target provided, or create your own:
    1. The project will be: eclipselink.jpa.test
    2. The test class will be: org.eclipse.persistence.testing.tests.jpa.FullRegressionTestSuite
    3. Add the JVM argument "-javaagent:<eclipselink-jar-location>/eclipselink.jar" - This will allow the test models to run with weaving enabled
    4. Add to your classpath the following:
      1. Your JDBC driver
      2. A library that includes all the jar files generated by the antbuild.xml in eclipselink.jpa.test you ran earlier
  5. Run the run/debug target you created

Testing Browser

The JPA tests can also be run through the foundation Testing Browser. This provides additional debugging capabilities so is sometimes desired. There are some JPA tests that extend the foundation test framework, which are not run through the normal JUnit test target. The "JPA Tests" in the Testing Browser include these tests.

Note: Before testing in Eclipse using the Testing Browser - you will need to a full root build of EclipseLink in 'trunk>ant' so that the test jars eclipse*model.jar get created and placed on the root of jpa/eclipselink.jpa.test. Please refresh your eclipselink.jpa.test project to pick these up before running the Testing Browser eclipse launch target.

The eclipselink.jpa.test Eclipse project contains a launch file for running the testing browser. The database login information and logging level can be configured. If you have previously run the JPA tests on the same database the "Fast" checkbox can be used to avoid recreating the database.

Running JPA tests against Application Servers Using Ant

The JPA tests can be run on any JEE EJB 3 compatible server. Currently you can run JPA tests on the following application servers, using the provided Ant targets:

  • BEA Weblogic Server 9.x, 10.x
  • IBM Websphere 6.x, 7.x
  • Oracle OC4J 10.1.3.x
  • JBoss 5.x (cv/eap)
  • GlassFish v2, v3
  • SAP NetWeaver 7.x

It may be helpful for you to review the following documentation before continuing with these instructions. The links below will introduce you to the EclipseLink build and test system, and how to integrate EclipseLink with various application servers:

Pre-requisites

Please make sure your environment is set up with the following before starting:

  1. Java VM 1.6+  is installed on your local environment.
  2. ANT 1.7+ is installed on your local environment.
  3. EclipseLink source tree (/trunk) is available in local folder. See this link for information on how to acquire the EclipseLink source. You can use TortoiseSVN to check out and manage the source code.
  4. Target application server is installed (Please note additional configuration steps for different app servers). You typically do not need to perform any additional server configuration post-install. Take note of the install location as you will need to provide this information later.
  5. You have user access to a relational database, and JDBC driver files are available.

Files and Directories

  • <trunk> : the root of the EclipseLink source tree.
  • <trunk>/antbuild.xml : top-level Ant build file for EclipseLink product. You will need to re-build EclipseLink before running the tests by executing 'ant -f antbuild.xml' in this directory
  • <trunk>/eclipselink.jar : the product bits in which the JPA tests run against.
  • <trunk>/../extension.lib.external : This is a directory that you must create and it resides at the same level as <trunk>. You will need to put build dependent JAR files in this directory.
  • <trunk>/../extension.oracle.lib.external : Similar to extension.lib.external, but used for Oracle specific dependent jars.
  • <trunk>/jpa/eclipselink.jpa.test : JPA test root. All the relevant Ant build files and property files reside here along with the JPA test source code. We will refer to this as <jpa_test_root> for short.
  • <jpa_test_root>/antbuild.xml : top-level Ant build file for building, deploying, and executing JPA tests on application servers.
  • <jpa_test_root>/antbuild.properties : Ant properties file for build.xml. You typically do not need to modify this file.
  • <jpa_test_root>/test.properties : Additional Ant properties file read by build.xml. It contains test-related properties for customizing the test run, such as the database connection info, desired logging level, etc... You will have to modify this file.
  • <jpa_test_root>/{appserver}.xml : Server-specific Ant build files for each supported application server.  Example: weblogic.xml, websphere.xml.  The build files contain targets for server specific actions such as setup, start, deploy, undeploy, reset, and stop. They are called from <jpa_test_root>/build.xml
  • <jpa_test_root>/{appserver}.properties : Ant properties file for corresponding {appserver}.xml. You will need to modify this file, typically with the application server install directory.
  • <jpa_test_root>/setenv.cmd [.sh] : Convenience script for setting environment variables before executing the tests, such as JAVA_HOME, ANT_HOME, and PATH. You will need to modify this file and execute it in your shell window, or set the environment variables manually in your shell.
  • <user_home> : User's home directory. On Linux, this should be defined by the $HOME env variable. On Windows, this is typically mapped to c:\Documents and Settings\{login name}.

Configuration

1. Verify proper installation of pre-requisite applications - Ant, Java VM, and the target application server. Note that there are additional install instructions for some application servers at the end of this document. Take note the install locations for each of these applications.

2 a) Set JAVA_HOME, ANT_HOME, and PATH environment variables in your shell window. The first two variables should be self explanatory. Set your PATH to $ANT_HOME/bin:$JAVA_HOME/bin:$PATH or something similar in your target OS (for Windows, %ANT_HOME%\bin;....). Note : the JAVA_HOME setting determines which JVM is used to start the application server when you execute the server-start target; tor some application servers such as WebLogic and Websphere you may want to use their own JVM version instead of the Sun JVM.

2 b) If you are using ANT version 1.6 or older, copy your JUnit jar file to $ANT_HOME/lib.

2 c) If you are testing against Websphere, you must set JAVA_HOME to the JVM included with Websphere - $WAS_HOME/java

3. Create the following directories: <trunk>/../extension.lib.external and <trunk>/../extension.oracle.lib.external. For example, if your <trunk> directory is c:\eclipselink\src\trunk, then create directories c:\eclipselink\src\extension.lib.external and c:\eclipselink\src\extension.oracle.lib.external.

4a. Copy your JUnit jar file to <trunk>/../extension.lib.external/junit.jar. Note that you must rename this jar to junit.jar to align with our test scripts.

4b. Copy your bnd-0.0.366.jar file to <trunk>/../extension.lib.external directory. You can download this file from http://www.aqute.biz/Code/Download.  <Need more info>

5. Copy your non-Oracle database JDBC driver jar files to <trunk>/../extension.lib.external. If you are using an Oracle database, copy the corresponding driver and xdb.jar, sdoapi.jar and xmlparserv2.jar to <trunk>/../extension.oracle.lib.external. These files will be picked up and added to the server classpath at runtime. Please choose the version of your JDBC driver carefully; some databases such as DB2 do not work well with older versions of their driver.

6. Copy test.properties and {appserver}.properties files from <jpa_test_root>  to your <user_home> directory. You will modify these working copies in <user_home> in the next few steps. Note: the test build.xml loads these property files from <user_home> first and also from <jpa_test_root> -- this means you can also choose not to copy these files over to <user_home> and edit them from <jpa_test_root>. The former approach may prevent the property files from being overwritten when the source is refreshed to the tip.

7. Edit the following properties in <user_home>/test.properties.

  • server.name : your target application server. Valid values are:  weblogic, websphere, oc4j, jboss and glassfish
  • jdbc.driver.jar : location of the JDBC driver jar file on file system
  • db.driver : fully qualified JDBC class name (see samples included in property file)
  • db.url : connection URL
  • db.user, db.pwd : db user and password
  • db.platform :  fully qualified database platform class in  (see samples included in property file).

8. Edit the properties in <user_home>/{appserver}.properties. Each application server has its own set of properties - the comments provided in the property files should explain how to set each required property. The following shows an example of properties required in the weblogic.properties and websphere.properties.

WebLogic Server (WLS)

  • weblogic.installdir : the location on the file system where WLS was installed
  • server.user, server.pwd : the admin user and password
  • weblogic.host : WLS admin server host name
  • weblogic.port : WLS admin server port
  • weblogic.domain : location where the tests will create the WLS domain. You need to specify this location, preferably an empty folder.
  • server.persistence20.lib : location where the JPA2.0 support patch added after apply patch by Smartupdate in order to enable JPA2.0 support with WLS10.3.x server.

It's not possible to run tests in parallel in separate domains under a single WebLogic installation. Ant script copies eclipselink.jar into oracle_common/modules/oracle.toplink directory of WebLogic installation and it will cause conflict.

Websphere (WAS)

  • server.user, server.pwd : the admin user and password
  • was.jython.scripts.dir
  • instance.host
  • was.home
  • server.url
  • server.depend

JBoss

  • edit jboss.server to point to appropriate jboss-as/server/default for EAP and server/default for the CE

9. For application servers that package EclipseLink as a persistence provider, you need to replace the jar that they package with the version in  /<trunk> - we are assuming here that you want to test the eclipselink jar from <trunk> and not the one included with the application server. Please refer to the EclipseLink documentation on how to use EclipseLink in various application servers for more details, but for the purpose of convenience, here are steps you need to perform for various application servers:

Application Server/Version
 Copy From:
 Copy To:
 Notes
Oracle WebLogic 10.3.1+
  <trunk>/eclipselink.jar
 <middleware_home>/modules/org.eclipse.persistence_1.0.0.0_1-1-0.jar
 <middleware_home> is a directory you have specified in install wizard; generally it is one level up from the WebLogic install directory.
Oracle WebLogic 12c+
  <trunk>/eclipselink.jar
 <trunk>/plugins/org.eclipse.persistence.jpa.modelgen_<version>.jar
 <trunk>/plugins/org.eclipse.persistence.nosql_<version>.jar
 <trunk>/plugins/org.eclipse.persistence.oracle.nosql_<version>.jar
 <middleware_home>/oracle_common/modules/oracle.toplink_<server_version>/eclipselink.jar
<middleware_home>/oracle_common/modules/oracle.toplink_<server_version>/org.eclipse.persistence.jpa.modelgen.jar
<middleware_home>/oracle_common/modules/oracle.toplink_<server_version>/org.eclipse.persistence.nosql.jar
<middleware_home>/oracle_common/modules/oracle.toplink_<server_version>/org.eclipse.persistence.oracle.nosql.jar
 <middleware_home> is a directory you have specified in install wizard; generally it is one level up from the WebLogic install directory.




Test Execution

Note: The eclipselink.jar is not automatically pushed to the server - therefore the version that was shipped will run unless you manually override/copy the jar. For example on WebLogic you can overwrite the one in the modules directory.

Once the setup is done, configuring and executing the tests is pretty straight-forward. Server configuration and test execution is controlled by ant targets in the <jpa_test_root>/build.xml file. You can execute the entire set of tests (lrg's - large regression) or individual suites. Browse the build.xml for a list of suites. To execute these targets simply run the command 'ant <target_name>' in the <jpa_test_root> directory. The following sequence of targets need to be executed to run the JPA tests:

1. Build eclipselink and tests. Go to the <trunk> directory, and execute 'ant' (the tests currently depend on this step; however, in the future we will be removing this dependency)

2. server-install : Go to the <trunk>/jpa/eclipselink.jpa.test/ directory - this actually does not install the server, but does some additional configuration to the app server prior to the server being started.
Note: There is a 30 second timeout during this step.

3. server-start :  starts the application server administration server. You need to invoke this target in a separate shell window. This involves the following:

  • a) set the JAVA_HOME, ANT_HOME, and PATH as described in the Configuration Section,
  • b)  Go to <jpa_test_root> directory 
  • c) Invoke 'ant server-start' .

    Note that your choice of JAVA_HOME may affect the stability of this target -- for example, WebLogic Server tends to run better if their JRockit JVM is used instead of (Sun JDK - Not currently supported from these ant test scripts for WebLogic). Alternatively, you can also start the application server yourself using the application server's provided start scripts, but use this option with caution.

4. server-setup :  performs additional setup (java:ELNonJTADS and java:EclipseLinkDS datasources) and configuration after the server has started. For example, the datasources are created and configured on the server.

5. server-test-{test suite name} : runs a JPA test suite. The following are common test targets. All the test suite names can be found by browsing the server-test-lrg target in <jpa_test_root>/build.xml.

     server-test:              run all JPA LRG tests on server
     server-test-lrg:          run all JPA LRG tests on server
     server-test-{model name}: run individual test model only on server, you will find the model name in “server-test-lrg” target

Note: customfeatures model is not included in server-test-lrg for WebSphere, you need to set "run.jpa.customfeatures.model" property to be "true" in test.properties to run the model individually

6. server-reset : cleans up the server after testing. For example, the datasources created earlier are removed.

7. server-stop :  stops the server

8. clean-runtime : ant target in <trunk>/build.xml to clean up all the runtime generated files during the build process.

Note: Stopping the WebLogic server in the CMD window will also require that the java.exe process be closed as well (because we are only closing the connection to the server)( - look for the one around 580Mb (64-bit) or 290 (32-bit) - or you will get a .lok exists error when rerunning the tests. Use server-stop.

Eclipse IDE users

  • If you are developing in eclipse while running these server tests - note that there is currently an issue with the JPA 2.0 test framework where a full build in eclipse will remove classes expected by the server test ant script.
  • You will see the following issue unless you do a full ant trunk build after any Eclipse IDE rebuild or clean.
<error type="java.lang.reflect.InvocationTargetException">
java.lang.reflect.InvocationTargetException Caused by: 
java.lang.NoClassDefFoundError: org/eclipse/persistence/testing/tests/jpa/criteria/metamodel/JUnitCriteriaSimpleTestSuite at org.eclipse.persistence.testing.tests.jpa.criteria.CriteriaServerTestSuite.suite(CriteriaServerTestSuite.java:34)
</error>

Debugging on WebLogic Server requires disabling the default 30 second transaction timeout

  • - launch admin console at http://127.0.0.1:7001/console
  • - change Domain Configuration | Services | JTA | Timeout Seconds: (from 30 to 2^30 (the normal 2147483647 max will throw a -1 int exception currently))

Additional Application Server Install Steps

OC4J:

OC4J Eclipse EAR Application Tutorial

  • If you want to do fresh install, put oc4j_extended.zip under extension.oracle.lib.external. Later when you call “server-install”, “oc4j-install” will unzip and config user/password as defined in oc4j.properties
  • If you have oc4j installed already, put the right location, user name and password to oc4j.properties, remove everything from “oc4j-install” except four <copy> tasks.
WebSphere:

WebSphere Eclipse EAR Application Tutorial

  • Install the product
  • Create following .py files as described below and copy to extension.lib.external, following contents is originally from WebSphere samples, later I modified that to comply eclipselink testing. These scripts will be used in websphere-install, websphere-deploy and websphere-undeploy targets during the testing.
  1. By default, the testing is on WebSphere Application Server base edition, you need to set server.version=nd in test.properties if you want to run tests on WebSphere Network Deployment edition
  2. For testing on WebSphere Application Server base edition and WebSphere Network Deployment edition, the configWebSphere.py and unInstallApps.py will be same, but installApps.py will be different, see following.
  3. For setting value to jdbc.driver.jar in test.properties and eclipselink.jar.dir and oracle.extensions.jar.dir properties in websphere.properties, you have to use absolute path, because these values will be used to replace the tokens in the follwoing .py files
  • For manually start server for WebSphere Network Deployment edition, you need to start deployment manager under WAS_HOME/profiles/Dmgr01/bin, start node and server from WAS_HOME/profiles/AppSrv01/bin; for manually stop server for WebSphere Network Deployment edition, you need to stop server and node first from WAS_HOME/profiles/AppSrv01/bin, stop deployment manager from WAS_HOME/profiles/Dmgr01/bin
installApps.py for WebSphere Application Server base edition
     # If the application is currently installed, uninstall it
     try:
     AdminApp.uninstall('%%appName%%')
     except:
     print '%%appName%% was not previously installed'
     AdminConfig.save()
     # Set the options for the install
     attrs = ['-appname', '%%appName%%']
     # Install the application
     AdminApp.install('%%ear%%', attrs)
     AdminConfig.save()
     # Associate shared library
     deployment = AdminConfig.getid('/Deployment:%%appName%%/')
     print deployment
     appDeploy = AdminConfig.showAttribute(deployment, 'deployedObject')
     print appDeploy
     classLoad1 = AdminConfig.showAttribute(appDeploy, 'classloader')
     print classLoad1
     print AdminConfig.create('LibraryRef', classLoad1, [['libraryName', 'eclipselinkjpa'],  ['sharedClassloader', 'true']])
     AdminConfig.save()
     # Start the application
     appManager = AdminControl.queryNames('type=ApplicationManager,*')
     AdminControl.invoke(appManager, 'startApplication', '%%appName%%')
installApps.py for WebSphere Network Deployment edition
     # If the application is currently installed, uninstall it
     try:
     AdminApp.uninstall('%%appName%%')
     except:
     print '%%appName%% was not previously installed'
     AdminConfig.save()
     # Set the options for the install
     attrs = ['-appname', '%%appName%%']
     # Install the application
     AdminApp.install('%%ear%%','[-appname %%appName%% -node %%hostName%%Node01 -server server1]')
     AdminConfig.save()
     sleep (30)
     print 'Performing a Sync operation on: application'
     Sync1=AdminControl.completeObjectName('type=NodeSync,node=%%hostName%%Node01,*')
     print Sync1
     print AdminControl.invoke(Sync1,'sync')
     sleep (30)
     # Associate shared library
     deployment = AdminConfig.getid('/Deployment:%%appName%%/')
     print deployment
     appDeploy = AdminConfig.showAttribute(deployment, 'deployedObject')
     print appDeploy
     classLoad1 = AdminConfig.showAttribute(appDeploy, 'classloader')
     print classLoad1
     print AdminConfig.create('LibraryRef', classLoad1, [['libraryName', 
     'eclipselinkjpa'],  ['sharedClassloader', 'true']])
     AdminConfig.save()
     print 'Performing a Sync operation on: shared library'
     Sync1=AdminControl.completeObjectName('type=NodeSync,node=%%hostName%%Node01,*')
     AdminControl.invoke(Sync1,'sync')
     sleep (30)
     # Start the application
     print 'start the application now'
     appManager = AdminControl.queryNames('cell=%%hostName%%Cell01,node=%%hostName%Node01,type=ApplicationManager,process=server1,*')
     AdminControl.invoke(appManager, 'startApplication', '%%appName%%')
unInstallApps.py
     # If the application is currently installed, uninstall it
     try:
     AdminApp.uninstall('%%appName%%')
     except:
     print '%%appName%% was not previously installed'
     AdminConfig.save()
configWebSphere.py
     # Create JTA DataSource
     name = ['name', 'EclipseLinkDS']
     scs = ['statementCacheSize', 0]
     dsAttrs = [name, ['jndiName', 'jdbc/EclipseLinkDS'], scs]
     newds = AdminConfig.create('DataSource', newJDBC, dsAttrs)
     AdminConfig.save()
     print newds
     # Create JTA DataSource Custom Properties
     newds = AdminConfig.getid('/Node:%%hostName%%  Node03/Server:server1/JDBCProvider:OracleJDBCProvider/DataSource:EclipseLinkDS/')
     print newds
     newpropset = AdminConfig.create('J2EEResourcePropertySet',newds,[])
     AdminConfig.create('J2EEResourceProperty', newpropset, [['name', 'URL'], ['value', '%%dbURL%%']])
     AdminConfig.create('J2EEResourceProperty', newpropset, [['name', 'user'], ['value', '%%dbUser%%']])
     AdminConfig.create('J2EEResourceProperty', newpropset, [['name', 'password'], ['value', '%%dbPassword%%']])
     AdminConfig.save()
     print '-> Done!'
     # Create Non-JTA DataSource
     name = ['name', 'ELNonJTADS']
     scs = ['statementCacheSize', 0]
     dsAttrs = [name, ['jndiName', 'jdbc/ELNonJTADS'], scs]
     newds = AdminConfig.create('DataSource', newJDBC, dsAttrs)
     AdminConfig.save()
     print newds
     # Create Non-JTA DataSource Custom Properties
     newds = AdminConfig.getid('/Node:%%hostName%%Node03/Server:server1/JDBCProvider:OracleJDBCProvider/DataSource:ELNonJTADS/')
     print newds
     newpropset = AdminConfig.create('J2EEResourcePropertySet',newds,[])
     AdminConfig.create('J2EEResourceProperty', newpropset, [['name', 'URL'], ['value', '%%dbURL%%']])
     AdminConfig.create('J2EEResourceProperty', newpropset, [['name', 'user'], ['value', '%%dbUser%%']])
     AdminConfig.create('J2EEResourceProperty', newpropset, [['name', 'password'], ['value', '%%dbPassword%%']])
     AdminConfig.create('J2EEResourceProperty', newpropset, [['name', 'nonTransactionalDataSource'], ['value', '%%nonTransactionalDS%%']])
     AdminConfig.save()
     print '-> Done!'
     # Create Shared Library
     try:
     AdminConfig.remove(AdminConfig.getid('/Node:%%hostName%%Node03/Server:server1/Library:eclipselinkjpa'))
     except:
     print 'eclipselinkjpa was not previously installed'
     AdminConfig.save()
     n1 = AdminConfig.getid('/Node:%%hostName%%Node03/Server:server1/')
     print n1
     #library = AdminConfig.create('Library', n1, [['name', 'eclipselinkjpa'], 
     #['classPath', '%%eclipselinkLibDir%%/eclipselink.jar']])
     library = AdminConfig.create('Library', n1, [['name', 'eclipselinkjpa'], 
     ['classPath', '%%eclipselinkLibDir%%/eclipselink.jar %%oracleExtensionLibDir%%/xdb.jar %%oracleExtensionLibDir% %/xmlparserv2.jar']])
     print library
     AdminConfig.save()

Note: if you are testing customfeatures model, you need to add xdb.jar and xmlparserv2.jar in shared library as well as: library = AdminConfig.create('Library', n1, [['name', 'eclipselinkjpa'], ['classPath', '%%eclipselinkLibDir%%/eclipselink.jar %%oracleExtensionLibDir%%/xdb.jar %%oracleExtensionLibDir%%/xmlparserv2.jar']])

Debugging an EclipseLink JPA EAR in WebSphere 7 from Eclipse

Retrieved from "https://wiki.eclipse.org/index.php?title=EclipseLink/Development/Testing/JPA&oldid=382212"

This page was last modified 13:48, 18 April 2015 by Eclipsepedia anonymous user Unnamed Poltroon.

Back to the top