EJB 3.0 Database Persistence with Oracle Fusion Middleware 11g: This book walks you through the practical usage of EJB 3.0 database persistence with Oracle Fusion Middleware. Lots of examples and a step-by-step approach make it a great way for EJB application developers to acquire new skills.

Metadata annotations were introduced in JDK 5.0 as a means to provide data about an application. Annotations are used for the following purposes:

EJB 3.0 specification has introduced some metadata annotations for annotating EJB 3.0 applications. EJB 3.0 metadata annotations have reduced the number of classes and interfaces a developer is required to implement. Also, the metadata annotations have eliminated the requirement for an EJB deployment descriptor. Three types of metadata annotations are used in EJB 3.0: EJB 3.0 annotations, object/relational mapping annotations, and annotations for resource injection and security. Though annotations follow a different semantic than Java code, they help in reducing code lines and—in the case of EJB—increase cross-platform portability. The EJB 3.0 annotations are defined in the javax.ejb package. For example, the @Stateless annotation specifies that an EJB is a Stateless Session Bean:

import javax.ejb.Stateless;
@Stateless
public class HelloBean implements Hello {
public void hello() {
System.out.println("Hello EJB 3.0!");
}
}

For all the new EJB 3.0, annotations, refer to the EJB 3.0 specification document EJBCore (ejb-3_0-fr-spec-ejbcore.pdf). Persistence annotations are defined in the javax.ejb.persistence package. For example, the @Entity annotation specifies that the EJB is an Entity Bean:

import javax.persistence.*;
@Entity
@Table(name = "Catalog")
public class Catalog implements Serializable {
private long id;
@Id
public long getId() {
return id;
}
public void setId(long id) {
this.id = id;
}
}

The resource injection and security annotations are defined in the Common Annotations for the Java Platform specification, and are in the javax.annotation and javax.annotation.security packages. For example, the @Resource injection may be used to inject a javax.sql.DataSource resource. First, configure a data source in a Java EE container. Subsequently, inject a data source handle by annotating a declaration for a variable of type javax.sql.DataSource with the @Resource annotation.

@Resource
private javax.sql.DataSource mysqlDS;
public getCatalogEntry(){
Connection conn = mysqlDS.getConnection();
}

Data source injection using the @Resource annotation precludes the requirement for JNDI lookup using an InitialContext object. The security annotations are presented in the following table.

Common expected behaviors and requirements for the EJB container are not required to be specified by a developer. For example, by default an EJB 3.0 container provides Container-Managed persistence and Container-Managed Transaction (CMT) demarcation. Default metadata values and programmatic defaults are provided by the EJB 3.0 implementation. A "configuration by exception" approach is taken rather than explicit configuration. Relationship Mapping Defaults are defined in the persistence API. Object/relational mapping defaults are also defined. For example, an Entity bean is mapped to a database table name of the same name as the capitalized entity class name. Therefore, an Entity class Catalog is mapped to database table CATALOG by default. Similarly, the default column name is the property or field name. The entity name defaults to the entity class name.

An enterprise bean's context may be divided into 3 components:

The container may be used to supply references to resources and environment entries. Environmental dependencies and JNDI access may be encapsulated with dependency annotations, a dependency injection mechanism, and a simple lookup mechanism. Dependency injection implies that the EJB container automatically supplies/injects a bean's variable or setter method with a reference to a resource or environment entry in the bean's context. Alternatively, you would have to use the javax.ejb.EJBContext or JNDI APIs to access the environment entries and resources. Dependency injection is implemented by annotating a bean's variable or setter method with one of the following annotations:

For accessing multiple resources, use the corresponding grouping annotations @javax.ejb.EJBs and @javax.annotation.Resources. An example of injecting dependency on an EJB into a bean's variable using the @javax.ejb.EJB annotation is as follows:

import javax.ejb.EJB;
@Stateful
public class CatalogBean implements Catalog {
@EJB(beanName = "HelloBean")
private Hello hello;
public void helloFromCatalogBean() {
hello.hello();
}
}

In the preceding example, the hello variable is injected with the EJB HelloBean. The type of the hello variable is Hello, which is the HelloBean's business interface that it implements. Subsequently, we invoked the hello() method of the HelloBean. A resource may also be injected into a setter method. If the resource type can be determined from the parameter type, the resource type is not required to be specified in the @Resource annotation. In the following code snippet, the setter method is annotated with the @Resource annotation. In the setter method, the dataSource property is set to a JNDI resource of type javax.sql.DataSource with value as catalogDB.

