Deployathon: Read Me

Print-friendly Version

Articles Index

Introduction | FAQ | Read Me | Download

• EJBCar Overview
• Requirements
• Installing and Running the EJBCar Application

Step 1: Unzip the zipfile

Step 2: Load and test servers

Step 3: Set up and run EJBCar

Step 4: Use the EJBCar client to submit an order to the factory

Running EJBCar from Your Browser

• Reference Information

Architectural Diagram

EJBCar Packages

EJBCar Classes

Deployment Descriptors

EJBCar Database Utilties

Transactions

EJBCar Overview

EJBCar is a sample application that demonstrates the use of Enterprise JavaBeans (EJB) technology. The application models an online car-buying service. It allows a user to search for cars based on preferences, to select and buy a car, and to obtain financing information for it.

Requirements

To install and run the EJBCar application, you need:

• The Java^TM Development Kit (JDK ) 1.1.5 or above
• An Oracle RDBMS (v7.3 and above) with the corresponding Java Database Connectivity (JDBC) 1.x driver
• A Web server that supports servlets
• An EJB 1.0-compatible server
• The javax.rmi.PortableRemoteObject class

You need thejavax.rmi.PortableRemoteObject class because the EJBCar application uses Remote Method Invocation (RMI) over Internet Inter-Orb Protocol (IIOP) to handle distributed processing. This means that your EJB server must support RMI-IIOP. Many EJB servers do. If your EJB server does not, you should download the implementation of RMI-IIOP from the RMI-IIOP home page. An alternative approach is to use the por.jar file supplied with EJBCar. You might need to update your CLASSPATH specification so that the Java interpreter can locate the RMI-IIOP classes.

Installing and Running the EJBCar Application

The EJBCar application is made up of EJB components, optional servlets, and test clients. For a description of the EJBCar components, see EJBCar Components below. All the necessary jar files are included in the EJBCar zipfile. To install the application, perform the folowing steps:

Step 1: Unzip the zipfile

Unzip the EJBCar zipfile as follows:

The unzipped file contains the following contents:

• jars directory
• broker.jar: Jar file for the Broker enterprise bean
• customer.jar: Jar file for the Customer enterprise bean
• dealercar.jar: Jar file for the DealerCar enterprise bean
• finance.jar: Jar file for the Finance enterprise bean
• orders.jar: Jar file for the EcPerf Orders enterprise bean
• corp.jar: Jar file for the EcPerf Corp enterprise bean
• schema.jar: Jar file for the database utilities
• por.jar: Jar file for a simple implementation of the javax.rmi.PortableRemoteObject class
• ejbcar_just_servlets.jar: Jar file containing the 3 servlets
• ejbcar_client.jar: Jar file containing the EJBCar test client (bytecodes)
• ejbcar_client_src.jar: Jar file containing the source of the EJBCar test client
• helloworld.jar: Jar file for the HelloWorld enterprise bean
• helloworld_client.jar: Jar file containing the java helloworldjava test client (bytecodes)
• docs directory:
• html directory:
• index.html: Deployathon introduction
• readme.html. Installation instructions and deployment guidelines for the EJBCar Sample Application.
• faq.html: Frequently Asked Questions
• EJBcar.gif: EJBCar sample application user interface
• EJBcarbig.gif: EJBCar sample application user interface (enlarged)
• EJBarch.gif: Architecture diagram
• EJBarchbig.gif: Architecture diagram (enlarged)
• javadoc directory: Javadoc for the EJBCar application classes and design

Step 2: Load and test servers

This step tests the server installation and checks the support of the fundamental EJB interfaces.

