Back to article

Introduction to EJBs: Part 4

August 1, 2002

This is the fourth 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.

Deploying and Using an EJB in the J2EE Reference Implementation

You should now be in a position to write and test an EJB client. However, before you can do that, you must deploy an EJB that it can use. In this section, you will look at how to deploy an EJB in the J2EE Reference Implementation (RI) and how to then use it from a simple client.

The J2EE on which your EJB is deployed will provide a complete server-side environment. It houses any EJBs, runs a Web Server for JSP/servlets, runs a naming server for storing component location information, and provides database access. All J2EE- compliant application servers will do this—even a non-commercial version, such as the J2EE RI. The RI also provides you with a ready-to-use database so you do not have to concern yourself with hooking up to an existing database or installing a separate one.

To deploy and test your EJBs (and servlets/JSPs later), you only need a single machine. Both the J2EE client and the J2EE server (and its EJBs, servlets and JSPs) can run on the same machine. No connection to the Internet is required. The J2EE RI is available on multiple platforms (Win32, Solaris, and Linux) and should be consistent across these platforms, so that J2EE applications created on one platform can be deployed on another.

If you encounter problems at any stage, try referring to the troubleshooting section just before today's Summary.


Before running any of the tools described in this section, you will need to set the J2EE_HOME environment variable to the location on your hard drive where you deployed the J2EE reference implementation. You should also add the bin directory below J2EE_HOME to your executable search path (%PATH% under Windows or $path under Unix/Linux) so that you can run J2EE tools and batch files from the command line.

Opening the Case Study EAR File

To deploy and manipulate EJBs under the RI, you will use a graphic tool called deploytool. Before you start using this, you will need to do two things:

  1. Ensure that you have created and configured your database environment as described on Day 2.

  2. Start the J2EE RI runtime environment and the associated Cloudscape database. To do this, run the cloudscape and j2ee scripts/batch files found in the bin directory under J2EE_HOME as follows:

  3. cloudscape -startj2ee -verbose

    The use of the -verbose flag for J2EE is not strictly necessary, but you may find it useful to help you understand what the J2EE server does when it starts up.

Now you are ready to run the deploytool. Again, this is a script/batch file found in the bin directory under J2EE_HOME. When you run it, the GUI screen will appear as shown in Figure 4.3.

You should now be able to open the initial agency enterprise archive provided in the JAR subdirectory of the Day 4 exercise code on the CD-ROM (agency.ear). Do this through the menus by selecting File, Open and then browsing for the file in the subsequent Open Object dialog box. Select the EAR file and click the Open Object button. The agency application will now be displayed in the list of applications, as shown in Figure 4.4.

All of the code for the Agency EJB that is contained in the Agency application can be found in the agency subdirectory of the src directory under the Day 4 Exercise part of the CD-ROM.

Now that the enterprise application is loaded in deploytool, you can examine its settings.

Figure 4.3
The initial screen shown by deploytool.

Figure 4.4
The Agency application has now been loaded by deploytool.

Examining the Case Study Application

You can use deploytool to examine and alter deployment descriptor information for the application and, if necessary, for individual components, such as EJBs.

If you select the JNDI Names tab for the agency application, you will see information about the resources that the application exports and consumes. This is largely based on information defined in the application deployment descriptor and the container-specific deployment descriptor described earlier in the Enterprise Applications section.

In Figure 4.5, you can see in the Application box that there is a single EJB in this initial form of the application. That EJB can be referenced through JNDI using the name ejb/Agency.

Figure 4.5
deploytool displays the JNDI information from the Agency application deployment descriptor.

In the References box, you can see that two of the components in the application use external resources. First, you can see that the component named Agency (the EJB) uses a resource called jdbc/Agency that is registered under JNDI as jdbc/Agency.

The References box also indicates that the application client, SimpleClient, references the Agency EJB by using the name ejb/Agency that appears under JNDI as ejb/Agency.

You can also examine the settings of the EJB through deploytool. Click the icon next to the Simple JAR file symbol to show the EJBs contained in the Simple EJB-JAR file. There is a single EJB in the JAR file called Agency. If you select the Agency EJB, you will see the properties defined in the deployment descriptor for that EJB. Select the Resource Refs tab to see what external resources this EJB uses, as shown in Figure 4.6.

Figure 4.6
You can examine the deployment descriptor information for a single EJB, such as the external resources it expects.

Figure 4.6 shows that the Agency EJB expects one resource called jdbc/Agency that is of type javax.sql.Datasource. This is the EJB deployment descriptor information you saw in Listing 4.5.

Figure 4.7 shows the environment entries for the Agency EJB. If you want to alter the AgencyName defined there, you can just double-click the Value field and type in an alternative name. If you make any changes to the configuration of the application or any of its components, the suffix (changed) will be added to the application name in the title bar.