private javax.sql.DataSource dataSource;
@Resource(name="catalogDB")
public void setDataSource (DataSource jndiResource) {
this.dataSource = jndiResource;
}

The setter method must follow the JavaBean conventions: the method name begins with set, returns void, and has only one parameter. If the name of the resource is the same as the property name, the resource name is not required to be specified in the @Resource annotation. The JNDI name of the resource is of the format class_name/catalogDB, class_name being the class name.

private javax.sql.DataSource catalogDB;
@Resource
public void setCatalogDB (DataSource jndiResource) {
this.catalogDB = jndiResource;
}

Setter injection methods are invoked by the container before any business methods on the bean instance. Multiple resources may be injected using the @Resources annotation. For example, in the following code snippet two resources of type javax.sql.DataSource are injected.

@Resources({
@Resource(name="ds1", type="javax.sql.DataSource"),
@Resource(name="ds2", type="javax.sql.DataSource")
})

JNDI resources injected with the dependency mechanism may be looked up in the java:comp/env namespace. For example, if the JNDI name of a resource of type javax.sql.DataSource is catalogDB, the resource may be looked up as follows.

InitialContext ctx = new InitialContext();
Javax.sql.DataSource ds = ctx.lookup("java:comp/env/catalogDB");

In EJB 2.x, a session bean is required to implement the SessionBean interface. An EJB 3.0 session bean class is a POJO (Plain Old Java Object) and does not implement the SessionBean interface.

An EJB 2.x session bean class includes one or more ejbCreate methods, the callback methods ejbActivate, ejbPassivate, ejbRemove, and setSessionContext, and the business methods defined in the local/remote interface. An EJB 3.0 session bean class includes only the business methods.

In EJB 3.0, EJB component interfaces and home interfaces are not required for session beans. A remote interface in an EJB 2.x session EJB extends the javax.ejb.EJBObject interface; a local interface extends the javax.ejb.EJBLocalObject interface. A home interface in an EJB 2.x session EJB extends the javax.ejb.EJBHome interface; a local home interface extends the javax.ejb.EJBLocalHome interface. In EJB 3.0 the home/local home and remote/local interfaces are not required. The EJB interfaces are replaced with a POJI (Plain Old Java Interface) business interface. If a business interface is not included with the session bean class, a POJI business interface gets generated from the session bean class by the EJB server.

An EJB 2.x session EJB includes a deployment descriptor that specifies the EJB name, the bean class name, and the interfaces. The deployment descriptor also specifies the bean type of Stateless/Stateful. In EJB 3.0, a deployment descriptor is not required for a session bean. An example EJB 2.x session bean, which implements the SessionBean interface, is listed next:

import javax.ejb.SessionBean;
import javax.ejb.SessionContext;
public class CatalogBean implements SessionBean {
private SessionContext ctx;
public String getJournal(String publisher) {
if (publisher.equals("Oracle Publisher"))
return new String("Oracle Magazine");
if (publisher.equals("OReilly"))
return new String("dev2dev");
}
public void ejbCreate() {
}
public void ejbRemove() {
}
public void ejbActivate() {
}
public void ejbPassivate() {
}
public void setSessionContext(SessionContext ctx) {
this.ctx = ctx;
}
}

In EJB 3.0, metadata annotations are used to specify the session bean type and local and remote business interfaces. A stateless session bean is specified with the annotation @Stateless, a stateful session bean with the annotation @Stateful. Component and home interfaces are not required for a session bean. A session bean is required to implement a business interface. The business interface, which is a POJI, may be a local or remote interface. A local interface is denoted with the annotation @Local and a remote interface is denoted with the annotation @Remote. A session bean may implement one or both (local and remote) of the interfaces. If none of the interfaces is specified, a local business interface gets generated. The remote and local business interface class may be specified in the @Local and @Remote annotations. For example, a local business interface may be specified as @Local ({CatalogLocal.class}).

The EJB 3.0 session bean corresponding to the EJB 2.x stateless session bean is annotated with the metadata annotation @Stateless. The EJB 3.0 bean class does not implement the SessionBean interface. The EJB 3.0 session bean implements a business interface. The @Local annotation specifies the local business interface for the session bean. The EJB 3.0 session bean corresponding to the EJB 2.x example session bean is listed next:

