How-To : Using EJB 3.0 and Java Persistence API with Spring in OC4J

How-To : Using EJB 3.0 and Java Persistence API with Spring in OC4J
Date: 7/06/06
Author: Debu Panda

Introduction

Entity example using EJB 3.0 JPA

Spring bean using JpaTemplate

Spring-enabled EJB 3.0 Session bean

Using EJB 3.0 Session bean from

Wiring all together with Spring configuration

Prerequisites

What you need to know

Software requirements

Notations

Building the Application

Running the Application

Examine the Sample File Directories

Configure the Environment

Start the Server

Generate, Compile and Deploy the Application

Run the application

Summary

Introduction
This example application demonstrates Oracle's support for Spring with EJB 3.0 Session beans, container-managed entity manager with Spring's

JpaTemplate

. This sample uses a Spring-enabled EJB 3.0 Session bean

(EmployeeFacade EJB

) that uses a Spring bean(

EmployeeService

bean). The Spring bean uses a Data Access Object (

EmployeeDAO

) that uses Spring's

JpaTemplate

to manipulate entities. The persistence unit is managed by the EJB container by using a container-managed entity manager and passing it to Spring using setter injection. The application uses declarative transaction with EJB 3.0. For simplicity and to demonstrate the dependency injection support in the web container we have used a Servlet (

InsertServlet

) as a controller and it uses dependency injection to inject an instance of

EmployeeFacade

.
Entity example using EJB 3.0 JPA

The entity class is a plain java class that is annotated with

@Entity

to mark it as an entity.

@Entity
@Table(name = "EMPLOYEES")
public class Employee implements java.io.Serializable
{
private Long empNo;
private String name;
private double sal;

@Id
@GeneratedValue(strategy=GenerationType.AUTO)
@Column(name="EMPNO")
public Long getEmpNo()
{
return empNo;
}

..

}

The entity is configured in a persistence unit named

howto

as defined the persistence.xml. Note that the persistence unit uses a datasource with jndi location

jdbc/OracleDS

.

Spring bean using JpaTemplate

The

JpaTemplate

in Spring 2.0 nicely abstracts dealing with EJB 3.0 JPA EntityManager API.

Following is the code for the DAO that uses

JpaTemplate

to manipulate entities:

public class EmployeeSpringDAO extends JpaDaoSupport implements EmployeeDAO {

public Employee addEmployee(String empName, double sal) {
Employee employee = new Employee();
employee.setEname(empName);
employee.setSal(sal);
this.getJpaTemplate().persist(employee);
return employee;
}

public Employee findEmployee(Long employeeId) {
return  (Employee) getJpaTemplate().find(Employee.class,employeeId);
}

}

The Spring Bean (EmployeeServiceBean) uses the

EmployeeDAO

. It uses setter injection to get an instance of

EmployeeDAO

. The following is the code for the EmployeeServiceBean:

public class EmployeeServiceBean implements EmployeeService  {
protected EmployeeDAO employeeDAO ;

public void setEmployeeDAO(EmployeeDAO employeeDAO) {
this.employeeDAO = employeeDAO;
}

public Employee addEmployee(String empName, Double sal){
return (Employee) this.employeeDAO.addEmployee(empName, sal);
}

public Employee findEmployeeByEmpNo(Long empNo) {
return (Employee) this.employeeDAO.findEmployee(empNo);
}

}

Spring-enabled EJB 3.0 Session bean

The EmployeeFacadeBean extends Spring's

AbstractStatelessSessionBean

and retrieves the EmployeeServiceBean from the bean factory.
Following is the code for the EJB 3.0 Session bean:

@PersistenceContext(name="howto/EntityManager",unitName="howto")
@Stateless
public class EmployeeFacadeBean extends AbstractStatelessSessionBean implements EmployeeFacade {
EmployeeServiceBean empService;

protected void onEjbCreate() {
empService = (EmployeeServiceBean) getBeanFactory().getBean("empService");
}

public Employee addEmployee(String empName, double sal) {
return empService.addEmployee(empName,sal);
}

public Employee findEmployeeByEmpNo(Long empNo){
return empService.findEmployeeByEmpNo(empNo);
}

}

Note that The Session bean references a PersistenceContext that is used by the Spring bean. The session bean implements

onEjbCreate

method that retrieves

EmployeeServiceBean

instance.