Figure 4.7
Environment entries can be viewed or edited through deploytool.

Deploying the Case Study Application

You can deploy the server-side components of the agency application (in this case, a single EJB) using deploytool. To deploy them, select the agency application item (indicated by a blue diamond under the Applications folder in the explorer area on the left side), and select Tools, Deploy from the deploytool menu. This will display the initial deployment screen shown in Figure 4.8.

As you can see from Figure 4.8, the default target host is localhost. This is fine, presuming that your copy of the J2EE RI is running on the local machine. If not, you should Cancel and add the appropriate server name through the File, Add Server menu item before proceeding.

The other point to note for this screen is that it allows you to obtain a client JAR file. Recall that this client JAR file will contain all of the classes required by a client of the application being deployed. A pre-prepared client JAR file is provided in the jar subdirectory of the Day 4 exercise code on the CD-ROM (agencyClient.jar), but you will need to obtain a client JAR file for any new applications or components you deploy. If you check the Return Client Jar box, you can browse and select an appropriate location to store the returned JAR file.

Figure 4.8
You can select a server on which to deploy an enterprise application.


If you are deploying the agency application on an other machine (not localhost), you should not use the pre-provided agencyClient.jar file. Instead, select the option to return the client JAR file and add this JAR to the classpath when you run the client later.

Click Next to move on to the JNDI Names screen. This gives the deployer another chance to provide server-specific deployment information. Note that this is the same information you saw earlier when examining the application's JNDI information. For now, just click the Next button. At the last screen, click Finish to deploy the application to the selected server.

The progress of the deployment is shown in a separate window, as seen in Figure 4.9. The blue and green bars are progress bars that will increase as the deployment proceeds. Click OK when the deployment is complete.

When you are done, the agency enterprise application should have been deployed, as shown in Figure 4.10. To view the applications deployed on a server, expand the Servers folder in the explorer area on the left side and then expand the particular server, such as localhost.

Figure 4.9
deploytool will show you the progress of the deployment.

Figure 4.10
You can list the applications deployed on a server.

Testing the Case Study Application

After you have successfully deployed the server-side components of the application under the J2EE RI, you can run the test client to check that everything is okay.

The test client, client.SimpleClient, is provided pre-compiled in the classes subdirectory. To run this, use the script/batch file runSimple that can be found in the run subdirectory. When you run the client, you will need to provide a username and password. Use the username guest with a password of guest123. Your interaction with the client should look something like the following:

Initiating login ...
Username = null
Enter Username:guest
Enter Password:guest123
Binding name:´java:comp/env/ejb/Agency´
Welcome to: J2EE in 21 Days Job Agency
Customer list: J2EE in 21 Days Job Agency
Unbinding name:´java:comp/env/ejb/Agency´

If you are not able to run this test, refer to the "Troubleshooting the Case Study Application," section next.

As you can see, this has used the Agency EJB to list all of the customers in the job agency database. The code for the client is provided in the client sub-directory of the src directory. If you examine it, you will see that it is identical to the code shown earlier, but with some extra code to invoke the customer listing methods on the EJB and display the results.

If you examine the runSimple script/batch file, you will see that it uses the runclient utility provided by the J2EE RI as follows:

runclient -client agency.ear -name SimpleClient -textauth


The precise command line used will differ between platforms to define the location of the agency EAR file using the correct direction of slashes (backslash or forwardslash). However, this makes no difference in how the command works.

This runs the client application directly from the EAR file without having to unpack it. The command line specifies that the client is called SimpleClient and that it lives in the agency.ear archive. It also specifies that simple, text-based authentication should be used between the client and the server.

The other thing to note in the script/batch file is that the environment variable APPCPATH is set before runclient is called. The runclient utility uses this environment variable to find the client JAR file for the application (in this case, it points to agencyClient.jar). This information will be needed at runtime, not only because the EJB's interface class files are needed, but also because it also contains RMI stubs that are targeted at the correct server and deployment information that is used to map resource names to the target server's JNDI names.

Should you need to re-compile the client, or to compile your own client, you will need to add this client JAR file to your classpath.

Initial Naming Context for the Client

When creating a JNDI InitialContext, the client runtime must get hold of information regarding the content of this initial context. In the case of runclient, it will find mappings in the deployment descriptors contained in the client JAR file. These mappings will be used to set up the initial context for the client. Consequently, when the client gets a new initial context and looks up java:comp/env/ejb/Agency, for example, the local naming service runtime will be able to use the pre-provided mapping information to match this text string to the appropriate JNDI name.

Other application servers may use different mechanisms to set up this initial context, such as passing a Properties object to the naming runtime containing the appropriate information.

Troubleshooting the Case Study Application

