You have now created and used an EJB. What happens now? Well, if you no longer need the EJB, you should get rid of it by calling its remove method, and set its reference to null as follows:

 // No longer need the agency EJB instance
 agency.remove();
 agency = null;

The remove() method can throw RemoveException. After calling remove() you should obviously not call any business methods on the bean as it has been removed from use. Using an EJB after remove() has been called will throw a RemoteException.

---

Note - Normally you would only call the remove() method for Session beans. Entity beans (see Day 5) represent data in a persistent data store, and calling remove() for an Entity bean would typically remove the data from the data store.

---

If you do not remove a Session EJB after a default period of inactivity (typically 30 minutes), then the EJB container will remove the bean on your behalf. This is an example of the added value provided by the EJB lifecycle. A lazy or novice developer can forget to remove an EJB and the container will still tidy up and release resources: a bit like your mother tidying your bedroom when you were a young child.

Running the Client

To compile and run the client, you will need the following:

• The J2EE classes.

• Access to the EJB's home and remote interface classes.

• RMI stubs for the home and remote interfaces.

• If the client does not have the JNDI name of the EJB compiled in, you may want to provide this on the command line or through a system property.

---

Note - If your client is a J2EE Web client (such as a servlet or JSP as discussed on Day 12, "Servlets" and Day 13, "JavaServer Pages"), then the client will implicitly have access to the J2EE classes, EJB interfaces, RMI stubs and JNDI name server.

---

When you deploy the EJB, you can usually ask the container for a client JAR file. This client JAR file will contain all of the classes and interfaces needed to compile the client (as defined in the previous bulleted list). You should add this client JAR file to your CLASSPATH when compiling your client.

Client Applications

Application client programs are simple Java programs with a main() method that run in their own JVM but make use of services provided by the J2EE server. Application clients are usually invoked by a program supplied by the J2EE server vendor. The J2EE RI, for instance, provides a program called appclient for running application clients.

The various J2EE server vendors may handle client applications differently, but the J2EE specification allows for application clients to be packaged into JAR files, together with a deployment descriptor, and deployed to the J2EE server. The J2EE RI uses this approach, and Listing 4.8 shows the application client deployment descriptor file (application-client.xml) for the simple Agency application client shown previously in Listing 4.7.

Listing 4.8 Application Client Deployment Descriptor application-client.xml

<?xml version="1.0" encoding="UTF-8"?>
<application-client version="1.4" xmlns="http://java.sun.com/xml/ns/j2ee"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
 http://java.sun.com/xml/ns/j2ee/application-client_1_4.xsd">
 <display-name>SimpleClient</display-name>
 <ejb-ref>
  <ejb-ref-name>ejb/Agency</ejb-ref-name>
  <ejb-ref-type>Session</ejb-ref-type>
  <home>agency.AgencyHome</home>
  <remote>agency.Agency</remote>
 </ejb-ref>
</application-client>

An application client deployment descriptor is used to define J2EE server resources required by the client. In this case, a single EJB reference is needed to define the name of the EJB as used in the code (ejb/Agency) and the type and classes for the EJB.

---

Note - As with all applications bundled into a JAR file, the class containing the main() method entry point is defined by a Main-class entry in the JAR Manifest file.

---

This chapter is from Teach Yourself J2EE in 21 Days, second edition, by Martin Bond et. al. (Sams, 2004, ISBN: 0-672-32558-6). Check it out at your favorite bookstore today. Buy this book now.