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.
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.
Create a source directory where you will assemble the EJB 3.0.
BEA 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
.
myEJB/
META-INF/
ejb-jar.xml
weblogic-ejb-jar.xml
weblogic-cmp-jar.xml
foo.class
fooHome.class
fooBean.class
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.
WARNING: | 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.
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
.
Note: | 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
Programming WebLogic Web Services. |
The EJB 3.0 programming model supports the use of generics in the business interface at the class level.
BEA 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 Root*<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) {
}
}
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.
An interceptor is a method that intercepts the invocation of a business method or a lifecycle 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 Lifecycle Callback Events for information on programming the bean class to use interceptors.
Once you have written the Java source code for your EJB bean class and optional interceptor class, you must compile it into class files. Typical tools to compile include:
weblogic.appc—
The weblogic.appc
Java class (or its equivalent Ant task wlappc
) generates and compiles the classes needed to deploy EJBs and JSPs to WebLogic Server. It validates the optional deployment descriptors for compliance with the current specifications at both the individual module level and the application level. The application-level checks include checks between the application-level deployment descriptors and the individual modules as well as validation checks across the modules. See Building Modules and Applications Using wlappc.
javac
compiler to compile your application's Java components in a split development directory structure.See Compiling Applications Using wlcompile
javac
—The javac
compiler provided with the Sun Java J2SE SDK provides java compilation capabilities.
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.
Note: | 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:
BEA 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 for additional EJB-specific packaging information.
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.