If you have problems running the case study application, check out the following possible issues:

  • Have you started the J2EE RI (j2ee -verbose)? Make sure by locating its console window or looking for it in the list of processes or applications on your machine.

  • Have you started the cloudscape database (cloudscape -start)? Try running the initial database test at the end of Day 2 to ensure that the data is present and that the database server is running.

  • Have you deployed the EJBs? By opening the EAR file, you are simply loading the enterprise application into the deploytool environment. You must explicitly deploy the application to the server you are using through the Tools, Deploy menu.

  • Have you set the classpath correctly for your client? The client will need access to the J2EE libraries in order to run.

  • Try re-creating the client JAR file when you deploy the J2EE application to your server. Make sure that this client JAR file is on the classpath when you compile and run the client application.

  • Check the J2EE RI console window to see if exceptions or errors are shown there.

  • Check the J2EE log files under the logs directory in J2EE_HOME. There is a directory below logs that is named after the machine on which the server is running. Below this, there are two nested j2ee directories. In the lower of these, you will find various log files that you can examine for errors.

If you still have problems and you suspect that there is a problem with the configuration of your J2EE RI, you can either re-install the RI or you could try deleting the server- specific repository directory and then re-starting your server. You will lose all of your deployed J2EE applications, but you may find this easier than re-installing. Under the J2EE_HOME directory, you will find a directory called repository, and below this there will be a directory named after the server on which you are running this instance of the RI (for example, if your hostname is "fred", there will be a fred directory below repository). Stop the J2EE RI, remove the directory that is named after your server, and then start the J2EE RI again.


Today, you have seen common ways that EJBs are used in applications and why you would want to use them. You have seen that an EJB will have a home interface, a business or remote interface, and an implementation. You have seen how the EJB container will provide much of the underlying code to support the EJB, and that it relies on detailed deployment information that defines the EJB's requirements.

You have also seen that a J2EE application consists of components and deployment information and how the server-side part of such an application can be deployed. You have seen a client that is able to use such server-side components and the code required to write such a client.


  1. How many Java classes and interfaces must I write to create an EJB?

  1. The EJB writer must define a remote (or business) interface, a home interface, and the bean implementation itself.

  1. Why does an EJB run inside a container?

  1. The container provides many services to the EJB, including distribution, lifecycle, naming/registration, transaction management, security/authentication, and persistence. If the container did not exist, you would have to write all the code to interact with these services yourself.

  1. What issues surround passing an object as part of a remote method call?

  1. To be passed as an argument or return type, an object must be either serializable or remote. If it is neither of these, an error will occur at runtime. If an object is defined as serializable, a new copy will be created and passed/returned. This can add to the overhead of making the method call, but it is a very useful tool when trying to cut down the amount of network traffic between clients and EJBs (as you will see later on Day 18).

  1. Most of the deployment descriptor information is straightforward, but what is the difference between a <resource-ref> and an <env-entry>, and what sort of information is contained in each type of entry?

  1. A <resource-ref> is part of a deployment descriptor that defines an external resource used by a J2EE component. The <resource-ref> will define a name and type for a resource together with other information for the container. The information in a <resource-ref> is really for the container rather than for the EJB itself. To access a resource defined in a <resource-ref>, you would use JNDI to look up its name java:comp/env/jdbc/Agency.

  2. On the other hand, an <env-entry> contains information that is intended for the EJB itself rather than the container. It will define a name, a class type and a value. The contents of <env-entry> elements are usually strings. Again, you would use JNDI to look up its name, java:comp/env/AgencyName.


The intention of this day is for you to familiarise yourself with the EJB environment and the use of EJBs. To ensure that you are comfortable with these areas, you should attempt the following tasks.

  1. If you have not already done so, follow the steps to deploy the example Agency EJB from the Day 4 Exercise directory on the CD-ROM.

  2. Examine the information displayed by deploytool and make sure that you can identify where the resource reference for the Agency JDBC connection is set, where the environment reference for the agency name is set, and where the JNDI name of the Agency EJB itself is set.

  3. Use the runSimple script/batch file provided under the Day 4 Exercise directory on the CD-ROM to run the test client. Make sure that this client runs without errors and successfully lists all the customers in the agency database.

  4. Without referring to the example client (but referring to the material you have covered today), create your own simple test client for the Agency EJB from scratch. This should just consist of a command-line client that creates an instance of an Agency EJB and asks it for its name.

  5. Try changing the name under which the EJB is registered in JNDI using deploytool. Change the JNDI name used by your client to find the Agency EJB and make sure that it still works.

Monday's installment: What is an EJB and why use them?

Tuesday's installment: What's in an EJB and how do I create one?

Wednesday's installment:How do I create, deploy, and use an EJB?

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

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.

To access the full Table of Contents for the book

Sitemap | Contact Us

Thanks for your registration, follow us on our social networks to keep up-to-date