Skip Headers

Oracle® Containers for J2EE Enterprise JavaBeans Developer's Guide 10g Release 3 (10.1.3) B14428-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# How Do You Use an EJB in Your Application?

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

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

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

## Understanding Client Access

In general, you use an EJB 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 EJB from a Client".

## Understanding EJB 3.0 Interceptors

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

This section describes:

- Interceptor Restrictions

- Interceptors and Invocation Context

For more information, see:

- "Configuring an Interceptor on an EJB 3.0 Session Bean"

- "Configuring an Interceptor on an EJB 3.0 MDB Message Listener Method"

Note: In this release, OC4J interceptor support does not comply with the functionality specified in the EJB 3.0 public review draft. If you use interceptors, you may need to make code changes to your EJB 3.0 OC4J application after the EJB 3.0 specification is finalized and OC4J is updated to full EJB 3.0 compliance. For more information, see "Understanding EJB Support in OC4J".

### Interceptor Restrictions

You can use interceptors with:

- stateless session beans

- stateful session beans

- message driven beans

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

In this release, you must define an interceptor as a method of the bean class to which it applies. You may define only one interceptor method per class.

An interceptor method may not be a business method.

An interceptor method has the following signature:

    public Object <METHOD>(InvocationContext) throws Exception

Within an interceptor, you can use the `InvocationContext` to access client invocation metadata (see "Interceptors and Invocation Context").

An interceptor must observe the following transaction restrictions:

- 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 runtime 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 "Container-Managed Transaction (CMT)"), 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.

### Interceptors and Invocation Context

Using the `InvocationContext` API, you can access (and modify) all the metadata relevant to the client invocation and implement fine grained control over method invocation flow by selectively choosing whether or not to allow the client invocation to proceed. Using EJB 3.0 interceptors, you can:

- Modify parameters before they're passed to the bean

- Modify the value returned from the bean

- Catch and swallow method exceptions

- Interrupt the call completely (for example, to implement your own security framework)

- Provide method profiling

## Understanding EJB Administration

After you deploy your J2EE application, you can use J2EE administration features to monitor and optimize your application at runtime.

For more information, see:

- "Administrating an EJB Application"

- "Optimizing EJB Performance" on page 32-1