Red Hat Application Server: JOnAS Tutorial
Prev		Next

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 described in Section 3.1.2 Configuring Your JOnAS Environment, the JOnAS service is started as follows:

/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.

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 directory. 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 <jonas-install>/conf directory. 
#  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 
# 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

#  Set the maximun size of the thread pool used for 
#  message driven beans
jonas.service.ejb.mdbmaxthreadpoolsize	25

#
###################### JOnAS Web container service configuration
#
#  Set the name of the implementation class of the 
#  web container service.
jonas.service.web.class    
  org.objectweb.jonas.web.catalina41.CatalinaJWebContainerServiceImpl
#jonas.service.web.class   
#  org.objectweb.jonas.web.jetty.JettyJWebContainerServiceImpl


### Experimental (Need that JOnAS be compiled with Tomcat 5)
#jonas.service.web.class    
#  org.objectweb.jonas.web.catalina50.CatalinaJWebContainerServiceImpl

#  Set the list of directories that contains WARs 
#  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/webapps/ directory. 
jonas.service.web.autoloaddir		autoload	

#  Set the list of WARs that must be depoyed by the 
#  JOnAS Server at launch time.
#  Give a comma-separated list of WAR files names.
#  If the file name has a relative path, 
#  this path is relative from where the
#  Application Server is launched.
jonas.service.web.descriptors

#  Set the XML deployment descriptors parsing mode for 
#  the WEB container service (with or without validation).
jonas.service.web.parsingwithvalidation		true

###################### JOnAS WebServices service configuration
#
#  Set the name of the implementation class of 
#  the WebServices service.
jonas.service.ws.class    
  org.objectweb.jonas.ws.axis.AxisWSServiceImpl

# Set the JServiceFactory to use
jonas.service.ws.factory.class 
  org.objectweb.jonas.ws.axis.JAxisServiceFactory

#  Set the XML deployment descriptors parsing mode for the 
#  WebServices service (with or without validation).
jonas.service.ws.parsingwithvalidation		true

# Set the WSDL Handler list for WSDL publication
# A minimum of 1 WSDLHandler is required !
# the list of desired WSDLHandlers (comma-separated)
jonas.service.ws.wsdlhandlers file1
# Configure the file1 WSDLHandler
jonas.service.ws.file1.class 
  org.objectweb.jonas.ws.handler.FileWSDLHandler
jonas.service.ws.file1.params location
# Where WSDLs will be published ?
jonas.service.ws.file1.location /tmp

# Set the Generator to use with wsgen
jonas.wsgen.generator.class 
  org.objectweb.jonas_ws.wsgen.axis.AxisConfigGenerator


#
###################### JOnAS EAR service configuration
#
#  Set the name of the implementation class of the ear service.
jonas.service.ear.class  org.objectweb.jonas.ear.EarServiceImpl

#  Set the list of directories that contains ears that must 
#  be deployed by the JOnAS Server at launch time.
#  Here should be given 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/apps/ directory. 
jonas.service.ear.autoloaddir		autoload	

#  Set the list of ears that must be depoyed by the JOnAS Server
#  at launch time.
#  Here should be given a comma-separated list of ear files names.
#  If the file name has a relative path, this path is relative 
#  from where the Application Server is launched.
jonas.service.ear.descriptors

#  Set the XML deployment descriptors parsing mode for the 
#  EAR service (with or without validation).
jonas.service.ear.parsingwithvalidation		true

#
###################### JOnAS DBM Database service configuration
#
#  Set the name of the implementation class of the dbm service
jonas.service.dbm.class  org.objectweb.jonas.dbm.DataBaseServiceImpl

#  Set the jonas DataSources. This enables the JOnAS server to load
#  the data dources, to load related jdbc drivers, and to register  
#  the data sources into JNDI.
#  This property is set with a comma-separated list of Datasource 
#  properties file names (without the '.properties' suffix).
#  Ex: Oracle1,InstantDB1 (while the Datasources 
#  properties file names are Oracle1.properties 
#  and InstantDB1.properties)
jonas.service.dbm.datasources   PostgreSQL1

#
###################### JOnAS Mail service configuration
#
#  Set the name of the implementation class of the mail service
jonas.service.mail.class  org.objectweb.jonas.mail.MailServiceImpl