import javax.ejb.*;
@Stateless
@Local( { CatalogLocal.class })
public class CatalogBean implements CatalogLocal {
public String getJournal(String publisher) {
if (publisher.equals("Oracle Publisher"))
return new String("Oracle Magazine");
if (publisher.equals("OReilly"))
return new String("java.net");
}
}

In EJB 3.0, the component and home interfaces of EJB 2.x are replaced with a business interface. The business interfaces for the session bean are POJIs, and do not extend the EJBLocalObject or the EJBObject. A local business interface is denoted with the annotation @Local. A remote business interface is denoted with the annotation @Remote. A remote business interface does not throw the RemoteException. The local business interface corresponding to the session bean class is listed next:

import javax.ejb.*;
@Local
public interface CatalogLocal {
public String getJournal(String publisher);
}

A client for an EJB 2.x session bean gets a reference to the session bean with JNDI. The JNDI name for the CatalogBean session bean is CatalogLocalHome. The local/remote object is obtained with the create() method. The client class for the EJB 2.x session bean is listed.

import javax.naming.InitialContext;
public class CatalogBeanClient {
public static void main(String[] argv) {
try {
InitialContext ctx = new InitialContext();
Object objref = ctx.lookup("CatalogLocalHome");
CatalogLocalHome catalogLocalHome = (CatalogLocalHome) objref;
CatalogLocal catalogLocal = (CatalogLocal) catalogLocalHome
.create();
String publisher = "OReilly";
String journal = catalogLocal.getJournal(publisher);
System.out.println("Journal for Publisher: " + publisher + " "
+
journal);
} catch (Exception e) {
System.err.println(e.getMessage());
}
}
}

In EJB 3.0, a reference to a resource may be obtained with a dependency injection with the @EJB annotation. JNDI lookup and create() method invocation is not required in EJB 3.0. The client class for the EJB 3.0 session bean is listed next:

public class CatalogClient {
@EJB
CatalogBean catalogBean;
String publisher="OReilly";
String journal=catalogBean.getJournal(publisher);
System.out.println("Journal for Publisher: "+publisher +" "+journal);
}

An EJB 2.x Entity EJB bean class must implement the javax.ejb.EntityBean interface, which defines callback methods setEntityContext, unsetEntityContext, ejbActivate, ejbPassivate, ejbLoad, ejbStore, and ejbRemove that are called by the EJB container. An EJB 2.x provides implementation for the callback methods in the interface. An EJB 2.x entity bean also includes the ejbCreate and ejbPostCreate callback methods corresponding to one create method in the home interface. An EJB 2.x entity bean's component and home interfaces extend the EJBObject/EJBLocalObject and EJBHome/EJBLocalHome interfaces respectively. In comparison, an EJB 3.0 entity bean class is a POJO which does not implement the EntityBean interface. The callback methods are not implemented in the EJB 3.0 entity bean class. Also, the component and home interfaces and deployment descriptors are not required in EJB 3.0. The EJB configuration information is included in the Entity bean POJO class using metadata annotations. An EJB 2.1 entity bean also consists of getter/setter CMP (Container Managed Persistence) field methods, and getter/setter CMR (Container Managed Relationships) field methods. An EJB 2.x entity bean also defines finder and ejbSelect methods in the home/local home interfaces for EJB-QL queries. An example EJB 2.x entity bean is listed next:

import javax.ejb.EntityBean;
import javax.ejb.EntityContext;
public class CatalogBean implements EntityBean {
private EntityContext ctx;
public abstract void setCatalogId();
public abstract String getCatalogId();
public abstract void setJournal();
public abstract String getJournal();
public String ejbCreate(String catalogId) {
setCatalogId(catalogId);
return null;
}
public void ejbRemove() {
}
public void ejbActivate() {
}
public void ejbPassivate() {
}
public void ejbLoad() {
}
public void ejbStore() {
}
public void setEntityContext(EntityContext ctx) {
this.ctx = ctx;
}
public void unsetEntityContext() {
ctx = null;
}
}

In EJB 2.x, the ejb-jar.xml deployment descriptor defines the EJB-QL for finder methods. An example finder method is specified in the ejb-jar.xml as follows:

<query>
<query-method>
<method-name>findByJournal</method-name>
<method-params>
<method-param>java.lang.String</method-param>
</method-params>
</query-method>
<ejb-ql>
<![CDATA[SELECT DISTINCT OBJECT(obj) FROM Catalog obj WHERE obj.journal =
?1 ]]>
</ejb-ql>
</query>

An EJB 3.0 entity bean is a POJO class annotated with the @Entity annotation. The finder methods are specified in the entity bean class itself using the @NamedQuery annotation. The EJB 3.0 entity bean persistence annotations are defined in the javax.persistence package. Some of the EJB 3.0 persistence annotations are presented in the following table:

The EJB 3.0 entity bean class corresponding to the EJB 2.x entity bean class is annotated with the metadata annotation @Entity. The finder method findByJournal in the EJB 2.x bean class is specified in the EJB 3.0 POJO class with the @NamedQuery annotation. The @Id annotation specifies the identifier property catalogId. The @Column annotation specifies the database column corresponding to the identifier property catalogId. If a @Column annotation is not specified for a persistent entity bean property, the column name is the same as the entity bean property name. Transient entity bean properties are specified with the @Transient annotation. The EJB 3.0 entity bean POJO class corresponding to the EJB 2.x entity bean is listed next:

import javax.persistence.Entity;
import javax.persistence.NamedQuery;
import javax.persistence.Id;
import javax.persistence.Column;
@Entity
@NamedQuery(name = "findByJournal", queryString = "SELECT DISTINCT OBJECT(obj) FROM Catalog obj WHERE obj.journal = ?1")
public class CatalogBean {
public CatalogBean() {
}
public CatalogBean(String catalogId) {
this.catalogId = catalogId;
}
private String catalogId;
private String journal;
@Id
@Column(name = "CatalogId", primaryKey = "true")
public String getCatalogId() {
return catalogId;
}
public void setCatalogId(String catalogId) {
this.catalogId = catalogId;
}
public void setJournal(String journal) {
this.journal = journal;
}
public String getJournal() {
return journal;
}
}

An EJB 2.x entity bean instance is created with the create() method in the entity bean home/local home interface. A client for an EJB 2.x entity bean obtains a reference for the entity bean with JNDI lookup; CatalogLocalHome is the JNDI name of the CatalogBean entity bean:

InitialContext ctx=new InitialContext();
Object objref=ctx.lookup("CatalogLocalHome");
CatalogLocalHome catalogLocalHome=(CatalogLocalHome)objref;
//Create an instance of Entity bean
CatalogLocal catalogLocal=(CatalogLocal)catalogLocalHome.create(catalogId);

To access the getter/setter methods of an entity bean, the remote/local object in EJB 2.x is obtained with the finder methods:

CatalogLocal catalogLocal =
(CatalogLocal) catalogLocalHome.findByPrimaryKey(catalogId);

An entity bean instance is removed with the remove() method:

catalogLocal.remove();

In EJB 3.0, persistence and lookup are provided by the EntityManger class. In a session bean client class for the EJB 3.0 entity bean, dependency injection is used to inject an EntityManager object using the @PersistenceContext annotation:

@PersistenceContext
private EntityManager em;

An entity bean instance is created by invoking new on the CatalogBean class and persisted with the persist() method of the EntityManager class:

CatalogBean catalogBean=new CatalogBean(catalogId);
em.persist(catalogBean);

An entity bean instance is obtained with the find() method:

CatalogBean catalogBean=(CatalogBean)em.find("CatalogBean", catalogId);

A Query object for a finder method is obtained with the createNamedQuery method:

Query query=em.createNamedQuery("findByJournal");

An entity bean instance is removed with the remove() method of the EntityManager class:

CatalogBean catalogBean;
em.remove(catalogBean);

The client class for the EJB 3.0 entity bean is listed next:

import javax.ejb.Stateless;
import javax.ejb.Resource;
import javax.persistence.EntityManager;
import javax.persistence.Query;
@Stateless
public class CatalogClient implements CatalogLocal {
@Resource
private EntityManager em;
public void create(String catalogId) {
CatalogBean catalogBean = new CatalogBean(catalogId);
em.persist(catalogBean);
}
public CatalogBean findByPrimaryKey(String catalogId) {
return (CatalogBean) em.find("CatalogBean", catalogId);
}
public void remove(CatalogBean catalogBean) {
em.remove(catalogBean);
}
}

The Java Persistence API (JPA) is the persistence component of EJB 3.0. "An EJB 3.0 entity is a lightweight persistent domain object." As discussed in the previous section, the entity class is a POJO annotated with the @Entity annotation. The relationship modeling annotations @OneToOne, @OneToMany, @ManyToOne, and @ManyToMany, are used for object/relational mapping of entity associations. EJB 3.0 specifies the object/relational mapping defaults for entity associations.

