BluePrints for Using the Simplified Java EE 5 Platform Programming Model

by Ed Ort

A growing number of articles, white papers, and other content describe the new usability features in the Java Platform, Enterprise Edition (Java EE) 5 such as annotations and dependency injection, but they give little guidance on when and where to use these features. In this session, Indejeet Singh and Smitha Kangath, members of Sun's Java BluePrints team, lent their considerable expertise in enterprise Java technology topics to this issue and offered their insights.

Singh focused on some of the key technology innovations that dramatically simplify programming in the Java EE 5 platform. These include the following:

• Annotations
• Dependency injection
• Enterprise JavaBeans (EJB) technology
• JavaServer Faces (JSF) technology and Asynchronous JavaScript with XML ((Ajax))
• Web services technologies: Java API for XML Web Services (JAX-WS) 2.0 and Java Architecture for XML Binding (JAXB) 2.0

Kangath also discussed another new Java EE 5 technology: the Java Persistence API.

Here's a summary of their views and recommendations.

Annotations

Metadata annotation, identified by an @ sign preceding an annotation type (for example, @EJB) was first introduced in Java 2 Platform, Standard Edition (J2SE) 5.0 and is used extensively in the Java EE 5 platform. You can use annotations to specify just about anything that you previously specified through XML deployment descriptors. For example, you can specify that a class is a web service (@WebService) or a stateless session bean (@Stateless), or specify permissions required to invoke a method (@MethodPermissions). Annotations simplify coding because they eliminate the need for deployment descriptors in many cases.

Singh noted that annotations are typically easier to write and understand than are XML deployment descriptors. In addition, because annotations are entered in class files rather than side files, there are fewer files to maintain.

But annotations are visible only in the class's source code, and you can't express all Java EE 5 metadata in annotations. Also, because you can use annotations to define components as well as to specify assembly and deployment metadata, such as security-related information, annotations blur the lines between the Java EE 5 platform roles such as component providers and application assemblers. But this blurring of roles may not be a big issue. Singh noted that one person often performs both roles -- as well as that of the application deployer.

When should you use annotations? Singh said they are best suited for specifying metadata that doesn't change often or that represents development-time -- versus assembly-time or deploy-time -- metadata. For example, annotations such as @Stateless, @WebService, and @Entity that define components are good uses of annotations. So too are annotations that specify environmental dependencies, such as @EJB, @Resources, @PersistenceContext, or annotations for EJB callbacks, such as @PostConstruct, @Timeout, and @Remove.

Deployment descriptors are best suited for metadata that isn't typically known until assembly or deployment time, or for metadata that is likely to change. An example of metadata that is best addressed by deployment descriptors is enterprise-bean security permissions. Also, there is information that simply can't be specified through annotations but can be specified through deployment descriptors. This includes metadata for EJB 3.0 default interceptors, EJB 2.x entity beans, and message destinations.

You can also use deployment descriptors to override annotations. However, Singh cautioned that too much overriding can make an application difficult to understand or maintain. Note too that overriding an annotation sometimes makes little sense. For example, you wouldn't want to override a bean type from, say, stateless to stateful.

And in some cases, defaults are all you need. The defaults for EJB 3.0 annotations and the Java Persistence API annotations are designed to correspond to what developers most typically specify. A case in point: The default transaction demarcation type in EJB 3.0 is container-managed transactions. If that's what you want, you don't have to specify an annotation or a deployment descriptor for it.

Dependency Injection

Dependency injection, also called resource injection, uses annotations -- or XML descriptors -- to identify dependencies that a class has on a resource or to obtain environmental references. These injections eliminate the need to do Java Naming and Directory Interface (JNDI) lookups. You can annotate a specific field or method in a class to request injection. You might think that you can request resource injection for the class as a whole. However, Singh pointed out that annotating a class, seemingly for dependency injection, is a dependency declaration -- it doesn't actually inject a resource into the class.

Which is best: field or method injection? Singh said that field-level annotations are easier to code. Method-level annotations are useful for logic tied to a specific dependency injection. He also said that if you do use field- or method-level injection, it's best to mark the fields or methods as private. That's because the injected data is internal to the class. Singh also reiterated that class-level annotations are not used for dependency injection but rather for dependency declarations without injection. They're also good for declaring dependencies for classes that are not managed by a container.

An important thing to note: Dependency injection is not a cure-all. For instance, it doesn't solve concurrency issues. Singh pointed out that if an object obtained through JNDI lookup is not sharable, it's still not sharable when injected.

What about performance? Singh said that most experts on the topic feel that injection is unlikely to cause performance issues. After all, resource injection essentially does a context lookup through JNDI when the class instance is created -- something a programmer already had to code for prior to the advent of resource injection.