#  Set the jonas mail factories.
#  This property is set with a comma-separated list of MailFactory 
#  properties file names (without the '.properties' suffix).
#  Ex: MailSession1,MailMimePartDS1 (while the properties file names 
#  are MailSession1.properties and MailMimePartDS1.properties)
jonas.service.mail.factories   	

#
###################### JOnAS JTM Transaction service configuration
#

#  Set the name of the implementation class of the jtm service
jonas.service.jtm.class  
  org.objectweb.jonas.jtm.TransactionServiceImpl

#  Set the Transaction Manager launching mode.
#  If set to 'true', TM is remote: TM must be already launched in 
#  another JVM.
#  If set to 'false', TM is local: TM is going to run in the same  
#  JVM as the jonas Server. 
jonas.service.jtm.remote	false

#  Set the default transaction timeout, in seconds.
jonas.service.jtm.timeout	60


#
###################### JOnAS SECURITY service configuration
#
#  Set the name of the implementation class of the security service
jonas.service.security.class
  org.objectweb.jonas.security.JonasSecurityServiceImpl

# Realm to use for the security on EJB for java client. 
# This is not used in the case of a client running in 
# a web container.
# Choose one of the realms defined in the jonas-realm.xml file
jonas.service.security.ejbrealm memrlm_1

#
###################### JOnAS JMS service configuration
#
#  Set the name of the implementation class of the jms service
jonas.service.jms.class  org.objectweb.jonas.jms.JmsServiceImpl

#  Indicates the Jms service must be started with this class 
#  for administering the mom
jonas.service.jms.mom  org.objectweb.jonas_jms.JmsAdminForJoram

#  Set the Jms Server launching mode
#  If set to 'true'  it launches in the same JVM as 
#  Application Server
#  If set to 'false' Jms Server launches in a separate JVM
jonas.service.jms.collocated  true

#  Set to the url connexion when the Jms server is not collocated
#jonas.service.jms.url  joram://localhost:16010

#  Set the list of administered objects topics to be created 
#  at Application Server launching time
jonas.service.jms.topics  sampleTopic

#  Set the list of administered objecst queuess to be created 
#  at Application Server launching time
jonas.service.jms.queues  sampleQueue
		
#
###################### JOnAS J2CA resource service configuration
#
#  Set the name of the implementation class of the J2CA
#  resource service
jonas.service.resource.class
  org.objectweb.jonas.resource.ResourceServiceImpl

#  Set the list of directories that contains rars 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/rars/ directory. 
jonas.service.resource.autoloaddir  autoload	

#  Set the list of Resource Adapter to be used. 
#  This enables the JOnAS server to configure the resource adapter 
#  and register it into JNDI.
#  This property is set with a comma-separated list of RAR file names 
#  (with/without the '.rar' suffix).
#  Ex: XXXX,YYYY (while the rar file names are XXXX.rar and YYYY.rar)
jonas.service.resource.resources

4.1.2.2. carol.properties

Access to JNDI is bound to the carol.properties file, which must be accessible from the classpath. This file is supplied with the JOnAS distribution in the $JONAS_ROOT/conf directory.

The carol.properties file contains the following:

# jonas rmi activation (jrmp, iiop, cmi) 
carol.protocols=jrmp

# RMI JRMP URL
carol.jrmp.url=rmi://localhost:1099

# RMI IIOP URL
carol.iiop.url=iiop://localhost:2001

#####################################################################
#             Configuration for CMI (clustering)
#####################################################################

# java.naming.provider.url property
# For a server : the URL on which the registry will be started
# For clients : lists the registries available
carol.cmi.url=cmi://localhost:2002

# Multicast address used by the registries in the cluster
carol.cmi.multicast.address=224.0.0.35:35467

# IP address or network mask of the local network interface to use 
# to send multicast messages
# Needed only when the server has several network interfaces 
# and the multicast messages do not go through to interface 
# you want them to use
# Works only on JDK 1.4
#carol.cmi.multicast.itf 192.168.25.0/24

# Groupname for Javagroups. No need to change if not known.
carol.cmi.multicast.groupname=G1

# Factor used for this server in wheighted round robin algorithms
carol.cmi.rr.factor=100