• Install and configure the following:
• The Java 2 Software Development Kit (JDK 1.1.5 or above)
• A web server that supports servlets
• An EJB 1.0-compliant server
• Test the server installation by running the HelloWorld Demo. The demo uses the HelloWorld Demo EJB and the HelloWorld Java client to display the message "Hello World" on your screen.
• Copy the HelloWorld Demo EJB jar file and deploy it in the EJB server using the server's deployment tool. It might be necessary to customize the deployment descriptor for the HelloWorld Demo EJB, either by using the EJB server's tools or by creating a new deployment descriptor. For information about the deployment descriptors provided for the EJBCar components see Deployment Descriptors below. An example text file and a serialized class file for the deployment descriptor are provided.
• Create the client properties file by customizing the example properties file for the HelloWorld client provided in the package. The properties file is used by the client to specify server-specific properties that might be required for the container, for example, JNDI names and login/password authorization. The example properties file is named example.props. You can find it in the helloworld_client.jar file. Copy the example properties file and rename it to Container.props, where Container is the name of the EJB server.
• Run the HelloWorld demo by invoking the HelloWorldClient Java application. You can find the application in the helloworld_client.jar file. Pass the Container name as a parameter to the application.

Step 3: Set up and run EJBCar

This step is similar to Step 2, but now a more complex set of EJBCar components is tested.

• Create and populate the database.Four EJBCar components, Broker, DealerCar, and ECperf's Corporate and Orders, require their own tables in the database. Scripts are provided in the package to create the tables in an Oracle RDBMS. All database access is performed through the Java Database Connectivity (JDBC^TM) application programming interface (API).
• Create an Oracle (v7.3 or above) database with four users (for example, broker, dealercar, order, corp), one each for the Broker, DealerCar, and ECperf's Corporate and Orders components.
• Populate the tables for the components. Run the SQL*Plus^TM utility to connect as the corresponding user, and execute each of the following SQL scripts:
• broker.sql
• dealer.sql
• orders.sql
• corp.sql
Other database utilities are provided in the package. See EJBCar Database Utilities. Verify that no errors occur. Ignore errors about dropping nonexistent tables (to make the application work for different conditions, the scripts begin by dropping tables).
• Deploy the EJBCar EJBs.
• Copy the EJBCar jar files, that is, broker.jar, customer.jar, dealercar.jar, and finance.jar, and deploy them in the EJB server. It might be necessary to customize the deployment descriptor for the EJBs, either by using the EJB server's tools or by creating a new deployment descriptor. For information about the deployment descriptors provided for the EJBCar components see Deployment Descriptors below. An example text file and a serialized class file for the deployment descriptor are provided.
• Create the client properties file for the EJBCar client by customizing the example properties file provided in the package. The example properties file is named example.props. You can find it in the ejbcar_client.jar file. Copy the example properties file and rename it to Container.props, where Containeris the name of the EJB server.
• Specify settings for transaction processing, as appropriate. See Transactions below for further information.
• Run EJBCar by invoking the CarClient Java application. You can find the application in the ejbcar_client.jar file. Alternatively, you can run EJBCar from your browser using EJBCar servlets (see Running EJBCar from Your Browser.)

Step 4: Use the EJBCar client to submit an order to the factory

This step exercises additional functions in the EJBCar appliation. In doing that it tests EJBCar components that were not tested in the step 3. These additional components simulate a car manufacturing plant. In this step, a separate instance of the EJB server runs on either the same or a different machine, and makes calls from the EJBCar ordering components to the EJBCar components running in the new instance.

• Deploy the remaining EJBCar EJBs, that is, copy the orders.jar and corp.jar files and deploy them in the EJB server. As in step 3, it might be necessary to customize the deployment descriptor for these EJBs.
• Run EJBCar again by invoking the CarClient Java application or run EJBCar from your browser. This time submit an order to the factory. You can cause an order to be sent to the factory by ordering a car that currently has no quantity in stock. Or you can repeatedly order a car until its inventory is depleted. The manufacturer's order number is returned to the client or your browser when the car order is sent to the factory.

Running EJBCar from Your Browser

To run the EJBCar sample application from a browser you need:

• A webserver that supports servlets
• The EJBCar components deployed in an EJB server
• A browser

You also need the files in the ejbcar_just_servlets.jar file. The ejbcar_just_servlets.jar file contains:

