The main objective of the Enterprise JavaBeans (EJB) 3.0 specification is to improve the EJB architecture by reducing its complexity from the developer's point of view. EJB 3.0 has simplified the development of EJBs with the introduction of some new features. The new features include support for metadata annotations, default values for a configuration, simplified access of environmental dependencies and external resources, simplified session and entity beans, interceptors, enhanced support for checked exceptions, and elimination of callback interfaces. The persistence and object/relational model has been revised and enhanced in EJB 3.0. The persistence and object/relational model in EJB 3.0 is the Java Persistence API (JPA). We shall discuss and introduce these new features in this chapter.
Metadata annotations were introduced in JDK 5.0 as a means to provide data about an application. Annotations are used for the following purposes:
Generating boilerplate code (code that is repeated in different sections of a Java program) automatically.
Replacing configuration information in configuration files such as deployment descriptors.
Replacing comments in a program.
Informing the compiler about detecting errors and generating or suppressing warnings. The
@Deprecated
annotation is used to inform the compiler about a deprecated feature, on detecting which the compiler generates a warning. The@Override
annotation informs the compiler about an overridden element. If the element is not overridden properly, the compiler generates an error. The@SuppressWarnings
annotation is used to inform the compiler to suppress specific warnings.Runtime processing of annotations by annotating the annotations with the
@Retention(RetentionPolicy.RUNTIME)
annotation.
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.
Annotation |
Description |
---|---|
DeclareRoles |
Declares references to security roles |
RolesAllowed |
Declares the methods that are allowed to invoke the methods of the entity bean |
PermitAll |
Specifies that all security roles are allowed to invoke the specified methods. |
DenyAll |
Specifies that no security roles are allowed to invoke the specified methods. |
RunAs |
Specify a security role as the bean's run-as property. |
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:
Container context
Resources
Environment context
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:
@javax.ejb.EJB
is used to specify dependency on another EJB.@javax.annotation.Resource
is used to specify dependency on an external resource such as a JDBC datasource, a JMS destination, or a JMS connection factory. The@Resource
annotation is not specific to EJB 3, and may be also used with other Java EE components.
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:
Annotation |
Description |
---|---|
@Entity |
Specifies an entity bean. |
@Table |
Specifies the entity bean table. |
@SecondaryTable |
Specifies a secondary table for an entity class for which data is stored across multiple tables. |
@Id |
Specifies an identifier property. |
@Column |
Specifies the database table column for a persistent entity bean property. |
@NamedQueries |
Specifies a group of named queries. |
@NamedQuery |
Specifies a named query or a query associated with a finder method. |
@OneToMany |
Specifies a one-to-many CMR relationship. |
@OneToOne |
Specifies a one-to-one CMR relationship. |
@ManyToMany |
Specifies a many-to-many CMR relationship. |
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.