|
|
| Home > Apache Geronimo v1.1 > Documentation > Apache Geronimo v1.1 - User's Guide > Sample applications > EJB sample application |
Enterprise Java Beans has been one of the corner stones of the J2EE specification. As a J2EE 1.4 certified application server, Apache Geronimo supports EJB's extensively with the help of OpenEJB EJB Container. Although it is possible to use standard Java objects to contain your business logic and business data, using EJBs addresses many of the issues of using simple Java objects, such as scalability, life cycle management and state management. In this article, you will see how an initial database application is extended and used for both local and remotely referred application clients for an Enterprise Java Beans back end. The application uses built-in Apache Derby as its database. Use this article to learn how to simplify your enterprise application development process.
Banking application has two types of application clients namely "Banking Remote Application" and "Banking Web Application". Each of these clients demonstrate how to refer Enterprise Java Beans in remote and local interfaces respectively. Both these clients are referring a common business layer which has been implemented with the help of Session and Entity Beans. Stateless Session Beans are acting as the business service interface between business entities and application clients. All the business entities of the application layer are implemented with the CMP and BMP Entity Beans. Relations between CMP entities are managed as Container Managed Relations.
After reading this article you should be able get the best out of EJB features of Geronimo, such as defining Enterprise Java Beans, managing relations between them and refer EJBs via different kind of clients.
This article is organized in to following sections.
EJB implementation may vary from one vendor to another. The following are the main list of features Apache Geronimo supports as a J2EE container.
As mentioned above the Banking application supports two types of business application clients. The overview of each client is given below.
Both of these clients use a common business service layer. Behind that business service layer, there are three common business entities that appear in the banking application domain Account, Customer and ExchangeRate. Each Customer can have more than one Account while an Account can only be owned by one Customer. ExchangeRate represents a rate value given by the bank relative to the USD for a particular currency.
The following figure gives the overall architecture of the banking application.
The Banking application consists of the following list of packages and classes.
Finally, the banking application will be deployed as an EAR to the application server. The overview of the structural content of the EAR file is given in the following example.
|-Bank.ear
|-BankEJB.jar
|-META-INF
|- ejb-jar.xml
|- openejb-jar.xml
|-BankWeb.war
|-jsp
|- customer_info.jsp
|- customer_main.jsp
|- error.jsp
|- exchange_rates.jsp
|- index.jsp
|-WEB-INF
|- web.xml
|- geronimo-web.xml
|- classes
|-META-INF
|- application.xml
|- geronimo-application.xml
|-tranql-connector-1.2.rar
|-BankPool.xml
First, we will look at how the business service layer of the application has been implemented with the help of EJBs. In this application environment all the EJBs are using XDoclet to generate their meta information and their interfaces.
Corresponding openejb-jar.xml defines Geronimo specific features of EJBs. It has both EJB information and their relationships. In addition, it gives a link to the database pool of the application. Entity Beans in the application are dependent on this pool. Also note that the final part of this file defines a 1-N Container Managed Relation (CMR) between Customer and Account Entity Beans.
<?xml version="1.0" encoding="UTF-8"?> <openejb-jar xmlns="http://www.openejb.org/xml/ns/openejb-jar-2.1"> <dep:environment xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.1"> <dep:moduleId> <dep:groupId>default</dep:groupId> <dep:artifactId>BankEJB</dep:artifactId> <dep:version>1.0</dep:version> <dep:type>car</dep:type> </dep:moduleId> <dep:dependencies/> <dep:hidden-classes/> <dep:non-overridable-classes/> </dep:environment> <cmp-connection-factory> <resource-link>BankPool</resource-link> </cmp-connection-factory> <enterprise-beans> <session> <ejb-name>BankManagerFacadeBean</ejb-name> <jndi-name>org.apache.geronimo.samples.bank.ejb.BankManagerFacadeBean</jndi-name> <ejb-ref> <ref-name>ejb/Customer</ref-name> <ejb-link>Customer</ejb-link> </ejb-ref> <ejb-ref> <ref-name>ejb/Account</ref-name> <ejb-link>Account</ejb-link> </ejb-ref> <ejb-ref> <ref-name>ejb/ExchangeRate</ref-name> <ejb-link>ExchangeRate</ejb-link> </ejb-ref> </session> <entity> <ejb-name>Account</ejb-name> <local-jndi-name>AccountLocalEntity</local-jndi-name> <table-name>Account</table-name> <cmp-field-mapping> <cmp-field-name>accountNumber</cmp-field-name> <table-column>ACC_NO</table-column> </cmp-field-mapping> <cmp-field-mapping> <cmp-field-name>accountType</cmp-field-name> <table-column>ACC_TYPE</table-column> </cmp-field-mapping> <cmp-field-mapping> <cmp-field-name>customer</cmp-field-name> <table-column>CUSTID_FK</table-column> </cmp-field-mapping> <cmp-field-mapping> <cmp-field-name>balance</cmp-field-name> <table-column>BALANCE</table-column> </cmp-field-mapping> <resource-ref> <ref-name>jdbc/BankDataSource</ref-name> <resource-link>BankPool</resource-link> </resource-ref> </entity> <entity> <ejb-name>Customer</ejb-name> <local-jndi-name>CustomerLocalEntity</local-jndi-name> <table-name>Customer</table-name> <cmp-field-mapping> <cmp-field-name>customerId</cmp-field-name> <table-column>CUST_ID</table-column> </cmp-field-mapping> <cmp-field-mapping> <cmp-field-name>customerName</cmp-field-name> <table-column>CUST_NAME</table-column> </cmp-field-mapping> <resource-ref> <ref-name>jdbc/BankDataSource</ref-name> <resource-link>BankPool</resource-link> </resource-ref> </entity> <entity> <ejb-name>ExchangeRate</ejb-name> <local-jndi-name>ExchangeRate</local-jndi-name> <resource-ref> <ref-name>jdbc/BankDataSource</ref-name> <resource-link>BankPool</resource-link> </resource-ref> </entity> </enterprise-beans> <relationships> <ejb-relation> <ejb-relation-name>Customer-Account</ejb-relation-name> <ejb-relationship-role> <ejb-relationship-role-name>Account-to-Customer</ejb-relationship-role-name> <relationship-role-source> <ejb-name>Account</ejb-name> </relationship-role-source> <cmr-field> <cmr-field-name>customer</cmr-field-name> </cmr-field> <foreign-key-column-on-source/> <role-mapping> <cmr-field-mapping> <key-column>CUST_ID</key-column> <foreign-key-column>CUSTID_FK</foreign-key-column> </cmr-field-mapping> </role-mapping> </ejb-relationship-role> </ejb-relation> </relationships> </openejb-jar>
BankPool.xml is a typical database pool configuration file, which will be connected to the BankDB defined through the inbuilt Derby database. Entity beans of the application refer the defined database via this configuration file.
<?xml version="1.0" encoding="UTF-8"?> <connector xmlns="http://geronimo.apache.org/xml/ns/j2ee/connector-1.1"> <dep:environment xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.1"> <dep:moduleId> <dep:groupId>console.dbpool</dep:groupId> <dep:artifactId>BankPool</dep:artifactId> <dep:version>1.0</dep:version> <dep:type>rar</dep:type> </dep:moduleId> <dep:dependencies> <dep:dependency> <dep:groupId>org.apache.derby</dep:groupId> <dep:artifactId>derby</dep:artifactId> <dep:type>jar</dep:type> </dep:dependency> </dep:dependencies> </dep:environment> <resourceadapter> <outbound-resourceadapter> <connection-definition> <connectionfactory-interface>javax.sql.DataSource</connectionfactory-interface> <connectiondefinition-instance> <name>BankPool</name> <config-property-setting name="Driver">org.apache.derby.jdbc.EmbeddedDriver </config-property-setting> <config-property-setting name="UserName">app</config-property-setting> <config-property-setting name="ConnectionURL">jdbc:derby:BankDB</config-property-setting> <connectionmanager> <local-transaction/> <single-pool> <max-size>10</max-size> <min-size>0</min-size> <match-one/> </single-pool> </connectionmanager> </connectiondefinition-instance> </connection-definition> </outbound-resourceadapter> </resourceadapter> </connector>
geronimo-application.xml and application.xml define the main components of the EAR. Both EJB component and Web archive information are given in these files. Additionally, these two XML files define application scoped database connection pool with tranql-connector-1.2.rar and BankPool.xml.
<?xml version="1.0" encoding="UTF-8"?> <application xmlns="http://geronimo.apache.org/xml/ns/j2ee/application-1.1"> <dep:environment xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.1"> <dep:moduleId> <dep:groupId>default</dep:groupId> <dep:artifactId>Bank</dep:artifactId> <dep:version>1.0</dep:version> <dep:type>car</dep:type> </dep:moduleId> <dep:dependencies/> <dep:hidden-classes/> <dep:non-overridable-classes/> </dep:environment> <module> <connector>tranql-connector-1.2.rar</connector> <alt-dd>BankPool.xml</alt-dd> </module> </application>
<?xml version="1.0" encoding="UTF-8"?> <application xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/application_1_4.xsd" version="1.4"> <module> <ejb>BankEJB.jar</ejb> </module> <module> <web> <web-uri>BankWeb.war</web-uri> <context-root>/Bank</context-root> </web> </module> <module> <connector>tranql-connector-1.2.rar</connector> </module> </application>
Since Banking Web Application is a part of EAR, the BankManagerFacade Session Bean will be referred as a local interface. Those additional configuration information required for the EJB reference can be found in the web.xml.
<?xml version="1.0" encoding="UTF-8"?> <web-app xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd" version="2.4"> <welcome-file-list> <welcome-file>/jsp/index.jsp</welcome-file> </welcome-file-list> <servlet> <display-name>CustomerServiceServlet</display-name> <servlet-name>CustomerServiceServlet</servlet-name> <servlet-class>org.apache.geronimo.samples.bank.web.CustomerServiceServlet</servlet-class> </servlet> <servlet> <display-name>CommonServiceServlet</display-name> <servlet-name>CommonServiceServlet</servlet-name> <servlet-class>org.apache.geronimo.samples.bank.web.CommonServiceServlet</servlet-class> </servlet> <servlet-mapping> <servlet-name>CustomerServiceServlet</servlet-name> <url-pattern>/customer_info</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>CommonServiceServlet</servlet-name> <url-pattern>/exchange_rates</url-pattern> </servlet-mapping> <!-- To refer local EJB's --> <ejb-local-ref> <ejb-ref-name>ejb/BankManagerFacade</ejb-ref-name> <ejb-ref-type>Session</ejb-ref-type> <local-home>org.apache.geronimo.samples.bank.ejb.BankManagerFacadeHomeLocal</local-home> <local>org.apache.geronimo.samples.bank.ejb.BankManagerFacadeLocal</local> <ejb-link>BankManagerFacadeBean</ejb-link> </ejb-local-ref> </web-app>
Account Balance Modifier swing application refers the same BankManagerFacade Session bean as a remotely refer EJB. It's configuration information can be found in the bank_client.properties file.
java.naming.factory.initial=org.openejb.client.RemoteInitialContextFactory java.naming.provider.url=localhost:4201 java.naming.security.principal=system java.naming.security.credentials=manager jndi.bankManager=org.apache.geronimo.samples.bank.ejb.BankManagerFacadeBean
 |
