Develop Entity using EJB 3.0 JPA

How-To Develop an Entity using EJB 3.0 JPA

• Introduction
  • Entity Bean example using EJB 3.0
  • Using EntityManager API
• 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 the EJB 3.0 specification with an Entity and further demonstrates the use of the EntityManager API for creating and finding entity instances.

in EJB 3.0, development is greatly simplified due to the following specifications:

• The entity class can be a plain java class (POJO)
• No interfaces are required for an entity bean
• Annotations are used for O-R Mapping

This demonstration uses the Employee entity to demonstrate a entity bean using EJB 3.0.

Entity example using EJB 3.0

The bean class is a plain java class that is annotated with @Entity to mark it as an entity.

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

@Id
@Column(name="EMPNO")
public int getEmpNo()
{
return empNo;
}

..

}

The @Table annotation is used to specify the table name to be used by this Entity bean.

The @Id annotation is used to mark the empNo field as the primary key of the entity bean.

The @Column annotation is used to specify that the empNo field is mapped to the EMPNO column in the table.

Using EntityManager API

The javax.persistence.EntityManager API is used for creating, finding, updating entity bean instances. The EmployeeFacade session bean uses EntityManager API to create and find entity instances. You can inject an instance of EntityManager and use persist or find method on EntityManager instance to create or query entity objects.

@Stateless
public class EmployeeFacadeBean implements EmployeeFacade
{
@PersistenceContext
private EntityManager em;
private Employee emp;

public Employee findEmployeeByEmpNo(int empNo)
{
return ((Employee) em.find("Employee",empNo));
}

public void addEmployee(int empNo, String eName, double sal)
{
if (emp == null) emp = new Employee();

...

em.persist(emp);
}

...

}

Note that Oracle Application Server provides the following features to make entities simpler to use from EJB modules:

• Do not require persistence.xml to be packaged in an EJB module
• You can inject javax.annotation.Resource to inject the default Entity manager in an EJB module and hence you can use the following code: @Resource private EntityManager em;

Prerequisites

What you need to know

In order to complete the example application, you should be familiar with the following:

• EJB 3.0

For further information on EJB 3.0, see the following documents 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
• Apache Ant version 1.6.2 or above, available here
• Any HTML browser like Mozilla, Microsoft Internet Explorer, Netscape, etc.
• A relational database, such as Oracle.

Notations

• %ORACLE_HOME% - The directory where you installed Oracle Application Server 10g 10.1.3 .1 Developer Preview
• %JAVA_HOME% - The directory where your JDK is installed
• %HOWTO_HOME% - The directory where this demo is unzipped

Building the Application

The Javadoc for this application is located in the %HOWTO_HOME%/doc/javadoc/ directory.

The configuration files are located in the %HOWTO_HOME%/etc directory, including deployment descriptor files such as application.xml, ejb-jar.xml, etc.

Running the Application

To run the sample application on a standalone instance of Oracle Application Server 10g 10.1.3.1 Developer Preview, 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
• 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-entity.html - this How-to page
• src - the source of the demo
  • ejb - contains the sample SLSB code
  • client - contains application client code

2. Configure the Environment

Ensure the following environment variables are defined:

• %ORACLE_HOME% - The directory where you installed OC4J.
• %JAVA_HOME% - The directory where you installed the J2SE 5.0
• %PATH% - includes %ORACLE_HOME% /ant/bin

Configure Database

This example is based on the EMP table from the SCOTT schema in an Oracle database. If you do not have SCOTT schema installed in your Oracle database, or are using a database other than Oracle, then the table will be automatically created during deployment of your applications because automatic table creation is switched. You can also manually create the table using the table.sql script in the %HOWTO_HOME%/scripts directory.

Configure Data Source

This example requires a DataSource to be configured to connect to the database that contains the EMP table.

For OC4J, you must configure a datasource in the %ORACLE_HOME%/j2ee/home/config/data-sources.xml file and point it at the schema that owns the EMP table.

An example configuration:

user="scott"
password="tiger"
url="jdbc:oracle:thin:@//localhost:1521/ORCL" >

connection-pool-name="ScottConnectionPool"
jndi-name="jdbc/OracleDS"
/>

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 demo directory) 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.

You have to make changes in jndi.properties such as provider.url, principal and credential appropriate to your environment. If you are using OracleAS install, you have to use provider.url in the following format: opmn:ormi://localhost:6003:home/ejb30entity.

To build the application, type the following command from the %HOWTO_HOME% directory:

>ant

You should now have the newly created ejb30entity.ear in your %HOWTO_HOME%/lib directory.

This command will also attempt to deploy the application to the defined OC4J if the build is successful. It will first test whether OC4J is running before attempting this task.

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 the following command, including a name as the program argument:

>ant run -Dempno= -Dname= -Dsal=

For example, run the sample with the following arguments to create a new record with the specified values:

>ant run -Dempno=358 -Dname=Debu -Dsal=5000

You will get the following output generated by the Java client. You can also check the database table to ensure the record was created.

run:
[java] Employee with empNo:358 created
[java] Find the employee using Entity Manager API
[java] EmployeeBean Details
[java] Class:oracle.ejb30.Employee :: empNo:358 ename:Debu sal:5000.0

Summary

In this document, you should have learned how to:

• Develop an Entity bean using EJB 3.0 and JDK 5.0 annotations
• Use the EntityManager API to create and find Entity beans
• Deploy and execute an Entity with the Oracle Application Server 10g 10.1.3 .1 Developer Preview