• mde/ejbcar/servlet/CarBuyServlet.class: Presents car
requirement choices to use as car search criteria
• mde/ejbcar/servlet/CarReqServlet.class: Searches for cars
• mde/ejbcar/servlet/CarSearchServlet.class: Buys cars
• mde/ejbcar/servlet/example.props: Example properties file used to customize access to the EJB components
• mde/ejbcar/servlet/EJBCar.html: An html file configured to allow access to the servlets.

To run the EJBCar sample application from a browser:

1. Edit the CLASSPATH entry in the webserver. Add any classes or jar files that are needed to run your server (including JNDI). Add the path to your generated classes, these were produced when you deployed the EJB components.
2. Create a .props file for your server. Name the file <server>.props. Use the example.props file in the ejbcar_just_servlets.jar file as a template, adding any additional entries needed for your server. Server names are case-sensitive and correspond to the selection list in EJBCar.html.
3. Copy the EJBCar.html file into a directory that is accessible to your web server, for example, copy it into the public_html directory of your web server.
4. Point your browser at the EJBCar.html page. The URL should look something like http://myhost:myport/EJBcar.html.

Back to Top

Reference Information

The EJBCar application comprises the following components:

• Customer presents to a client, such as the servlet, an interface to the EJBCar application's buying and financing service. Customer consolidates search results from Broker and DealerCar, and interacts with the Finance component.
• Broker represents a car brokerage service. It offers online access to car information from multiple dealers. Broker is closely integrated with car makers: it places orders back to manufacturers when the inventory level falls below a predefined threshold. Placing an order to a manufacturer is an example of a business-to-business transaction.
• DealerCar represents a single car dealer. It offers search and buy capabilities on its inventory, but unlike the Broker, it is not integrated with the manufacturers' systems. Entity beans are optional in Enterprise JavaBeans 1.0; therefore, the EJBCar application can be deployed with or without this component.
• Finance offers car financing information. It searches the internet to find the best rate for car loans, based on the down payment specified by the user. This activity demonstarates call outs to the Web from an Enterprise JavaBean component.
• ECperf^TM is a workload framework that tests the scalability of component architectures, specifically EJB components. ECperf is a self-contained application, consisting of four domains: orders, corporate, manufacturing, and supply. The Orders and Corporate domains are integrated into EJBCar to represent a car manufacturer:
• Orders processes order requests for items^__in this case, cars. To fill an order, it requests a credit check from Corporate.
• Corporate performs credit checks based on requests from Orders.
• EJBCar Client: Provides the user interface layer, exposing all the capabilities offered by the Customer component.
  As an alternative user interface, a servlet is also provided which can be accessed by any browser.

All these components, except for the client, are implemented as Enterprise JavaBeans components called enterprise beans. All types of enterprise beans are used, as summarized in this table:

Component	EJB Type
Broker	Stateless session
Customer	Stateful session
DealerCar*	Entity
Finance	Stateless session
ECperf Orders	Stateless session
ECperf Corporate	Stateless session

* Entity beans are optional in EJB 1.0. Therefore, the EJBCar application can be deployed with or without this component.

Detailed information on each component is available in javadoc format.

Architectural Diagram

The following architectural diagram shows the relationship between the EJBCar components.

Click on image to enlarge

Back to Top

EJBCar Packages

The following packages are provided:

Package Name	Package Content
mde.ejbcar	Common classes
mde.ejbcar.broker	Broker bean
mde.ejbcar.customer	Customer bean
mde.ejbcar.dealercar	DealerCar bean
mde.ejbcar.finance	Finance bean
corp.[interfaces, server]	ECperf Corporate bean
orders.[interfaces, server]	ECperf Orders bean

Beans may require certain environment properties to be defined. See the deployment descriptor supplied with the package.

Back to Top

EJB Classes

For EJB classes, the following naming convention is used:

<Component name>: EJB remote interface

<Component name>Home: EJB Home interface

<Component name>Bean: EJB implementation

<Component name>DB: Database access class (where needed)

<Component name>PrimaryKey: EJB primary key (for DealerCar)

Back to Top

Deployment Descriptors

