When you implement an EJB, create the following:
1. A home interface for the bean. The home interface extends
javax.ejb.EJBHome. It defines thecreatemethod for your bean. If the bean is an entity bean, it also defines the finder method(s) for that bean.
2. A remote interface for the bean. The remote interface declares the methods that a client can invoke. It extendsjavax.ejb.EJBObject.
3. The bean implementation that includes the following:
a. the implementation of the business methods that are declared in the remote interface
Note: For EJB modules, the top of the module (<ejb_module>) represents the start of a search path for classes. As a result, classes belonging to packages are expected to be located in a nested directory structure beneath this point. For example, a reference to a package class ’myapp.Employee.class’ is expected to be located in "...employee/<ejb_module>/myapp/Employee.class".
Developing EJBs
b. the container callback methods that are inherited from either the javax.ejb.SessionBean orjavax.ejb.EntityBean interfaces c. theejbCreate method with parameters matching those of thecreate
method as defined in the home interface
Creating the Home Interface
The home interface is used to create and destroy the bean instance; thus, it defines thecreate method for your bean. Each type of EJB can define thecreate method in the following ways:
For eachcreate method, a correspondingejbCreate method is defined in the bean implementation. The client invokes thecreate method that is declared within the home interface. The container turns around and calls theejbCreate method—with the appropriate parameter signature—within your bean
implementation. You can use the parameter arguments to initialize the state of the new EJB object.
1. The home interface must extend thejavax.ejb.EJBHome interface.
2. Allcreate methods must throw the following exceptions:
■ javax.ejb.CreateException
■ eitherjava.rmi.RemoteException orjavax.ejb.EJBException
EJB Type Create Parameters
Stateless Session Bean Can have only a singlecreate method, with no parameters.
Stateful Session Bean One or morecreate methods, each with its own defined parameters.
Entity Bean Zero or morecreate methods, each with its own defined parameters. All entity beans must define one or more finder methods, where at least one is afindByPrimaryKey method.
Developing EJBs
Example
The following code sample shows a home interface for a session bean called EmployeeHome.
package employee;
import javax.ejb.*;
import java.rmi.*;
public interface EmployeeHome extends EJBHome {
public Employee create()
throws CreateException, RemoteException;
}
Creating the Remote Interface
The remote interface defines the business methods of the bean that the client can invoke.
1. The remote interface of the bean must extend thejavax.ejb.EJBObject interface and its methods must throw thejava.rmi.RemoteException exception.
2. You must declare the remote interface and its methods aspublic, because clients that invoke these methods are remote.
3. The remote interface, all its method parameters, and return types must be serializable. In general, any object that is passed between the client and the EJB must be serializable, because RMI marshals and unmarshals the object on both ends.
4. Any exception can be thrown to the client, as long as it is serializable. Runtime exceptions, includingEJBException andRemoteException, are transferred back to the client as remote runtime exceptions.
Example
The following code sample shows a remote interface called Employee with its defined methods, each of which will be implemented in the stateless session bean.
package employee;
import javax.ejb.*;
import java.rmi.*;
import java.util.*;
Developing EJBs
public interface Employee extends EJBObject {
public Collection getEmployees() throws RemoteException;
public EmpRecord getEmployee(Integer empNo) throws RemoteException;
public void setEmployee(Integer empNo, String empName, Float salary) throws RemoteException;
public EmpRecord addEmployee(Integer empNo, String empName, Float salary)
throws RemoteException;
public void removeEmployee(Integer empNo) throws RemoteException;
}
Implementing the Bean
The bean contains the business logic for your application. It implements the follow-ing methods:
1. The bean methods defined in the remote interface. The signature for each of these methods must match the signature in the remote interface.
The bean in the example application consists of one class,EmployeeBean, that retrieves an employee’s information.
2. The methods defined in the home interface are inherited from the
SessionBean orEntityBean interface. The container uses these methods for controlling the life cycle of the bean. These include theejb<Action>methods, such asejbActivate,ejbPassivate, and so on.
3. TheejbCreate methods that correspond to thecreate method(s) that are declared in the home interface. The container invokes the appropriate ejbCreate method when the client invokes the correspondingcreate method.
4. Any methods that are private to the bean or package used for facilitating the business logic. This includes private methods that your public methods use for completing the tasks requested of them.
Developing EJBs
Accessing the Bean
All EJB clients—including standalone clients, servlets, JSPs, and
JavaBeans—perform the following steps to instantiate a bean, invoke its methods, and destroy the bean:
1. Look up the bean home interface through a JNDI lookup, which is used for the life cycle management. Follow JNDI conventions for retrieving the bean reference, including setting up JNDI properties if the bean is remote to the client.
2. Narrow the returned object from the JNDI lookup to the home interface through thePortableRemoteObject.narrow method.
3. Create instances of the bean in the server through the home interface. Invoking thecreatemethod on the home interface causes a new bean to be instantiated.
This returns a bean reference to the remote interface. Narrow the returned object through thePortableRemoteObject.narrow method.
4. Invoke business methods that are defined in the remote interface.
5. After you are finished, invoke theremove method. This either will remove the bean instance or return it to a pool. The container controls how to act on the remove method.
Example The following example is executed from a servlet, which can also be executed from a JSP or JavaBean, that is co-located in the same container with the stateless session bean. Thus, the JNDI lookup does not require JNDI properties, such as the factory, location, or security parameters.
Note: For entity beans that are already instantiated, you can retrieve the bean reference through one of its finder methods.
Developing EJBs
This code should be executed within a TRY block for catching errors, but the TRY block was removed to show the logic clearly. See the downloadable example for the full exception coverage.
public class EmployeeServlet extends HttpServlet {
EmployeeHome home;
Employee empBean;
public void init() throws ServletException {
//Retrieve the initial context for JNDI Context context = new InitialContext();
//Retrieve the home interface using a JNDI lookup using
// the java:comp/env bean environment variable specified in web.xml Object homeObject =
context.lookup("java:comp/env/EmployeeBean");
//Narrow the returned object to be an EmployeeHome object home =
(EmployeeHome) PortableRemoteObject.narrow(homeObject,
EmployeeHome.class);
// Create the remote Employee bean instance and return a reference // to the remote interface to this bean.
empBean =
(Employee) PortableRemoteObject.narrow(home.create(), Employee.class);
}
public void doGet(HttpServletRequest request, HttpServletResponse response)
Note: The JNDI name is specified in the<ejb-ref> element in the EJB client XML configuration file—in this case, the servlet web.xml file—as follows:
<ejb-ref>
<ejb-ref-name>EmployeeBean</ejb-ref-name>
<ejb-ref-type>Session</ejb-ref-type>
<home>employee.EmployeeHome</home>
<remote>employee.Employee</remote>
</ejb-ref>
Developing EJBs
throws ServletException, IOException {
response.setContentType("text/html");
ServletOutputStream out = response.getOutputStream();
//Invoke a method on the remote interface reference.
Collection emps = empBean.getEmployees();
out.println("<html>");
out.println("<head><title>Employee Bean</title></head>");
out.println("<body>");
out.println("<table border='2'>");
out.println("<tr><td>" + "<b>EmployeeNo</b>"
+ "</td><td>" + "<b>EmployeeName</b>"
+ "</td><td>" + "<b>Salary</b>"
+ "</td></tr>");
Iterator iterator = emps.iterator();
while(iterator.hasNext()) {
EmpRecord emp = (EmpRecord)iterator.next();
out.println("<tr><td>" + emp.getEmpNo()
+ "</td><td>" + emp.getEmpName() + "</td><td>" + emp.getSalary() + "</td></tr>");
}
out.println("</table>");
out.println("</body>");
out.println("</html>");
out.close();
} }