This demo application demonstrates support of developing and testing simple related EJB 3.0 entity beans with Oracle TopLink outside of EJB 3.0 Container of Oracle Application Server 10g 10.1.3 with or without transparent lazy loading. It is showcased by a set of JUnit tests using javax.persistence.
This example uses three related entities Customer, Order and Item used by a session bean facade OrderDemoSessionEJB.
Configuring Entity Managers
Standard Configuration options
EntityManagers are configured with a set of properties. These properties define things like the datasources that EntityManager will connect to.
These properties can be provided in a couple of ways.
1. They can be provided in a map in the Persistence.createEntityManagerFactory(Map) method call.
e.g.
HashMap map = new HashMap();
map.put(java.persistence.setup.config, "examples.ejb.cmp30.relationships.OrderDemoSessionConfig");
map.put(javax.persistence.provider, "oracle.toplink.ejb.cmp3.EntityManagerFactoryProvider");
map.put(jdbc.driver, "oracle.jdbc.driver.OracleDriver");
map.put(jdbc.connection.string, "jdbc:oracle:thin:@//localhost:1521/ORCL");
map.put(jdbc.user, "scott");
map.put(jdbc.password, "tiger");
em = Persistence.createEntityManagerFactory(map).createEntityManager();
2. They can be provided as system properties when the java application is run.
e.g.
-Djava.persistence.setup.config=examples.ejb.cmp30.relationships.OrderDemoSessionConfig
-Djavax.persistence.provider=oracle.toplink.ejb.cmp3.EntityManagerFactoryProvider
-Djdbc.driver=oracle.jdbc.driver.OracleDriver
-Djdbc.connection.string=jdbc:oracle:thin:@//localhost:1521/ORCL
-Djdbc.user=scott
-Djdbc.password=tiger
Adding JTA
TopLink provides a JTA implementation suitable for simple testing. You can enable this JTA implementation by adding the following three properties either through a map or system properties.
e.g.
map.put(use.toplink.jta, "true");
map.put(datasource.name, "Datasource");
map.put(datasource.jndi.name, "jdbc/OracleManagedDS");
or
-Duse.toplink.jta=true
-Ddatasource.name=Datasource
-Ddatasource.jndi.name=jdbc/OracleManagedDS
Adding Transparent Lazy Loading
TopLink has always supported Lazy Loading through it's indirection feature. The EJB 3.0 specification provides for transparent lazy loading. In other words, objects referenced across relationships can be loaded on an as needed basis.
To enable Transparent lazy loading, please follow the following three steps:
1. Use the fetch=LAZY property
e.g. From Order.java
@ManyToOne(fetch=LAZY)
@JoinColumn(name="CUST_ID")
public Customer getCustomer() {
return customer;
}
2. Several of the properties mentioned above will have to be included as java system properties.
e.g.
-Djava.persistence.setup.config=examples.ejb.cmp30.relationships.OrderDemoSessionConfig
-Djavax.persistence.provider=oracle.toplink.ejb.cmp3.EntityManagerFactoryProvider
3. Your java program will have to run with the -javaagent tag and use TopLink's agent jar file.
To make your EJBs testable outside the EJB container you have to create a class that returns the names of entities to be unit tested. For example:
public class OrderDemoSessionConfig {
public static Collection getClassList() {
Vector classes = new Vector();
classes.add("examples.ejb.cmp30.relationships.Customer");
classes.add("examples.ejb.cmp30.relationships.Item");
classes.add("examples.ejb.cmp30.relationships.Order");
return classes;
}
}
Create Your Test Class
You have to create your test class to execute your test scenarios. You can choose your favorite framework to build your test cases. We have provided an example class OrderDemoSessionJunitTest.java that uses JUnit test framework.
Execute Your Test Case
You have to include the test classes and EJB classes in the CLASSPATH. For example, you have to execute OrderDemoSessionJunitTest as follows (using system properties and transparent lazy loading):
%TOPLINK_HOME% - The directory where you installed Oracle TopLink.
%JAVA_HOME% - The directory where your JDK is installed
%HOWTO_HOME% - The directory where this demo is unzipped
%JUNIT_HOME% - The directory where you installed JUnit
Running the Application with Transparent Lazy Loading
To run the sample application with transparent lazy loading on a standalone instance
of Oracle TopLink, follow these steps:
1. Examine the Sample File Directories
build - temporary directory created during the build
etc - all necessary files to package the application
META-INF - sessions xml file
script - contains SQL script to create a table
doc - the How-to document and Javadoc's
javadoc - the javadoc of the different source files
how-to-ejb30-out-of-container.html - this How-to page
src - the source of the demo
lib - holds the application archives
log - holds build logs
2. Configure the Environment
Ensure
the following environment variables are defined:
%TOPLINK_HOME% - The directory where you installed TopLink.
%JAVA_HOME% - The directory where you installed
the J2SE 5.0
Configure Database
This example requires the creation of the database to be done using initdb.sql in %HOWTO_HOME%/scripts directory. This script will create the tables and set up the sample data used in this how to. The supplied script will work only with Oracle database, you have to make necessary changes to use any other Oracle database.
Configure Data Source
This example requires the DataSource configured to connect to the database. Hence you need to edit the %HOWTO_HOME%/ant-oracle.properties. It must be edited to include values that are appropriate to your database for url, jdbc driver, username and password.
Configure JDBC Driver
JDBC driver path must be provided in %HOWTO_HOME%/ant-oracle.properties.
Configure Ant for JUnit
Make sure that %JUNIT_HOME/junit.jar file is on your CLASSPATH used by ant or this file is copyied to %ANT_HOME%/lib directory.
Additional steps if not connected to an Oracle database
If you are not connecting to an Oracle database, you must also do the following additional steps:
configure your datasource to use the proper configuration for the chosen database.
rename %HOW_TO_HOME%/META-INF/ejb3-toplink-sessions.xml.removeforuse to %HOW_TO_HOME%/META-INF/ejb3-toplink-sessions.xml. This file will now be picked up and put into your jar when you build.
configure %HOW_TO_HOME%/META-INF/ejb3-toplink-sessions.xml by opening the file and change the platform tag to point to your chosen database.
if the session name defined in %HOW_TO_HOME%/META-INF/ejb3-toplink-sessions.xml is not "default", provide toplink.session.name property to have the same session name as defined in %HOW_TO_HOME%/META-INF/ejb3-toplink-sessions.xml, either through a map or system properties. For instance, if the session name defined in %HOW_TO_HOME%/META-INF/ejb3-toplink-sessions.xml is "example_session", do the following:
map.put(toplink.session.name, "example_session");
or
-Dtoplink.session.name=example_session
ensure that your JDBC driver is on your classpath.
3. Generate and Compile the Application
Ensure Ant 1.6.2 or above is installed on your machine and configured correctly.
On some operating systems, Ant does not currently
support the use of environment variables. If this is the case for your operating
system, please modify the ant-oracle.properties file located in the
%HOWTO_HOME% directory.
To build the application, type the following command
from the %HOWTO_HOME% directory:
ant
You should now have the newly created cmp30-relationships-junit.jar in your
%HOWTO_HOME% directory.
4. Run the Application
Run the transparent lazy loading example by runnning
ant run
Running the Application without Transparent Lazy Loading
If you can not use transparent lazy loading in your application, follow these steps:
3. Prepare for No Transparent Lazy Loading Example
You need to either turn off indirection or change the field type of the entity to use ValueHolderInterface. To run the no transparent lazy loading example, you need to follow one of the following two options:
Remove fetch=LAZY annotation for OneToOne and ManyToOne mappings in Order class. Indirection will not be used in this case.
or
Replace %HOWTO_HOME%/src/examples/ejb/cmp30/relationships/Order.java with %HOW_TO_HOME%/etc/Order_noweaving_lazy.java (rename to Order). Indirection will still be used in this case.
Run the no transparent lazy loading example by runnning
ant run.noagent
Summary
In this document, you should have learned how to:
Use TopLink to bootstrap the deployment of EntityBeans in EJB 3.0 when deployed in a non-managed setting to build examples for out-of-container testing.
Bookmark
