One of the key new features in Enterprise JavaBeans 3.0 are
interceptors
. Actually, the concept of interceptors is not new and has been alive for quite some time. But now, with version 3.0 of the EJB specification they become a standard. And they are as easy to learn and use as everything else in EJB 3.0 and Java EE 5. The EJB container in
SAP NetWeaver Application Server, Java EE 5 Edition , as a fully compatible EJB 3.0 implementation, also supports interceptors.
In this first part of a two-part blog series I'm giving a basic introduction to EJB 3.0 interceptors and discuss their main features.
What are interceptors?
Well, as the EJB specification defines them, "interceptors are used to interpose on business method invocations and lifecycle events that occur on an enterprise bean instance". More precisely, interceptors are classes defining methods that are invoked in response to client business method invocations and/or lifecycle events on the bean. Interceptor methods wrap business method invocations or lifecycle callbacks with some custom user-defined code (we'll see in the second part of these series some examples of such code).
Defining interceptors
Interceptor classes and methods are defined by means of metadata annotations or the ejb-jar.xml deployment descriptor. Both approaches are almost equivalent (with only two exceptions which I'll mention later), so for simplicity and because Java EE 5 heavily relies on them I'll talk about annotations here, but should say that the same can be expressed with corresponding XML tags too.
Interceptor methods can be defined on the bean class itself as well as on an interceptor class associated with the bean. Any number of interceptor classes may be associated with a bean. They are denoted by applying the
@Interceptors
annotation to the bean class (
class-level interceptors) and/or to business methods of the bean (
method-level interceptors). There is also a third kind -
default interceptors - which may be defined only in the deployment descriptor and apply to all components within the ejb-jar.
Within each interceptor class or the bean class itself, interceptor methods are designated again with annotations. Business method interceptor methods are denoted by the - when defined on a bean class
and can have any access modifier (public, private, protected, or package level).
Interceptor methods invocation order
The EJB specification strictly defines the order in which interceptor methods are invoked in case more than one are defined for a given business method or lifecycle event of a bean. First, default interceptors, if any, are invoked in the order of their specification in the ejb-jar.xml. After that, class-level interceptors are invoked in the order of their specification in the
@Interceptors
annotation. Next, method-level interceptors are invoked in the same order as the specification of interceptor classes in the
@Interceptors
annotation applied to the given business method (method-level interceptors can be defined only for business methods and not for lifecycle event callbacks). Finally, the interceptor method, if any, on the bean class itself is invoked. For a more formal definition of these rules please refer to sections 12.3.1 and 12.4.1 of the
EJB 3.0 Core specification .
This default ordering of interceptors invocation may be overridden in the deployment descriptor by using the
interceptor-order
XML element. The invocation of default interceptors and class-level interceptors for a given class and/or business method may be excluded by applying the
@ExcludeDefaultInterceptors
and
@ExcludeClassInterceptors
annotations, respectively, to that class and/or business method.
Interceptors characteristics
The programming restrictions that apply to enterprise bean components apply to interceptors as well. This means, for example, that you must not attempt to manage threads, use file I/O operations, or create or manage class loaders in interceptor classes. See section 21.1.2 of the EJB 3.0 Core specification for the complete list and explanations of the EJB programming restrictions.
Interceptor instances share the same lifecycle with the bean instance they are associated with. Interceptor instances are created, destroyed, passivated, and activated, when the bean instance is created, removed, passivated, and activated (the latter two are relevant only in the case of stateful session beans, of course). Interceptors may hold state and also support dependency injection. They share the environment naming context (ENC) of the bean for which business methods and lifecycle callbacks they are invoked. Interceptor classes may request the injection of the
EJBContext
object and may use its
lookup
method to access the bean's ENC. They can also invoke JNDI, JDBC, JMS, UserTransaction, EntityManager, other enterprise beans - in short, any component or resource that the respective business method or lifecycle callback can.
Business method interceptor methods may throw system runtime exceptions or any application exceptions that are allowed in the throws clause of the business method. Lifecycle callback interceptor methods may throw system runtime exceptions but not application exceptions. In both cases, if a system exception escapes the interceptor chain the bean instance and any associated interceptor instances are discarded and the PreDestroy callbacks are not invoked in this situation. Business method interceptor methods run in the same transaction and security context as the business method for which they are invoked. Lifecycle callback interceptor methods are invoked in an unspecified transaction and security context.
In the EJB 3.0: Interceptors and Callbacks Made Easy - Part II of these series we explore the
InvocationContext
interface and see some examples of interceptors use cases.
References:
Enterprise JavaBeans Technology
Java EE 5 at SAP
Enterprise JavaBeans Specification
EJB 3.0: Interceptors and Callbacks Made Easy - Part II
