Programming WebLogic Enterprise JavaBeans, Version 3.0

      

Iterative Development of Enterprise JavaBeans 3.0

The sections that follow describe the general EJB 3.0 implementation process, and provide guidance for how to get an EJB 3.0 up and running in WebLogic Server.

For a review of WebLogic Server EJB features, see WebLogic Server Value-Added EJB 3.0 Features.

 

Overview of the EJB 3.0 Development Process

This section is a brief overview of the EJB 3.0 development process. It describes the key implementation tasks and associated results.

The following section mostly discusses the EJB 3.0 programming model and points out the differences between the 3.0 and 2.X programming model in only a few places. If you are an experienced EJB 2.X programmer and want the full list of differences between the two models, see Understanding EJB 3.0: New Features and Changes From EJB 2.X.

Table 4-1 EJB Development Tasks and Results
# Step Description Result
1 Create a Source Directory Create the directory structure for your Java source files, and optional deployment descriptors. A directory structure on your local drive.
2 Program the EJB 3.0 Business Interface Create the required business interface that describes your EJB. .java file.
3 Program the Annotated EJB Class Create the Java file that implements the business interface and includes the EJB 3.0 metadata annotations that describe how your EJB behaves. .java file.
4 Optionally Program Interceptors Optionally create the interceptor classes that describe the interceptors that intercept a business method invocation or a life cycle callback event. .java file.
5 Compile Java Source Compile source code. .class file for each class and interface.
6 Optionally Create and Edit Deployment Descriptors Optionally create the EJB-specific deployment descriptors, although this step is no longer required when using the EJB 3.0 programming model.

  • ejb-jar.xml,

  • weblogic-ejb-jar.xml, which contains elements that control WebLogic Server-specific features, and

  • weblogic-cmp-jar.xml if the bean is a container-managed persistence entity bean.
7 Packaging EJBs Package compiled classes and optional deployment descriptors for deployment. If appropriate, you can leave your files unarchived in an exploded directory. Archive file (either an EJB JAR or Enterprise Application EAR) or equivalent exploded directory.
8 Deploying EJBs Target the archive or application directory to desired Managed Server, or a WebLogic Server cluster, in accordance with selected staging mode. The deployment settings for the bean are written to EJBComponent element in config.xml.

 

Create a Source Directory

Create a source directory where you will assemble the EJB 3.0.

Oracle recommends a split development directory structure, which segregates source and output files in parallel directory structures. For instructions on how to set up a split directory structure and package your EJB 3.0 as an enterprise application archive (EAR), see “Overview of the Split Development Directory Environment” in Developing Applications with WebLogic Server.

If you prefer to package and deploy your EJB 3.0 in a JAR file, create a directory for your class files. If you are also creating deployment descriptors (which is optional but supported in the EJB 3.0 programming model) put them in a subdirectory named META-INF. Listing 4-1 Directory Structure for Packaging JAR

myEJB/
META-INF/
ejb-jar.xml
weblogic-ejb-jar.xml
weblogic-cmp-jar.xml
foo.class
fooHome.class
fooBean.class

 

Program the EJB 3.0 Business Interface

The EJB 3.0 business interface is a plain Java interface that describes the full signature of all the business methods of the EJB. For example, assume an Account EJB represents a client's checking account; its business interface might include three methods (withdraw, deposit, and balance) that clients can use to manage their bank accounts.

The EJB 3.0 business interface can extend other interfaces. In the case of message-driven beans, the business interface is typically the message-listener interface that is determined by the messaging type used by the bean, such as javax.jms.MessageListener in the case of JMS. The interface for a session bean has not such defining type; it can be anything that suits your business needs.

The only requirement for an EJB 3.0 business interface is that it must not extend javax.ejb.EJBObject or javax.ejb.EJBLocalObject, as required in EJB 2.X.

See Example of a Simple Stateless EJB and Example of a Simple Stateful EJB for examples of business interfaces implemented by stateless and stateful session beans.

 

Business Interface Application Exceptions

When you design the business methods of your EJB, you can define an application exception in the throws clause of a method of the EJB's business interface. An application exception is an exception that you program in your bean class to alert a client of abnormal application-level conditions. For example, a withdraw() method in an Account EJB that represents a bank checking account might throw an application exception if the client tries to withdraw more money than is available in their account.

Application exceptions are different from system exceptions, which are thrown by the EJB container to alert the client of a system-level exception, such as the unavailability of a database management system. You should not report system-level errors in your application exceptions.

Finally, your business methods should not throw the java.rmi.RemoteException, even if the interface is a remote business interface, the bean class is annotated with the @WebService JWS annotation, or the method is annotated with @WebMethod. The only exception is if the business interface extends java.rmi.Remote. If the EJB container encounters problems at the protocol level, the container throws an EJBException which wraps the underlying RemoteException.

The @WebService and @WebMethod annotations are in the javax.jws package; you use them to specify that your EJB implements a Web Service and that the EJB business will be exposed as public Web Service operations. For details about these annotations and programming Web Services in general, see Getting Started With WebLogic Web Services Using JAX-WS.

 

Using Generics in EJBs

The EJB 3.0 programming model supports the use of generics in the business interface at the class level.