The application context is passed to the Session Bean by using an environment variable named

ejb/BeanFactoryPath

in the deployment descriptor (ejb-jar.xml) as follows:

<session>
<ejb-name>EmployeeFacadeBean</ejb-name>
<env-entry>
<env-entry-name>ejb/BeanFactoryPath</env-entry-name>
<env-entry-type>java.lang.String</env-entry-type>
<env-entry-value>/howto-service.xml</env-entry-value>
</env-entry>
</session>

Note that the howto-service.xml contains the bean factory configuration that we see next.
Wiring all together with Spring configuration
The

howto-service.xml

contains the Spring configuration. Note that the DAO uses a container-managed entity manager and is retrieved from the ENC using the

JndiObjectFactoryBean

as follows:

<bean id="entityManager" class="org.springframework.jndi.JndiObjectFactoryBean">
<property name="jndiName">
<value>java:comp/env/howto/EntityManager</value>
</property>
<property name="resourceRef">
<value>true</value>
</property>
</bean>

An instance of container-managed entity manager is injected to the

EmployeeDAO

. Note that the EmployeeSpringDAO refers to enityManager bean that we defined earlier as follows:

<bean id="employeeDAO" class="oracle.ejb30.EmployeeSpringDAO"
autowire="byType">
<property name="entityManager" ref="entityManager"/>
</bean>

The EmployeeService bean uses EmployeeDAO that is injected using setter injection:

<bean id="empService" class="oracle.ejb30.EmployeeServiceBean">
<property name="employeeDAO">
<ref bean="employeeDAO"/>
</property>
</bean>

Remember that the Spring enabled EJB 3.0 Session bean (

EmployeeFacadeBean

) invokes the EmployeeService bean from the bean factory

empService = (EmployeeServiceBean) getBeanFactory().getBean("empService");

If you want your Spring beans to appear in the Application MBean browser you have the following configuration to register your beans:

<bean id="howToMbeanServer" class="org.springframework.jmx.support.MBeanServerFactoryBean">
<property name="defaultDomain" value="SpringHowTo" />
</bean>

<bean id="exporter" class="org.springframework.jmx.export.MBeanExporter">
<property name="beans">
<map>
<entry key="bean:name=empService" value-ref="empService" />
<entry key="bean:name=employeeDAO" value-ref="employeeDAO" />

</map>
</property>
<property name="server" ref="howToMbeanServer" />
</bean>

Prerequisites
What you need to know
In order to complete the example application, you should be familiar with the following:

EJB 3.0

Java Persistence API

Spring 2.0

For further information on EJB 3.0, see the following documents on OTN:

Link to other EJB 3.0 Resources on OTN

Link to other JPA Howto's on OTN

Software Requirements
This demonstration requires that the following software components are installed and configured correctly:

Oracle Application Server 10g 10.1.3.1.

Sun JDK version 1.5 or above, available here

Spring 2.0

Any HTML browser like Mozilla, Microsoft Internet Explorer, Netscape, etc.

A relational database such as Oracle.

Notations

%ORACLE_HOME% - The directory where you installed the Oracle Application Server 10g 10.1.3 .1

%SPRING_HOME% - The directory where Spring Framework version 2.0 is installed

%JAVA_HOME% - The directory where your JDK is installed

%HOWTO_HOME% - The directory where this demo is unzipped

Building the Application
The configuration files are located in the %HOWTO_HOME%/etc directory, including deployment descriptor files such as application.xml.
Running the Application
To run the sample application on a standalone instance of Oracle Application Server 10g 10.1.3.1, follow these steps:
1. Examine the Sample File Directories

build - temporary directory created during the build

log - temporary directory holding build/deploy logs

etc - all necessary files to package the application

lib - holds the application archives that could be deployed

doc - the How-to document and Javadoc's

how-to-ejb30-jpa-spring.html - this How-to page

src - the source of the demo

ejb - contains the sample entity, Spring bean and DAO

web- contains application

2. Configure the Environment
Ensure the following environment variables are defined:

%ORACLE_HOME% - The directory where you installed OC4J.

%SPRING_HOME% - The directory where you installed Spring 2.0

%JAVA_HOME% - The directory where you installed the J2SE 5.0

%PATH% - includes %ORACLE_HOME% /ant/bin

Configure Data Source
This example requires the default DataSource (with

jndi-location

as

jdbc/OracleDS

)to be configured to connect to the database where you want to persist the entity. The persistence unit is configured to use automatic table creation feature of Oracle TopLink Essentials. For details see http://www.oracle.com/technology/products/ias/toplink/jpa/resources/toplink-jpa-extensions.html.

For OC4J, you must configure a datasource in the %ORACLE_HOME%/j2ee/home/config/data-sources.xml file and point it at the schema.
An example configuration. You can use Application Server Control to create or modify an existing DataSource.

<connection-pool name="ScottConnectionPool">
<connection-factory factory-class="oracle.jdbc.pool.OracleDataSource"
user="scott"
password="tiger"
url="jdbc:oracle:thin:@localhost:1521:ORCL" >
</connection-factory>
</connection-pool>
<managed-data-source name="OracleManagedDS"
connection-pool-name="ScottConnectionPool"
jndi-name="jdbc/OracleDS"
/>

You can create the JDBC resources by using ANT tasks. Make sure you change the database configurations (db.host, db.sid, db.port, db.user, db.password) in ant-oracle.properties file.
Ensure $ORACLE_HOME/ant/bin is included in your PATH environment variable and then use the following command:

>ant configure-ds

3. Start the Server
Start OC4J stand alone using the following command after you make the above changes.

>%ORACLE_HOME%/bin/oc4j -start

If you are using an OracleAS managed install, start using the following command after you make the above changes.

> %ORACLE_HOME%/opmn/bin/opmnctl startall

4. Generate, Compile, and Deploy the Application
Ant 1.6.2 is shipped with OC4J and you have to set your PATH environment variable to $ORACLE_HOME/ant/bin. 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.xml file located in the %HOWTO_HOME% directory.
Edit ant-oracle.properties (in the demodirectory) and ensure the following properties are set to the correct values, as indicated below for OC4J standalone:

oc4j.host: host where OC4J is running (default localhost)

oc4j.admin.port: RMI port number (default 23791)

oc4j.admin.user: admin user name (default oc4jadmin)

oc4j.admin.password: admin user password (default welcome)

oc4j.binding.module: website name where deployed web modules are bound (default http-web-site)

If you are using OracleAS managed install then you have appropriately change the following properties beside changing oc4j.admin.user and oc4j.admin.password for your managed OC4J instance in OracleAS install.

opmn.host: the hostname/IP where OracleAS is running (default localhost)

opmn.port: OPMN request port (default 6003) for the OracleAS install

oc4j.instance: admin user name (default oc4jadmin)

You have to uncomment appropriate deployer.uri in the ant-oracle.properties based on your environment i.e. a single instance OC4J or a clustered OC4J instance/group managed by OPMN.
To build the application, type the following command from the %HOWTO_HOME% directory:

>ant

You should now have the newly created ejb3spring.ear in your %HOWTO_HOME%/lib directory.
This command will attempt to deploy the application archive if the build is successful. It will first test whether OC4J is running before attempting the deployment operation.
Note that you can also deploy the application separately . Ensure the %ORACLE_HOME% environment variable is defined, and from the %HOWTO_HOME% directory, type the command:

>ant deploy

5. Run the Application
Run the sample by providing invoking the following URL from your favorite browser:
http://localhost:8888/ejb3spring
In this page, enter employee no, Name and Salary and then click on Add Employee button.
The InsertServlet will be invoked that will try to persist the employee. The InsertServlet invokes

addEmployee

method EmployeeFacade. The EmployeeFacade bean uses the EmployeeServiceBean (Spring managed Bean) that in turns uses Spring

JpaTemplate

to persist the entity instance.
You will be redirected to a success page if your record was inserted successfully. You can also check the database table to ensure the record was created.

Summary
In this document, you should have learned how to:

Develop a simple Spring enabled EJB 3.0 Session Bean

Use the container-managed EntityManager with Spring JpaTemplate

Deploy an execute a sample application using Spring-enabled EJB 3.0 Session bean, JPA Integration with Spring on Oracle Application Server 10g 10.1.3.1

<persistence-unit name="howto">
<jta-data-source>jdbc/OracleDS</jta-data-source>
<properties>
<property name = "toplink.ddl-generation"
value = "drop-and-create-tables"/>
<property name = "toplink.ddl-generation.output-mode" value = "database"/>
</properties>
</persistence-unit>
</persistence>