# If enabled, cluster stubs will print messages on some error cases
carol.cmi.stub.debug=false

# If true, local call with jrmp are optimized. 
# If you get "ClassCastException with 2 beans in different jars, 
# you should set it at "false".
carol.jvm.rmi.local.call=false

carol.jndi.java.naming.factory.url.pkgs=org.objectweb.jonas.naming

4.1.3. Database Access

Any database with a JDBC driver can be used with JOnAS. Sample properties files are provided for Oracle, InstantDB, Interbase, and PostgreSQL. If you want to setup a new database, you can modify one of those configuration files to suit your database driver requirements. Here is the PostgreSQL example:

###################### PostgreSQL DataSource configuration example
#

#####
#  DataSource configuration
#  Replace db_jonas and jonas by appropriate values.
#
datasource.name         jdbc_1
datasource.url          jdbc:postgresql://localhost:5433/db_jonas
datasource.classname    org.postgresql.Driver
datasource.username     jonas
datasource.password     jonas
datasource.mapper	rdb.postgres


#####
#  ConnectionManager configuration
#

#  JDBC connection checking level.
#     0 = no special checking
#     1 = check physical connection is still open before reusing it
#     2 = try every connection before reusing it
jdbc.connchecklevel	1

#  Max age for jdbc connections
#     nb of minutes a connection can be kept in the pool
jdbc.connmaxage		30

#  Test statement
jdbc.connteststmt	select 1

Note that postgresql_ds is the name that you will have to use in your beans deployment descriptors to reference this datasource. Also, if you called this file postgresql.properties, you must define a line such as jonas.service.dbm.datasources postgresql in your jonas.properties file.

4.1.4. Loading Beans Using jonas.properties

You can statically define the beans you want to load at JOnAS startup by updating the jonas.properties file. Here are some examples:

If you want to load the beans defined in a single ejb-jar.xml file, and not packaged in an ejb-jar file, place this line in your jonas.properties file:
jonas.service.ejb.descriptors META-INF/ejb-jar.xml
Note that in the above case, the shell CLASSPATH used to start the JOnAS server must also allow access to your bean classes.
To deploy beans defined in several deployment descriptors, the syntax is as follows:
jonas.service.ejb.descriptors Bean1.xml,Bean2.xml
If you want to load all the beans of your application, you can give the name of the application jar file, but you must store your xml deployment descriptor in the META-INF directory:
jonas.service.ejb.descriptors myApp.jar

4.1.5. JOnAS Administration

JOnAS can be administered from a Web interface with:

http://hostname:9000/jonasAdmin

JOnAS can also be managed using the command-line tool called jonas, using username jonas and password jonas. The administrative option is started by passing admin as a command-line argument. For example:

jonas admin

See JOnAS Command Reference in the Red Hat Application Server User Guide.

4.1.6. Loading Beans Using jonas admin

JOnAS provides a command-line console that allows you to perform many administration tasks such as dynamically loading beans. Here is how to load beans with JOnAS Admin:

Loading all beans of the application stored in myApp.jar into the JOnAS server named jonas (default name):
jonas admin -a myApp.jar
Load all beans defined in an ejb-jar file into a JOnAS server named jonas2:
jonas admin -n jonas2 -a mybean-ejb.jar

Same as the previous example but using the interactive console:

> jonas admin
You must first choose a jonas server. (command `name`)
Type `help` to get the list of available commands
jonas admin (jonas) > name jonas2
jonas admin (jonas2) > addbeans mybean-ejb.jar

You can find a complete description of JOnAS Admin in the JOnAS Command Reference section of the Red Hat Application Server User Guide.

4.1.7. Unloading Beans

Beans can be unloaded either by stopping JOnAS or using the command line jonas admin. Here is how to unload beans with JOnAS Admin:

Unload all beans defined in an ejb-jar file from a JOnAS server named jonas2:
jonas admin -n jonas2 -r mybean-ejb.jar

Same as the previous example but using the interactive console:

> jonas admin
You must first choose a jonas server. (command `name`)
Type `help` to get the list of available commands
jonas admin (jonas) > name jonas2
jonas admin (jonas2) > removebeans mybean-ejb.jar

Prev	Home	Next
Configuring Your Environment		Session Beans