Oracle recommends as a best practice that you first define a super-interface that uses the generics, and then have the actual business interface extend this super-interface with a specific data type.

The following example shows how to do this. First, program the super-interface that uses generics: 

  public interface RootI<T> {

    public T getObject();

    public void updateObject(T object);

  }

Then program the actual business interface to extend RootI<T> for a particular data type: 

  @Remote

  public interface StatelessI extends RootI<String> { }

Finally, program the actual stateless session bean to implement the business interface; use the specified data type, in this case String, in the implementation of the methods: 

  @Stateless

  public class StatelessSample implements StatelessI {

    public String getObject() {

      return null;

    }

    public void updateObject(String object) {

    }

  }

If you define the type variables on the business interface or class, they will be erased. In this case, the EJB application can be deployed successfully only when the bean class parameterizes the business interface with upper bounds of the type parameter and no other generic information. For example, in the following example, the upper bound is Object: 

public class StatelessSample implements StatelessI<Object> { 

   public Object getObject() { 

      return null;

   } 

   public void updateObject(Object object) { 

   } 

}

 

Serializing and Deserializing Business Objects

Business object serialization and deserialization are supported by the following interfaces, which are implemented by all business objects:

Use the BusinessObject._WL_getBusinessObjectHandle() method to get the business handle object and serialize the business handle object.

To deserialize a business object, deserialize the business handle object and use the BusinessHandle.getBusinessObject() method to get the business object.

 

Program the Annotated EJB Class

The EJB bean class is the main EJB programming artifact. It implements the EJB business interface and contains the EJB metadata annotations that specify semantics and requirements to the EJB container, request container services, and provide structural and configuration information to the application deployer or the container runtime.

In the 3.0 programming model, there is only one required annotation: either @javax.ejb.Stateful, @javax.ejb.Stateless, or @javax.ejb.MessageDriven to specify the type of EJB. Although there are many other annotations you can use to further configure your EJB, these annotations have typical default values so that you are not required to explicitly use the annotation in your bean class unless you want it to behave other than in the default manner. This programming model makes it very easy to program an EJB that exhibits typical behavior.

For additional details and examples of programming the bean class, see Programming the Annotated EJB 3.0 Class.

 

Optionally Program Interceptors

An interceptor is a method that intercepts the invocation of a business method or a life cycle callback event.

You can define an interceptor method within the actual bean class, or you can program an interceptor class (distinct from the bean class itself) and associate it with the bean class using the @javax.ejb.Interceptor annotation.

See Specifying Interceptors for Business Methods or Life Cycle Callback Events for information on programming the bean class to use interceptors.

 

Compile Java Source

Once you have written the Java source code for your EJB bean class and optional interceptor class, compile it into class files. Typical tools to compile include:

 

Optionally Create and Edit Deployment Descriptors

A very important aspect of the new EJB 3.0 programming model is the introduction of metadata annotations. Annotations simplify the EJB development process by allowing a developer to specify within the Java class itself how the bean behaves in the container, requests for dependency injection, and so on. Annotations are an alternative to deployment descriptors that were required by older versions (2.X and earlier) of EJB.

However, EJB 3.0 still fully supports the use of deployment descriptors, even though the standard Java Platform, Enterprise Edition (Java EE) Version 5 ones are not required. For example, you may prefer to use the old 2.X programming model, or might want to allow further customizing of the EJB at a later development or deployment stage; in these cases you can create the standard deployment descriptors in addition to, or instead of, the metadata annotations.

Deployment descriptor elements always override their annotation counterparts. For example, if you specify the @javax.ejb.TransactionManagement(BEAN) annotation in your bean class, but then create an ejb-jar.xml deployment descriptor for the EJB and set the <transaction-type> element to container, then the deployment descriptor value takes precedence and the EJB uses container-managed transaction demarcation.

This version of EJB 3.0 also supports all 2.X WebLogic-specific EJB features. However, the features that are configured in the weblogic-ejb-jar.xml or weblogic-cmp-rdbms-jar.xml deployment descriptor files must continue to be configured that way for this release of EJB 3.0 because currently they do not have any annotation equivalent.

The 2.X version of Programming WebLogic Enterprise JavaBeans provides detailed information about creating and editing EJB deployment descriptors, both the Java EE standard and WebLogic-specific ones. In particular, see the following sections:

 

Packaging EJBs

Oracle recommends that you package EJBs as part of an enterprise application. For more information, see Deploying and Packaging from a Split Development Directory in Developing Applications with WebLogic Server.

See Packaging Considerations for EJBs with Clients in Other Applications in Programming WebLogic Enterprise JavaBeans for additional EJB-specific packaging information.

 

Deploying EJBs

Deploying an EJB enables WebLogic Server to serve the components of an EJB to clients. You can deploy an EJB using one of several procedures, depending on your environment and whether or not your EJB is in production. Deploying an EJB created with the 3.0 programming model is the same as deploying an EJB created with the 2.X programming model.

For general instructions on deploying WebLogic Server applications and modules, including EJBs, see Deploying Applications to WebLogic Server. For EJB-specific deployment issues and procedures, see Deployment Guidelines For Enterprise Java Beans in the Programming WebLogic Enterprise JavaBeans guide, which concentrates on the 2.X programming model.