Skip Headers
Oracle® Fusion Middleware Solution Guide for Oracle TopLink
11g Release 1 (11.1.1)
E25034-01
  Go To Table Of Contents
Contents

Previous
Previous
 
Next
Next
 

8 Testing TopLink JPA Outside a Container

With TopLink, you can use the persistence unit JAR to test your application outside the container (for instance, in applications for the Java Platform, Standard Edition (Java SE)).

This chapter includes the following sections:

8.1 Understanding JPA Deployment

When deploying outside of a container, use the createEntityManagerFactory method of the javax.persistence.Persistence class to create an entity manager factory. This method accepts a Map of properties and the name of the persistence unit. The properties that you pass to this method are combined with those specified in the persistence.xml file. They may be additional properties or they may override the value of a property that you specified previously in the persistence.xml file.


Tip:

This is a convenient way to set properties obtained from a program input, such as the command line.

8.1.1 Using an EntityManager

The EntityManager is the access point for persisting an entity bean loading it from the database. Normally, the JPA container manages interaction with the data source. However, if you are using a JTA data source for your JPA persistence unit, you can access the JDBC connection from the Java EE container's data source. You must include the connection information to the persistence.xml file because the managed data source is not available.

With Oracle TopLink, you also have access to the EclipseLink extensions to the EntityManager.

8.2 Configuring the persistence.xml File

The persistence.xml file is the deployment descriptor file for persistence using Java Persistence API (JPA). It specifies the persistence units and declares the managed persistence classes, the object/relation mapping, and the database connection details.

8.2.1 Main Tasks

This section includes the following tasks:

8.2.1.1 Task 1: Use the persistence.xml File

Example 8-1 illustrates a persistence.xml file for a JavaSE configuration (that is, outside a container):

Example 8-1 A persistence.xml File Specifying JavaSE Configuration

<persistence xmlns="http://java.sun.com/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/persistence persistence_1_0.xsd" version="1.0">
    <persistence-unit name="my-app" transaction-type="RESOURCE_LOCAL">
        <provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>
        <exclude-unlisted-classes>false</exclude-unlisted-classes>
        <properties>
            <property name="javax.persistence.jdbc.driver" value="oracle.jdbc.OracleDriver"/>
            <property name="javax.persistence.jdbc.url" value="jdbc:oracle:thin:@localhost:1521:orcl"/>
            <property name="javax.persistence.jdbc.user" value="scott"/>
            <property name="javax.persistence.jdbc.password" value="tiger"/>
        </properties>
    </persistence-unit>
</persistence>

8.2.1.2 Task 2: Instantiate the EntityManagerFactory

An EntityManagerFactory provides an efficient way to construct EntityManager instances for a database. You can instantiate the EntityManagerFactory for the application (illustrated in Example 8-1) by using:

Persistence.createEntityManagerFactory("my-app");

8.3 Using a Property Map

You can use a property map to override the default persistence properties.

8.3.1 Main Tasks

This section includes the following steps:

8.3.1.1 Task 1: Configure the persistence.xml File

Example 8-2 illustrates a persistence.xml file that uses container deployment.

Example 8-2 A persistence.xml File Specifying JavaSE Configuration

<persistence xmlns="http://java.sun.com/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/persistence persistence_1_0.xsd" version="1.0">
    <persistence-unit name="employee" transaction-type="RESOURCE_LOCAL">
        <non-jta-data-source>jdbc/MyDS</non-jta-data-source>
    </persistence-unit>
</persistence>

Note:

There is no data source available when tested outside of a container.

8.3.1.2 Task 2: Configure the Bootstrapping API

To test the persistence unit shown in Example 8-2 outside the container, you must use the JavaSE bootstrapping API. Example 8-3 contains sample code that illustrates this bootstrapping:

Example 8-3 Sample Configuration

import static org.eclipse.persistence.config.PersistenceUnitProperties.*;

...

  Map properties = new HashMap();

  // Ensure RESOURCE_LOCAL transactions is used.
  properties.put(TRANSACTION_TYPE,
    PersistenceUnitTransactionType.RESOURCE_LOCAL.name());

  // Configure the internal connection pool
  properties.put(JDBC_DRIVER, "oracle.jdbc.OracleDriver");
  properties.put(JDBC_URL, "jdbc:oracle:thin:@localhost:1521:ORCL");
  properties.put(JDBC_USER, "scott");
  properties.put(JDBC_PASSWORD, "tiger");

  // Configure logging. FINE ensures all SQL is shown
  properties.put(LOGGING_LEVEL, "FINE");
  properties.put(LOGGING_TIMESTAMP, "false");
  properties.put(LOGGING_THREAD, "false");
  properties.put(LOGGING_SESSION, "false");

  // Ensure that no server-platform is configured
  properties.put(TARGET_SERVER, TargetServer.None);

8.3.1.3 Task 3: Instantiate the EntityManagerFactory

An EntityManagerFactory provides an efficient way to construct EntityManager instances for a database. You can instantiate the EntityManagerFactory for the application (illustrated in Example 8-3) by using:

Persistence.
createEntityManagerFactory("unitName", "Properties");

8.4 Additional Resources

For additional information on JPA deployment, see the following sections of the JPA Specification (http://jcp.org/en/jsr/detail?id=317):

8.4.1 Javadoc

For more information, see the following APIs in Oracle Fusion Middleware Java API Reference for EclipseLink.

  • PersistenceUnitProperties class

  • EntityManagerFactory interface

  • JpaEntityManager interface