Developing Your First Beans

Now that our Cabin entity is ready, we need to create a session bean that will act as the interface for interacting with the Cabin entity. This session bean will take on the business process and responsibilities of a travel agent and will be called the TravelAgent EJB.

The first part of creating the TravelAgent EJB is to define its remote interface. This interface specifies what business methods a client is allowed to invoke on the EJB. Clients interact with the TravelAgents createCabin() and findCabin() methods to manipulate Cabin entities:

  package com.titan.travelagent;

  import javax.ejb.Remote ;
  import com.titan.domain.Cabin;

  @Remote
  public interface TravelAgentRemote {

     public void createCabin(Cabin cabin);
     public Cabin findCabin(int id);
  }

There really is nothing special about the remote interface of the TravelAgent EJB. It looks like a plain Java interface, except that it is annotated with the @javax.ejb.Remote annotation. This annotation tells the EJB container that this particular inter face is the remote business interface of the TravelAgent EJB. Unlike EJB 2.1, also notice that the business methods do not have to throw java.rmi.RemoteException . They can if they want to, but they dont have to.

Now that we have defined the remote interface to the TravelAgent EJB, we need to implement the bean class that contains the business logic for this session bean. The TravelAgent EJB is defined as a stateless bean. We use the @javax.ejb.Stateless annotation to denote this. Although they are not required to, it is good practice for stateless session beans to implement all of their business interfaces so that the client/ bean contract can be enforced by the Java compiler. In this case, the business interface is TravelAgentRemote . Here is the complete definition of the TravelAgentBean class:

  package com.titan.travelagent;

  import javax.ejb.Stateless ;
  import javax.persistence.EntityManager; 
  import javax.persistence.PersistenceContext;

  import com.titan.domain.Cabin;

  @Stateless
  public class TravelAgentBean implements TravelAgentRemote{ 
      @PersistenceContext(unitName="titan") private EntityManager manager;

      public void createCabin(Cabin cabin) {
         manager.persist(cabin);
      }

      public Cabin findCabin(int pKey) {
         return manager.find(Cabin.class, pKey);
      }
  }

A bunch of things are going on in this implementation. First, the TravelAgentBean class uses the @javax.persistence.PersistenceContext annotation to get access to the EntityManager service that it uses to create and find Cabin entities. @PersistenceContext tells the EJB container that it must set the manager field with an EntityManager instance. The EJB container sees that the type of the field is javax.persistence.EntityManager and knows that it must set the field to be a reference to an EntityManager service that references the Titan persistence unit we defined in the persistence.xml file. This field will be initialized when the bean instance is instantiated.

The next two methods interact with the EntityManager service to create a Cabin entity within the database and to locate a Cabin entity based on its primary key. The createCabin() method invokes EntityManager.persist() , passing in an instance of the entity that we want to create. After this operation is complete, the Cabin instance is attached to persistence management and is stored in the database. Well see later on that you create the Cabin instance as you would any other plain Java object. The findCabin() method takes as its parameter a primary key of a cabin in the database. It calls the EntityManager.find() method, passing the Cabin bean class as a parame ter and the actual primary key. The Cabin bean class parameter tells the
EntityManager which entity it is trying to find in the database. The findCabin() method then returns the found Cabin entity back to the remote client.

The JAR file is a platform-independent file format for compressing, packaging, and delivering several files together. Based on the Zip file format and the zlib compression standards, the JAR (Java Archive) tool was originally developed to make downloads of Java applets more efficient. As a packaging mechanism, however, the JAR file format is a very convenient way to shrink-wrap components and other software for delivery to third parties. In EJB development, a JAR file packages all the classes and interfaces associated with a bean. Besides EJB definitions and classes, you are also allowed to package entity beans and their persistence.xml deployment descriptor.

Creating the JAR file for deployment is easy. Position yourself in the dev directory that is just above the com/titan directory tree and execute the following command:

  C:\dev> jar cf titan.jar com/titan/domain/*.class
        com/titan/travelagent/*.class
           META-INF/persistence.xml

The c option tells the jar utility to create a new JAR file that contains the files indicated in subsequent parameters. It also tells the jar utility to stream the resulting JAR file to standard output. The f option tells jar to redirect the standard output to a new file named in the second parameter (titan.jar). Its important to get the order of the option letters and the command-line parameters to match. You can learn more about the jar utility and the java.util.zip package in Java in a Nutshell or Learning Java (both published by OReilly).

The jar utility creates the file titan.jar in the dev directory. If youre interested in looking at the contents of the JAR file, you can use any standard Zip application (WinZip, PKZIP, etc.) or the command jar tvf titan.jar . Figure 4-2 shows the structure of this Jar file.