Redhat APPLICATION SERVER JONAS User Manual

Red Hat Application Server
JOnAS Tutorial
Red Hat Application Server: JOnAS Tutorial
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: rhaps-jonas-EN-3-PDF-RHI (2003-09-24T01:08)
HTML: rhaps-jonas-EN-3-HTML-RHI (2003-09-24T01:08)
JOnAS is copyright © ObjectWeb Consortium. The JOnAS logo is copyright© Bruno Bellamy. Tomcat is copyright © The Apache Software Foundation (ASF). Red Hat is a registered trademarkand the Red Hat Shadow Man logo, RPM, and theRPM logo are trademarks of Red Hat, Inc. 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
1. Introduction.....................................................................................................................................1
1.1. About this Guide ................................................................................................................1
1.2. Enterprise JavaBeans ......................................................................................................... 1
1.2.1. What Does What? ...............................................................................................1
1.2.2. JOnAS Features .................................................................................................. 3
1.2.3. Software Requirements....................................................................................... 4
2. Quick Start ...................................................................................................................................... 5
2.1. Setting Up the Red Hat Application Server Environment ................................................. 5
2.2. Running Your First EJB Application. ................................................................................ 5
2.2.1. Building the Examples ........................................................................................ 5
2.2.2. Quick Start to the SB Example ........................................................................... 6
3. Configuring Your Environment. .................................................................................................. 11
3.1. Setting Up Your Java Environment..................................................................................11
3.1.1. Configuring Ant ................................................................................................11
3.1.2. Configuring Your JOnAS Environment ............................................................11
4. Getting Started With JOnAS .......................................................................................................13
4.1. Overview of the Tools...................................................................................................... 13
4.1.1. Starting and Stopping JOnAS ...........................................................................13
4.1.2. JOnAS Configuration Files ...............................................................................13
4.1.3. Database Access................................................................................................20
4.1.4. Loading Beans Using jonas.properties .............................................................21
4.1.5. JOnAS Administration......................................................................................21
4.1.6. Loading Beans Using jonas admin ................................................................... 21
4.1.7. Unloading Beans............................................................................................... 22
5. Session Beans................................................................................................................................. 23
5.1. Finding the Example Application ....................................................................................23
5.2. Building the Example ...................................................................................................... 23
5.3. Running the SB Example................................................................................................. 23
5.4. Understanding Session Beans ..........................................................................................24
5.5. Deployment Descriptor.................................................................................................... 24
6. Entity Beans...................................................................................................................................27
6.1. Finding the Example Application ....................................................................................27
6.1.1. Understanding Entity Beans .............................................................................27
6.1.2. Building the Example ....................................................................................... 27
6.1.3. Configuring Database Access ........................................................................... 28
6.1.4. Running the EB Example.................................................................................. 29
7. Message-Driven Beans.................................................................................................................. 31
7.1. Building the Examples ..................................................................................................... 31
7.2. Running the Examples ..................................................................................................... 31
7.3. Understanding Message-Driven Beans ............................................................................32
8. Accessing Beans From a Servlet ..................................................................................................35
8.1. Quick Introduction to Servlets......................................................................................... 35
8.2. Retrieving a Home Interface and Creating a Bean .......................................................... 35
8.3. Initiating a Transaction From a Servlet............................................................................ 36
9. Accessing Beans From a JSP .......................................................................................................39
9.1. Accessing a Bean From a JSP.......................................................................................... 39
10. The Alarm Application............................................................................................................... 41
10.1. Application Architecture Overview...............................................................................41
10.2. Finding the Alarm Application ......................................................................................42
10.3. Setting Up the Application............................................................................................. 42
10.4. Configuring Database Access ........................................................................................43
10.5. Running the Alarm Demo ..............................................................................................43
10.6. Known Bugs or Limitations........................................................................................... 45
11. Documentation ............................................................................................................................ 47
11.1. Documentation...............................................................................................................47
11.1.1. Release Documentation .................................................................................. 47
11.2. Mailing Lists .................................................................................................................. 47
11.2.1. JOnAS Users Mailing List ..............................................................................47
11.2.2. JOnAS Team Mailing List ..............................................................................48
Glossary .............................................................................................................................................49
Index...................................................................................................................................................55
Chapter 1.
Introduction
This tutorial explains how to configure and run the Red Hat Application Server server. In addition, it explains how to run the examples provided in the Red Hat Application Server distribution. It is assumed that a JDK is already installed. For installation details, refer to the Red Hat Application Server Installation Guide.
1.1. About this Guide
This introduction gives an overview of Red Hat Application Server. For those who want to imme­diately start using Red Hat Application Server without going through the overview, you can go to Chapter 2 Quick Start.
Chapter 3 Configuring Your Environment helps you set up all the software needed for a complete J2EE environment, including a Web server, Servlet, and EJB (Enterprise JavaBean) servers.
Chapter 4 Getting Started With JOnAS is a quick reference to JOnAS that guides you through the most common tasks you will have to perform.
The remaining chapters are specific to EJB application development. Each chapter treats a different programming concept and illustrates it with a specific example. The Alarm application is a “putting it all together” example that gives an overview of a complete application using JOnAS.
1.2. Enterprise JavaBeans
The Sun Enterprise JavaBeans specification (http://java.sun.com/products/ejb/docs.html) defines an architecture and interfaces for developing and deploying distributed Java server applications based on a multi-tier architecture.
The intent of this specification is to facilitate and normalize the development, deployment, and as­sembly of application components (called enterprise beans); such components will be deployable on EJB platforms. The resulting applications are typically transactional, database-oriented, multi-user, secured, scalable, and portable. More precisely, this EJB specification addresses the following areas:
The runtime environment, called the EJB server, which provides the execution environment together
with the transactional service, the distribution mechanisms, the persistence management, and the security.
A programmer and user guide explaining how an enterprise bean should be developed, deployed,
and used.
Not only will an enterprise bean be independent of the platform and operating system (since it is written in Java), but also of the EJB platform.
1.2.1. What Does What?
The Java2 Enterprise Edition (J2EE) platform is an n-tier platform. Each tier has a specific role:
Clients. Clients are the end-users of the system and can access the J2EE server by several means. One of the most common is to use a Web browser such as Mozilla to connect to a Web server where Java Servlets or Java Server Pages (JSP) access the business logic of the J2EE server (see Figure 1-1). Another solution is to use a specific Java program that directly communicates with the J2EE server (see Figure 1-2).
2 Chapter 1. Introduction
Web server. The Web server is responsible for accepting client requests and sending HTML replies
back to the client. HTML pages can be static files that reside on the Web server filesystem or dynam­ically built with Servlets or JSPs from data generated by the beans.
Servlet/JSP server. The Java Server Page (JSP) server or Servlet container can be integrated into the Web server or be a separate entity communicating with the Web server. JSP or servlets run within a Java Virtual Machine that can be the same as the one used by the J2EE server.
J2EE application server. The J2EE application server is the place where the beans are executed. JOnAS is fully implemented in Java and all the beans loaded in an instance of JOnAS run within the same Java Virtual Machine. It is possible to run several different JOnAS J2EE application servers on the same or separate machines.
Database server. The database server is used to store and retrieve data. It is accessed through the standard JDBC (Java DataBase Connectivity) API by the beans.
Figure 1-1. J2EE n-tier architecture overview
Figure 1-2. Accessing the Red Hat Application Server server business logic from a Java client
The distributed environment in the EJB world uses RMI, but JOnAS supports several distributed processing environments:
RMI using the Sun proprietary protocol JRMP
Chapter 1. Introduction 3
Jeremie: the RMI personality of an Object Request Broker called Jonathan, which also provides
a CORBA (Common Object Request Broker Architecture) personality. Jeremie allows JOnAS to benefit from the optimization of local RMI calls.
RMI/IIOP: JOnAS now provides support for both RMI/IIOP (Java Remote Method Invocation over
Internet Inter-Orb Protocol) and RMI/JRMP by integrating the CAROL communication frame-
work.
CMI (Cluster Method Invocation): A new ORB (Object Request Broker) used by JOnAS to provide
clustering for load balancing and high availability.
1.2.2. JOnAS Features
JOnAS implements a set of J2EE specifications. The following list shows the specifications that are implemented by JOnAS and gives a brief description of the services provided by JOnAS.
1.2.2.1. Specifications
JOnAS provides full support of the following specifications:
EJB (Enterprise JavaBean) (http://java.sun.com/products/ejb): Enterprise JavaBeans containers are
provided by a set of Java classes and a tool to generate interposition classes.
JTA (Java Transaction API) (http://java.sun.com/products/jta): a Transaction Manager that provides
Java Transaction API support and distributed transaction coordination.
JDBC (Java DataBase Connectivity) (http://java.sun.com/products/jdbc): a Database Manager that
provides Java DataBase Connectivity support.
JMS (Java Messaging Service) (http://java.sun.com/products/jms): Java Messaging Service is pro-
vided by JORAM, a technology from ScalAgent (http://www.scalagent.com).
JMX (Java Management Extension) (http://java.sun.com/products/JavaManagement): JOnAS con-
tains the Java Management Extension technology. Management and monitoring is available through a Web interface.
J2EE CA (J2EE Connector Architecture) (http://java.sun.com/j2ee/connector): JOnAS supports the
J2EE Connector Architecture that defines a set of mechanism that enable the integration of Enter­prise Information Systems (EIS).
JNDI (Java Naming and Directory Interface) (http://java.sun.com/products/jndi): Provides naming
and directory functionality.
Security management.
1.2.2.2. JOnAS Services
JOnAS offers several services that can be turned on or off as required:
EJB Container Service: A set of Java classes implementing the EJB specification.
Web Container Service: A servlet/JSP engine in the JVM (Java Virtual Machine) of the Red Hat
Application Server server and the loading of web applications (“WAR files”) within this engine. Currently this service can be configured to use Tomcat or Jetty, although only Tomcat is supplied with Red Hat Application Server.
EAR Service: A service used for deploying complete J2EE applications; that is, applications pack-
aged in EAR files, which themselves contain ejb-jar files and/or WAR files.
4 Chapter 1. Introduction
JDBC Service: JDBC 2.0 support including XA (Distributed transaction mode for JDBC 2.0) re-
sources and connection pooling.
Security Service: This service implements the authorization mechanisms for accessing EJB com-
ponents, as specified in the EJB specification. EJB security is based on the notion of roles.
Transaction Service: This is a Java Transaction Monitor called JOnAS JTM, which ensures the
coordination of distributed transactions using XA. It handles two-phase commit protocol against any number of Resource Managers (XA Resources).
Messaging Service: This service is in charge of launching (or establishing connection to) an inte-
grated JMS server. JOnAS makes use of a third-party JMS implementation. Currently the JORAM open-source JMS server is integrated and delivered with JOnAS.
Management Service: Integration of a JMX server.
J2EE CA Resource Service: Allows application component access to an external EIS.
Mail Service: Allows application components to read or send e-mail using JavaMail.
Database Service: This service is responsible for handling Datasource objects. A Datasource is a
standard JDBC administrative object for handling connections to a database.
Communication and Naming Service: This service provides the JNDI API to application com-
ponents and to other services to bind and lookup remote objects (for example, EJB Homes) and resource references (JDBC Datasource, Mail, and JMS connection factories, etc.)
Configuring and starting the various services is described in Section 4.1.2 JOnAS Configuration Files.
1.2.3. Software Requirements
Here is a list of the main software components needed to run Red Hat Application Server:
Red Hat Enterprise Linux 3.
A Java2 Software Development Kit (SDK) version 1.4. These are available on the RHEL3 Extras
Channel.
Here is a list of software components that may also be needed to run JOnAS in some configurations:
A Web server may be used in front of the Red Hat Application Server application server. The most
popular Open Source web server software used is Apache.
A Database server may be needed. Any database with a JDBC driver can be used with Red Hat
Application Server. Red Hat Application Server is configured to use PostgreSQL - Red Hat Edition (which is available on the RHEL3 Base Channel), although any database with a JDBC driver can be used.
Chapter 2.
Quick Start
This chapter will help you set up Red Hat Application Server and run your first EJB application. If you do not understand all the steps, you should read the next two chapters to familiarize yourself with the details of setting up Red Hat Application Server.
2.1. Setting Up the Red Hat Application Server Environment
We assume that your JDK is already installed and configured.
Once you have installed your Red Hat Application Server distribution, you have to set up the
JONAS_ROOT environment variable prior to using JOnAS or any of its tools. You will also have to
update your PATH variable as well.
Open a new terminal and proceed as follows:
bash> export JONAS_ROOT=/usr/share/jonas bash> export PATH=${PATH}:${JONAS_ROOT}/bin/unix
2.2. Running Your First EJB Application
Several example programs are included with the JOnAS distribution. They are located in the
$JONAS_ROOT/examples/src directory. The one we will use as your first EJB application is the
Session Bean (SB) example that resides in $JONAS_ROOT/examples/src/sb.
The SB example involves a Java client that accesses a Stateful Session Bean and twice invokes the
buy method of the bean transaction. The client communicates with JOnAS using RMI and the config-
uration files should be already set so that the RMI registry will be automatically started and embedded in the same JVM as JOnAS. The figure below gives an overview of this application.
Figure 2-1. EB example overview
6 Chapter 2. Quick Start
2.2.1. Building the Examples
The simplest way to compile all examples is to start in the $JONAS_ROOT/examples/src directory and enter the following command line as user jonas:
ant -find build.xml install
This command compiles all examples in the $JONAS_ROOT/examples/src directory.
Note
All examples assume that the current directory is $JONAS_ROOT/exampl es/src/ followed by the di­rectory that contains the example. In other words, the commands entered for the SB example assume the current folder is $JONAS_ROOT/examples/sr c/sb, whereas the commands entered for the EB ex­ample assume the current folder is $JONAS_ROOT/examp les/src/eb.
To login as user jonas, first login as root, then su to user jonas, specifying /bin/bash as the shell:
su -s /bin/bash jonas
2.2.2. Quick Start to the SB Example
Note
This example is described in more detail in Section 5.3 Running the SB Example.
To run this example, you will have to first start the Red Hat Application Server server and then run the Java client. Finally, at the end of the execution you should stop the Red Hat Application Server server.
Note
The following example assumes that the current directory is $JONAS_ROOT/examples/src/sb.
Here is how to proceed:
1. As root, start the Red Hat Application Server server:
/sbin/service jonas start
2. Deploy the JAR file:
To deploy the JAR file from the command line:
jonas admin -a sb.jar
To deploy the JAR file using the web interface:
a. Log into the JOnAS Administrator.
Chapter 2. Quick Start 7
Figure 2-2. JOnAS Administration Login
Log in with User Name jonas and Password jonas.
Figure 2-3. JOnAS Administration Web Interface
b. Click Deployments > EJB Modules (JAR).
8 Chapter 2. Quick Start
Figure 2-4. Deploy the sb.jar Example
c. On the sb.jar in the Deployable list box on the left side, Click Deploy, then click
Apply.
d. A Confirm dialog appears; click Confirm.
Figure 2-5. Confirm the sb.jar Deployment
e. A Result dialog appears, and the newly deployed jar is in the list.
Chapter 2. Quick Start 9
Figure 2-6. Results of the sb.jar Deployment
f. If you click Deployments > EJB Modules (JAR) again, sb.jar will appear in the
right list box, which lists the deployed jar files.
3. Start the Java Client:
jclient sb.ClientOp
A successful run should output:
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 Rollback the transaction Request outside any transaction ClientOp OK. Exiting.
Congratulations! You have succeeded running your first EJB application with JOnAS!
4. As root, stop the Red Hat Application Server server with the following command:
/sbin/service jonas stop
10 Chapter 2. Quick Start
Chapter 3.
Configuring Your Environment
In this chapter, we will put all the pieces together that are required to configure a complete J2EE platform. Note that you can find a more detailed description in the documentation provided with each software component.
3.1. Setting Up Your Java Environment
To set up your Java environment, you must set the value for JAVA_HOME and update the PATH en­vironment variable. JAVA_HOME must point to the SDK directory and PATH must point to the bin subdirectory of the SDK.
Assuming that you installed the SDK in the /usr/local/jdk1.4.2 directory, you should enter
the following:
bash> export JAVA_HOME=/usr/local/jdk1.4.2
You then have to update your PATH variable by appending /usr/local/jdk1.4.2/bin. If
JAVA_HOME has been properly set, you can proceed as follows: bash> export PATH=${PATH}:${JAVA_HOME}/bin
Environment variables must be correctly set at all times. It is common practice to inser t these com­mands in your shell start file (~/.bashrc).
3.1.1. Configuring Ant
You have to set the ANT_HOME environment variable and update your PATH variable.
Assuming that you installed Ant in the /usr/share/ant directory, you should enter the following command:
bash> export ANT_HOME=/usr/share/ant
Note
Make sure that the ant executable is available through the PATH. (Usually the ant executable is installed in /usr/bin.)
Warning
If you want Ant to automatically set the CLASSPATH variable, you have to correctly set your JAVA_HOME environment variable as described in Section 3.1 Setting Up Your Java Environment.
12 Chapter 3. Configuring Your Environment
3.1.2. Configuring Your JOnAS Environment
You have to set up the JONAS_ROOT environment variable prior to using JOnAS or any of its tools. You also have to update your PATH.
Assuming that you installed JOnAS in the /usr/share/jonas directory, enter the following com­mands:
bash> export JONAS_ROOT=/usr/share/jonas bash> export PATH=${PATH}:${JONAS_ROOT}/bin/unix
Chapter 4.
Getting Started With JOnAS
This chapter will help you to understand the various JOnAS components as well as how to start and manage a JOnAS server.
4.1. Overview of the Tools
JOnAS comes with a set of tools that are briefly described below.
/sbin/service jonas start starts the JOnAS server.
newbean generates skeleton files when developing a new bean.
registry starts the JNDI according to the setting in the carol.properties file (usually the
setting is RMI or JEREMIE). This command should be used only if you configured JOnAS to use a remote registry.
GenIC generates container classes.
JmsServer starts the JMS server.
jonas admin a command-line administration console for JOnAS.
RAConfig Resource Adapter deployment tool.
All these commands and their respective options are fully detailed in the Red Hat Application Server User Guide.
4.1.1. Starting and Stopping JOnAS
If JOnAS has been properly installed and your environment variables are correctly defined as de­scribed in Section 3.1.2 Configuring Your JOnAS Environment, the JOnAS service is started as fol­lows:
/sbin/service jonas start
A name is assigned to each JOnAS server in the jonas.properties file (see Section 4.1.2 JOnAS Configuration Files). The default name for a JOnAS server is jonas. To stop a JOnAS server, you
can use the jonas tool. The following command stops the JOnAS server named jonas (default):
/sbin/service jonas stop
To stop a JOnAS server with a user defined name such as myEJBserver, use:
/sbin/service jonas stop -n myEJBserver
Note
If the registry was launched with the JOnAS server, halting the server also terminates the registry. However, if the registry was launched separately, it is up to you to stop it if needed.
14 Chapter 4. Getting Started With JOnAS
4.1.2. JOnAS Configuration Files
This section is a guide for the JOnAS configuration files. If you need more in-depth information, check the JOnAS Configuration chapter of the Red Hat Application Server User Guide.
The JOnAS distribution contains configuration files that reside in the $JONAS_ROOT/conf directory:
jonas.properties is used to configure the JOnAS server and the different services that it may
launch.
carol.properties is used to configure access to JNDI (RMI or JEREMIE).
Additional properties file used to configure database access.
The JOnAS distribution contains a number of configuration files in the $JONAS_ROOT/conf direc­tory. You can edit these files to change the default configuration, but we recommend that you use a different location for the configuration files needed by a specific application running on JOnAS. This is achieved by using an additional environment variable called JONAS_BASE.
Additional configuration files may be required for specific features. For those advanced features, refer to the JOnAS Configuration chapter of the Red Hat Application Server User Guide.
4.1.2.1. jonas.properties
JOnAS first checks $JONAS_BASE/conf/jonas.properties. If $JONAS_BASE is not defined, it is automatically initialized to $JONAS_ROOT. JOnAS then checks in
$JONAS_ROOT/conf/jonas.properties, then $HOME/jonas.properties, and finally in ./jonas.properties. Files are read in this order each one overriding the values previously
defined. Here is a jonas.properties file example:
###################### JOnAS Server configuration # The current file is in the # It can be copyed and customized in the # JONAS_BASE/conf directory ######################
# Set the port number on which the remote objects receive calls # If port is zero, an anonymous port is chosen. jonas.orb.port 0
# Enable the Security context propagation (for jrmp) # With Jeremie, this has no effect: you should modify jonathan.xml jonas.security.propagation true
# Enable the Transaction context propagation jonas.transaction.propagation true
# Set the name of log configuration file jonas.log.configfile trace
# Set the list of the services launched in the JOnAS Server. # All the possible JOnAS services are: # registry,jmx,security,jtm,mail,dbm,resource,jms,ejb,ws,web,ear. # registry,jmx,jtm,ejb are mandatory # registry, and then jmx, are automatically started even # if not present in the list # Order in the list is important (see ’Configuring JOnAS services’ # in the JOnAS documentation) # # list of services for JOnAS as a full J2EE server # jonas.services # registry,jmx,security,jtm,mail,dbm,jms,resource,ejb,ws,web,ear
jonas-install>/conf directory.
Chapter 4. Getting Started With JOnAS 15
# list of services for JOnAS as a EJB server jonas.services registry,jmx,jtm,dbm,security,jms,resource,ejb,web,ear
# ###################### JOnAS Registry service configuration # # Set the name of the implementation class of the Registry service jonas.service.registry.class
org.objectweb.jonas.registry.RegistryServiceImpl
# Set the Registry launching mode # If set to ’automatic’, the registry is launched in the same JVM as # the Application Server, if it’s not already started. # If set to ’collocated’, the registry is launched in the same JVM # as the Application Server # If set to ’remote’, the registry has to be launched beforehand in # a separate JVM jonas.service.registry.mode automatic
# ###################### JOnAS JMX service configuration # # Set the name of the implementation class of the jmx service # IF you want to use SUN RI: # org.objectweb.jonas.jmx.sunri.JmxServiceImpl # IF you want to use MX4J: # org.objectweb.jonas.jmx.mx4j.Mx4jJmxServiceImpl # We use sunri for default because of compatibility with rmi iiop # jonas.service.jmx.class # org.objectweb.jonas.jmx.mx4j.Mx4jJmxServiceImpl jonas.service.jmx.class org.objectweb.jonas.jmx.sunri.JmxServiceImpl
# ###################### JOnAS EJB Container service configuration # # Set the name of the implementation class of the ejb service jonas.service.ejb.class org.objectweb.jonas.container.EJBServiceImpl
# Set the list of directories that contains ejbjars that # must be deployed by the JOnAS Server at launch time. # Give a comma-separated list of directories. # If the directory has a relative path, this path is relative from # where the Application Server is launched. # If the directory is not found, JOnAS searches for it in the # JONAS_BASE/ejbjars/ directory. jonas.service.ejb.autoloaddir autoload
# Set the list of ejbjars that must be deployed by the JOnAS Server # at launch time. # Give a comma-separated list of ejb-jar files names or standard # XML deployment descriptors files names. # If the file name has a relative path, this path is # relative from where the Application Server is launched. jonas.service.ejb.descriptors
# Set the XML deployment descriptors parsing mode # (with or without validation) jonas.service.ejb.parsingwithvalidation false
# Set the size of the thread pool used for message driven beans jonas.service.ejb.mdbthreadpoolsize 10
Loading...
+ 43 hidden pages