How Do I Deploy an EJB? - Java

After an EJB is packaged, it can be deployed in an appropriate J2EE server. This is done using tools supplied by the J2EE Server vendor. Often these will be Java GUI applications, but command-line tools and Web interfaces are also used by some vendors. The typical process is to define the target J2EE server, identify the EAR file to be deployed, supply user credentials (typically administrative username and password) and away you go.

Remember that J2EE defines a separate role for the application Deployer. It may be that, for particular installations the databases or other resource names need to be changed to match the local environment. When configuring the application, the Deployer may need to alter the EJB or enterprise deployment descriptors but will not need to change the Java source code.

When an EJB is deployed into a particular EJB container, the EJB must be plugged into that container. To do this, an EJB Object must be generated based on the EJB's remote interface. This EJB Object will be specific to that EJB container and will contain code that allows the EJB Object to interface with that container to access security and transaction information. The container will examine the deployment descriptors supplied with the EJB to determine what type of security and transaction code is required in the EJB Object.

The container will also generate a class that implements the EJB home interface so that calls to the create, find, and destroy EJB instances are delegated to container-defined methods.

Finally, the container will register the JNDI name for the home interface of the EJB. This allows other application components to create and find this application's EJBs.

After the EJB has been deployed, any subsequent changes to its functionality will mean that the EJB must be redeployed. If the enterprise application or EJB is no longer needed, it should be undeployed from the container.

How Do I Use an EJB?

Given that EJBs are middle-tier business components, they are of little use without a client to drive them. As mentioned earlier, those clients can be Web components, standalone Java clients, or other EJBs.

Regardless of the type of client, using an EJB requires the same set of steps—namely, discovery, retrieval, use, and disposal. Listing 4.7 shows a simple client for use with the Agency EJB illustrating these steps. The following three sections cover these steps in more detail.

Listing 4.7 Simple Agency Client SimpleClient.java

package client;

import agency.*;
import javax.ejb.*;
import javax.naming.*;
import java.rmi.*;
import javax.rmi.*;
import java.util.*;

public class SimpleClient
{
  private static String agencyJNDI = "java:comp/env/ejb/Agency";

  public static void main(String[] args) {
    if (args.length == 1)
      agencyJNDI = args[0];
    else if (args.length > 1) {
      System.err.println("Usage: SimpleClient [ AgencyJNDI ]");
      System.exit(1);
    }
   
    try {
      InitialContext ic = new InitialContext();
      Object lookup = ic.lookup(agencyJNDI);
     
      AgencyHome home = (AgencyHome)
        PortableRemoteObject.narrow(lookup, AgencyHome.class);    
      Agency agency = home.create();
      System.out.println("Welcome to: "+agency.getAgencyName());
      System.out.println("Customer list: "+agency.getAgencyName());
      Collection customers = agency.findAllCustomers();
      Iterator it = customers.iterator();
      while (it.hasNext())
      {
        String name = (String)it.next();
        System.out.println(name);
      }
      agency.close();
    }
    catch (NamingException ex) {
       System.err.println(ex);
    }
    catch (ClassCastException ex) {
       System.err.println(ex);
    }
    catch (CreateException ex) {
       System.err.println(ex);
    }
    catch (RemoteException ex) {
       System.err.println(ex);
    }
    catch (RemoveException ex) {
       System.err.println(ex);
    }
  }
}

Discovery

To create or find an EJB, the client must call the appropriate method on the EJB's home interface. Consequently, the first step for the client is to obtain a remote reference to the home interface. The client obtains the reference by accessing the J2EE server's name service using JNDI.

For this simple process to work, the following three actions must have taken place:

• The developer has defined the EJB reference used in the Java code

• The Deployer has mapped this reference onto the actual JNDI name of the EJB

• The EJB container has registered the home interface using the JNDI name specified as part of the platform specific deployment descriptor

As discussed on Day 3, each J2EE component has its own Java Component Environment space and the JNDI name used in the client code will be prefixed with java:comp/env. The object retrieved is a reference to the RMI-IIOP remote stub that must be downcast to the home interface. The following code shows the initial lookup required for the Agency EJB:

try
 {
  InitialContext ic = new InitialContext();
  Object lookup = ic.lookup("java:comp/env/ejb/Agency");
  AgencyHome home =
     (AgencyHome)PortableRemoteObject.narrow(lookup, AgencyHome.class);
  ...
 }
 catch (NamingException ex) { /* Handle it */ }
 catch (ClassCastException ex) { /* Handle it */ }

Now that you have a reference to the home interface, you can create the EJB.

Retrieval and Use

Once you have a reference to the EJB home interface, you can call the create() method you saw defined on the AgencyHome interface. The create() method returns a remote reference to the newly-created EJB. If there are any problems with the EJB creation or the remote connection, a CreateException or RemoteException will be thrown. CreateException is defined in the javax.ejb package, and RemoteException is defined in the java.rmi package, so remember to import these packages in your client class.

Now that you have a reference to an EJB, you can call its business methods as follows:

 try
 {
  ...
  Agency agency = home.create();
  System.out.println("Welcome to: " + agency.getAgencyName());
  ...
 }
 catch (RemoteException ex) { /* Handle it */ }
 catch (CreateException ex) { /* Handle it */ }

The previous code sample shows the getAgencyName() method being called on the returned Agency reference. Again, whenever you call a remote method that is defined in an EJB remote interface, you must be prepared to handle a RemoteException.

---

Note - You will see later that some Entity beans are found rather than created. In this case, all steps are the same except that the create() method is replaced by the appropriate finder method and find-related exceptions must be handled. You still end up with a remote reference to an EJB. All of this is covered when Entity beans are discussed on Day 6.

---