August 8, 2020
Hot Topics:

Packaging EJB 3 Applications

  • By Debu Panda, Reza Rahman, Derek Lane
  • Send Email »
  • More Articles »

Overriding annotations with deployment descriptors

As we explained, you can mix and match deployment descriptors with annotations and use descriptors to override settings originally specified using annotations. Keep in mind that the more you mix the two, the more likely you are to make mistakes and create a debugging nightmare.

NOTE The basic rule to remember is that the name element in stateless, stateful, and message-driven annotations is the same as the ejb-name element in the descriptor. If you do not specify the name element with these annotations, the name of the bean class is understood to be the ejb-name element. This means that when you are overriding an annotation setting with your deployment descriptor, the ejb-name element must match the bean class name.

Suppose we have a stateless session bean that uses these annotations:

@Stateless (name = "BazaarAdmin")
public class BazaarAdminBean implements BazaarAdmin {
@TransactionAttribute (TransactionAttributeType.REQUIRES_NEW)
public Item addItem() {

The value for the name element specified is BazaarAdmin, which is the same as the value of the ejb-name element specified in the deployment descriptor:


If you do not specify the name element, the container will use the name of BazaarAdminBean as the name of the bean class, and in order to override annotations you have to use that name in the deployment descriptor:


We used @TransactionAttribute to specify that the transaction attribute for a bean method be REQUIRES_NEW. If we want to override it to use REQUIRED,1 then we use the following descriptor:

Click here for a larger image.

Editor's Note: The bracketed numbers in the following paragraph refer to the callouts in the code snippet above.

In this example, we used the assembly-descriptor element to specify a transaction attribute [2]. In addition, the ejb-name element [1] in the assembly-descriptor matches the original name specified with the @Stateless annotation in the bean class.

Specifying default interceptor settings

Interceptors allow you to implement cross-cutting code in an elegant manner. An interceptor can be defined at the class or method level, or a default interceptor can be defined at the module level for all EJB classes in the EJB-JAR. We mentioned that default interceptors for an EJB module can only be defined in the deployment descriptor (ejb-jar.xml). Listing 4 shows how to specify default interceptors for an EJB module.

Listing 4 Default interceptor setting in ejb-jar.xml

Editor's Note: The bracketed numbers in the following paragraph refer to the callouts in listing 4.

The interceptor-binding [1] tag defines the binding of interceptors to a particular EJB with the ejb-name element. If we want to define the default interceptor or an interceptor binding for all EJBs in the EJB module, then we can specify * as the value for ejb-name [2]. We specify a class to use as the interceptor with the <interceptor-class> tag. As evident from the listing, you can specify multipleinterceptors in the same binding, and the order in which they are specified in the deployment descriptor determines the order of execution for the interceptor. In our example, CheckPermissionInterceptor will be executed prior to ActionBazaarDefaultInterceptor when any EJB method is executed.

Using vendor-specific annotations and descriptors

We've already explained that stateless session beans and MDBs may be pooled. In addition, you can configure passivation for stateful session beans, and you can set up the handling of poisonous messages for MDBs. However, we have not discussed configuration details for either of these scenarios. Unfortunately, these configurations are left to the vendors as proprietary features, and they can be supported with proprietary annotations, proprietary deployment descriptors, or both. Table 4 lists the name of the deployment descriptor file for some popular application servers.

Table 4 Vendor-specific deployment descriptors for popular application servers

Application Server Vendor-Specific Deployment Descriptor
BEA WebLogic weblogic-ejb-jar.xml
IBM WebSphere ibm-ejb-jar.xml
JBoss jboss.xml
Oracle Application Server orion-ejb-jar.xml
Sun GlassFish sun-ejb-jar.xml

Many developers shun deployment descriptors as a matter of inconvenience. Application server vendors will continue to provide support for annotations that match deployment descriptor elements, as developers voice their preference for these features. Chances are that each vendor has a set of proprietary annotations to set configuration information with the code.

For example, you can use the oracle.j2ee.ejb.StatelessDeployment proprietary annotation to provide configuration information such as pooling and transaction management for stateless session beans. Look at the following code, which configures pooling with Oracle's proprietary annotation:

import oracle.j2ee.ejb.StatelessDeployment;

   minInstances = 100, maxInstances = 500,
   poolCacheTimeout = 120) @Stateless (name = "BazaarAdmin")
public class BazaarAdminBean implements BazaarAdmin {

As other Java EE vendors create their implementations of EJB 3, we anticipate that each vendor will devise its own subset of corresponding annotations as well.

You should review these proprietary annotations with caution for a couple of reasons. First, adding configuration information in the code is not a good idea, although application servers provide the ability to override this information with their proprietary deployment descriptors. This is not desirable because in order to make a change to the setting, the code must be edited and compiled, and in most organizations it must go through a significant quality assurance effort before being released to production. Another reason is that as the code is promoted across different environments (Development, Test, Production, etc.), the deployer may change the configuration to accommodate different servers and environmental configurations.

Second, this defeats the goal of portability of applications. Deployment descriptors serve as a guideline to the deployer to understand the contents, the applications, and the suggested configurations. Deployers manage the deployment to each environment by tweaking the configuration. We recommend using the proprietary deployment descriptors instead of using deployment annotations. If you're using Oracle, you could use the following element in Oracle's proprietary descriptor (orion-ejb-jar.xml) element as follows:

