The Enterprise JavaBeans (EJB) 3.0 specification has facilitated the development of EJBs, by providing an annotations-based API in which the remote/local and home/local home interfaces are not required. The deployment descriptors that form the basis of an EJB 2.0 entity bean are also not required for deploying an EJB 3 entity bean.

This tutorial covers the procedure for converting an EJB 2.0 entity bean to an EJB 3.0 entity bean.

Overview

EJB 3.0 support is implemented in Oracle Application Server (10g) 10.1.3 (in Developer Preview at the time of this writing). The EJB 3.0 entity bean classes are simplified in comparison to the EJB 2.0 specification classes.

The EJB 3.0 entity bean class is a Plain Old Java Object (POJO) instead of a class implementing the EntityBean interface. The component interfaces in EJB 2.0, which were required to extend the EJBLocalObject/EJBObject and home interfaces, which were required to extend the EJBLocalHome/EJBHome interfaces, are replaced with the javax.persistence.EntityManager API to create, find, and update entity bean instances.

Preliminary Setup

This tutorial uses the oraxsl utility to provide the XSLT transformation for converting the EJB 2.0 entity bean to the EJB 3.0 specification. Download Oracle XML Developer's Kit (XDK) 10g, and add <XDK10g>\lib\xmlparserv2.jar to Classpath. The example EJB 2.0 entity EJB is included in the samples zip file.

Migrating the Entity Bean Class

The EJB 3.0 entity bean class is a nonabstract POJO class with implementations for the getter/setter methods, in comparison to the EJB 2.0 entity bean class, which is abstract with abstract getter/setter methods. EJB 3.0 does not require component and home interfaces. The entity bean class may implement a business interface.

The EntityManager class is used to create, find, and update an entity EJB. In EJB 3.0, deployment descriptors are not required and are replaced with metadata annotations. If the deployment descriptors are included, the deployment descriptor values override the annotations. An entity EJB is specified with the @Entity annotation.

name (if the name element is not specified, the EJB class name is used as the table name)

@Column

Specifies a column corresponding to an EJB property

name, nullable, length, updatable, primaryKey

@Id

Specifies a primary key column property

@Transient

Specifies a property that is not persistent

EJB Query Language (QL) queries in EJB 2.0 are specified with the <query/> element in the ejb-jar.xml deployment descriptor. EJB QL queries in EJB 3.0 are specified with the metadata annotations @NamedQuery and @NamedQueries, which are listed below.

Annotation

Description

Annotation Elements

@NamedQueries

Specifies a group of EJB QL queries

@NamedQuery

Specifies an EJB QL query

name="query name"
queryString="SQL query"

The entity bean container-managed relationship (CMR) relationships in EJB 2.0 are specified with the <ejb-relation/> elements in the ejb-jar.xml deployment descriptor, and the entity bean CMR relationships in EJB 3.0 are specified in the bean class. The metadata annotations used to specify the entity bean CMR relationships are:

Annotation

Description

@OneToMany

One-to-many entity bean CMR relationship

@OneToOne

One-to-one entity bean CMR relationship

@ManyToOne

Many-to-one entity bean CMR relationship

@ManyToMany

Many-to-many entity bean CMR relationship

The EJB 2.0 entity bean being migrated to EJB 3.0 in our example is shown below.

Modify the ejb-jar.xml deployment descriptor for the example entity bean to include elements for the table name, field type, and EJB QL query collection type for multi-entity return values. Add the <table-name/>, <field-type/>, and <collection-type/> elements to ejb-jar.xml. The modified ejb-jar.xml deployment descriptor for the example entity bean is shown below.

The EJB 3.0 bean class has the import statements for the javax.persistence package classes. The @Entity annotation specifies the class as an entity EJB class. The @Table annotation specifies the database table name for the entity EJB, the @NamedQueries annotation specifies the named queries, the @Id annotation specifies the identifier property/primary key field, and the @Column annotation specifies the database column corresponding to the identifier property. The EJB 2.0-to-EJB 3.0 conversion XSLT also includes the conversion of entity bean CMR relationships.

Developing a Session Facade for an Entity Bean

In EJB 2.0, an entity bean is created with the create method in the home/local home interface and the entity bean fields are modified with the getter/setter methods in the local/remote interface. In EJB 3.0, an entity bean is created and modified with the EntityManager API. The EntityManager class provides methods for finding, persisting, and removing an entity bean instance. This section covers generation of a session EJB that implements the EntityManager API.

In the session EJB bean class, the EntityManager is obtained with the @Resource annotation.

@Resource private EntityManager em;

Some of the commonly used methods of the EntityManager class are listed below.

EntityManager Method

Description

persist(Object entity)

Saves an entity bean instance in the database. The persist method returns the entity bean that is persisted in the database.

find(String entityName, Object primaryKey)

Finds an entity bean instance with a primary key.

remove(Object entityBean)

Removes an entity bean from the database.

createQuery(String ejbQlString)

Creates an EJB QL query.

createNamedQuery(String queryName)

Creates a NamedQuery query.

In the session bean class, an entity bean is created with the create method. For example, the create method corresponding to the identifier property catalogId is

The find method of the EntityManager class is used to find an entity bean. For example, the findByPrimaryKey method corresponding to the identifier property catalogId, which is defined in the entity bean class with the @Id annotation, is

In the session EJB, add finder methods for the named queries defined in the EJB bean class. The createNamedQuery method is used to obtain a query object for a named query. For example, the finder method corresponding to the named query FindByCatalogId, which is defined in the entity bean class, is

In the findByCatalogId method, a javax.persistence.Query object is obtained from the named query FindByCatalogId. The parameter values are set on the query object. An entity EJB bean instance is obtained with the getSingleResult method of the query object. The named query FindByCatalogId returns a single entity of the entity EJB bean.

A named query may also return a collection of entities. For example, the named query FindByJournal returns a collection. The finder method corresponding to the FindByJournal named query is

The @Remote annotation specifies a remote interface. The XSLT facade-bean.xslt, used to generate the session bean class, and the XSLT facade.xslt, session bean interface are available in the samples zip file.

Conclusion

Entity EJBs developed with the previous versions of EJB specifications can be converted to the EJB 3.0 specification with XSLT transforms. The example XSLT transforms can be used to convert EJB 2.0 and EJB 2.1.