Entity EJBs in the EJB 1.1 specification were fairly simple representations of business objects in a storage mechanism, usually a database. There was no defined standard for defining relationships, finder methods or local beans (as opposed to assuming every bean is a potentially remote object). Container providers therefore created these features in their containers. Each container implemented these features in different ways, so making the process of moving applications from one vendor to another more difficult.
Recognizing this, the EJB 2.0 specification more clearly defines the roles
of entity beans. This includes standard query definition (EJB QL), local interfaces
and abstract classes. This article will focus on Local Interfaces in CMP beans.
The EJB 1.1 specification defines all EJBs as remote objects. This means that every time you make a call to an EJB, you are making a remote call. This means that there is considerable overhead to each EJB call, and hence performance implications. To combat this, server vendors invented a way of circumventing the remote calls to some degree. Oracle's solution with OC4J was the pass-by-reference setting, which determined whether EJB objects were communicated by reference to the object, or whether the whole object had to be passed to the client.
An EJB has a remote interface and a home interface, with the exception of MessageDrivenBeans. The remote interface extends the interface javax.ejb.EJBObject and the home interface extends the interface javax.ejb.EJBHome. The EJB is accessible from any client, in any JVM, provided they have the proper authorization.
For example, the Home and Remote interfaces of an EJB called EMP may look like this.
Remote:
public interface Emp extends EJBObject
{
long getEmpno() throws RemoteException;
void setEmpno(long newDeptno) throws RemoteException;
String getEname() throws RemoteException;
void setEname(String newDname) throws RemoteException;
Home:
public interface DeptHome extends EJBHome
{
public Emp create() throws RemoteException, CreateException;
public Dept findByPrimaryKey(DeptPK primaryKey) throws RemoteException, FinderException;
Note that both the home and the remote interface throw a RemoteException in all of their method definitions. The ejb-jar.xml deployment descriptor for these EJBs would look something like the snippets below:
<entity>
<ejb-name>Emp</ejb-name>
<home>ejb.cmplocal.EmpHome</home>
<remote>ejb.cmplocal.Emp</remote>
<ejb-class>ejb.cmplocal.EmpBean</ejb-class>
.
.
.
The EJB 2.0 specification standardize a means of making local connections to EJBs with Local Interfaces.
For an EJB to be classed as a local EJB, it must implement the local versions of the home and remote interfaces, javax.ejb.EJBLocalObject for the Home interface, and javax.ejb.EJBLocalHome. For a client to call the Local interface, they must be running in the same JVM as the JVM that the EJB exists in. This means that not only an EJB can call a local EJB , Servlets or JSPs can also call the EJB via it's local interface if they are packaged together as part of same application.
For example, the LocalHome and Local interfaces of an EJB called EMP may look like this.
Local:
public interface Emp extends EJBLocalObject
{
long getEmpno();
void setEmpno(long newEmpno);
String getEname();
void setEname(String newEname);
LocalHome:
public interface EmpHome extends EJBLocalHome
{
public Emp create() throws CreateException;
public Emp findByPrimaryKey(EmpPK primaryKey) throws FinderException;
The ejb-jar.xml deployment descriptor for these EJBs would look something like the snippets below:
<entity>
<ejb-name>Emp</ejb-name>
<local-home>ejb.cmplocal.EmpHome</local-home>
<local>ejb.cmplocal.Emp</local>
<ejb-class>ejb.cmplocal.EmpBean</ejb-class>
<cmp-version>2.x</cmp-version>
<abstract-schema-name>Emp</abstract-schema-name>
.
.
.
Note that now the local interfaces no longer throw the RemoteException, showing that they are not remotely called methods. Also, the XML contains different elements. There is now a local-home and a local tag. Also we are declaring that this is an EJB 2.x bean, using the cmp-version tag.
Calling a local bean from Java code is very simple, and very similar to using a remote bean. The code to call a remote bean is shown below.
try
{
Context ctx = new InitialContext();
Object o = ctx.lookup("Emp");
EmpHome empHome = PortableRemoteObject.narrow(o, EmpHome.class)
return empHome.findByDeptno(getDeptno());
}
catch (RemoteException r)
{
System.err.println("Error loading Employees(Remote): " + r.getMessage()); return null;
}
catch (NamingException n)
{
System.err.println("Error loading Employees(Naming): " + n.getMessage());
return null;
}
catch (FinderException f)
{
System.err.println("Error loading Employees(Finder): " + f.getMessage());
return null;
}
The code for a local bean is similar, but we no longer have to worry about the PortableRemoteObject, as the bean is no longer remote.
try
{
Context ctx = new InitialContext();
Object o = ctx.lookup("java:comp/env/LocalEmp");
EmpHome empHome = (EmpHome)o;
return empHome.findByDeptno(getDeptno());
}
catch (NamingException n)
{
System.err.println("Error loading Employees(Naming): " + n.getMessage());
return null;
}
catch (FinderException f)
{
System.err.println("Error loading Employees(Finder): " + f.getMessage());
return null;
}
As you can see, the local bean has to lookup the EJB slightly differently, even though they are running in the same container. Also, there is no RemoteException thrown by the find or the create methods, so the exception does not have to be caught.
There is one more difference, and that is in the ejb-jar.xml deployment descriptor. For an EJB to look up a local EJB, it must point to the correct location using an <ejb-local-ref> tag. If this is not used, the container will not be able to find the bean. For each EJB that needs to use the local EJB, the XML below must be in the deployment descriptor.
<entity>This example will allow the EJB Dept to call the local EJB Emp using the name LocalEmp. This is required because EJBs can have both local and remote interfaces, and to call the EJB Emp via it's remote interface the EJB Dept would look up the name Emp rather than the local reference LocalHome.
<ejb-name>Dept</ejb-name>
.
.
.
<ejb-local-ref>
<ejb-ref-name>LocalEmp</ejb-ref-name>
<ejb-ref-type>Entity</ejb-ref-type>
<local-home>ejb.cmplocal.EmpHome</local-home>
<local>ejb.cmplocal.Emp</local>
<ejb-link>Emp</ejb-link>
</ejb-local-ref>
</entity>
The example zip file contains three EJBs, a servlet and a JSP. There is a stateless session bean (SLSB) ejb.cmplocal.FrontSessionBean calling a local EJB ejb.cmplocal.Dept, which in turn calls a local EJB ejb.cmplocal.Emp. The Entity beans are examples of the Abstract implementation and use the SCOTT/TIGER schema's EMP and DEPT tables. You may notice this is also an example of the Session Facade design pattern, as clients call the session bean, and are hence decoupled from the structure of the database. DeptQuery.jsp demonstrates direct use of local interface by a web client.
<entity-deployment name="Emp" data-source="jdbc/OracleDS" table="EMP">
Make sure that you have turned off autocreate-tables as the EMP and DEPT tables already exist. This is done using the orion-application.xml. Make sure the the <orion-application... tag have an attribute autocreate-tables="false".
Examine the code in the following methods, to see how the local EJBs are called.:
We have provided a build script for building the application using Ant. Alternatively
you can use the pre-bulit enterprise archive file cmplocal.ear
located in the lib directory.
ant
and deploy-usingadmin.jar
You should be now ready to run this demo application.
In this document you should have: