Appendices

Appendix A: Installing and running J2EE

This tutorial uses the J2EE 1.3.1 Reference Implementation, which is included in the J2EE SDK download. If you use a different J2EE application server, you should ensure that it is compliant with J2EE 1.3.1 and the EJB 2.0 specification. The reference implementation requires J2SE 1.3.1_02 or later.

You can download the J2EE SDK from Sun's J2EE site; see Resources. While there, be sure to read and follow the Installation Instructions for your platform. In addition, the tutorial uses the standard javac command to compile the example code, so you will need to put j2ee.jar in your classpath. j2ee.jar is located in J2EE_HOME/lib. Once the SDK is installed, you should review the Release Notes and the Configuration Guide. API documentation and J2EE SDK Tools instructions are also provided. These are all HTML pages that you can access from J2EE_HOME/doc/index.html.

Starting and stopping J2EE

To run J2EE, enter:
j2ee -verbose
at the command line. To stop j2ee, enter:
j2ee -stop
at the command line.

Starting and stopping Cloudscape

To run the Cloudscape database engine, which is the default for J2EE, enter:
cloudscape -start
at the command line. To stop Cloudscape, enter:
cloudscape -stop
at the command line.

Starting deploytool

To run deploytool (see Appendix B: Deployment ), enter deploytool at the command line. Exit as you would any other GUI application.

Back to top

Appendix B: Deployment

Figure 7. The J2EE Reference Implementation deploytool

Enterprise JavaBean component configuration is defined in deployment descriptors, which are XML documents. Tools like deploytool (pictured in Figure 7) generate or update the descriptors when you set the configuration elements. For example, here's the relatively brief ejb-jar.xml deployment descriptor generated for MetricCvtJAR in Deploying the Metric Converter example:

<ejb-jar>
  <display-name>MetricCvtJAR</display-name>
  <enterprise-beans>
    <session>
      <display-name>MetricCvtEJB</display-name>
      <ejb-name>MetricCvtEJB</ejb-name>
      <home>MetricCvtRemoteHome</home>
      <remote>MetricCvtRemote</remote>
      <local-home>MetricCvtLocalHome</local-home>
      <local>MetricCvtLocal</local>
      <ejb-class>MetricCvtBean</ejb-class>
      <session-type>Stateless</session-type>
      <transaction-type>Bean</transaction-type>
      <security-identity>
        <description></description>
        <use-caller-identity></use-caller-identity>
      </security-identity>
    </session>
  </enterprise-beans>
</ejb-jar>

Most developers decide rather quickly that they would prefer not to do this process manually.

J2EE deployment can be a daunting task (enough so that the EJB specification defines a role for an expert deployer) for two reasons. The first is that J2EE provides an enormous amount of declarative functionality for the developer. While this is a good thing, the downside is that the functionality must be declared, and with so many options, the task quickly becomes very complicated. The second is that while portions of packaging, like ejb and web descriptor elements, are mandated by the specification, the overall deployment process is not standardized; each vendor provides its own means of deployment and requires additional associated proprietary descriptors.

deploytool hides this fact of J2EE life somewhat by generating both the standard and necessary proprietary descriptors. You can't really tell from the settings which are standard and which are proprietary to the Reference Implementation. For the curious, a look into the .ear file generated by deploytool will reveal that the J2EE RI creates its own sun-j2ee-ri.xml file that begins with a <j2ee-ri-specific-information> tag -- not particularly encouraging for portability.

The tutorial walks you through setting up the deployment descriptors and actual deployment with deploytool after the discussion for each example. If you make changes to the files referenced by the descriptors (that is, if you add, remove, or recompile them) and need to redeploy, first select "Update Files" from the Tools menu, then select "Deploy". Alternatively, you can use the "Update and Redeploy" selection.

The following lists, taken from the J2EE "XML DTD for the EJB 2.0 deployment descriptor" (see Resources ), show the elements that can be described for EJB components.

