Table of Contents
In the first part of this series we've introduced the mechanisms provided by the Enterprise JavaBeans v. 3.0 Specification to define EJB components, declare a reference to an EJB and wiring them up both by dependency injection or programmatic JNDI lookup.
In this blog post we'll examine some basic examples to understand how to use the EJB API.
A Basic EJB
An EJB is basically a POJO with some extra EJB metadata. The required metadata to deploy it as an EJB component can be provided both by using the EJB annotations or by the standard deployment descriptor. The following class implements a very basic stateless session EJB:
package es.reacts;
import javax.ejb.Stateless;
@Stateless(name = "UniqueLocalSessionEJB")
public class UniqueLocalSessionEJBBean implements UniqueLocalBusinessInterface {
public UniqueLocalSessionEJBBean() {
}
public String sayLocalHello() {
return this.getClass().getName() + "::" + "Local hello.";
}
}
As you may recollect from our previous blog post, the @Stateless annotation is used to define a stateless session bean. The optional name element is used to define the session bean name. This element is analogous to the <ejb-name/> element of the standard deployment descriptor. This element defaults to the unqualified name of the bean class (UniqueLocalSessionEJBBean in the example above), and the example above uses it to rename the bean to UniqueLocalSessionEJB.
Since we're using the @Stateless annotation, there's no further need to declare the EJB in the deployment descriptor.
In this example, we're assuming that the EJB is packaged in an EJB module that depends on the module containing the definition of its business interface (as explained in the following section.)
Business interfaces
Every EJB implements one or more business interfaces. Business interfaces can be local or remote. The most important differences between the two types of business interfaces can be summarized as follows:
- Local business interfaces use pass-by-reference semantics for their methods and method invocations cannot cross the JVM boundary. Local business interfaces are available only to callers in the same application and JVM instance of the callee.
- Remote business interfaces use pass-by-value semantics for their methods and method invocations can cross the JVM boundary. Remote business interfaces are available to callers outside the application of the callee.
In the previous example, the business interface UniqueLocalBusinessInterface is declared as follows:
package es.reacts;
import javax.ejb.Local;
@Local
public interface UniqueLocalBusinessInterface {
String sayLocalHello();
}
In the EJB v. 3.0 world a business interface is just a plain old Java interface annotated with either the @Local or @Remote annotation.
Packaging Business Interfaces
In this example we're assuming that the EJB business interface is packaged in a JAR file that the EJB module depends on. Since EJB clients only depend on an EJB business interface, it's a good practice to package the business interfaces in a separate library in order to ease the interface distribution and to decouple them from their implementations.
Injecting an EJB into a Java Servlet
Now that we've defined an EJB, we're ready to use it from a servlet in a Java EE web module. Assuming that there's only one EJB implemented the UniqueLocalBusinessInterface in our application, we can inject it using an empty @EJB annotation:
package es.reacts;
import java.io.IOException;
import java.io.PrintWriter;
import javax.ejb.EJB;
import javax.servlet.*;
import javax.servlet.http.*;
public class ServletTest1 extends HttpServlet {
@EJB
UniqueLocalBusinessInterface lc;
public void doGet(HttpServletRequest request,
HttpServletResponse response)
throws ServletException, IOException {
[...]
lc.sayLocalHello();
[...] }
The first thing to note is that the EJB is injected into our servlet by the application server since the bean interface alone is sufficient to identify the target EJB. In this case the beanInterface element of the @EJB annotation takes on its default value, as explained in our previous post, that is the type of the injected field: UniqueLocalBusinessInterface. Since there's just one EJB in the application that implements this business interface, the lc field of the servlet is injected with a reference to an instance of such a class.
The second thing worth pointing out is that we're injecting an EJB into a servlet field safely because the EJB is stateless. Since servlet are stateless by default, you should not inject stateful resources into servlet fields properties otherwise you may run into concurrency-related problems. If you needed to use a stateful EJB into a servlet, you should retrieve a reference by programmatic JNDI lookup since that will guarantee that a new instance is returned for every lookup operation.
Let's deploy and run our application and we'll see that the servlet is injected its target EJB and the method invocation to the sayLocalHello() method of its business interface is carried out correctly.
If we wanted to inject a reference to a remote interface the client code would not be affected. If you try and change the UniqueLocalBusinessInterface from @Local to @Remote, you'll see that the servlet sees no change and continues to work correctly.
What Happens If More Than One EJB Implements the Same Interface?
Let's suppose that the we add another EJB in our EJB module in this application that implements the same interface as the previous one, UniqueLocalBusinessInterface. In this case, since the bean interface is not sufficient any longer to determine the target bean for injection, you'll be returned an error. Deploying such an application in the WebLogic Application Server, for example, results in the following error being thrown:
[08:46:25 PM] Caused by: weblogic.deployment.EnvironmentException: [J2EE:160199]Error resolving ejb-ref 'es.reacts.ServletTest1/lc1' from module 'WebTest0' of application 'EJBTestApp'. The ejb-ref does not have an ejb-link and the JNDI name of the target bean has not been specified. Attempts to automatically link the ejb-ref to its target bean failed because multiple EJBs in the application were found to implement the 'es.reacts.UniqueLocalBusinessInterface' interface. Please specify a qualified ejb-link for this ejb-ref to indicate which EJB is the target of this ejb-ref.
Injecting a Reference to a Specific EJB Instance
To solve the problem occurred in the previous section we need to provide the application server with the required information to identify the target EJB. As explained in our previous post, we can use the following two methods:
- Either we use the name element of the @EJB annotation (or the corresponding <ejb-ref-name/> element of the deployment descriptor) to declare an EJB reference in the private namespace of the application and link it to the target bean using the deployment descriptor.
- Or we use the beanName element of the @EJB annotation (or the corresponding <ejb-link/> element of the deployment descriptor) to do it directly in our code.
Mapping an EJB into the Private Namespace
Using the first method we'll end up with the following code in our servlet:@EJB(name = "ejb/bean-name")
UniqueLocalBusinessInterface lc;
and the following element in the deployment descriptor (web.xml) of our Java EE web module that acts as an EJB client:
<ejb-local-ref>
<ejb-ref-name>ejb/bean-name</ejb-ref-name>
<ejb-ref-type>Session</ejb-ref-type>
<local>es.reacts.UniqueLocalBusinessInterface</local>
<ejb-link>UniqueLocalSessionEJB</ejb-link>
</ejb-local-ref>
The <ejb-link/> element contains the bean name that we defined at the beginning of our example with the annotation:
@Stateless(name = "UniqueLocalSessionEJB")
in the EJB implementation class.
Please note that, in this example, we used the @EJB name element explicitely but we could have established the link using its default value. The default value of the name element is:
[qualified class name]/[property or field name]
that, in this case, would be:
es.reacts.ServletTest1/lc
The disadvantage of using the default auto-generated name together with EJB linking using <ejb-link/> is that every time you refactor your code you'll have to check the deployment descriptors. Although developers sometimes think otherwise, the Java EE Specification defines some other roles such as the assambler and the deployer. In large corporate environments, it's not uncommon for such profiles to override developers' annotations to "plumb" the components used by the applications. Annotation override is one of the reasons why standard deployment descriptors still exist. This is especially true when references are to remote components, inside or outside your application. For this reason I suggest you do not rely on auto-generated names and use custom well documented names instead.
Please note that, in this example, we used the @EJB name element explicitely but we could have established the link using its default value. The default value of the name element is:
[qualified class name]/[property or field name]
that, in this case, would be:
es.reacts.ServletTest1/lc
The disadvantage of using the default auto-generated name together with EJB linking using <ejb-link/> is that every time you refactor your code you'll have to check the deployment descriptors. Although developers sometimes think otherwise, the Java EE Specification defines some other roles such as the assambler and the deployer. In large corporate environments, it's not uncommon for such profiles to override developers' annotations to "plumb" the components used by the applications. Annotation override is one of the reasons why standard deployment descriptors still exist. This is especially true when references are to remote components, inside or outside your application. For this reason I suggest you do not rely on auto-generated names and use custom well documented names instead.
Linking an EJB to a Reference in the Private Namespace
The second method provides a direct way to link the reference to its target bean using the beanName element of the @EJB annotation. The servlet code will use the following EJB reference:
@EJB(beanName = "UniqueLocalSessionEJB")
UniqueLocalBusinessInterface lc;
and we need no additional information in the deployment descriptor.
Although this method allows the developer to link a reference to an EJB without relying on the deployment descriptor, the suggestion given at the end of the previous section is still valid. Remember that annotations can be overridden at deployment time! Do not link an EJB to a reference if you know beforehand that such a reference is eligible for override. In such cases, prefer assigning a name to the reference instead, as explained in the previous section.
Although this method allows the developer to link a reference to an EJB without relying on the deployment descriptor, the suggestion given at the end of the previous section is still valid. Remember that annotations can be overridden at deployment time! Do not link an EJB to a reference if you know beforehand that such a reference is eligible for override. In such cases, prefer assigning a name to the reference instead, as explained in the previous section.
Next Steps
In the following post we'll make a quick overview of how the EJB 3.0 API can be used to perform EJB programmatic lookups.
