REDHAT APPLICATION SERVER User Manual
Red Hat Application Server
JOnAS User Guide
Red Hat Application Server: JOnAS User Guide
Copyright © 1999-2004 by ObjectWeb Consortium
ObjectWeb Consortium
INRIA - ZIRST, 655 avenue de l’Europe
Montbonnot
38334 SAINT-ISMIER Cedex
FRANCE
Additional information copyright © Red Hat, Inc., 2003-2004.
1801 Varsity Drive
Raleigh NC 27606-2072 USA
Phone: +1 919 754 3700
Phone: 888 733 4281
Fax: +1 919 754 3701
PO Box 13588
Research Triangle Park NC 27709 USA
Manual identifier:
• PDF: rhel-jonas-EN-3-PDF-RHI (2003-09-24T01:08)
• HTML: rhel-jonas-EN-3-HTML-RHI (2003-09-24T01:08)
Red Hat is a registered trademarkand the Red Hat Shadow Man logo, RPM, and theRPM logo are trademarks of Red Hat, Inc.
JOnAS is copyright © ObjectWeb Consortium.
The JOnAS logo is copyright© Bruno Bellamy.
Tomcat is copyright © The Apache Software Foundation (ASF).
IntelTM, PentiumTM, ItaniumTM, and CeleronTMare registered trademarks of Intel Corporation.
EJBTM, J2EETM, JCATM, JCEETM, JDBCTM, JDOTM, JMSTM, RMITM, and SunTM, and Sun Microsystems® are registered
trademarks of Sun Microsystems,Inc.
Linux is a registered trademark of Linus Torvalds.
All other trademarks and copyrights referredto are the property of their respectiveowners.
The GPG fingerprint of the security@redhat.comkey is:
CA 20 86 86 2B D6 9D FC 65 F6 EC C4 21 91 80 CD DB 42 A6 0E
Table of Contents
I. Introductory JOnAS Documentation ..........................................................................................vii
1. Java Open Application Server (JOnAS): a J2EE Platform ...................................................1
1.1. Introduction to Red Hat Application Server .......................................................... 1
1.2. JOnAS Features ..................................................................................................... 2
1.3. JOnAS Architecture............................................................................................... 4
1.4. JOnAS Development and Deployment Environment ..........................................10
1.5. Clustering and Performance................................................................................. 11
1.6. Future Development............................................................................................. 13
2. Getting Started with JOnAS................................................................................................ 15
2.1. Running the First EJB Application ......................................................................15
2.2. More Complex Examples .................................................................................... 16
3. JOnAS Configuration..........................................................................................................21
3.1. JOnAS Configuration Rules................................................................................. 21
3.2. Configuring the JOnAS Environment ..................................................................22
3.3. Configuring the Communication Protocol and JNDI........................................... 23
3.4. Configuring Logging System (monolog) ............................................................. 24
3.5. Configuring JOnAS Services ...............................................................................26
3.6. Configuring the DB Service (hsql) ......................................................................44
3.7. Configuring JMS Resource Adapters...................................................................44
4. Configuring JDBC DataSources .........................................................................................51
4.1. Configuring DataSources .....................................................................................51
4.2. CMP2.0/JORM ....................................................................................................52
4.3. ConnectionManager Configuration......................................................................53
4.4. Tracing SQL Requests Through P6Spy ...............................................................53
5. JOnAS Class Loader Hierarchy .......................................................................................... 55
5.1. Understanding the Class Loader Hierarchy .........................................................55
5.2. Commons Class Loader .......................................................................................55
5.3. Application Class Loader..................................................................................... 55
5.4. Tools Class Loader............................................................................................... 55
5.5. Tomcat Class Loader............................................................................................ 56
5.6. JOnAS Class Loaders ..........................................................................................56
5.7. JOnAS Class Loader Hierarchy ........................................................................... 56
6. JOnAS Command Reference .............................................................................................. 59
6.1. jonas ..................................................................................................................... 59
6.2. jclient.................................................................................................................... 62
6.3. newbean ...............................................................................................................62
6.4. registry .................................................................................................................65
6.5. GenIC...................................................................................................................65
6.6. JmsServer............................................................................................................. 67
6.7. RAConfig .............................................................................................................68
II. Enterprise Beans Programmer’s Guide.....................................................................................71
7. Developing Session Beans ..................................................................................................73
7.1. Introduction to Session Beans..............................................................................73
7.2. The Home Interface ............................................................................................. 73
7.3. The Component Interface ....................................................................................74
7.4. The Enterprise Bean Class ................................................................................... 74
7.5. Tuning the Stateless-Session Bean Pool .............................................................. 77
8. Developing Entity Beans .................................................................................................... 79
8.1. Introduction to Entity Beans ................................................................................79
8.2. The Home Interface ............................................................................................. 80
8.3. The Component Interface ....................................................................................81
8.4. The Primary Key Class ........................................................................................82
8.5. The Enterprise Bean Class ................................................................................... 84
8.6. Writing Database Access Operations (Bean-Managed Persistence) ................... 89
8.7. Configuring Database Access for Container-Managed Persistence..................... 91
8.8. Using CMP2.0 Persistence...................................................................................94
8.9. Standard CMP2.0 Aspects ...................................................................................94
8.10. JOnAS Database Mappers ................................................................................. 95
8.11. JOnAS Database Mapping (Specific Deployment Descriptor)..........................97
8.12. Tuning a Container for Entity Bean Optimizations ......................................... 115
9. Developing Message-Driven Beans..................................................................................119
9.1. Description of a Message-Driven Bean .............................................................119
9.2. Developing a Message-Driven Bean.................................................................. 119
9.3. Administration Aspects......................................................................................121
9.4. Running a Message-Driven Bean ...................................................................... 122
9.5. Transactional Aspects ........................................................................................ 124
9.6. Message-Driven Beans Example .......................................................................124
9.7. Tuning the Message-Driven Bean Pool .............................................................126
10. Defining the Deployment Descriptor .............................................................................. 129
10.1. Principles.......................................................................................................... 129
10.2. Example of Session Descriptors ...................................................................... 130
10.3. Example of Container-managed Persistence Entity Descriptors (CMP 1.1) ... 131
10.4. Tips...................................................................................................................133
11. Transactional Behavior of EJB Applications ..................................................................135
11.1. Declarative Transaction Management.............................................................. 135
11.2. Bean-managed Transactions ............................................................................ 136
11.3. Distributed Transaction Management .............................................................. 137
12. Enterprise Bean Environment .........................................................................................141
12.1. Introduction......................................................................................................141
12.2. Environment Entries ........................................................................................141
12.3. Resource References ........................................................................................ 141
12.4. Resource Environment References ..................................................................142
12.5. EJB References ................................................................................................ 142
13. Security Management ..................................................................................................... 145
13.1. Introduction......................................................................................................145
13.2. Declarative Security Management ...................................................................145
13.3. Programmatic Security Management...............................................................146
14. EJB Packaging ................................................................................................................149
14.1. Enterprise Bean Principles ............................................................................... 149
15. Application Deployment and Installation Guide ............................................................151
15.1. Deployment and Installation Process Principles..............................................151
15.2. Example of Deploying and Installing an EJB Using an EJB-JAR File ........... 151
15.3. Deploying and Installing a Web Application...................................................153
15.4. Deploying and Installing a J2EE Application.................................................. 153
III. Web Application Programmer’s Guide .................................................................................. 155
16. Developing Web Components......................................................................................... 157
16.1. Introduction to Web Component Development ............................................... 157
16.2. The JSP Pages.................................................................................................. 157
16.3. The Servlets ..................................................................................................... 158
16.4. Accessing an EJB from a Servlet or JSP Page.................................................160
17. Defining the Web Deployment Descriptor......................................................................163
17.1. Principles.......................................................................................................... 163
17.2. Examples of Web Deployment Descriptors..................................................... 164
17.3. Tips...................................................................................................................166
18. WAR Packaging..............................................................................................................167
18.1. Principles.......................................................................................................... 167
IV. J2EE Client Application Programmer’s Guide .....................................................................169
19. Launching J2EE Client Applications.............................................................................. 171
19.1. Launching Clients ............................................................................................171
19.2. Configuring the Client Container.....................................................................171
19.3. Examples.......................................................................................................... 172
20. Defining the Client Deployment Descriptor ...................................................................173
20.1. Principles.......................................................................................................... 173
20.2. Examples of Client Deployment Descriptors .................................................. 173
20.3. Tips...................................................................................................................175
21. Client Packaging ............................................................................................................. 177
21.1. Principles.......................................................................................................... 177
V. J2EE Application Assembler’s Guide ...................................................................................... 179
22. Defining the EAR Deployment Descriptor .....................................................................181
22.1. Principles.......................................................................................................... 181
22.2. Simple Example of Application Deployment Descriptor ................................ 181
22.3. Advanced Example .......................................................................................... 182
22.4. Tips...................................................................................................................182
23. EAR Packaging...............................................................................................................183
23.1. Principles.......................................................................................................... 183
VI. Advanced Topics ....................................................................................................................... 185
24. JOnAS Services .............................................................................................................. 187
24.1. Introducing a New Service............................................................................... 187
24.2. Advanced Understanding.................................................................................189
25. JOnAS and the Connector Architecture.......................................................................... 193
25.1. Introducing the Connector Architecture ..........................................................193
25.2. Defining the JOnAS Connector Deployment Descriptor.................................193
26. JMS User’s Guide ...........................................................................................................197
26.1. JMS is Pre-installed and Configured................................................................ 197
26.2. Writing JMS Operations Within an Application Component.......................... 197
26.3. Some Programming Rules and Restrictions When Using JMS within EJB ....201
26.4. JMS Administration......................................................................................... 204
26.5. Running an EJB Performing JMS Operations ................................................. 205
26.6. A JMS EJB Example .......................................................................................207
27. Ant EJB Tasks: Using EJB-JAR ..................................................................................... 211
27.1. ejbjar Parameters.............................................................................................. 211
28. Login Modules in a Java Client ...................................................................................... 215
28.1. Configuring an Environment to Use Login Modules with Java Clients ..........215
28.2. Example of a Client ......................................................................................... 215
29. Web Services with JOnAS.............................................................................................. 217
29.1. Web Services.................................................................................................... 217
29.2. Exposing a J2EE Component as a Web Service .............................................. 219
29.3. The Web Services Client..................................................................................222
29.4. WsGen.............................................................................................................. 224
29.5. Limitations .......................................................................................................225
VII. How-to Documents..................................................................................................................227
30. JOnAS Versions Migration Guide ..................................................................................229
30.1. JOnAS 3.3.x to Red Hat Application Server 1.0 ............................................. 229
31. How to Install a jUDDI Server on JOnAS ...................................................................... 231
31.1. UDDI Server ....................................................................................................231
31.2. What is jUDDI? ............................................................................................... 231
31.3. Where Can I Find the Latest Version? .............................................................231
31.4. Installation Steps ..............................................................................................231
31.5. Links ................................................................................................................234
32. Clustering with JOnAS ...................................................................................................235
32.1. Cluster Architecture .........................................................................................235
32.2. Load Balancing at the Web Level with mod_jk............................................... 236
32.3. Session Replication at the Web Level..............................................................239
32.4. Load Balancing at the EJB Level..................................................................... 241
32.5. Preview of a Coming Version .......................................................................... 243
32.6. Used Symbols ..................................................................................................243
32.7. References........................................................................................................244
33. Distributed Message Beans in JOnAS 4.1 ......................................................................245
33.1. Scenario and General Architecture .................................................................. 245
33.2. Common Configuration ................................................................................... 245
33.3. Specific Configuration .....................................................................................246
33.4. The Beans.........................................................................................................247
34. How to use Axis in JOnAS .............................................................................................249
34.1. Unique Axis Webapp ....................................................................................... 249
34.2. Embedded Axis Webapp..................................................................................249
34.3. Axis Tests.........................................................................................................250
34.4. Axis Tools........................................................................................................250
35. Using WebSphere MQ JMS............................................................................................253
35.1. Architectural Rules .......................................................................................... 253
35.2. Setting the JOnAS Environment ......................................................................253
35.3. Configuring WebSphere MQ ........................................................................... 254
35.4. Starting the Application ................................................................................... 256
35.5. Limitations .......................................................................................................256
36. Web Service Interoperability between JOnAS and BEA WebLogic ..............................257
36.1. Libraries ........................................................................................................... 257
36.2. Accessing a JOnAS Web Service from a WebLogic Server’s EJB..................257
36.3. Accessing a WebLogic Web Service from a JOnAS EJB................................ 259
37. RMI-IIOP Interoperability between JOnAS and BEA WebLogic..................................263
37.1. Accessing a JOnAS EJB from a WebLogic Server’s EJB using RMI-IIOP .... 263
37.2. Access a WebLogic Server’s EJB from a JOnAS EJB using RMI-IIOP ......... 263
38. Interoperability between JOnAS and CORBA ............................................................... 265
38.1. Accessing an EJB Deployed on a JOnAS Server by a CORBA Client ........... 265
38.2. Accessing a CORBA Service by an EJB Deployed on JOnAS Server............ 267
39. How to Migrate the New World Cruises Application to JOnAS ....................................269
39.1. JOnAS Configuration.......................................................................................269
39.2. SUN Web Service ............................................................................................ 270
39.3. JOnAS Web Service.........................................................................................272
40. Configuring JDBC Resource Adapters ...........................................................................275
40.1. Configuring Resource Adapters .......................................................................275
40.2. Using CMP2.0/JORM......................................................................................277
40.3. ConnectionManager Configuration..................................................................278
40.4. Tracing SQL Requests through P6Spy ............................................................278
40.5. Migration from dbm Service to the JDBC RA ................................................ 280
41. Configuring Resource Adapters ......................................................................................281
41.1. Principles.......................................................................................................... 281
41.2. Description and Examples ...............................................................................281
Index.................................................................................................................................................283
I. Introductory JOnAS Documentation
The chapters in this section contain introductory information for all JOnAS users.
Table of Contents
1. Java Open Application Server (JOnAS): a J2EE Platform ........................................................ 1
2. Getting Started with JOnAS ........................................................................................................ 15
3. JOnAS Configuration ...................................................................................................................21
4. Configuring JDBC DataSources.................................................................................................. 51
5. JOnAS Class Loader Hierarchy ..................................................................................................55
6. JOnAS Command Reference ....................................................................................................... 59
Chapter 1.
Java Open Application Server (JOnAS): a J2EE
Platform
This chapter provides an overview of Red Hat Application Server and the JOnAS J2EE platform.
1.1. Introduction to Red Hat Application Server
Red Hat Application Server is a middleware platform—it is layered between the operating system and
applications. This middleware links systems and resources that are scattered across the network.
Red Hat Application Server comprises a runtime system and associated development libraries for creating and deploying Java-based Web applications with dynamic content (for example, dynamic Web
sites, portal servers, and content management systems). These applications might retrieve, display, or
update data in database management systems such as PostgreSQL or Oracle, or they might communicate with standard application software, such as ERP systems, or with proprietary legacy applications.
Red Hat Application Server is a robust platform for the development and deployment of Web applications written in Java and built with JSP, servlet, and Enterprise JavaBeans (EJB) technologies. It has
been built to standard protocols and APIs that have emerged from Java, J2EE, Web Services, SOAP
(Single Object Access Protocol), XML (Extensible Markup Language), and CORBA (Common Object Request Broker Architecture) standards groups. Developers build their applications using these
standards, while Red Hat’s middleware infrastructure ensures compatibility with the guidelines set
forth by the J2EE specifications.
1.1.1. J2EE
The Sun J2EE specification (http://java.sun.com/j2ee/), together with related specifications such as
EJB (http://java.sun.com/products/ejb/) and JMS (http://java.sun.com/products/jms/), define an architecture and interfaces for developing and deploying distributed Internet Java server applications based
on a multi-tier architecture. This specification facilitates and standardizes the development, deployment, and assembling of application components that will be deployable on J2EE platforms. These
applications are typically web-based, transactional, database-oriented, multi-user, secure, scalable,
and portable.
More precisely, the Sun J2EE specification describes two kinds of information:
• The first is the runtime environment, called a J2EE server, that provides the execution environment
and the required system services, such as the transaction service, the persistence service, the Java
Message Service (JMS), and the security service.
• The second is programmer and user information that explains how an application component should
be developed, deployed, and used.
Not only will an application component be independent of the platform and operating system (because
it is written in Java), it will also be independent of the J2EE platform.
A typical J2EE application is composed of:
• Presentation components, also called web components, that define the application
Web interface. These are servlets (http://java.sun.com/products/servlet/) and JSPs
(http://java.sun.com/products/jsp/).
• Enterprise components, the Enterprise JavaBeans (EJB), that define the application business logic
and application data.
2 Chapter 1. Java Open Application Server (JOnAS): a J2EE Platform
The J2EE server provides containers for hosting web and enterprise components. The container provides the component with life-cycle management and interfaces the components with the services
provided by the J2EE server:
• The web container handles servlet and JSP components.
• The EJB container handles the Enterprise JavaBeans components.
• A J2EE server can also provide an environment for deploying Java clients (accessing EJBs); this is
called a client container.
Figure 1-1. J2EE Architecture
1.2. JOnAS Features
JOnAS is a pure Java, open-source, application server that conforms to the J2EE specification. Its high
degree of modularity enables it to be used as:
• A J2EE server, for deploying and running EAR applications (that is, applications composed of both
web and EJB components)
• An EJB container, for deploying and running EJB components (for example, for applications with-
out web interfaces or when using JSP/servlet engines that are not integrated as a JOnAS J2EE
container)
• A Web container, for deploying and running JSPs and servlets (for example, for applications without
EJB components).
1.2.1. System Requirements
JOnAS is available for JDK 1.4. It has been used on many operating systems (Linux, AIX, Windows,
Solaris, HP-UX, etc.) and with different databases (Oracle, PostgreSQL, MySQL, SQL server, Access,
DB2, Versant, Informix, Interbase, etc.).
Chapter 1. Java Open Application Server (JOnAS): a J2EE Platform 3
1.2.2. Java Standard Conformance
JOnAS is an implementation of J2EE 1.4. It currently conforms to EJB 2.1. Its current integration of
Tomcat as a Web container ensures conformity to Servlet 2.4 and JSP 2.0 specifications. The JOnAS
server relies on or implements the following Java APIs: JCA 1.5, JDBC 3.0, JTA 1.0.1, JMS 1.1, JMX
1.2, JNDI 1.2.1, JAAS 1.0, JACC 1.0, and JavaMail 1.3.
1.2.3. Key Features
In addition to the implementation of all J2EE-related standards, JOnAS provides the following important advanced features:
• Management: JOnAS server management uses JMX and provides a servlet-based management con-
sole.
• Services: JOnAS’s service-based architecture provides for high modularity and configurability of
the server. It allows the developer to apply a component-model approach at the middleware level,
and makes the integration of new modules easy (for example, for open source contributors). It also
provides a way to start only the services needed by a particular application, thus saving valuable
system resources. You can manage JOnAS services through JMX.
• Scalability: JOnAS integrates several optimization mechanisms for increasing server scalability.
This includes a pool of stateless session beans, a pool of message-driven beans, a pool of threads, a
cache of entity beans, activation/passivation of entity beans, a pool of connections (for JDBC and
JMS), and storage access optimizations (shared flag, isModified).
• Clustering: JOnAS clustering solutions, both at the WEB and EJB levels, provide load balancing,
high availability, and failover support.
• Distribution: JOnAS works with several distributed processing environments, due to the
integration of ObjectWeb’s CAROL (Common Architecture for RMI ObjectWeb Layer) project
(http://www.objectweb.org/carol/index.html), which enables simultaneous support of several
communication protocols:
• CMI (Cluster Method Invocation), the “Cluster aware” distribution protocol of JOnAS
• RMI (Java Remote Method Invocation) using the Sun proprietary protocol JRMP (Java Remote
Method Protocol)
• RMI on IIOP (Java Remote Method Invocation over Internet Inter-Orb Protocol).
• Support of "Web Services": Due to the integration of AXIS, JOnAS allows J2EE components to
access "Web Services" (that is, to be "Web Services" clients), and allows J2EE components to be
deployed as "Web Services" endpoints. Standard Web Services clients and endpoints deployment,
as specified in J2EE 1.4, is supported.
• Support of JDO: By integrating the ObjectWeb implementation of JDO (Java Data Objects)
(http://java.sun.com/products/jdo), SPEEDO (http://speedo.objectweb.org), and its associated
J2EE CA Resource Adapter, JOnAS provides the capability of using JDO within J2EE
components.
Three critical J2EE aspects were implemented early on in the JOnAS server:
• J2EE CA: JOnAS applications can easily access Enterprise Information Systems (EIS). By sup-
porting the Java Connector Architecture, JOnAS allows deployment of any J2EE CA-compliant
Resource Adapter (connector), which makes the corresponding EIS available from the J2EE application components. Moreover, resource adapters will become the standard way to plug JDBC
drivers (and JMS implementation, with J2EE 1.4) into J2EE platforms. A JDBC Resource Adapter
4 Chapter 1. Java Open Application Server (JOnAS): a J2EE Platform
available with JOnAS provides JDBC PreparedStatement pooling and can be used in place of the
JOnAS DBM service. A JORAM JMS Resource adapter is also available.
• JMS (Java Messaging Service): JMS implementations can be easily plugged into JOnAS. They run
as a JOnAS service either in the same JVM (Java Virtual Machine) or in a separate JVM, and JOnAS
provides administration facilities that hide the JMS proprietary administration APIs. Currently,
three JMS implementations can be used: the JORAM open-source JMS implementation from ObjectWeb (http://joram.objectweb.org/), SwiftMQ (http://www.swiftmq.com/), and Websphere MQ.
J2EE CA Resource Adapters are also available, providing a more standard way to plug JORAM or
SwiftMQ into JOnAS.
• JTA (Java Transaction API): The JOnAS platform supports distributed transactions that involve
multiple components and transactional resources. The JTA transactions support is provided by a
Transaction Monitor that has been developed on an implementation of the CORBA Object Transaction Service (OTS).
1.3. JOnAS Architecture
JOnAS is designed with services in mind. A service typically provides system resources to containers.
Most of the components of the JOnAS application server are pre-defined JOnAS services. However,
it is possible and easy for an advanced JOnAS user to define a service and to integrate it into JOnAS.
Because J2EE applications do not necessarily need all services, it is possible to define, at JOnAS
server configuration time, the set of services that are to be launched at server start.
The JOnAS architecture is illustrated in the following figure, showing WEB and EJB containers relying on JOnAS services (all services are present in this figure). Two thin clients are also shown in this
figure, one of which is the JOnAS administration console (called JonasAdmin).
Figure 1-2. J2EE Architecture
Chapter 1. Java Open Application Server (JOnAS): a J2EE Platform 5
1.3.1. Communication and Naming Service
The Communication and Naming Service (also called Registry) is used for launching the RMI registry, the CosNaming, and/or the CMI registry, depending on the JOnAS configuration (that is, the
CAROL configuration, which specifies which communication protocols are to be used). There are
different registry launching modes, such as using the same JVM or not, and launching automatically
if not already running. CAROL enables multi-protocol runtime support and deployment, which avoids
having to redeploy components when changing the communication protocol.
The Communication and Naming Service provides the JNDI (Java Naming and Directory Interface)
API to application components and to other services in order to bind and look up remote objects
(for example, EJB Homes) and resource references (JDBC DataSource, Mail, and JMS connection
factories, etc.).
1.3.2. EJB Container Service
The EJB Container Service is in charge of loading the EJB components and their containers. EJB
containers consist of a set of Java classes that implement the EJB specification and a set of interposition classes that interface the EJB components with the services provided by the JOnAS application
server. Interposition classes are specific to each EJB component and are generated by the deployment
tool called GenIC.
JOnAS configuration provides a means for specifying that this service be launched during JOnAS
initialization.
Enterprise JavaBeans (EJB) are software components that implement the business logic of an application (while the servlets and JSPs implement the presentation). There are three types of Enterprise
JavaBeans:
• Session beans are objects associated with only one client; they are short-lived (one method call or a
client session) and represent the current state of the client session. They can be transaction-aware,
stateful, or stateless.
• Entity beans are objects that represent data in a database. They can be shared by several clients
and are identified by means of a primary key. The EJB container is responsible for managing the
persistence of such objects. The persistence management of such an object is entirely transparent
to the client that will use it, and may or may not be transparent to the bean provider who develops
it. This depends on if it is one of the following:
• For an Enterprise Bean with Container-Managed Persistence, the bean provider does not de-
velop any data access code; persistence management is delegated to the container. The mapping
between the bean and the persistent storage is provided in the deployment descriptor, in an application server-specific way.
• For an Enterprise Bean with Bean-Managed Persistence, the bean provider writes the database
access operations in the methods of the Enterprise Bean that are specified for data creation, load,
store, retrieval, and remove operations.
• Message-driven Beans are objects that can be considered as message listeners. They execute
on receipt of a JMS Java Message Service message; they are transaction-aware and
stateless. They implement some type of asynchronous EJB method invocation. (Refer to
http://java.sun.com/products/jms/.)
JOnAS configuration provides a means for specifying a set of EJB-JAR files to be loaded. EJB-JAR
files can also be deployed at server runtime using the JOnAS administration tools.
For implementing Container-Managed Persistence of EJB 2.0 and EJB 2.1 (CMP2), JOnAS relies
on the ObjectWeb JORM (Java Object Repository Mapping http://jorm.objectweb.org/) and MEDOR
(Middleware Enabling Distributed Object Requests http://medor.objectweb.org/) frameworks. JORM
6 Chapter 1. Java Open Application Server (JOnAS): a J2EE Platform
supports complex mappings of EJBs to database tables, as well as several types of persistency support
(relational databases, object databases, LDAP repositories, etc.).
JOnAS also implements the Timer Service features as specified in EJB 2.1.
1.3.3. WEB Container Service
The WEB Container Service is in charge of running a servlet/JSP engine in the JVM of the JOnAS
server and of loading web applications (WAR files) within this engine. Currently, this service can be
configured to use Tomcat (see http://jakarta.apache.org/tomcat/). Servlet/JSP engines are integrated
within JOnAS as web containers, that is, containers that provide the web components with access to
the system resources (of the application server) and to EJB components, in a J2EE-compliant way.
JOnAS configuration provides a means for specifying that the WEB Container Service be launched
during JOnAS initialization. Additionally, JOnAS configuration provides a means for specifying a set
of WAR files to be loaded. Such WAR files can also be deployed at server runtime using the JOnAS
administration tools. User management for Tomcat and JOnAS has been unified. The class-loading
delegation policy (priority to the Webapp classloader or to the parent classloader) can be configured.
Servlet (http://java.sun.com/products/servlet/) and JSP (http://java.sun.com/products/jsp/) are technologies for developing dynamic web pages. The servlet approach allows the development of Java
classes (HTTP servlets) that generate HTML pages and that can be invoked through HTTP requests.
Typically, servlets access the information system using Java APIs (such as JDBC or the APIs of EJB
components) in order to build the content of the HTML page they will generate in response to the
HTTP request. The JSP technology is a complement of the servlet technology. A JSP is an HTML
page containing Java code within particular XML-like tags; this Java code is in charge of generating
the dynamic content of the HTML page.
Servlets and JSPs are considered as J2EE application components, responsible for the application
presentation logic. Such application components can access resources provided by the J2EE server
(such as JDBC datasources, JMS connection factories, EJBs, mail factories). For EJB components,
the actual assignment of these resources is performed at component deployment time and is specified
in the deployment descriptor of each component, because the component code uses logical resource
names.
1.3.4. EAR Service
The EAR Service is used for deploying complete J2EE applications, that is, applications packaged in
EAR files, which themselves contain EJB-JAR files and/or WAR files. This service handles the EAR
files and delegates the deployment of the WAR files to the WEB Container service and the EJB-JAR
files to the EJB Container service. It handles creating the appropriate class loaders, as defined in the
J2EE specification, in order for the J2EE application to execute properly.
For deploying J2EE applications, JOnAS must be configured to launch the EAR service and to specify
the set of EAR files to be loaded. EAR files can also be deployed at server runtime using the JOnAS
administration tools.
1.3.5. Transaction Service
The Transaction Service encapsulates a Java Transaction Monitor called JOTM, a project from ObjectWeb (http://jotm.objectweb.org). It is a mandatory service that handles distributed transactions. It
provides transaction management for EJB components as defined in their deployment descriptors. It
handles two-phase commit protocol against any number of Resource Managers (XA Resources). For
J2EE, a transactional resource can be a JDBC connection, a JMS session, or a J2EE CA Resource
Adapter connection. The transactional context is implicitly propagated with the distributed requests.
The Transaction Monitor can be distributed across one or more JOnAS servers; thus a transaction
Chapter 1. Java Open Application Server (JOnAS): a J2EE Platform 7
may involve several components located on different JOnAS servers. This service implements the
JTA 1.0.1 specification, thus allowing transactions from application components or from application
clients to be explicitly started and terminated. Starting transactions from application components is
allowed only from Web components, session beans, or message-driven beans. Restricting transactions
to only these two types of beans is called Bean-managed transaction demarcation.
One of the main advantages of the EJB support for transactions is its declarative aspect, which means
that transaction control is no longer hard-coded in the server application, but is configured at deployment time. This is known as container-managed transaction demarcation. With container-managed
transaction demarcation, the transactional behavior of an Enterprise Bean is defined at configuration
time and is part of the deployment descriptor of the bean. The EJB container is responsible for providing the transaction demarcation for the enterprise beans according to the value of transactional
attributes associated with EJB methods. These attributes can be one of the following:
• NotSupported: If the method is called within a transaction, this transaction is suspended during
the time of the method execution.
• Required: If the method is called within a transaction, the method is executed in the scope of this
transaction; otherwise, a new transaction is started for the execution of the method and committed
before the method result is sent to the caller.
• RequiresNew: The method is always executed within the scope of a new transaction. The new
transaction is started for the execution of the method and committed before the method result is
sent to the caller. If the method is called within a transaction, this transaction is suspended before
the new one is started, and resumed when the new transaction has completed.
• Mandatory: The method should always be called within the scope of a transaction; otherwise, the
container throws the TransactionRequired exception.
• Supports: The method is invoked within the caller transaction scope. If the caller does not have
an associated transaction, the method is invoked without a transaction scope.
• Never: With this attribute the client is required to call the method without a transaction context,
otherwise the container throws the java.rmi.RemoteException exception.
The ObjectWeb project JOTM (Java Open Transaction Manager), is actually based on the transaction
service of earlier JOnAS versions. It will be enhanced to provide advanced transaction features, such
as nested transactions and “Web Services” transactions (an implementation of DBTP is available).
1.3.6. Database Service
This service is responsible for handling Datasource objects. A Datasource is a standard JDBC administrative object for handling connections to a database. The database service creates and loads such
datasources on the JOnAS server. DataSources to be created and deployed can be specified at JOnAS
configuration time, or they can be created and deployed at server runtime using the JOnAS administration tools. The database service is also responsible for connection pooling; it manages a pool of
database connections to be used by the application components, thus avoiding many physical connection creations, which are time-consuming operations. The database service can now be replaced
by the JDBC Resource Adapter, to be deployed by the J2EE CA resource service, which additionally
provides JDBC PreparedStatement pooling.
1.3.7. Security Service
The Security Service implements the authorization mechanisms for accessing J2EE components, as
specified in the J2EE specification.
8 Chapter 1. Java Open Application Server (JOnAS): a J2EE Platform
• EJB security is based on the concept of roles. The methods can be accessed by a given set of roles.
In order to access the methods, you must be in at least one role of this set.
The mapping between roles and methods (permissions) is done in the deployment descriptor using
the security-role and method-permission elements. Programmatic security management
is also possible using two methods of the EJBContext interface in order to enforce or complement security check in the bean code: getCallerPrincipal() and isCallerInRole (String
roleName). The role names used in the EJB code (in the isCallerInRole method) are, in fact,
references to actual security roles, which makes the EJB code independent of the security configuration described in the deployment descriptor. The programmer makes these role references available to the bean deployer or application assembler by way of the security-role-ref elements
included in the session or entity elements of the deployment descriptor.
• Web security uses the same mechanisms; however, permissions are defined for URL patterns instead
of EJB methods. Therefore, the security configuration is described in the Web deployment descriptor. Programmatically, the caller role is accessible within a web component via the isUserInRole
(String roleName) method.
In JOnAS, the mapping between roles and user identification is done in the user identification repository. When using Tomcat for user authentication, this user identification repository can be stored
either in files, in a JNDI repository (such as LDAP), or in a relational database. This is achieved
through a JOnAS implementation of the Realm for each Web container and through the JAAS (Java
Authentication and Authorization Service) login modules for Java clients.
Realms use authentication resources provided by JOnAS, which enable you to rely on files, LDAP,
or JDBC. These realms are in charge of propagating the security context to the EJB container during EJB calls. JAAS login modules are provided for user authentication of Web Container and Java
clients. Certificate-based authentication is also available, with the CRLLoginModule login module for
certificate revocation.
JOnAS also implements the Java Authorization Contract for Containers (JACC 1.0) specification,
allowing you to manage authorizations as Java security permissions and to plug in any security policy
provider.
1.3.8. Messaging Service
Asynchronous EJB-method invocation is possible on Message-driven Bean components. A
Message-driven Bean is an EJB component that can be considered to be a JMS (Java Message
Service) MessageListener; that is, a service that processes JMS messages asynchronously (see
http://java.sun.com/products/jms). It is associated with a JMS destination. Its onMessage method is
activated on the reception of messages sent by a client application to this destination. It is also
possible for any EJB component to use the JMS API within the scope of transactions managed by the
application server.
For supporting Message-driven Beans and JMS operations coded within application components, the
JOnAS application server relies on a JMS implementation. JOnAS makes use of a third-party JMS implementation; currently the JORAM open-source software is integrated and delivered with JOnAS, the
SwiftMQ product can also be used, and other JMS provider implementations can easily be integrated
(see http://joram.objectweb.org/ and http://www.swiftmq.com/). JORAM provides several noteworthy
features, particularly:
• Reliability (with a persistent mode)
• Distribution (transparently to the JMS client, it can run as several servers, thus allowing load bal-
ancing)
• The choice of TCP or SOAP as the communication protocol for messages.
Chapter 1. Java Open Application Server (JOnAS): a J2EE Platform 9
The JMS service is in charge of launching (or establishing a connection to) the integrated JMS server,
which may or may not run in the same JVM as JOnAS. It also provides connection pooling and thread
pooling (for Message-driven Beans). Through this service, JOnAS provides facilities to create JMSadministered objects such as the connection factories and the destinations, either at server-launching
time or at runtime using the JOnAS administration tools.
Note that the same function of JMS implementation integration can now be achieved through a Resource Adapter, to be deployed by the J2EE CA Resource Service. Such a Resource Adapter, J2EE
CA 1.5, is provided for JORAM.
1.3.9. J2EE CA Resource Service
The J2EE Connector Architecture (J2EE CA) allows the connection of different Enterprise Information Systems (EIS) to a J2EE application server. It is based on the Resource Adapter (RA); this is
an architecture component—comparable to a software driver—that connects the EIS, the application
server, and the enterprise application (J2EE components). The RA is generally provided by an EIS
vendor and provides a Java interface (the Common Client Interface or CCI) to the J2EE components
for accessing the EIS (this can also be a specific Java interface). The RA also provides standard interfaces for plugging into the application server, allowing them to collaborate to keep all system-level
mechanisms (transactions, security, and connection management) transparent from the application
components.
Figure 1-3. JCA Architecture
The application performs "business logic" operations on the EIS data using the RA client API (CCI),
while transactions, connections (including pooling), and security on the EIS are managed by the application server through the RA (system contract).
The JOnAS Resource service is in charge of deploying J2EE CA-compliant Resource Adapters (connectors), packaged as RAR files, on the JOnAS server. RAR files can also be included in EAR files,
in which case the connector will be loaded by the application classloader. Once Resource Adapters
are deployed, a connection factory instance is available in the JNDI namespace to be looked up by
application components.
A J2EE CA 1.0 Resource Adapter for JDBC is available with JOnAS. It can replace the current JOnAS
database service for plugging JDBC drivers and managing connection pools. It also provides JDBC
10 Chapter 1. Java Open Application Server (JOnAS): a J2EE Platform
PreparedStatement pooling.
A J2EE CA 1.5 Resource Adapter for JMS is available with JOnAS. It can replace the current JOnAS
Messaging service for plugging into JORAM.
1.3.10. Management Service
You require the Management service in order to administer a JOnAS server from the JOnAS administration console. Each server running this service is visible from the administration console.
The Management service is based on JMX (Java Management Extension). Standard MBeans defined
within the JOnAS application server expose the management methods of the instrumented JOnAS
server objects, such as services, containers, and the server itself. These MBeans implement the management model as specified in the J2EE Management Specification. The Management service runs a
JMX server (currently the MX4J server, but the Sun RI server is also available). The MBeans of the
JOnAS server are registered within this JMX server.
The JOnAS administration console is a Struts-based Web application (servlet/JSP) that accesses the
JMX server to present the managed features within the administration console. Thus, through a simple
Web browser, it is possible to manage one or several JOnAS application servers. The administration
console provides a means for configuring all JOnAS services (and making the configuration persistent) and for deploying any type of application (EJB-JAR, WAR, EAR) and any type of resource
(DataSources, JMS and Mail connection factories, J2EE CA connectors), all without the need to
stop or restart the server. The administration console displays information for monitoring the servers
and applications. This information includes used memory, used threads, number of EJB instances, and
which component currently uses which resources. When Tomcat is used as Web Container, the Tomcat
Management is integrated within the JOnAS console. A Management EJB (MEJB) is also delivered,
providing access to the management features, as specified in the J2EE Management Specification.
1.3.11. Mail Service
A J2EE application component can send e-mail messages using JavaMail (see
http://java.sun.com/products/javamail/). The Mail service of the JOnAS application server provides
the resources necessary for the J2EE application components. The Mail service creates mail factories
and registers these resources in the JNDI namespace in the same way that the database service
or the JMS service creates Datasources or ConnectionFactories and registers these objects
in the JNDI namespace. There are two types of mail factories: javax.mail.Session and
javax.mail.internet.MimePartDataSource.
1.3.12. WebServices Service
This service is implemented on top of AXIS and is used for the deployment of Web Services.
1.4. JOnAS Development and Deployment Environment
The JOnAS development and deployment environment comprises the JOnAS configuration and deployment facilities and the JOnAS development environment.
1.4.1. JOnAS Configuration and Deployment Facilities
Once JOnAS has been installed in a directory referenced by the JONAS_ROOT environment variable,
it is possible to configure servers and to deploy applications into several execution environments.
This is achieved using the JONAS_BASE environment variable. JONAS_ROOT and JONAS_BASE can
Chapter 1. Java Open Application Server (JOnAS): a J2EE Platform 11
be compared to the CATALINA_HOME and CATALINA_BASE variables of Tomcat. While JONAS_ROOT
is dedicated to JOnAS installation, JONAS_BASE is used to specify a particular JOnAS instance configuration. JONAS_BASE designates a directory containing a specific JOnAS configuration, and it identifies subdirectories containing the EJB-JAR, WAR, EAR, and RAR files that can be loaded in this
application environment. There is an ANT target in the JOnAS build.xml file for creating a new
JONAS_BASE directory structure. Thus, from one JOnAS installation, it is possible to switch from one
application environment to another by just changing the value of the JONAS_BASE variable.
There are two ways to configure a JOnAS application server and load applications: either by using the
administration console or by editing the configuration files. There are also “autoload” directories for
each type of application and resource (EJB-JAR, WAR, EAR, RAR) that allow the JOnAS server to
automatically load the applications located in these directories when starting.
JOnAS provides several facilities for deployment:
• For writing the deployment descriptors, plugins for Integrated Development Environments (IDE)
provide some generation and editing features (Eclipse and JBuilder plugins are available). The
NewBean JOnAS built-in tool generates template deployment descriptors. The Xdoclet tool also
generates deployment descriptors for JOnAS. The Apollon ObjectWeb project generates Graphical User Interfaces for editing any XML file; it has been used to generate a deployment descriptor editor GUI (see http://debian-sf.objectweb.org/projects/apollon). A deployment tool developed by the ObjectWeb JOnAS community, earsetup (http://sourceforge.net/projects/earsetup),
will also be available for working with the JSR88-compliant (J2EE 1.4) deployment APIs provided
by the ObjectWeb Ishmael project (see http://sourceforge.net/projects/earsetup/ and http://debiansf.objectweb.org/projects/ishmael/ respectively.
• Some basic tools for the deployment itself are the JOnAS GenIC command line tool and the cor-
responding ANT EJB-JAR task. The IDE plugins integrate the use of these tools for deployment
operations. The main feature of the Ishmael project will be the deployment of applications on the
JOnAS platform.
1.4.2. JOnAS Development Environments
There are many plugins and tools that facilitate the development of J2EE applications to be deployed
on JOnAS. IDE plugins for JBuilder Kelly (http://forge.objectweb.org/projects/kelly/), JOPE
(http://forge.objectweb.org/projects/jope/), and Lomboz (http://lomboz.objectweb.org) provide the
means to develop, deploy, and debug J2EE components on JOnAS. The Xdoclet code generation
engine (http://xdoclet.sourceforge.net/) can generate EJB interfaces and deployment descriptors
(standard and JOnAS specific ones), taking as input the EJB implementation class containing
specific JavaDoc tags. The JOnAS NewBean tool generates templates of interfaces, implementation
class, and deployment descriptors for any kind of EJB. Many development tools may work with
JOnAS; refer to the JOnAS tools page at http://www.objectweb.org/jonas/tools.html for more details.
In addition, JOnAS is delivered with complete J2EE examples, providing a build.xml ANT file with
all the necessary targets for compiling, deploying, and installing J2EE applications.
1.5. Clustering and Performance
Clustering for an application server generally makes use of three features: Load Balancing (LB), High
Availability (HA), and Failover. Such mechanisms can be provided at the Web-container level by
dispatching requests to several Servlet/JSP engine instances, at the EJB-container level by dispatching
EJB requests to several EJB container instances, and at the database level by using several databases.
A replicated JNDI naming is also necessary.
JOnAS provides Load Balancing, High Availability, and Failover at the WEB container level using
the Apache Tomcat mod_jk plugin and an HTTP-in-memory session-replication mechanism based
12 Chapter 1. Java Open Application Server (JOnAS): a J2EE Platform
on JGroups. The plugin dispatches HTTP requests from the Apache web server to Tomcat instances
running as JOnAS web containers. Server fluctuations are automatically taken into account. This plugin supports round-robin and weighted round-robin load-balancing algorithms, with a sticky session
option.
Load balancing and HA are provided at the EJB container level in JOnAS. Operations invoked on
EJB Home interfaces (EJB creation and retrieval) are dispatched on the nodes of the cluster. The
mechanism is based on a clustered-aware replicated JNDI registry using a Clustered remote Method
Invocation protocol (CMI). The stubs contain the knowledge of the cluster and implement the loadbalancing policy, which may be round-robin and weighted round-robin. In the near future, a loadbalancing mechanism based on the nodes load will be available. Failover at the EJB level will be
provided by implementing a stateful Session Bean state replication mechanism.
The JOnAS clustering architecture is illustrated in the following figure.
Figure 1-4. Clustered Architecture
Apache is used as the front-end HTTP server; Tomcat is used as the JOnAS web container. The JOnAS
servers share the same database. The mod_jk plug-in provides load balancing/high availability at the
Servlet/JSP level. Failover is provided through the in-memory, session-replication mechanism. Load
balancing/high availability are provided at the EJB level through the CMI protocol associated with the
replicated, clustered-aware JNDI registry. Tomcat may or may not run in the same JVM as the EJB
container. JOnAS provides some documentation for configuring such an architecture.
The use of the C-JDBC ObjectWeb project offers load balancing and high availability at the database
level (see http://www.objectweb.org/c-jdbc/index.html). The use of C-JDBC is transparent to the application (in our case, to JOnAS), because it is viewed as a standard JDBC driver. However, this
“driver” implements the cluster mechanisms (reads are load-balanced and writes are broadcasted).
The database is distributed and replicated among several nodes, and C-JDBC load balances the queries
between these nodes. An evaluation of C-JDBC using the TPC-W benchmark on a 6-node cluster has
shown performance scaling linearly up to six nodes.
Chapter 1. Java Open Application Server (JOnAS): a J2EE Platform 13
In addition to clustering solutions, JOnAS provides many intrinsic mechanisms to ensure high scalable
and efficiency:
• A pool of stateless Session Bean instances
• A pool of Entity Bean instances, configurable for each Entity Bean within its deployment descriptor
• Activation/passivation of entity beans (passivation can be controlled through the management con-
sole)
• Pools of connections, for JDBC, JMS, J2EE CA connectors
• A pool of threads for message-driven beans
• Session Bean timeout can be specified at deployment
• A “shared” flag in the specific deployment descriptor of an Entity Bean that indicates whether the
persistent representation of this Entity Bean is shared by several servers/applications, or whether it
is dedicated to the JOnAS server where it is loaded. In the latter case, the optimization performed
by JOnAS consists of not reloading the corresponding data between transactions.
• The usual EJB 1.1 “isModified” (or “Dirty”) mechanism is available, for avoiding storage of un-
modified data.
Some benchmarks and JOnAS Use cases have already proven that JOnAS is highly scalable. Refer to the Rubis http://www.cs.rice.edu/CS/Systems/DynaServer/perf_scalability_ejb.pdf results or the
OpenUSS Use case (http://openuss.sourceforge.net/openuss/). Rubis is a benchmark for e-commerce
J2EE applications, which now belongs to the ObjectWeb JMOB (Java Middleware Open Benchmarking) project (http://www.objectweb.org/jmob/index.html). OpenUSS is an operational university portal that has approximately 20,000 users.
1.6. Future Development
As an open source implementation of a J2EE server, JOnAS is constantly evolving to satisfy user
requirements and to follow the related standards. These are the current JOnAS plans:
• J2EE 1.4 compliance, JOnAS being currently in the process of passing the Sun J2EE Compatibility
Test Suite.
• JOnAS administration will be enhanced by completing the concept of management domain, and by
introducing cluster management facilities.
• Addressing performance issues by developing workbenches and by producing tuning guides.
• Support of “Web Services” and tools for developing those services.
• Deployment APIs as specified in JSR88 (J2EE 1.4) will be supported as a result of the Ishmael
project.
14 Chapter 1. Java Open Application Server (JOnAS): a J2EE Platform
Chapter 2.
Getting Started with JOnAS
This tutorial guides you through running a first example EJB. Guidance is also provided for running
a more complex example in which an EJB has access to a database.
You can find additional information about JOnAS configuration in Chapter 3 JOnAS Configuration.
2.1. Running the First EJB Application
2.1.1. JOnAS Examples
There are several examples in the JOnAS distribution under $JONAS_ROOT/examples/src. You
should run the example located in the $JONAS_ROOT/examples/src/sb/ directory first.
In this example, a Java client accesses a stateful Session Bean and calls the buy method of the bean
several times inside the scope of transactions.
2.1.2. Building the sb Example
The easiest way to compile this example is to go to the sb directory $JONAS_ROOT/examples/src/sb/
and use the compile.sh shell script.
2.1.3. Running the sb Example
This a distributed example in which two processes are involved:
• The JOnAS server, in which beans will be loaded
• The Java client that creates instances of beans and calls business methods on it.
To run this example:
1. Run the JOnAS server:
service jonas start
The following message is displayed on the standard output:
The JOnAS Server ’jonas’ version-number is ready
2. Make beans available to clients by loading the jar containing the sb example:
jonas admin -a sb.jar
The following message is displayed on the standard output:
message-header: Op available
3. Run the Java client in another terminal command-line window:
jclient sb.ClientOp
4. If the following output displays, the first EJB application with JOnAS has run successfully:
Create a bean
Start a first transaction
First request on the new bean
Second request on the bean
Commit the transaction
Start a second transaction
16 Chapter 2. Getting Started with JOnAS
Rollback the transaction
Request outside any transaction
ClientOp OK. Exiting.
5. Before ending this session, be sure to stop the JOnAS server:
service jonas stop
These instructions are also located in the README file in the working directory.
2.1.4. Understanding Why This Works
• This example demonstrates that the CLASSPATH is correctly set because, when the JOnAS server is
launched, the jonas script calls the JOnAS bootstrap class.
The jclient script is being used to run the client. Note that the bean classes were found in
$JONAS_ROOT/examples/classes. If this had not been the case, it would have been necessary
to call the jclient script with the -cp "$JONAS_ROOT/ejbjars/sb.jar" option.
• The client has succeeded in contacting the JOnAS server because the client has a distributed refer-
ence that was previously registered in the naming service. To do this, server and client use JNDI
(the Java Naming and Directory Interface). The carol.properties file (which contains the JNDI
configuration) is located in the $JONAS_ROOT/conf directory.
This carol.properties has the JNDI properties set to the default values.
With these default values, the registry runs on localhost on the default port (1099 for
RMI/JRMP).
By default, the registry is launched in the same JVM as the JOnAS Server.
2.2. More Complex Examples
2.2.1. Other JOnAS Examples
The following examples are located under $JONAS_ROOT/examples/src:
• The eb example ($JONAS_ROOT/examples/src/eb/) uses Entity beans. (See Section 2.2.2 An Ex-
ample With Database Access.)
The two beans share the same interface (Account): one uses bean-managed persistence (explicit
persistence), the other uses container-managed persistence (implicit persistence).
This is a good example for understanding what must be done, or not done, for persistence, based
on the chosen mode of persistence. It provides both a CMP 1.1 and a CMP 2.0 implementation.
• The lb example ($JONAS_ROOT/examples/src/lb/) uses Entity beans with local interfaces.
A Session Bean, Manager, locally manages an Entity Bean, Manac, which represents an account.
This is a good example for understanding what must be done for a local client collocated with an
Entity Bean providing local interfaces.
• The jms directory ($JONAS_ROOT/examples/src/jms/) contains a stateful Session Bean with
methods performing JMS operations and a pure JMS client message receptor.
A complete description of this example is in Section 26.6 A JMS EJB Example.
• The mailsb directory ($JONAS_ROOT/examples/src/mailsb/) contains a SessionMailer and
MimePartDSMailer Stateful Session beans with methods providing a way for building and
sending mail.
Chapter 2. Getting Started with JOnAS 17
• The mdb/samplemdb directory ($JONAS_ROOT/examples/src/mdb/samplemdb/) contains a Mes-
sage Driven Bean that listens to a topic and an MdbClient, which is a pure JMS client, that sends
10 messages on the corresponding topic.
This is a very good example for understanding how to write and use message-driven beans.
• The mdb/sampleappli directory ($JONAS_ROOT/examples/src/mdb/sampleappli/) contains the
following:
• Two Message-Driven beans, one listening to a topic (StockHandlerBean) the other listening
to a queue (OrderBean)
• An Entity Bean with container-managed persistence (StockBean) and a stateless Session Bean
for creating the table used in the database.
SampleAppliClient sends several messages on the topic. Upon receipt of a message, the StockHan-
dlerBean updates the database via the StockBean and sends a message to the queue inside a global
transaction. All of the EJBs are involved in transactions that may commit or rollback.
• Alarm (http://jonas.objectweb.org/current/examples/alarm/) is an application that watches alarm
messages generated asynchronously through JMS. It utilizes the different techniques used in
JOnAS:
• An Entity Bean for AlarmRecord, persistent in a database
• A Session Bean to allow clients to visualize Alarms received
• A Message Driven Bean to catch Alarms
• JMS to use a topic where Alarms are sent and received
• Tomcat (for JSP pages and servlets)
• Security.
• Earsample (http://jonas.objectweb.org/current/examples/earsample/) contains a complete J2EE ap-
plication. This sample is a simple stateful Session Bean that has synchronization and security.
This bean is accessed from a servlet in which the user is authenticated and JOnAS controls access to
the methods of the bean. The servlet performs a variety of lookups (resource-ref, resource-env-ref,
env-entry, ejb-ref, and ejb-local-ref) in the java:comp/env environment to illustrate how the uniform
naming works in the servlets.
• The CMP2 directory (http://jonas.objectweb.org/current/examples/cmp2/) contains an example il-
lustrating most of the concepts of CMP 2.0.
• jaasclient (http://jonas.objectweb.org/current/examples/jaasclient/) contains an example of a
JAAS login module that illustrates the different methods for authentication.
There are different callback handlers that demonstrate how to enter identification at a command line
prompt, either with a dialog or without a prompt (where the client uses its own login/password).
Each directory contains a README that explains how to build and run each example.
2.2.2. An Example With Database Access
The eb example contains two Entity beans that manage Account objects.
The two beans share the same interface (Account); one with bean-managed persistence (BMP, explicit
persistence), the other with container-managed persistence (CMP, implicit persistence). The default
CMP implementation is CMP 1.1. A CMP 2.0 implementation is also provided and its use is described
in the README.
Before running this example, perform the steps in:
18 Chapter 2. Getting Started with JOnAS
• Section 2.2.2.1 Configuring Database Access
• Section 2.2.2.2 Creating the Table in the Database
• Section 2.2.2.3 Configuring the Classpath
2.2.2.1. Configuring Database Access
In order to be able to access your relational database, JOnAS will create and use a DataSource object
that must be configured according to the database that will be used.
These DataSource objects are configured via properties files. $JONAS_ROOT/conf contains templates
for configuring DataSource objects for databases such as Oracle and PostgreSQL:
• $JONAS_BASE/conf/Oracle1.properties
• $JONAS_BASE/conf/PostgreSQL1.properties
Depending on your database, you can customize one of these files with values appropriate for your
installation. After doing so, you must update the property jonas.service.dbm.datasources in
the jonas.properties file.
For example, for the Oracle1.properties file.
jonas.service.dbm.datasources Oracle1
Section 3.5.7 Configuring the Database Service provides more details about DataSource objects and
their configuration.
2.2.2.2. Creating the Table in the Database
The $JONAS_ROOT/examples/src/eb directory contains an SQL script for Oracle: Account.sql
($JONAS_ROOT/examples/src/eb/Account.sql). If your Oracle server is running and you are using
CMP 1.1, you can create the table used by the example. If you are using CMP 2.0, do not create the
table.
2.2.2.2.1. Example: Creating the Table in Oracle
sqlplus user/passwd
SQL
@Account.sql
SQLquit
2.2.2.3. Configuring the Classpath
The JDBC driver classes must be accessible from the classpath. To enable that, update the
config_env file (http://jonas.objectweb.org/current/bin/unix/config_env).
In this file, set one of the following variables: IDB_CLASSES, ORACLE_CLASSES, or POSTGRE_CLASSES with the appropriate value for your database installation.
Chapter 2. Getting Started with JOnAS 19
2.2.2.4. Building the eb Example
The simplest way to compile this example is to go to the $JONAS_ROOT/examples/src/eb
directory ($JONAS_ROOT/examples/src/eb/) and use the compile.sh shell script
($JONAS_ROOT/examples/src/eb/compile.sh).
If the Ant 1.5 build tool is installed on your machine, you can build the JOnAS examples by using
the build.xml files located in the $JONAS_ROOT/examples or $JONAS_ROOT/examples/src
directories. To do this, use the build.sh shell script.
2.2.2.5. Running the eb Example
Here, again, two processes are involved:
• The JOnAS server in which beans will be loaded
• The Java client that creates instances of beans and calls business methods on it.
To run this example:
1. Run the JOnAS server to make beans available to clients:
service jonas start
jonas admin -a eb.jar
The following messages are displayed on the standard output:
The JOnAS Server ’jonas’ version-number is ready and running on rmi
message-header : AccountExpl available
message-header : AccountImpl available
2. Run the Java clients in another terminal emulator window:
jclient eb.ClientAccount AccountImplHome
jclient eb.ClientAccount AccountExplHome
The example eb has run successfully if the following output displays:
Getting a UserTransaction object from JNDI
Connecting to the AccountHome
Getting the list of existing accounts in database
101 Antoine de St Exupery 200.0
102 alexandre dumas fils 400.0
103 conan doyle 500.0
104 alfred de musset 100.0
105 phileas lebegue 350.0
106 alphonse de lamartine 650.0
Creating a new Account in database
Finding an Account by its number in database
Starting a first transaction, that will be committed
Starting a second transaction, that will be rolled back
Getting the new list of accounts in database
20 Chapter 2. Getting Started with JOnAS
101 Antoine de St Exupery 200.0
102 alexandre dumas fils 300.0
103 conan doyle 500.0
104 alfred de musset 100.0
105 phileas lebegue 350.0
106 alphonse de lamartine 650.0
109 John Smith 100.0
Removing Account previously created in database
ClientAccount terminated
3. Before ending this session, be sure to stop the JOnAS server:
service jonas stop
Chapter 3.
JOnAS Configuration
This chapter describes how to configure JOnAS.
3.1. JOnAS Configuration Rules
As described in Chapter 2 Getting Started with JOnAS, JOnAS is pre-configured and ready to use
directly with RMI/JRMP for remote access, if visibility to classes other than those contained in the
JOnAS distribution in $JONAS_ROOT/lib is not required.
To use RMI/IIOP for remote access or to work with additional Java classes (for example, JDBC driver
classes), you must perform additional configuration tasks, such as setting a specific port number for
the registry.
The JOnAS distribution contains a number of configuration files in $JONAS_ROOT/conf directory.
These files can be edited to change the default configuration. However, it is recommended that the
configuration files needed by a specific application running on JOnAS be placed in a separate location.
This is done by using an additional environment variable called JONAS_BASE.
3.1.1. JONAS_BASE Environment Variable
Warning
JOnAS configuration files are read from the $JONAS_BASE/conf directory. If JONAS_BASE is not defined, it is automatically initialized to $JONAS_ROOT.
There are two ways to use the JONAS_BASE environment variable:
1. Perform the following actions:
a. Create a new directory and initialize JONAS_BASE with the path to this directory.
b. Create the following sub-directories in $JONAS_BASE:
• conf
• ejbjars
• apps
• webapps
• rars
• logs
c. Copy the configuration files located in $JONAS_ROOT/conf into $JONAS_BASE/conf.
Then, modify the configuration files according to the requirements of your application, as
explained in the following sections.
2. Perform the following actions:
• Initialize $JONAS_BASE with a path.
• Change to the $JONAS_ROOT directory and enter:
ant create_jonasbase
22 Chapter 3. JOnAS Configuration
This copies all the required files and creates all the directories.
Note
The build.xml files provided with the JOnAS examples support JONAS_BASE. If this environment
variable is defined prior to building and installing the examples, the generated archives are installed
under the appropriate sub-directory of $JONAS_BASE. For example, the EJB-JAR files corresponding
to the sample examples of $JONAS_ROOT/examples/s rc/ are installed in $JONAS_BASE/ejbjars.
3.2. Configuring the JOnAS Environment
3.2.1. The JOnAS Configuration File
The JOnAS server is configured via a configuration file named jonas.properties. It contains a list
of key/value pairs presented in the Java properties file format.
The default configuration is provided in $JONAS_ROOT/conf/jonas.properties (refer to
$JONAS_BASE/conf/jonas.properties). This file, which holds all possible properties with
their default values, is mandatory. The JOnAS server looks for this file at start time in the
$JONAS_BASE/conf directory ($JONAS_ROOT/conf if $JONAS_BASE is not defined).
Most of the properties are related to the JOnAS services that can be launched in the JOnAS server.
These properties are described in detail in Section 3.5 Configuring JOnAS Services.
The property jonas.orb.port is not related to any service. It identifies the port number on which
the remote objects receive calls. Its default value is 0, which means that an anonymous port is chosen.
When the JOnAS server is behind a firewall, this property can be set to a specific port number.
When several JOnAS servers must run simultaneously, it is beneficial to set a different name for each
JOnAS server in order to administer these servers.
Also note that it is possible to define configuration properties on the command line:
java -Dproperty=value
Use the jonas check command to review the JOnAS configuration state. (Refer to Section 6.1
jonas.)
3.2.2. Configuration Scripts
The JOnAS distribution contains the $JONAS_ROOT/bin/unix/setenv and
$JONAS_ROOT/bin/unix/config_env configuration scripts.
These configuration scripts set useful environment variables for JAVA setup ($JAVA and $JAVAC).
They add $JONAS_BASE/conf to the $CLASSPATH if $JONAS_BASE is set, otherwise they add
$JONAS_ROOT/conf. These scripts are called by almost all other scripts (jclient, jonas,
newbean, registry, GenIC).
Therefore, when requiring the visibility of specific .jar files, the best practice is to update the
config_env file. For example, to see some of the JDBC driver classes, one or more of the variables
IDB_CLASSES, ORACLE_CLASSES, and POSTGRE_CLASSES must be updated.
Another way to place an additional .jar in the classpath of your JOnAS server is to insert it at the
end of the config_env file:
Loading...