• The entity element declares an entity bean. The declaration consists of:
  • An optional description
  • An optional display name
  • An optional small icon file name
  • An optional large icon file name
  • A unique name assigned to the enterprise bean in the deployment descriptor
  • The names of the entity bean's remote home and remote interfaces, if any
  • The names of the entity bean's local home and local interfaces, if any
  • The entity bean's implementation class
  • The entity bean's persistence management type
  • The entity bean's primary key class name
  • An indication of the entity bean's reentrancy
  • An optional specification of the entity bean's cmp-version
  • An optional specification of the entity bean's abstract schema name
  • An optional list of container-managed fields
  • An optional specification of the primary key field
  • An optional declaration of the bean's environment entries
  • An optional declaration of the bean's EJB references
  • An optional declaration of the bean's local EJB references
  • An optional declaration of the security role references
  • An optional declaration of the security identity to be used for the execution of the bean's methods
  • An optional declaration of the bean's resource manager connection factory references
  • An optional declaration of the bean's resource environment references
  • An optional set of query declarations for finder and select methods for an entity bean with cmp-version 2.x.
• The message-driven element declares a message-driven bean. The declaration consists of:
  • An optional description
  • An optional display name
  • An optional small icon file name
  • An optional large icon file name
  • A name assigned to the enterprise bean in the deployment descriptor
  • The message-driven bean's implementation class
  • The message-driven bean's transaction management type
  • An optional declaration of the message-driven bean's message selector
  • An optional declaration of the acknowledgment mode for the message-driven bean if bean-managed transaction demarcation is used
  • An optional declaration of the intended destination type of the message-driven bean
  • An optional declaration of the bean's environment entries
  • An optional declaration of the bean's EJB references
  • An optional declaration of the bean's local EJB references
  • An optional declaration of the security identity to be used for the execution of the bean's methods
  • An optional declaration of the bean's resource manager connection factory references
  • An optional declaration of the bean's resource environment references.
• The session element declares an (sic) session bean. The declaration consists of:
  • An optional description
  • An optional display name
  • An optional small icon file name
  • An optional large icon file name
  • A name assigned to the enterprise bean in the deployment description
  • The names of the session bean's remote home and remote interfaces, if any
  • The names of the session bean's local home and local interfaces, if any
  • The session bean's implementation class
  • The session bean's state management type
  • The session bean's transaction management type
  • An optional declaration of the bean's environment entries
  • An optional declaration of the bean's EJB references
  • An optional declaration of the bean's local EJB references
  • An optional declaration of the security role references
  • An optional declaration of the security identity to be used for the execution of the bean's methods
  • An optional declaration of the bean's resource manager connection factory references
  • An optional declaration of the bean's resource environment references.

You can view the generated deployment descriptors at any time by selecting the appropriate EJB JAR file, then choosing Tools->Descriptor Viewer from the deploytool menu.

The tutorial uses the J2EE RI deploytool and takes the path of deployment by example, for the reasons above and the simple fact that explaining every option could take another complete tutorial. With the number of applications and beans in the tutorial, the developer should pick up the basic patterns fairly quickly. For more detailed information about deployment, see the J2EE and EJB specifications, along with the other links in Resources.

Back to top

Appendix C: About the example applications

Figure 8. The Alice's World site

When trying to decide on example code to illustrate the material presented in the tutorial, I wanted something that was conceptually simple, but had the functionality required in real-world applications. In addition, I felt the examples should reinforce and add to the tutorial text, and possibly bring some amusement to what can be dead boring, detailed technical information. Last, I wanted no shopping carts! While shopping carts are great, sometimes it seems that every article or tutorial uses them for example apps. There actually are other things being done with J2EE.

The result is the Alice's World site. Alice's World presents three applications: a metric/English measure conversion program; a survey program; and a program to display the results of the survey. These applications exhibit the functionality required in nearly every real program: gather data, process it, store it, and display the resulting information. The client applications are all based on servlets and JSP pages. While a detailed explanation of the programs is "beyond the scope of the tutorial" -- that favorite technical author's excuse, but the tutorial is, after all, about EJB technology -- I felt that the applications warranted a section that described the rationale and flow of the examples. That's particularly true for the Survey application, because it is revisited three times in the tutorial -- much as happens while developing an application in the real world. Each revision adds to or refines the application until it is complete. Each revision also introduces a different type of bean into the mix. You can see the applications in action before, or instead of, deploying them yourself at conceptGO's Community page.

