Download Implementing Java Transactions Using Enterprise JavaBeans with

Project Report
On
“Implementing Java Transactions
Using Enterprise JavaBeans with JBoss 3.2”
Prepared for:
Dr Wei Dai
Written by:
Say Tian, Tan (3655743)
15 June, 2004
TABLE OF CONTENTS
1.
ABSTRACT
1
2.
INTRODUCTION
1
3.
PROJECT OBJECTIVE
1
4.
TRANSACTIONS
1
4.1.
Definition
1
4.2.
The Need for Transaction Mechanisms
2
4.3.
J2EE Transactions
2
4.4.
JBoss support of JTS
2
5.
SAMPLE IMPLEMENTATION
2
5.1.
System Architecture
2
5.2.
Description of Components
3
5.3.
Background Literature
3
5.4.
Installation of JBoss 3.2 (Brief Descriptions)
4
5.4.1.
Requirements
4
5.4.2.
Setting Up JBoss 3.2
4
5.4.3.
Running of JBoss 3.2
4
5.5.
Re-configuring of JBoss 3.2 and Hypersonic RDBMS
4
5.6.
Basic Administration of Hypersonic RDBMS
5
5.7.
The JNDI Client Test Program
5
5.8.
Declarative Transactions in J2EE
6
5.9.
Container-Managed Persistence (CMP) in J2EE
6
5.10.
SDLC Schedule for Sample Implementation
7
5.11.
Run-time Screen Shots
7
6.
SHORT DISCUSSIONS ON INDEX AND WEB SERVICES
7
6.1.
INDEX
7
6.1.1.
INDEX With Transactions
8
6.2.
Web Services
8
6.2.2.
Definition
8
6.2.3.
Web Services With Transactions
8
7.
CONCLUSION
8
8.
REFERENCE
9
9.
BIBLIOGRAPHY
9
10. APPENDIX A
10
11. APPENDIX A
12
12. APPENDIX C
13
1. Abstract
This paper describes a sample implementation of Java transactions using
Enterprise JavaBeans (EJBs) with JBoss 3.2.
2. Introduction
As part of the J2EE (Java 2 Enterprise Edition) initiative, SUN Microsystems
released the Java Transaction Service (JTS). JTS specifies the
implementation of a Java-based transaction manager supporting a high-level
Java Transaction API (JTA) (Juric et al., 2001). In essence, JTA is a clientside API (Application Programming interface) that allows clients to requests
transaction support from a JTS-compliant server.
Currently, there are various JTS-compliant servers on the market; JBoss
(from the JBoss Group) is one of the more popular open source JTScompliant J2EE servers. The current version 3.2 of JBoss is also an EJB 2.0
compliant container. EJB 2.0 defines two types of Java transactions – beanmanaged transaction and container-managed transaction. Monson-Haefel
(2001) recommended using container-managed transaction as it allows EJBs
to be more portable across J2EE containers. Container-managed transaction
is also known as “declarative transaction management” – the desired
transaction attributes (e.g., transaction scope, synchronization, etc.) are
specified in a XML-based configuration file known as EJB deployment
descriptor (Monson-Haefel, 2001).
This paper describes the installation, setup, and basic administration of JBoss
3.2. It also discusses a sample application that was developed to investigate
Java transactions using JBoss. The sample application comprises client-side
Java JNDI code, and server-side session and entity EJBs. The entity EJB was
designed to work with JBoss’ built-in Hypersonic RDBMS.
Lastly, this paper outlines the time-frame it took to achieve the
aforementioned tasks (inclusive of learning, coding, and debugging) – which
will be invaluable to future programming projects of a similar nature.
3. Project Objective
The main objective of the project is to provide sample working code utilizing
an actual live transaction server. The finished work aims to serve as a useful
reference platform to build transactions for other Java projects within the
Pheonix Group.
4. Transactions
4.1.
Definition
A transaction is a set of one or more operations that are treated as a single
unit – either they all occur or none of them do (Juric et al., 2001).
Transactions are often described as having ACID (Atomicity, Consistency,
Isolation, and Durability) properties. Henderson (2000) defined ACID as:
1
•
•
•
•
Atomicity – a transaction is atomic if it’s an all-or-nothing
proposition. When the transaction succeeds, all of its
changes are committed permanently; when it fails, they are
completely reversed.
Consistency – a transaction is consistent if it ensures that its
underlying data never appears in an interim or illogical state.
Isolation – a transaction is isolated if it is not affected by, nor
affects, other concurrent transactions on the same data.
Durability – a transaction is considered durable if it can
complete despite a system failure or, in the case of
uncommitted transactions, if it can completely reversed
following a system failure.
4.2.
The Need for Transaction Mechanisms
Transaction mechanisms permit the reliable operation of distributed
operations. They allow persistent operation states to be modified in a
controlled manner, so that applications can be made robust to all sorts of
system failures – including system crashes, network failures, and power
failures. Transactions are one of the tenets needed to build fault-tolerant,
highly-reliable, and highly-available distributed applications.
4.3.
J2EE Transactions
JTS specifies the implementation of a transaction manager (also known as a
TPM, Transaction Processing Monitor) supporting the JTA. A J2EE
transaction typically involves a Java application, a JTS-compliant TPM, and
one or more resources managed by their respective Resource Managers
(RMs). A resource is usually a relational database, but it can also be a
message queue. A TPM coordinates the activities of RMs to ensure the ACID
properties of transactions are honoured. If all participating RMs support a twophase commit protocol, transactions can even be made distributed across
different nodes on a network.
4.4.
JBoss support of JTS
JBoss 3.2 implements a default JTS-compliant TPM. However, the default
TPM does not currently support distributed 2-phase commits – only
transactions local to the same Java Virtual Machine (JVM). Hence, the
sample implementation does not involve distributed transactions.
5. Sample Implementation
5.1.
System Architecture
Figure 1 shows the system architecture using UML 1.1 deployment view.
2
:Unix/MS Windows Server
JBoss
3.2
:PC
JNDI
Client
<<server>>
Transaction
Server
RMI-IIOP,
port 1099
Hypersonic
RDBMS
Pheonix
GroupBean
Member
Bean
RDBMS
Figure 1. System Architecture (UML 1.1 Deployment View)
The sample implementation comprises the server processes (JBoss 3.2 and
Hypersonic RDBMS) and a Java JNDI client. The Java client communicates
with the JBoss transaction server via RMI-IIOP, using the default JNDI port
1099.
5.2.
Description of Components
At the server end, two sample EJBs were developed:
• PheonixGroupBean stateless session bean – PheonixGroupBean
provides an external JNDI-callable interface. In the J2EE model,
session beans represent business logic, and they store operation
states.
•
MemberBean entity bean – MemberBean’s deployment descriptor
has been mapped to a sample database of users provided with
Hypersonic RDBMS. The sample database schema contains basic
personnel data (e.g., name, address, etc.). In the J2EE model,
entity beans represent the abstraction of persistent data stores.
It is a common J2EE design pattern to use a session bean to wrap the
persistency services provided by entity beans (Monson-Haefel, 2001). Hence,
in the sample implementation, the PheonixGroupBean session bean exposes
a function to allow Java clients to query a sample user database.
PheonixGroupBean internally calls MemberBean to perform the actually
database queries.
At the client end, a sample Java JNDI client was developed. It makes use of
the JNDI client-stubs provided by JBoss 3.2 in order to find and invoke the
functions exposed by the PheonixGroupBean session bean.
5.3.
Background Literature
A list of Java APIs/specifications and tools used in the project is as follows:
• JNDI
• EJB
• JTA/JTS
• JDBC
• JMX
• XDoclet
The list provides a useful overview of the background literature needed to
effectively understand and debug the sample implementation.
3
5.4.
Installation of JBoss 3.2 (Brief Descriptions)
The following subsections give brief descriptions on how to install and get
JBoss running. More details can be found in (Schaefer, 2002).
5.4.1.
Requirements
JBoss 3.2 requires JDK 1.3 or later. Ensure that the environment
<JAVA_HOME> is defined.
5.4.2.
Setting Up JBoss 3.2
Download JBoss 3.2 from www.jboss.org (choose the one packaged with
Tomcat), and unpack the binaries into its own folder. After that, set up an
environmental variable <JBOSS_HOME> to point to the folder containing
JBoss binaries.
5.4.3.
Running of JBoss 3.2
By default, there are 3 configurations available for running JBoss; they are
“minimal”, “default”, and “all”. The sample implementation makes use of the
“default” configuration as it includes bootstrapping of Hypersonic RDBMS.
Start JBoss with the “run” script (inside <JBOSS_HOME>/bin) without any
command line parameters; this will start JBoss with the “default” configuration.
Once JBoss has stopped its startup logging to the console, and if no Java
exceptions were observed, it can be assumed that JBoss is successfully
started.
Point a browser to http://localhost:8080/jmx-console; the built-in JBoss
Tomcat web server, will return a “JMX Agent View” JSP page. (This pages is
referred in JBoss documentation as JMX-Console). This confirms that JBoss
is up and running.
5.5.
Re-configuring of JBoss 3.2 and Hypersonic RDBMS
The “default” configuration set ups JBoss’ web server to listen to port 8080.
This can be changed in the file <JBOSS_HOME>/server/default/deploy/
jbossweb-tomcat41.sar/META-INF/jboss-service.xml.
In order to be able to manage Hypersonic RDBMS, it needs to be set up in
“client-server” mode. In JBoss 3.2, the “default” configuration runs Hypersonic
in a “in-process” mode – this was done for security reasons. However, when
running “in-process” mode, Hypersonic cannot be configured at run-time, but
only through static XML configurations.
The sample implementation requires Hypersonic to be in the “client-server”
mode. Refer to (Schaefer, 2002, p. 21) for instructions, which entails changing
the default settings in <JBOSS_HOME>/server/default/deploy/hsqldb-ds.xml.
Once Hypersonic has been re-configured to run in “client-server”, refresh the
JMX-Console at http://localhost:8080/jmx-console. A “service=Hypersonic”
link should show up in the JMX-Console page. Clicking the
“service=Hypersonic” link will bring up the “JMX Mbean View” for Hypersonic.
4
5.6.
Basic Administration of Hypersonic RDBMS
Invoke the “startDatabaseManager” operation in the Hypersonic “JMX Mbean
View”. This action launches a separate Java Swing client application this is
used to manage Hypersonic (see Figure 2). This client connects to
Hypersonic through the default port 1701.
Figure 2. Java Swing client to manage Hypersonic
The sample implementation makes use of a sample personnel database
provided by Hypersonic. Instruct Hypersonic to create the sample personnel
database, by invoking the “Options” from the main menu bar, and choosing
“Insert test data”.
The schema for the sample personnel database table is as follows:
Field
ID
FIRSTNAME
LASTNAME
STREET
CITY
Type
Text
Text
Text
Text
Text
5.7.
The JNDI Client Test Program
The sample implementation JNDI client test program makes a run-time query
to Hypersonic by invoking a “getMemberFirstName(String ID)” function
exposed by the PheonixGroupBean via RMI-IIOP at port 1099. The program
returns the “FIRSTNAME” field of the record specified by the “ID” primary key.
Figure 3 shows the sequence diagram for the sample implementation
depicting the interacting components at run-time. The getMemberFirstName()
function exposed by PheonixGroupBean is designed to work in a containermanaged transaction. Subsequent exceptions encountered during the lifetime of the function call will result in a transaction exception returned to the
client. Hence, if the transaction completes without exceptions, no transaction
exception is returned to the client.
5
:JNDI
Client
:PheonixGroup
Bean
:Member
Bean
:Hypersonic
RDBMS
getMembeFirstName()
RMI-IIOP
getFirstName()
Java local procedure call
getFirstName()
Returns
record from
sample
personnel DB
Figure 3. Sequence Diagram for Sample Implementation
5.8.
Declarative Transactions in J2EE
Under the J2EE EJB framework, two types of transaction management are
provisioned: declarative (through declarative transaction attributes), and
explicit (through JTA) (Monson-Haefel, 2001).
The sample implementation chose to use declarative transaction in the
PheonixGroupBean session bean, which is specified as “Container” argument
to the <transaction-type> parameter in its ejb-jar.xml deployment descriptor.
5.9.
Container-Managed Persistence (CMP) in J2EE
In the EJB 2.0 specification, CMP fields are defined in an entity bean by
including abstract getter and setter methods for the field, and including a
corresponding <cmp-field> element in ejb-jar.xml EJB deployment descriptor.
In the sample implementation, the abstract methods correspond to the
following methods in MemberCMP.java (see Listing 1):
public abstract java.lang.String getId() ;
public abstract void setId( java.lang.String id ) ;
public abstract java.lang.String getFirstName() ;
public abstract void setFirstName( java.lang.String firstName ) ;
public abstract java.lang.String getLastName() ;
public abstract void setLastName( java.lang.String lastName ) ;
public abstract java.lang.String getStreet() ;
public abstract void setStreet( java.lang.String street ) ;
public abstract java.lang.String getCity() ;
public abstract void setCity( java.lang.String city ) ;
Listing 1. CMP Abstract Methods
As noted, an abstract getter and setter method is declared for each of the field
defined in the Hypersonic’s sample personnel database; i.e., ID,
FIRSTNAME, LASTNAME, STREET, and CITY. The associated <cmp-field>
declarations are shown in Appendix A-Listing 2. Additionally, the ID field is
also declared as the primary key using the <primkey-field> element (see
Monson-Haefel (2001) for more details).
6
In order for JBoss to perform the CMP Object-Relational (O-R) mappings to
the Hypersonic RDBMS, an additional deployment descriptor is needed –
jbosscmp-jdbc.xml. The necessary JBoss CMP O-R declarations are shown in
Appendix A, Listing 3:
•
•
•
<cmp-field> declarations perform the required mappings between
enitity beans methods and database record fields.
<create-table> is set to “false” as the database is pre-defined by
Hypersonic.
<remove-table> is set to “false” as the sample personnel database
is not to be deleted after entity bean operations.
Please refer to Fleury and Stark (2002) for more information on JBoss CMP
Object-Relational mapping.
5.10. SDLC Schedule for Sample Implementation
The rough-cut Software Development Life Cycle (SDLC) schedule for the
sample implementation is as follows (time-frames specified as week number
in semester 1/2004):
Phase
Tasks
Week No
Specification
5
• Set up a J2EE Transaction Server
• Develop a sample implementation using
J2EE declarative transactions
Design
6-7
• Readings in JBoss, JMX, JTA/JTS
Development I
8
• Readings in EJB
• Develop session bean
• Develop entity bean
• Write deployment descriptors
Debugging
9
• Troubleshooting JBoss configurations
Development II • Readings in XDoclet, JDBC, JNDI
10
• Use XDoclet to generate deployment
descriptors (DDs)
• Map entity bean to sample Hypersonic
personnel database
• Develop JNDI client test program
Debugging
11
• Troubleshooting Hypersonic, JNDI &
XDoclet-generated DDs
Deployment
12
• Final testing on sample implementation
Documentation • Writing doc on how to setup and run
13
sample implementation
5.11. Run-time Screen Shots
Appendix B lists some run-time screen shots for the sample implementation.
6. Short discussions on INDEX and Web Services
6.1.
INDEX
INDEX is Java-based Knowledge Management (KM) server.
7
6.1.1.
INDEX With Transactions
INDEX can be extended to make use of transactions by implementing
functions requiring transactional ACID properties as session beans (see
Appendix C for a possible deployment scenario utilizing this design). This
approach is akin to the sample implementation’s JNDI client test program.
Hence, in Appendix C INDEX acts as a JNDI client to the JBoss Transaction
Server.
6.2.
Web Services
6.2.2.
Definition
W3C (2002) defined a web service as follows:
A web service is a software system identified by a URI, whose
public interfaces and bindings are defined and described using
XML. Its definition can be discovered by other software systems.
These systems may then interact with the Web service in a
manner prescribed by its definition, using XML-based messages
conveyed by Internet protocols.
From a programming perspective, a web service is an application-layer XML
procedure call mechanism (Chappell & Jewell, 2002). Two common web
services protocols are SOAP and XML-RPC.
From a business perspective, a web service (when it is bound to HTTP) offers
a firewall friendly application protocol, which can be very useful in integrating
(Chappel & Jewell, 2002) business applications distributed across corporate
firewalls. Hence, instead of transporting the usual HTML documents over
HTTP, web services deliver XML documents over HTTP. These XML
documents carry data payloads, remote procedure calls, and web services
descriptions (described in WSDL – Web Services Description Language).
6.2.3.
Web Services With Transactions
When web services applications are implemented as J2EE servlets (e.g.,
using Apache Group’s AXIS or SOAP), they can also be extended to make
use of transactions. Functions desired to have transactional ACID properties
are re-implemented as session beans; the web service application then acts
as a JNDI client to a EJB Transaction Server like JBoss.
7. Conclusion
This project was completed successfully with the set up of a running JBoss
3.2 J2EE Transaction Server, and a sample application (comprising Java
JNDI client, session and entity EJBs) demonstrating how each components
can participate in a J2EE transaction.
The sample session bean was designed to expose transaction-based
functions using RMI-IIOP, and uses container-managed transactions
(because they are the simplest type to implement, and are recommended by
the J2EE specifications (Monson-Haefel, 2001)). As this is a Java-based
8
project, only other J2EE-based projects can make use of the architecture
proposed in the sample implementation.
A total of 9 man-weeks were taken to complete the sample implementation –
from specification-phase to documentation-phase, within a fully loaded 4subject semester (60 credits). This rough-cut schedule can serve as a useful
gauge for future projects of a similar nature.
Lastly, this paper also discusses possible extensions of J2EE transactions to
INDEX and Java-based web services applications.
8. Reference
Chappell, D., and Jewell, T. (2002), Java Web Services, O’Reilly.
Fleury, M. and Stark. S. (2002), JBoss Administration and Development,
Sams Publishing.
Henderson, K. (2000), The Guru’s Guide to Transac-SQL, Addison Wesley.
Juric, M.B., Basha, S.J., Leander, R., and Nagappan, R. (2001), Professional
J2EE EAI, Wrox Press.
Monson-Haefel, R. (2001), Enterprise JavaBeans, O’Reilly, 3rd Edition.
Schaefer, A. (2002), JBoss 3.0 Quick Start Guide, The JBoss Group, viewed
on 8 June 2004,
<http://www.jboss.org/modules/html/docs/jbossj2ee.pdf>
W3C (2002), Web Services Architecture Document, viewed on 6 June 2004,
<http://www.w3.org/TR/ws-arch>.
9. Bibliography
Kreger, H, Harold, W., and Williamson, L. (2002), Java and JMX: Building
Manageable Systems, Addison Wesley.
Sullins, B. G., and M. B, Whipple (2003), EJB CookBook, Manning
Publications.
Walnes, J., Abrahamian, A., Cannon-Brookes, M., and Lightbody, P. (2004),
Java Open Source Programming with XDoclet, Junit, WebWork, Hibernate,
Wiley Publishing.
9
10.
Appendix A
<!-- Entity Beans -->
<entity >
<description><![CDATA[EJB that correspond to a Member record]]></description>
<display-name>Member</display-name>
<ejb-name>Member</ejb-name>
<local-home>vu.pheonix.interfaces.MemberLocalHome</local-home>
<local>vu.pheonix.interfaces.MemberLocal</local>
<ejb-class>vu.pheonix.ejb.MemberCMP</ejb-class>
<persistence-type>Container</persistence-type>
<prim-key-class>java.lang.String</prim-key-class>
<reentrant>False</reentrant>
<cmp-version>2.x</cmp-version>
<abstract-schema-name>Member</abstract-schema-name>
<cmp-field >
<description><![CDATA[]]></description>
<field-name>id</field-name>
</cmp-field>
<cmp-field >
<description><![CDATA[]]></description>
<field-name>firstName</field-name>
</cmp-field>
<cmp-field >
<description><![CDATA[]]></description>
<field-name>lastName</field-name>
</cmp-field>
<cmp-field >
<description><![CDATA[]]></description>
<field-name>street</field-name>
</cmp-field>
<cmp-field >
<description><![CDATA[]]></description>
<field-name>city</field-name>
</cmp-field>
<primkey-field>id</primkey-field>
</entity>
Source: ejb-jar.xml
Listing 2. CMP Declarations in ejb-jar.xml
10
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE jbosscmp-jdbc PUBLIC "-//JBoss//DTD JBOSSCMP-JDBC 3.0//EN"
"http://www.jboss.org/j2ee/dtd/jbosscmp-jdbc_3_0.dtd">
<jbosscmp-jdbc>
<defaults>
</defaults>
<enterprise-beans>
<!-To add beans that you have deployment descriptor info for, add
a file to your XDoclet merge directory called jbosscmp-jdbc-beans.xml
that contains the <entity></entity> markup for those beans.
-->
<entity>
<ejb-name>Member</ejb-name>
<create-table>false</create-table>
<remove-table>false</remove-table>
<table-name>Customer</table-name>
<cmp-field>
<field-name>id</field-name>
<column-name>Id</column-name>
</cmp-field>
<cmp-field>
<field-name>firstName</field-name>
<column-name>FirstName</column-name>
</cmp-field>
<cmp-field>
<field-name>lastName</field-name>
<column-name>LastName</column-name>
</cmp-field>
<cmp-field>
<field-name>street</field-name>
<column-name>Street</column-name>
</cmp-field>
<cmp-field>
<field-name>city</field-name>
<column-name>City</column-name>
</cmp-field>
</entity>
</enterprise-beans>
</jbosscmp-jdbc>
Source: jbosscmp-jdbc.xml
Listing 3. JBoss CMP Object-Relational Mappings
11
11.
Appendix A
Figure 4. JMX Console View
Figure 5. Hypersonic RDBMS With Sample Personnel Database
Figure 6. Client Test Program With Query Result For ID = 2
12
12.
Appendix C
INDEX running as a
single-threaded
server with SOAP
interfaces.
:Unix/MS Windows Server
<<subsystem>>
<<subsystem>>
INDEX
GDI
RDBMS
SOAP 1.0 (HTTP)
Port 8080
TS
module
RMI-IIOP
Port 1099
Session
Bean
EDI
:SOAP Client (.NET)
MS
WSE 1.0
Transaction Server (TS)
ICS
KD
PRB
DDT
Entity
Bean
Apache
SOAP
JDBC
RDBMS
SOAP 1.0 (HTTP)
Port 8080
:SOAP Client (Java)
AXIS
SOAP
<<subsystem>>
UDDI Service
HTTP Port 8080
Deployment Diagram (in UML 1.1)
13
UDDI
registry
with
WSDL
docs
<<subsystem>>
:XML/DDT
Converter
EJB Container
(using Jboss 3.2).
This subsystem ‘s
role is to provide
transaction service
to INDEX.