Always check for the correct network information to run this application client out side of the local computer. |
The sample database that is being used to demonstrate this application is inbuilt Derby database. The name of the sample database is BankDB and it consists of three tables, CUSTOMER ,ACCOUNT and EXCHANGE_RATE. The fields for each of these tables are described below.
| Table Name | Fields |
|---|---|
| CUSTOMER | CUST_ID (PRIMARY KEY) CUST_NAME |
| ACCOUNT | ACC_NO (PRIMARY KEY) ACC_TYPE BALANCE CUSTID_FK |
| EXCHANGE_RATE | RATE_ID (PRIMARY KEY) CURRENCY RATE |
The CUSTOMER table stores the data related to the customers.It stores only the identification number and and the name. ACCOUNT table has a unique account number for identification. Account type and balance are the other information stored. CUSTID_FK is a foriegn key to the Customer table which is the owner of the Account. EXCHANGE_RATE table has a primary key of RATE_ID for an identification. Each record of EXCHANGE_RATE has CURRENCY name and RATE paid by the bank.
The tools used for developing and building the Banking applications are:
XDoclet is an open source code generation engine. It enables Attribute-Oriented Programming for java. In short, this means that you can add more significance to your code by adding meta data (attributes) to your java sources. This is done in special JavaDoc tags.
Although XDoclet originated as a tool for creating EJBs, it has evolved into a general-purpose code generation engine. XDoclet consists of a core and a constantly growing number of modules. It is fairly straight forward to write new modules if there is a need for a new kind of component.
http://xdoclet.sourceforge.net/xdoclet/index.html
Apache Derby, an Apache DB subproject, is a relational database implemented in Java. Its footprint is so small you can easily embed it in any Java-based solution. In addition to its embedded framework, Derby supports a more familiar client/server framework with the Derby Network Server.
http://db.apache.org/derby/index.html
The Eclipse IDE was used for development of the sample application. This is a very powerful and popular open source development tool. It has integration plug-ins for the Geronimo too. Eclipse can be downloaded from the following URL:
http://www.eclipse.org
Ant is a pure Java build tool. It is used for building the war files for the Inventory application. Ant can be downloaded from the following URL:
http://ant.apache.org
Download the bank application from the following link:
Bank
After decompressing the given file, the bank directory will be created.
Configuration of the application consists of creating the database and defining the connection pool to access it.
After starting Apache Geronimo log into the console and follow the given steps to create the BankDB.
CREATE TABLE customer(
CUST_ID VARCHAR(15) PRIMARY KEY,
CUST_NAME VARCHAR(40)
);
CREATE TABLE account(
ACC_NO VARCHAR(15) PRIMARY KEY,
ACC_TYPE VARCHAR(10),
BALANCE DOUBLE,
CUSTID_FK VARCHAR(15),
FOREIGN KEY (CUSTID_FK) REFERENCES customer
);
CREATE TABLE exchange_rate(
RATE_ID VARCHAR(10) PRIMARY KEY,
CURRENCY VARCHAR(10),
RATE DOUBLE
);
INSERT INTO customer(CUST_ID,CUST_NAME) VALUES('12345','Lasantha Ranaweera');
INSERT INTO account(ACC_NO,ACC_TYPE,BALANCE,CUSTID_FK) VALUES('1234567890','Savings',1005.35,'12345');
INSERT INTO account(ACC_NO,ACC_TYPE,BALANCE,CUSTID_FK) VALUES('2345678901','Current',999.95,'12345');
INSERT INTO exchange_rate(RATE_ID,CURRENCY,RATE) VALUES('001','EURO',0.812);
INSERT INTO exchange_rate(RATE_ID,CURRENCY,RATE) VALUES('002','YEN',111.15);
INSERT INTO exchange_rate(RATE_ID,CURRENCY,RATE) VALUES('003','SLR',99.18);
Bank application comes with an Ant script to help users to build from source code. It has to be properly configured before using it to build from source code. build.properties file in the config directory has to modify according to your enviroment. Set the correct paths to the xdoclet.home and geronimo.home directories.
Also set the correct network information in the bank_client.properties file, which is going to reffered by remote application client.
|
This build script depends on XDoclet version 1.2.3 and Geronimo 1.1.1. Also make sure to use "/" as you directory separator in Windows environment when you are setting the above properties. |
Use a command prompt to navigate into the bank directory and just give ant command to build. It will create the Bank.ear and bankclient.jar under the bank/releases folder. Also note it will create a lib folder with a list of jar files reffered by the client application. Now, you are ready to deploy bank application in the Geronimo Application server.
Deploying sample application is pretty straight forward as we are going to use the Geronimo Console.
Core business application logic of the banking application is shared between two different clients. Testing of each client is given below.
To test the sample web application open a browser and type http://localhost:8080/Bank. It will forward you to the index page of banking application which has direct links to the view customer and exchange rate information. To view the list of account information of each customer, provide a relavant customer id in the DB. Exchange rate page will display list of all currencies in the exchange rate table.
Banking remote application client can be run by issuing the ant run-client in a command prompt. Use an existing account number in the database to view it's balance. Modification of account balance can be done by providing a numeric value to the balance field and using the Update button.
This article has shown you how to use the EJB features of the Apache Geronimo. It has provided step-by-step instructions to build an application, deploy and run it to elaborate those features.
Following are some of the highlights of the article.