The Home Interface - Java

To facilitate the creation and discovery of EJBs, each type of EJB provides a home interface. The bean developer will provide an EJB home interface that acts as a factory for that particular EJB. A home interface will extend the javax.ejb.EJBHome interface and will contain the necessary methods identified by the bean developer to allow a client to create, find, or remove EJBs.

There are two ways for a client to get hold of the EJB itself, depending on the type of EJB (Session or Entity) and the way it is intended to be used. The EJB Home interface can contain one or more create() methods to create a new instance of an EJB. So, for example, you can create a new instance of a Session bean before using it. On the other hand, when you interact with Entity EJBs, you will frequently use findXXX()methods to use existing beans. Message-Driven beans do not have a home interface as their lifecycle is more rigidly controlled compared to Session and Entity beans (the Message-driven bean life-cycle is covered in detail on Day 10.

Listing 4.2 shows the home interface for the example Agency EJB.

Listing 4.2 Home Interface for the Agency Bean

package agency;

import java.rmi.*;
import javax.ejb.*;

public interface AgencyHome extends EJBHome
{
  Agency create () throws RemoteException, CreateException;

The code underlying the home interface will work with the container to create, populate, and destroy EJBs as requested by the client. The effects of the method calls will vary depending on the type of EJB being manipulated. As a result, a request to remove a Session EJB will just result in the EJB being thrown away, while the same request on an Entity EJB may cause underlying data to be removed. The types and effects of different home interface methods are discussed in more detail on Days 5 and 6.

The Bean Implementation

After the interfaces are defined, there is the none-too-trivial task of implementing the business logic behind them. The business logic for an EJB will live in a class referred to as the bean. The bean consists of two parts:

• The business logic itself, including implementations of the methods defined in the remote interface

• A set of methods that allow the container to manage the bean's lifecycle

---

Note - Although the bean itself must contain these elements, it is possible, indeed common, for non-trivial beans to delegate some or all of their business functionality to other, helper, classes.

---

Drilling down into these areas reveals more about the structure of an EJB.

Implementing the Business Interface

The first thing to note is that the bean itself does not implement the remote interface previously defined. This may seem slightly bizarre at first sight; however, there is a very good reason for this.

In order for the container to apply services, such as access control, on behalf of the EJB the container must have some way of intercepting the method call from the client. When it receives such a method call, the container can then decide if any extra services need to be applied before forwarding the method call on to the bean itself.

The interception is performed by a server-side object called the EJB Object (not to be confused with the interface of the same name). The EJB Object acts as a server-side proxy for the bean itself, and it is the EJB Object that actually implements the EJB's remote interface. Figure 4.1 shows the relationship between the client, the bean, and the EJB Object.

Figure 4.1
The EJB Object acts as a server-side proxy for the bean itself.

As shown in Figure 4.1, the client calls the business methods on the EJB Object implementation. The EJB Object applies the required extra services and then forwards the method calls to the bean itself.

The J2EE server generates the EJB Object class when you deploy the EJB. The deployment process uses the information you provide in the home and remote interfaces and the DD to generate the required EJB Object class.

Every business method in the remote interface must have a corresponding business method in the bean. The method name, parameters, and return type must be identical and the bean method must throw the same exceptions as the interface method apart from the RemoteException required by all remote methods. All business methods must have public visibility.

For example, the remote interface method

public Collection findAllApplicants() throws RemoteException; must have the corresponding method in the bean:

public Collection findAllApplicants();

If you are using a developer tool that supports the creation of EJBs, it will generally generate empty methods for you to populate. Listing 4.3 shows the outlines of the business methods in the example AgencyBean with some of the code removed for clarity.

Listing 4.3 Business Method Implementation Signatures for the AgencyBean

package agency;

import java.rmi.*;
import java.util.*;
import javax.ejb.*;
// Remaining imports removed for clarity

public class AgencyBean implements SessionBean
{
  public String getAgencyName() { ... }
  public Collection findAllApplicants() { ... }

  public void createApplicant(String login, String name, String email)
   throws DuplicateException, CreateException { ... }

  public void deleteApplicant (String login)
   throws NotFoundException { ... }

  public Collection findAllCustomers() { ... }

  public void createCustomer(String login, String name, String email)
   throws DuplicateException, CreateException { ... }

  public void deleteCustomer (String login) throws NotFoundException { ... }

  public Collection getLocations() { ... }

  public void addLocation(String name) throws DuplicateException { ... }

  public void removeLocation(String code) throws NotFoundException { ... }

  public Collection getSkills() { ... }

  public void addSkill (String name) throws DuplicateException { ... }

  public void removeSkill (String name) throws NotFoundException { ... }

  public List select(String table) { ... }
}

An EJB implementation must implement the appropriate javax.ejb class, as described in the section "Implementing the Home Interface." The AgencyBean example is a Session EJB and therefore must extend javax.ejb.SessionBean.

---

Note - Note that your bean methods will only throw business exceptions or standard Java exceptions. They should not throw java.rmi.RemoteException, because this exception should only be generated by the RMI subsystem.

---