The annotations for object/relational mapping are defined in the javax.persistence package. An entity instance is created with the new operator and persisted using the EntityManager API. An EntityManager is injected into an entity bean using the @PersistenceContext annotation:

@PersistenceContext
EntityManager em;

An entity instance is persisted using the persist() method:

CatalogBean catalogBean=new CatalogBean();
em.persist(catalogBean);

The EntityManager is also used to remove entity instances using the remove() method:

em.remove(catalogBean);

EntityManager is also used to find entities by their primary key with the find method:

CatalogBean catalogbean=(CatalogBean)(em.find("CatalogBean", catalogId));

The @NamedQuery annotation is used to specify a named query in the Java Persistence Query language, which is an extension of EJB-QL. The Java Persistence Query language further adds operations for bulk update and delete, JOIN operations, GROUP BY, HAVING, and subqueries, and also supports dynamic queries and named parameters. Queries may also be specified in native SQL.

@NamedQuery(
name="findAllBlogsByName",
query="SELECT b FROM Blog b WHERE b.name LIKE :blogName"
)

The EntityManager is used to query entities using a Query object created from a named query:

Query query = em.createNamedQuery("findAllBlogsByName");

The named query parameters are set using the setParameter() method:

query.setParameter("blogName", "Smythe");

A SELECT query is run using the getResultList() method. A SELECT query that returns a single result is run using the getSingleResult() method. An UPDATE or DELETE statement is run using the executeUpdate() method. For a query that returns a list, the maximum number of results may be set using the setMaxResults() method.

List blogs=query.getResultList();

A persistence unit defines a set of entities that are mapped to a single database and managed by an EntityManager. A persistence unit is defined in the persistence.xml deployment descriptor, which is packaged in the META-INF directory of an entity bean JAR file. The root element of the persistence.xml file is persistence, which has one or more persistence-unit sub-elements. The persistence-unit element consists of the name and transaction-type attributes and subelements description, provider, jta-data-source, non-jta-data-source, mapping-file, jar-file, class, exclude-unlisted-classes, and properties. Only the name attribute is required; the other attributes and subelements are optional. The jta-data-source and non-jta-data-source are used to specify the global JNDI name of the data source to be used by the persistence provider. For all the elements in the persistence.xml and a detailed discussion on Java Persistence API, refer to the EJB 3.0 specification (ejb-3_0-fr-spec-persistence.pdf).

An interceptor is a method that intercepts a business method invocation or a lifecycle callback event. In EJB 2.x, runtime services such as transaction and security are applied to bean objects at the method's invocation time, using method interceptors that are managed by the EJB container. EJB 3.0 has introduced the Interceptor feature with which the interceptors may be managed by a developer. EJB interceptors are methods annotated with the @javax.ejb.AroundInvoke annotation. Interceptors may be used with business methods of session beans and message-driven beans. Interceptor methods may be defined in the bean class or an external interceptor class with a maximum of one interceptor method per class.

Checked exceptions are exceptions that are not a subclass of the java.lang.RuntimeException. In EJB 2.1, if a bean method performs an operation that results in a checked exception that the bean method cannot recover, the bean method should throw the javax.ejb.EJBException that wraps the original exception. In EJB 3.0, application exceptions that are checked exceptions may be defined as such by being declared in the throws clause of the methods of the bean's business interface, home interface, component interface, and web service endpoint. AroundInvoke methods are allowed to throw checked exceptions that the business methods allow in the throws clause.

As we discussed in the previous sections, callback interfaces javax.ejb.SessionBean, and javax.ejb.EntityBean are not implemented by the session beans and entity beans respectively. The callback methods of these methods are not implemented by the session and entity beans. Any method may be made a callback method using the callback annotations such as PostActivate, PrePassivate, PreDestroy, and PostConstruct. The callback methods may be specified in a callback listener class instead of the bean class.

In this chapter, we discussed the new features in EJB 3.0. We compared the EJB 3.0 features with EJB 2.0 features and discussed how EJB 3.0 is different from EJB 2.0. EJB 3.0 metadata annotations reduce the code required and make the deployment descriptors redundant. The local/remote and local home/home interfaces are not required in EJB 3.0 entity beans, and only a POJO class is required for an entity bean. The Java Persistence API provides an object-relational mapping model. Interceptors, simplified checked exceptions, and callback interfaces are some of the other new features in EJB 3.0.

In the next chapter, we shall convert an example EJB 2.x entity bean to an EJB 3.0 entity bean.