The bean and client applications for the Metric Converter are deployed separately. This is what should happen in the real world: EJB components, and all of our code really, should aim for decoupling and reusability as much as possible. In the Survey and Survey Results applications, the client and associated beans are deployed together, mostly for administrative reasons, but the beans can still be accessed by other clients.

You may notice that the application tasks could have been done without using EJB components or J2EE at all, but the design seemed justified for the tutorial. If I had included a "J2EE-worthy" application, you would be reading this six months later and 600 pages longer. In that scenario, the tutorial may well have lost its focus. However, you should keep this critical mind-set when designing your own applications, to avoid the "When you have a hammer..." syndrome, and to use the proper tools and techniques for useful, functional, efficient, and effective applications.

Deploying the Alice application

So, remember Alice? The Alice's World page is a small JSP page that primarily invokes the sample applications. If there had not been the need to have a vehicle to execute the program that creates and resets the database, it could have been just an HTML page. It does provide an opportunity to take our first look at deploying a J2EE application. If you prefer, you can take the easy route: after downloading the source code, start J2EE and deploytool, copy Alice.ear from the Alice/prod directory to the Alice directory, and open Alice.ear in deploytool. Select the "Alice" application, then "Deploy" from the Tools menu. You can also deploy any or all of the other applications, including the beans, using the same method: copy the appropriate EAR from the example directory's prod directory, open the EAR in deploytool, then select the "Deploy" menu item, and continue at the step labeled "Deployment".

To deploy the Alice application from scratch, follow these directions:

1. Compile CreateRSTables.java (or copy the .class file from the prod folder.)
2. Start J2EE and deploytool.
3. Create new application:
   • From the deploytool menu, select File, New, Application.
   • Browse to the Alice folder.
   • Key Alice.ear in file name, click New Application.
   • Application Display name is "Alice" by default; click OK.
4. Create new Web component:
   • Ensure that Application Alice is selected.
   • From the menu, select File, New, Web Component -- Intro display appears; click Next.
   • Select Create New WAR File In Application.
   • Ensure that Alice is selected in the drop-down menu.
   • In WAR Display Name, key "AliceWAR", then click Edit.
   • Select the files necessary for the application:
     • The images directory
     • CreateRSTables.class
     • index.jsp
   • Click Add; click OK; click Next.
   • Select JSP for the type of Web component.
   • Click Next.
   • From the JSP Filename combo, select "index.jsp", and leave the Web component name as "index".
   • Click Next; click Finish.
   • AliceWAR now appears under Alice.
   • Select AliceWAR, then select the Resource Refs tab, and click Add.
   • Under Coded Name, enter "jdbc/gsejbDB". Leave Type as "javax.sql.DataSource", Authentication as "Container", and Sharable checked.
   • Select the Alice application.
   • Click the JNDI Names tab. In JNDI Name under References, enter "jdbc/gsejbDB".
   • Click Web Context from the tabbed pane.
   • Enter "/Alice", click General.
5. Deployment. We can now actually deploy the Alice application:
   • Ensure that the Alice application is selected.
   • From the menu, select Tools, Deploy.
   • Under Object To Deploy, ensure that Alice is selected.
   • Under Target Server, we are using localhost. Be sure that is the selection.
   • Unselect the Return Client JAR check box.
   • Select Save object before deploying.
   • Click Next.
   • Verify that the JNDI name under References is "jdbc/gsejbDB"; click Next.
   • Ensure that "/Alice" is in the context root entry.
   • Click Next, then Finish.

The Deployment Progress dialog will display. Wait until the progress bars are complete and the Cancel button changes to OK, then click OK. The Alice application is deployed.

If you look in the Alice folder, you will see that it now contains Alice.ear. To run Alice, start your browser and enter http://localhost:8000/Alice as the target URL; you should see the Alice home page shown in Figure 8. Understand that none of the example applications have been deployed yet, so you can't do anything but look at the Alice display for now. The other applications will be deployed in the appropriate example sections of the tutorial.