EJB 3.0 Technology

The EJB 3.0 programming model is a major simplification of the EJB 2.1 model. EJB 3.0 components are coded as Plain Old Java Objects (POJOs), and most of the previous requirements for container interfaces have been eliminated. Also, EJB 3.0 takes advantage of annotations and resource injection, so deployment descriptors or JNDI lookups are no longer required.

Singh said that EJB 3.0's many benefits make it an excellent choice for developers over the EJB 2.1 model. EJB 3.0 helps componentize and modularize code. It enforces good programming technique and good application architecture. It's also a good interface to the Java Persistence API -- in fact, the Java Persistence API started out as an attempt to improve the persistence model in EJB 2.1. And EJB 3.0 is easy to use. However, nothing in the Java EE platform requires the use of EJB 3.0. So Singh said, "Use it based on your application requirements."

JSF Technology and (Ajax)

Another ease-of-use feature in the Java EE 5 platform is JSF 1.2 technology, which gives developers a framework for building web applications in the Java EE platform. Developers can use prepackaged JSF components in their applications, significantly reducing the need to write new code. Singh said that JSF technology is best used with tools such as Sun Java Studio Creator, which allows developers to take advantage of the tool's drag-and-drop capabilities. He also pointed out that JSF 1.2 technology is particularly good for use with (Ajax). Using JSF technology in this context requires little or no knowledge of JavaScript technology.

If you use a traditional approach such as servlets or JavaServer Pages (JSP) technology, Singh recommends using a Model-View-Controller (MVC) framework. He pointed out that JSF 1.2 technology is the standard MVC framework for the Java EE platform. Singh also said that, for Web 2.0 applications, you should "use an (Ajax) library like the DOJO toolkit to program your web pages."

Web Services (JAX-WS and JAXB)

The Java EE 5 platform includes two new APIs for web services: Java API for XML-Web Services (JAX-WS) 2.0 and Java Architecture for XML Binding (JAXB) 2.0. JAX-WS 2.0 provides a simplified programming model -- through annotations and dependency injection -- for developing and accessing web services. It provides an automatic mapping between Java objects and XML schema. JAX-WS 2.0 uses JAXB 2.0 for type mappings.

Singh mentioned that JAX-WS 2.0 is a follow-on to the Java API for XML-Based RPC (JAX-RPC) 1.1, but it breaks compatibility with JAX-RPC 1.1. That's why JAX-RPC 1.1 is still available for use. He also pointed out that JAXB 2.0 is bidirectional. You can use it both to map XML schema to Java objects and to map Java objects to XML schema. You can also use annotations to control the XML representation.

The strong recommendation here is to use JAX WS 2.0 with JAXB 2.0 for new web services applications.

Java Persistence API

Kangath described the features of the new Java Persistence API. In short, this API is used to manage entity persistence. It simplifies the EJB 2.1 entity persistence model and adds capabilities that were not in EJB 2.1 technology, such as support for inheritance and polymorphism and a complete Java Persistence Query Language. The API also standardizes object-relational mapping. Kangath emphasized that you do not have to use the Java Persistence API with EJB technology. You can use it in the Java EE web tier or in Java Platform, Standard Edition (Java SE).

Despite the many simplifications that the Java Persistence API provides, Kangath cautioned the audience about using it. To highlight this, she showed a persistence example that demonstrated a potential thread-safety hole. The example showed the code for a servlet with multiple methods, in which each method creates a query to retrieve data. Using an annotation, the servlet injected a dependency on a persistence context. This is the context in which a Java Persistence API Entity Manager manages the entities' persistence. However, the request was coded at the class level. In this case, the persistence context is injected when the servlet instance is created, and it's done only once. So concurrent requests coming to the servlet share the same persistent context. The problem is that because the persistence context is not thread-safe, neither is the servlet as a whole. Kangath suggested a number of alternatives that solve the problem. One alternative is to do a JNDI lookup for each method. This gets a separate persistence context for each request.

Summary

Singh summarized this session's key points as follows:

• Use annotations and defaults to define components and external dependencies.
• Use deployment descriptors to override annotations.
• Use EJB 3.0 for modularized components.
• Use the Java Persistence API for object-relational needs.
• Use JSF 1.2 technology components for drag-and-drop web application development.
• Use JAX-WS 2.0 (with integrated JAXB 2.0) to create web services.

For more insights and recommendations about the Java EE 5 programming model, as well as reference applications and a solutions catalog that shows code examples that use the platform's new features, see the BluePrints page.

Back to top