A deployment descriptor describes the content of a functional unit (a component or components) that is deployed in a server. All the information about the EJBCar components that are deployed in the EJB server are stored as environment properties in deployment descriptors. Examples of such properties are:

• The Java Naming and Directory Interface (JNDI) properties, such as java.naming.factory.initial.
• Database connection parameters, such as jdbcDriverClass and jdbcDriverURL.

Deployment descriptors need to be customized to suit the target environment. A plain text file (DeploymentDescriptor.txt) is provided for each EJBCar component. The text file contains a description of each environment property and sample values. You can use the EJB server's deployment tools to customize the deployment descriptors as appropriate. Alternatively you can use a Java language program provided in the package to create deployment descriptors (GenerateDescriptors.java). The program is in source format, so you can modified it as required to create customized descriptors.

In particular, pay close attention to the JNDI names specified in the deployment descriptors. Here is a list of JNDI properties for each bean, giving the current value:

• CustomerBean
  • beanHomeName: specifies the JNDI name for the bean (test/customer/CustomerHome)
  • brokerURL: specifies the JNDI name for the Broker bean
  • financeURL: specifies the JNDI name for the Finance bean
  • dealerCarURL: specifies the JNDI name for the DealerCar bean
• BrokerBean
• beanHomeName: specifies the JNDI name for the bean (test/broker/BrokerHome)
• ecOrdersURL: specifies the JNDI name for the Orders bean
• FinanceBean
• beanHomeName: specifies the JNDI name for the bean (test/finance/FinanceHome)
• DealerCarBean
• beanHomeName: specifies the JNDI name for the bean (test/dealercar/DealerCarHome)
• OrdersBean
• beanHomeName: specifies the JNDI name for the bean (test/OrdersEntry/OrdersHome)
• ecCustURL: specifies the JNDI name for the ECperf's Corporate bean
• CorporateBean
• beanHomeName: specifies the JNDI name for the bean (test/corp/CustomerHome)

Back to Top

EJBCar Database Utilities

The EJBCar package includes a number of utilities for use with the EJBCar database. The utilities are:

• SQL scripts. Use the following scripts to populate the database:
• broker.sql
• dealer.sql
• orders.sql
• corp.sql

You can find these SQL scripts in the schema.jar file. The scripts are designed to run with a database utility such as SQL*Plus.

• PrintDatabase. Use this program to display the contents of the database, and to determine the values (such as car types) to use for the client application. To use the utility, specify:

<dir>java mde.ejbcar.schema.PrintDatabase <service> <sort option></dir>
where:
<service> is broker or dealercar,
<sort option> is 1 to sort by make, or 2 to sort by price.

• RefreshDatabase. Use this utility to quickly reset the database. Purchasing cars through the client application will make changes to the database and reduce the number of cars in stock. Eventually, this depletes the database of cars. To repopulate the database and continue testing, use this utility to refresh the tables to their original state. The orders and corp tables do not need to be refreshed. To use the utility, specify:
  
  <dir>java mde.ejbcar.schema.RefreshDatabase <service> where <service> can be broker, dealercar, or all (for both).

The PrintDatabase and RefreshDatabase utility programs require two property files that contain the JDBC connection parameters: broker.props and dealercar.props. These property files must be present in the directory in which the programs are run. Sample property files are provided under mde/ejbcar/schema.

Transactions

EJBCar components perform database updates to an Oracle database within the context of a transaction. Some EJB servers can interact with Oracle as a Resource Manager (in transactional terminology) and demarcate transactions. They do this based on the corresponding deployment descriptor attribute. However the EJB specification does not require this capability.

If the EJB server you use is not able to interact with Oracle in this way, set the environment property resMgrSupport to false. This will generate a commit after each database call and guarantee that changes are stored permanently. In this case, the bean's transactional flag should be set to TX_NOT_SUPPORTED. (Note that this flag would not be needed with EJB 1.1 versions of the code. The flag was needed for the Deployathon because the EJB servers that were tested at the time were not fully mature.)

Back to Top
Introduction
FAQ
Read Me
Download