How do you use an Enterprise Bean in Your Application?

In general, you use an enterprise bean from a client (see "Understanding Client Access").

You can also use enterprise beans to implement fine-grained control over method invocation flow (see "Understanding EJB 3.0 Interceptors").

You can also use enterprise beans with Web services, either as a Web service client or as a Web service endpoint (see "Understanding EJB and Web Services").

In a deployed EJB application, you can exploit the component nature of a Java EE application to monitor and control EJB performance and resource utilization (see "Understanding EJB Administration").

Understanding Client Access

In general, you use an enterprise bean from a client (see "What Type of Client do you Have?") to perform application tasks such as conducting a session, persistence, or message handling. For more information, see "Accessing an Enterprise Bean From a Client".

Understanding EJB 3.0 Interceptors

An interceptor is a method that you associate with an EJB 3.0 session bean business method or message-driven bean message listener method. When a client invokes such a method, OC4J intercepts the client invocation and invokes your interceptor method before allowing the client invocation to proceed.

You can define an interceptor method and interceptor life cycle callback methods on the bean class or in a separate interceptor class that you associate with the bean.

You can define only one non-life cycle callback interceptor for each bean: this method is known as the javax.interceptor.AroundInvoke method. Each time a business method is invoked, OC4J first invokes the AroundInvoke method. A life cycle callback interceptor method is invoked only when the corresponding life cycle event occurs.

An interceptor method you define in a separate interceptor class takes an invocation context as argument: using this context, your interceptor method implementation can access details of the original session bean business method or message-driven bean message listener method invocation.

This section describes the following:

Interceptor Restrictions
Singleton Interceptors

For more information, see the following:

Interceptor Restrictions

You can use interceptors with session beans (stateless and stateful) and message-driven beans.

OC4J applies an interceptor to all business methods of a bean.

If there are multiple interceptors (one interceptor method and one or more interceptor classes each with one interceptor method of their own), then each time a client invokes a business method, OC4J first invokes the interceptor classes in the order in which they are defined and then the interceptor method, before allowing the client invocation to proceed.

An interceptor method may not be a business method.

An interceptor method must have the following signature:

Object <METHOD>(InvocationContext) throws Exception

An interceptor method may have public, private, protected, or package level access but must not be declared as final or static.

Within an interceptor, you can use the InvocationContext to access client invocation metadata.

Interceptor method invocations occur within the same transaction and security context as the business method for which they are invoked.

Interceptor methods can mark their transaction for rollback by throwing a run-time exception, or by calling setRollbackOnly using its EJBContext object as follows:

InvocationContext.getEJBContext().setRollbackOnly();

Interceptors may cause this rollback before or after they call InvocationContext.proceed().

For more information, see "Using a Rollback Strategy".

When using container-managed transactions (see "What are Container-Managed Transactions?"), interceptors must not use any resource-manager specific transaction management methods that would interfere with the container's demarcation of transaction boundaries. For example, the interceptor must not use the following methods of the java.sql.Connection interface: commit, setAutoCommit, and rollback; or the following methods of the javax.jms.Session interface: commit and rollback. Interceptors must not attempt to obtain or use the javax.transaction.UserTransaction interface.

Singleton Interceptors

As specified in the EJB 3.0 specification, by default, OC4J creates bean interceptors: the life cycle of a bean interceptor instance is the same as that of the bean instance with which it is associated. When the bean instance is created, interceptor instances are created for each interceptor class defined for the bean. These interceptor instances are destroyed when the bean instance is removed. This allows you to store state in your interceptors.

If your interceptors are stateless, you can use an OC4J optimization extension to the EJB 3.0 specification that allows you to specify singleton interceptors. When you configure a session bean or message-driven bean to use singleton interceptors and you associate the bean with an interceptor class, OC4J creates a single instance of the interceptor class that all bean instances share. This can reduce memory requirements and life cycle overhead.

For more information, see the following:

Understanding EJB and Web Services

You can expose a stateless session bean as a Web service endpoint. Any EJB type can be the client of a Web service.

For more information, see "Using EJB and Web Services".

Understanding EJB Administration

After you deploy your Java EE application, you can use Java EE administration features to monitor and optimize your application at run time.

For more information, see the following: