Introduction to EJBs: Part 3

How Do I Deploy an EJB?

After an EJB is packaged, it can be deployed in an appropriate J2EE server.
There is no limit to the number of times an EJB can be deployed as a part of
different applications.

Remember that J2EE defines a separate role for the application deployer. It
may be that for particular installations, databases, or other resource names
need to be changed to match the local environment. When configuring the
application, the deployer can alter this EJB or enterprise application
metadata.

Plugging into the Container

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

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

The container will examine the EJB and enterprise application metadata and
hook up resource references. It will also provide an environment for the
application components.

Finally, the container will register the home interface of the EJB with JNDI.
This allows other application components to create and find EJBs of this
type.

Performing the Deployment

As mentioned previously, when deploying an EJB or enterprise application, the
application developer taking on the J2EE role of deployer can choose to alter
certain of the metadata relating to the configuration of the application.
Although this can be done manually, it is usually done through a GUI tool to
make things easier and to keep things consistent.

After the EJB has been deployed, any subsequent changes to its functionality
will mean that the EJB must be re-deployed. 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. These steps are
covered in the next three sections.

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 get
hold of a remote reference to the home interface. On Day 3, you looked at naming
services and how these can be used to register information in a distributed
environment. In a J2EE environment, such a naming service is accessible through
JNDI and can be used to store references to EJB home interfaces.

The EJB container will have registered the home interface using the JNDI name
specified during deployment (as part of the deployment descriptor). This is the
name that the client should use to look up the home interface. Recall from the
EJB deployment descriptor shown in Listing 4.5 that the EJB name specified was
Agency. When deploying the EJB, the deployer has a chance to set the
JNDI name by which clients will find this EJB. In this case, you would expect
the deployer to simply set a JNDI name of ejb/Agency so that the client
could find the home interface by looking up java:comp/env/ejb/Agency.
The following code shows the initial lookup required:

As you can see, because the reference returned from JNDI is just an object,
you must narrow it to the home interface type you expectin this case,
AgencyHome. If there are any problems with the JNDI access or if the
wrong object type is returned, a NamingException or
ClassCastException will be thrown.

There is no magic here. The object returned by the JNDI is simply an RMI remote
object stub. This stub represents the home interface remote object created by
the container when the EJB was deployed. This can be seen in Figure 4.2.

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

Retrieval and Use

You can now call the create() method you saw defined on the
AgencyHome interface in Listing 4.4 as follows:

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 at the top of your client class.

Now that you have a reference to an EJB, you can call its methods. 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
RemoteExceptions.

Note

You will see later that some types of EJB 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 later when Entity EJBs are discussed on Day 6.

Disposing of the EJB

You have now created and used an EJB. What happens now? Well, if you no
longer need the EJB, you can get rid of it in exactly the same way that you
would get rid of a local Java object or a remote Java object defined using
RMIby setting its reference to null as follows:

// No longer need the agency EJB instance
agency = null;

When the local RMI runtime detects that the remote object no longer has any
local references, it will trigger remote garbage collection for that object,
which means that its remote reference will time out. This will result in the
object being de-referenced at the server-side. In the case of the simple
Agency bean (a stateless Session bean), this will cause the bean to be
destroyed.

Although it is possible to use the remove() method to get rid of the
EJB, you would not normally use this for such a simple bean. Use of this method
is discussed in more detail on Days 5 and 6.

Running the Client

You are now in a position to write a simple application client for the
Agency EJB. After you have written it, you will want to compile and run
it.

Before compiling your client, you should ensure that you have
j2ee.jar on your classpath. This JAR file lives in the lib
directory under J2EE_HOME. If you are using an enterprise IDE, you may
find that all the relevant classes are already in your classpath.

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

The J2EE classes. These must be accessible through the
classpath.

Access to the EJB's home and remote interface class files via the
classpath.

RMI stubs for the home and remote interfaces. These can either be
installed on the local classpath or downloaded dynamically from the EJB
server.

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.

When you deploy the EJB, you should be able to 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.

In theory, this should be it. However, you will find that any form of
security definition on the server will require you to authenticate yourself
before you can run the application. In this case, you must explicitly use the
client container to provide the required security mechanism.

Thursday's installment: Deploying and Using an EJB in the J2EE Reference Implementation

About the Author

Andy Longshaw is a consultant, writer and educator specializing in J2EE, XML, Web-based technologies and components, particularly the design and architecture decisions required to use these technologies successfully. Andy has been explaining technology for most of the last decade as a trainer and in conference sessions. A wild rumor suggests that some people have managed to stay awake in these sessions. Despite being well educated and otherwise fairly normal, Andy still subjects himself, and his family, to "trial by unpredictability" by watching Manchester City FC far more often than is healthy.

Andy and the other authors work for Content Master Ltd., a technical authoring company in the United Kingdom specializing in the production of training and educational materials. For more information on Content Master, please see their web site at www.contentmaster.com

Source of this material

This is the first of four installments that make up Chapter 4: Introduction to EJBs from the book Sams Teach Yourself J2EE in 21 Days (ISBN:0-672-32384-2) written by Martin Bond, Dan Haywood, Debbie Law, Andy Longshaw, and Peter Roxburgh, published by Sams Publishing.