Back to top

A word about naming conventions

The tutorial uses the following naming conventions for consistent tracking of all the EJB components, application pieces, and deployment names. You may use the convention for your own code or choose another; there's nothing blessed here and a real-world set of naming conventions should be considerably more rigorous and flexible. To avoid major headaches, do be sure that whatever you use is consistent and provides a logical way to track the component parts.

The EJB 2.0 specification "recommends, but does not require, that all references to other enterprise beans be organized in the ejb subcontext of the bean's environment." For that reason, the tutorial prepends ejb/ to the bean JNDI names. The actual mechanism for JNDI loading is not addressed by the specification, so this is definitely a vendor-proprietary area to check when deploying your own applications.

I'll use the bean name for the one used in the Metric Converter program, which is MetricCvt, to illustrate:

• The bean class: MetricCvtBean
• The remote component interface: MetricCvtRemote
• The remote home interface: MetricCvtRemoteHome
• The local component interface: MetricCvtLocal
• The local home interface: MetricCvtLocalHome
• In this case, some constants were also defined in an interface to share among the bean and the application: MetricCvtConstants

For the initial page of the application: index.jsp. I am aware of the downsides to using "index" as a page name, but it does resolve some mapping issues.

Since the tutorial at times deploys beans and applications separately, deployment names for bean "applications" are:

• The application EAR name: MetricCvt
• The EJB JAR name: MetricCvtJAR
• The Enterprise JavaBean component name: MetricCvtBean

Deployment names for the real applications, all Web components here, are:

• The application EAR name: MetricCvtApp
• The WAR JAR name: MetricCvtWAR

Back to top

The Alice files

These are the source, class, and JAR files used in the Alice application. They reside in the Alice directory in the code download.

Table 4. Source, class, and JAR files used in the Alice application

Back to top

The Metric Converter application

The Metric Converter is a straightforward one-page application that converts between U.S. English and metric measures based on the type of conversion selected and the input value. It calls on a stateless session bean to perform the calculation and return a formatted answer string. When the user clicks Done, the servlet session is invalidated and control is returned to the Alice's World home page.

Figure 9. The Metric Converter application

The stateless session bean and the application are deployed separately. An interface with static final constants is used to ensure that both the client and the bean use the same values to identify the conversion type. For the details, see Example: A metric conversion program.

Back to top

The Metric Converter files

These are the source, class, and JAR files used in the Metric Converter application. They reside in the MetricCvt directory in the code download.

Table 5. Source, class, and JAR files used in the Metric Converter application

Back to top

The Rock Survey application

Alice's Rock Survey is the primary example application in the tutorial. Much as happens in practice, the application goes through several iterations before it is a finished product. Each iteration introduces a different kind of EJB component and functionality to the application.

In Example: The Rock Survey, take 1, the Rock Survey uses a stateful session bean to handle the business methods for collecting the survey information. The session bean also acts as a dummy data store in this version; there is no actual persistence at this point. In Example: The Rock Survey, take 2, an entity bean is added, which uses BMP for persisting the SurveyNames table data. In Example: The Rock Survey, take 2 (continued), another entity bean uses CMP for persistence with the "SurveyBeanTable" table. In the final iteration, Example: The Rock Survey, take 3, a message-driven bean is added to allow for asynchronous updates to the database.

The application begins with a "welcome to the survey" page that collects data appropriate to all surveys and gives the user -- let's call her Chrissie -- an opportunity to return to the home page. At this point, of course, we only have one survey, the Rock Survey.

Figure 10. Survey application -- Welcome page

The logic for purposes of the example is:

• The "Mr./Ms." salutation allows inference of gender.
• The Last Name entries are saved to determine the most frequent entries.
• Marital Status is directly entered.
• A Postal Code entry with a length of five is assumed to be a U.S. zip code. Any other entry is assumed to denote residents of other countries.

After entering the initial data, Chrissie clicks Go. The Rock Survey welcome page is displayed. This page asks her to verify the data entered and allows a return to the previous page for corrections.