   name = "BazaarAdmin"
   tx-retry-wait = "60"
   max-instances = "500"
   min-instances = "100"
   pool-cache-timeout = "120"
   location = "BazaarAdmin">


1. Keep in mind the impact of changing a transaction attribute from RequiresNew to Required, as shown in this example.


At the heart of Java EE applications lies the art of assembly and packaging enterprise applications. This article briefly introduced the concepts of class loading and code sources used by various application archives. We also explained how to package all of the EJB types, including persistence entities. You learned about the deployment descriptor of an EJB-JAR module, and how you can use descriptors to override settings specified in metadata annotations.

About the Authors

Debu Panda is a Lead Product Manager of the Oracle Application Server development team, where he drives development of the Java EE container. He has more than 15 years of experience in the IT industry and has published numerous articles on enterprise Java technologies in several magazines and has presented at many conferences. His J2EE-focused weblog can be found at debupanda.com.

Reza Rahman is an architect with Tripod Technologies, an IT solutions company focusing on Java EE in the Baltimore-NYC corridor. Reza has been working with Java as a language and Java EE as a platform since their inception in the mid-nineties. He has worked with both Enterprise Java Beans and open source tools like Spring and Hibernate, developing enterprise systems in the software, consulting, financial, Telecommunications, and manufacturing industries.

Derek Lane is the CTO of Semantra, Inc. He has worn various hats in his career including mentor, coach, architect, manager, developer, trainer, methodologist, and resident open source zealot. Lane is a contributor to projects of various shape and size as author, presenter, and technical reviewer. Lane is the founder of both the Oklahoma City Java User Group (OKCJUG) and the Dallas/Fort Worth, Texas MicroJava User Group; and has been active as a member, presenter, and mentor for over a decade at various technology user groups across the Midwest and Southern U.S.

Source of This Material

EJB 3 in Action
By Debu Panda, Reza Rahman, Derek Lane
Published: April 4, 2007, Paperback: 712 pages
Published by Manning Publications Co.
ISBN: 1-933988-34-7
Retail price for softbound print book + PDF ebook
PDF ebook: $22.50
This material is from Chapter 11 of the book. Reprinted with the publisher's permission.

Page 4 of 4

This article was originally published on April 9, 2007

Enterprise Development Update

Don't miss an article. Subscribe to our newsletter below.

Thanks for your registration, follow us on our social networks to keep up-to-date