Figure 11. Rock Survey application -- Welcome page

If Chrissie is happy with her entries, she clicks Next, which causes the actual Rock Survey page to be displayed.

Figure 12. Rock Survey application -- Survey page

This page collects and validates the actual survey data. All entries here are straightforward, except that the weight of the rocks is always kept in pounds in the database. Once the entries are made, Chrissie clicks Next, and the Rock Survey "thank you" page is displayed.

Figure 13. Rock Survey application -- Thank you page

The thank you page asks her to verify the input data and allows a return to the previous page for corrections. If the entries are satisfactory, she clicks Done, which causes the data to be stored, invalidates the servlet session, and returns to the Alice's World home page.

Back to top

The Rock Survey files, take 1

These are the source, class, image, and JAR files used in the Rock Survey, take 1. They reside in the Survey1 directory in the code download.

Table 6. Source, class, and JAR files used in the Rock Survey, take 1

Back to top

The Rock Survey files, take 2

These are the source, class, image, and JAR files used in the Rock Survey, take 2. They reside in the Survey2 directory in the code download.

Table 7. Source, class, and JAR files used in the Rock Survey, take 2

Back to top

The Rock Survey files, take 3

These are the source, class, image, and JAR files used in the Rock Survey, take 3. They reside in the Survey3 directory in the code download.

Table 8. Source, class, and JAR files used in the Rock Survey, take 3

Back to top

The Survey Results application

The Survey Results application displays the information and statistics gathered from Alice's surveys.

Figure 14. Survey Results application -- Welcome page

At this point there is only one survey, the Rock Survey, so Chrissie just clicks Go, and the Rock Survey Results page is displayed.

Figure 15. Rock Survey Results application -- Display page

The basis for the displayed information is explained in The Rock Survey application. When Chrissie is finished viewing the results, she clicks Done, which invalidates the servlet session and returns her to the Alice's World home page.

Back to top

The Survey Results files

These are the source, class, image, and JAR files used in the SurveyResults application. They reside in the SurveyResults directory in the code download.

Table 9. Source, class, and JAR files used in the SurveyResults application

Back to top

Appendix D: What's new in the EJB 2.1 specification?

The changes and additional services in J2EE 1.4, and therefore the EJB 2.1 specification, primarily focus on Web services. The major new goals and capabilities for EJB 2.1 are:

• Support for Web services. A new interface for Web services endpoints has been added, allowing stateless session bean implementations. All beans can access external Web services.
  
  
• A container-managed timer service. The service "provides a coarse-grained, transactional time-based event notifications" (sic).
  
  
• Generalized architecture for message-driven beans. MDBs can access various messaging types in addition to JMS messages.
  
  
• Enhanced EJB Query Language. EJB QL now has support for various aggregate and scalar functions, and results may be ordered.

For further information, see Resources.

8 of 10 | Previous | Next

Comments

Back to top

Table of contents

• About this tutorial
• J2EE/EJB technology overview
• Session beans
• Entity beans
• Message-driven beans
• Displaying the Rock Survey example results
• Wrapup
• Appendices
• Resources
• About the author

---

8 of 10 | Previous | Next

Next steps from IBM

With the WebSphere Application Server you can benefit from the simplified EJB 3.0 development experience, new persistence model, and interceptors.

---

• Try: Download a free trial version of WebSphere Application Server Community Edition, the lightweight Java 5 application server with robust EJB 3.0 funtionality.
• Article: Learn how call patterns and components involved in making calls to EJB components deployed in the EJB container operate in WebSphere Application Server.
• Tutorial: This tutorials shows you how to create an enterprise J2EE application that implements both Plain Old Java Object (POJO) and EJB Web services endpoints.
• Demo: Watch this demo and learn how to configure and use the WebSphere Application Server and the Eclipse IDE with the Web Tool Project Platform.
• Buy: WebSphere Application Server

Dig deeper into Java on developerWorks

Discover knowledge paths

Skill-building guides for Java, Linux, open source, cloud, business analytics, and more.