JOnAS 4.8 EE Configuration guide

A server or JOnAS instance is a java process started via the jonas start command or via the administration tool JonasAdmin.

Several servers may run on the same physical host.

When a server starts, services are started.

A service typically provides system resources to containers. Most of the components of the JOnAS application server are pre-defined services. However, it is possible and easy for an advanced user to define a new service and to integrate it into JOnAS.

JOnAS services are manageable through JMX.

A container consists of a set of Java classes that implement the Java EE specification. The role of the container is to provide the facilities for executing J2EE components.

There are three types of containers:

A domain represents an administration perimeter which is under the control of an administration authority.

This perimeter contains management targets like servers and clusters.

If a domain contains several elements, it provides at least one common administration point represented by a master server.

A master is a JOnAS instance having particular management capabilities within the domain:

A cluster is a group of server instances. It usually allows to run a J2EE application, or a J2EE module, on the cluster members as if they were a single server. The objective is to achieve applications scalability and high availability.

JOnAS supports several cluster types:

From the administrator point of view, a cluster represents a single administration target.

Note that a particular JOnAS server may belong to zero, one or more clusters.

JONAS_BASE has the following structure:

This directory contains configuration files in various format (properties file, xml files).

The main configuration file is jonas.properties but there are also:

Most of these files are described in following sections.

$JONAS_BASE/conf/jonas.properties is the key file for configuring JOnAS.

This file is used for:

2.1.4.1. Global properties of jonas.properties

# Enable the Security context propagation for jrmp
jonas.security.propagation    true

# Enable the rmi Security manager
jonas.security.manager    true

# Enable csiv2 security propagation for rmi/iiop
jonas.csiv2.propagation    true

# Enable the Transaction context propagation
jonas.transaction.propagation    true

#  Set the name of log configuration file to trace.properties
jonas.log.configfile    trace

Properties are self commented.

	Note
	setting jonas.security.manager to false implies a colocated registry and implies to set in carol.properties: carol.jvm.rmi.local.registry=true

jonas.services    registry,jmx,jtm,db,dbm,security,resource,ejb,ws,web,ear

#  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 an other JVM.
#  If set to 'false', TM is local: TM is going to run into the same JVM
#  than the jonas Server.
jonas.service.jtm.remote    false
#  Set the default transaction timeout, in seconds.
jonas.service.jtm.timeout    60

The choice of the protocol is made in the carol.protocols property of carol.properties file in JONAS_BASE/conf directory.

carol.protocols=jrmp

2.2.1.1. configuring jrmp protocol

carol.protocols=jrmp 
carol.jrmp.url=rmi://localhost:1099 
carol.jvm.rmi.local.call=false 
carol.jvm.rmi.local.registry=false 
carol.jrmp.server.port=0 
carol.jrmp.interfaces.bind.single=false 

	choice of the protocol or list of protocols
	connexion url to the RMI registry the hostname (localhost) and port number must be changed if needed. In a distributed configuration changing the hostname is mandatory.
	if true local calls are optimized: calls to methods of the remote interface are treated as call to local methods (it is not always possible depending on the packaging of the application).
	if true a local Naming context is used. This must be used only with a collocated registry and it is mandatory when the jonas.security.manager property of jonas.properties is set to true.
	exported objects will listen on this port for remote method invocations. 0 means random port. Specify a port may be useful when the server run behind a firewall.
	if true use only a single interface (choosen from the url) when creating the registry. False means use all interfaces available.

2.2.1.2. configuring RMI/IIOP protocol

The JacORB implementation of RMI over the IIOP is used. The configuration file of JacORB is the $JONAS_BASE/conf/jacorb.properties file.

As for the other protocols RMI over IIOP is ready to used in the default distribution. It is only for tuning purpose that the $JONAS_BASE/conf/jacorb.properties file must be customized.

By default the CORBA Naming service is run using the port 2001 (as it is set in the carol.properties file)

So the only thing to do for working in RMI over IIOP is to set the property protocols in carol.properties:

carol.protocols=iiop
# RMI IIOP URL
carol.iiop.url=iiop://localhost:2001
carol.iiop.server.port=0 
carol.iiop.server.sslport=2003 
carol.iiop.PortableRemoteObjectClass=org.objectweb.jonas_lib.naming.JacORBPRODelegate  

	0 means random port
	this port is used only if SSL mode is enabled (default configuration = not used).Is used to set the SSL port of the objects listener
	delegate used by JOnAS for rmi-iiop protocol.

2.2.1.3. configuring irmi protocol

carol.protocols=irmi
carol.irmi.url=rmi://localhost:1098 
carol.irmi.server.port=0 
carol.irmi.interfaces.bind.single=false 

	for irmi the default port is 1098
	exported objects will listen on this port for remote method invocations:0 means random port. Caution if the port is set to n the port 'n + 1' will be used by the JMX server.So, for the firewall configuration, you have to open the port numbers 'n' and 'n+1'
	if true use only a single interface when creating the registry (specified in carol.irmi.url property). Default configuration = false(use all interfaces available)

2.2.1.4. configuring cmi protocol

CMI is the protocol to use for clustering purpose.

CMI brings its own registry that implements JNDI replication. CMI relies on JGroups group-communication protocol for ensuring the global registry replication. CMI provides jndi high availability, the load-balancing and fail-over at the EJB level.

For using CMI the protocol must be set in carol.properties:

carol.protocols=cmi
carol.cmi.url=cmi://host:2002 
carol.cmi.jgroups.conf=jgroups-cmi.xml 
carol.cmi.multicast.groupname=G1 

	for CMI the default port is 2002
	name of the JGroups configuration file
	groupname for JGroups. All instances in a same cluster must share the same groupname.

The $JONAS_BASE/conf/jgroups-cmi.xml file defines the setting of the JGroups protocol stack. By default this stack uses UDP protocol and multicast IP for broadcasting CMI registry updates.

Further information about clustering and CMI configuration can be found in Chapter 4, Configuring a cluster

2.2.1.5. multi protocol configuration

JOnAS can be configured to use several protocols simultaneously. To do this, just specify a comma-separated list of protocols in the carol.protocols property of the carol.properties file. For example:

carol.protocols=jrmp,cmi
carol.jrmp.url=rmi://localhost:1099
carol.cmi.url=cmi://localhost:2002

	Caution
	When iiop is used in a multiprotocol configuration, it must appear at the first position in the protocol list.

JOnAS Monolog configuration files are:

Configuring trace messages inside JOnAS can be done in two ways:

Applications make logging calls on logger objects.Loggers are organized in a hierarchical namespace and child loggers may inherit some logging properties from their parents in the namespace. Loggers allocates messages and passes them to handler for output; they uses logging levels in order to decide if they are interested in by a particular message.

In trace.properties it is possible to define handlers, loggers, levels:

log.config.classname org.objectweb.util.monolog.wrapper.javaLog.LoggerFactory  

handler.tty.type Console 
handler.tty.output Switch 
handler.tty.pattern  %d : %O{1}.%M : %m%n 

handler.logf.type File 
handler.logf.output automatic 
handler.logf.pattern  %d : %l : %h : %O{1}.%M :    %m%n

logger.root.handler.0 tty 
logger.root.handler.1 logf 

logger.root.level INFO 
logger.org.objectweb.level INFO

#logger.org.objectweb.jonas_ejb.level DEBUG 

handler.mesonly.type Console 
handler.mesonly.output Switch
handler.mesonly.pattern  %m%n

logger.org.objectweb.jonas.genic.handler.0 mesonly 
logger.org.objectweb.jonas.genic.additivity false 

[...]

	Definition of the wrapper to use: here the java logging API wrapper.
	Definition of the console handler tty
	Switch means that the logs will be on System.out or System.err depending of the level of the log.
	Definition of the message format. here it contains the date followed by ':' the basename of the class followed by '.' the method name followed by ':' the message itself terminated by newline.
	Definition of the file handler logf
	Logs are in a file whose name is $JONAS_BASE/logs/<jonas_name_server>-<timestamp>.log
	Definition of the root logger. It uses handler tty
	Definition of the root logger: It uses also handler logf
	Definition of the root logger: level INFO is used for all child loggers if there is no overriden definition
	This line must be uncommented for setting DEBUG level for the logger used in the jonas_ejb module
	Definition of the console handler mesonly used by GenIC tool which want to log messages without headers
	Definition of the handler used by the logger org.objectweb.jonas.genic
	This logger wants to use its own handler.

When a problem occurs it may be worth to set some debugging traces in the JOnAS server. It is not easy to know which logger to set to obtain the pertinent traces that may help the debbugging process.

The trace.properties file contains several commented lines prepared to set loggers in DEBUG level.

Usually the name of loggers are related to the java package name in which it is used.

This service is used for accessing the RMI registry, CMI registry, or the CosNaming (rmi/iiop), depending on the configuration of communication protocols specified in carol.properties, refer to Section 2.2, “Configuring the communication protocol and JNDI” .

Here is the part of jonas.properties file concerning the registry service.

###################### 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 Application Server,
#                         if it's not already started.
#  If set to 'collocated', the registry is launched in the same JVM as Application Server
#  If set to 'remote', the registry has to be launched before in a separate JVM
jonas.service.registry.mode    collocated

The jmx service is automatically started in order to administrate or instrument the JOnAS server. It is currently based on MX4J and does not require any specific configuration.

Here is the part of jonas.properties concerning the jmx service:

###################### JOnAS JMX service configuration
#
#  Set the name of the implementation class of the jmx service
jonas.service.jmx.class		org.objectweb.jonas.jmx.JmxServiceImpl

This service provides containers for EJB components.

An EJB container can be created from an ejb-jar file using one of the following possibilities:

Here is the part of jonas.properties concerning the ejb service:

###################### 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.
#  Here should be given a coma-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 it will be searched in 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.
#  Here should be given a coma-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    true

#  Set the size of the worker thread pool
jonas.service.ejb.minworkthreads   3

#  Set the maximun size of the worker thread pool
jonas.service.ejb.maxworkthreads   80

#  Set the max # of seconds that a thread will wait for work
#  This is used to shrink the worker thread pool back to minimum
jonas.service.ejb.threadwaittimeout 60


# If enabled, the GenIC tool will be called if :
#  - JOnAS version of the ejb-jar is not the same version than the running JOnAS instance
#  - Stubs/Skels stored in the ejb-jar are not the same than the JOnAS current protocols.
# By default, this is enabled
jonas.service.ejb.auto-genic true

# Arguments for the auto GenIC
#jonas.service.ejb.auto-genic.args.0 -invokecmd
#jonas.service.ejb.auto-genic.args.1 -verbose

For customizing the ejb service it is possible to:

This service provides containers for the web components used by the Java EE applications.

JOnAS provides two implementations of this service: one for Jetty 5.0.x, one for Tomcat 5.0.x. It is necessary to run this service in order to use the JonasAdmin tool. A web container is created from a war file. If the file name does not contain an absolute path name, it must be located in the $JONAS_BASE/webapps/ directory.

A web container can be created from a file using one of the following possibilities:

Using webapp directories instead of packaging a new war file each time can improve the development process. You can replace the classes with the new compiled classes and reload the servlets in your browser, and immediately see the changes. This is also true for the JSPs. Note that these reload features can be disabled in the configuration of the web container (Jetty or Tomcat) for the production time. Example of using the jonasAdmin/ webapp directory instead of jonasAdmin.war

Here is the part of jonas.properties concerning the web service:

###################### 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.wrapper.catalina55.CatalinaJWebContainerServiceWrapper
#jonas.service.web.class    org.objectweb.jonas.web.jetty50.JettyJWebContainerServiceImpl

#  Set the list of directories that contains wars that must be deployed by
#  the JOnAS Server at launch time.
#  Here should be given a coma-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 it will be searched in 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.
#  Here should be given a coma-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

The resource service must be started when Java EE components require access to an external Enterprise Information Systems. The standard way to do this is to use a third party software component called Resource Adapter.

The role of the Resource service is to deploy the Resource Adapters in the JOnAS server, i.e., configure it in the operational environment and register in JNDI name space a connection factory instance that can be looked up by the application components. The resource service implements the Java EE Connector Architecture 1.5^[9].

The resource service can be configured in one of the following ways:

A JOnAS specific resource adapter configuration xml file must be included in each resource adapter. This file replicates the values of all configuration properties declared in the deployment descriptor for the resource adapter. Refer to Defining the JOnAS Connector Deployment Descriptor in J2EE Connector Programmer's Guide for additional information.

Here is the part of jonas.properties related to resource service:

###################### 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.
#  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 it will be searched in JONAS_BASE/rars/
#  directory.
jonas.service.resource.autoloaddir    autoload

#  Set the XML connector deployment descriptors parsing mode (with or without validation)
jonas.service.resource.parsingwithvalidation    true

#  Set the min size of the worker thread pool used for all J2CA 1.5 Resource Adapters deployed
jonas.service.resource.minworkthreads  5

#  Set the max size of the worker thread pool used for all J2CA 1.5 Resource Adapters deployed
jonas.service.resource.maxworkthreads  80

#  Set the max # of seconds that a thread will wait for work
#  This is used to shrink the worker thread pool back to minimum
jonas.service.resource.threadwaittimeout 60

#  Set the max # of seconds of execution time for a work object
#  This functionality may not be supported by all Resource Adapter
jonas.service.resource.execworktimeout 0

#  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 coma-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

For customizing the resource service it is possible to:

resource service is mainly used in JOnAS for accessing databases via a JDBC resource adapter (in this case it replace dbm service) and for providing JMS facilities (and it replace jms service).

JOnAS provides several JDBC resource adapters and a JMS resource adapter on top of JORAM More information about configuring resource adapters can be found in Section 2.6, “Configuring JDBC Resource Adapters”

The ear service allows deployment of complete Java EE applications (including ejb-jar, war and rar files packed in an ear file). This service is based on the web service for deploying the included wars, the ejb service for deploying the EJB containers for the included ejb-jars and the resource service for deploying the included rars.

A J2EE application can be deployed by the ear service using one of the following possibilities:

Here is the part of jonas.properties concerning the ear service:

###################### 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 coma-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 it will be searched in 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 coma-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

For customizing the ear service It is possible to :

The jtm service is used by ejb service in order to provide transaction management for EJB components as defined in the deployment descriptor. The jtm service uses a Transaction manager that may be local or may be launched in another JVM (a remote Transaction manager). Typically, when there are several JOnAS servers working together, one jtm service must be considered as the master and the others as slaves. The slaves must be configured as if they were working with a remote Transaction manager.

By default JOTM is the Transaction manager used.

Here is the part of jonas.properties concerning the jtm service:

###################### 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 an other JVM.
#  If set to 'false', TM is local: TM is going to run into the same JVM
#  than the jonas Server.
jonas.service.jtm.remote    false

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

For customizing the jtm service It is possible to

The ws service use the Axis implementation.

Here is the part of jonas.properties concerning the ws service:

###################### 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 !
#  This property is set with a coma-separated list of WSDLHandler properties
#  file names (without the '.properties' suffix).
#  Ex: file1,uddi (while the properties file names are
#                  file1.properties and uddi.properties)
jonas.service.ws.wsdlhandlers file1

# Set the Generator to use with wsgen
jonas.service.ws.wsgen.generator.factory     org.objectweb.jonas_ws.wsgen.generator.ews.EWSGeneratorFactory

# Set the prefix that will be used to compute URL endpoints for web services
#jonas.service.ws.url-prefix http://www.mydomain.com:8888

# Set automatic WsGen mode on/off
# If set to 'true', WsGen will automatically be applied to all deployed archives (EjbJars, Webapps, Applications)
# default to 'true'
#jonas.service.ws.auto-wsgen.engaged false

or customizing the ws service It is possible to :

More information on How to Develop a J2EE-Compliant Web Service (endpoint + client) and Web Services with JOnAS.

The mail service is an optional service that may be used to send email.

It is based on JavaMail and on JavaBeans Activation Framework (JAF) API.The default implementation of the mail service rely on the GNUMail implementation of these API.

A mail factory is required in order to send or receive mail. JOnAS provides two types of mail factories: javax.mail.Session and javax.mail.internet.MimePartDataSource. MimePartDataSource factories allow mail to be sent with a subject and the recipients already set.

Mail factory objects must be configured according to their type. The subsections that follow briefly describe how to configure Session and MimePartDataSource mail factory objects, in order to run the SessionMailer SessionBean and the MimePartDSMailer SessionBean delivered with the platform.

Here is the part of jonas.properties concerning the mail service:

###################### 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 coma-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

Mail factory objects created by JOnAS must be given a name. In the mailsb example (see $JONAS_ROOT/examples/src/mailsb) , two factories called MailSession1 and MailMimePartDS1 are defined. Each factory must have a configuration file whose name is the name of the factory with the .properties extension (MailSession1.properties for the MailSession1 factory).

For this example jonas.service.mail.factories property must be set to:

jonas.service.mail.factories MailSession1,MailMimePartDS1

#Factory Name/Type
mail.factory.name mailSession_1
mail.factory.type javax.mail.Session

#Factory Name/Type
mail.factory.name mailMimePartDS_1
mail.factory.type javax.mail.internet.MimePartDataSource

Here is the part of jonas.properties related to security service:

###################### 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 used for CsiV2 authentication
jonas.service.security.csiv2.realm    memrlm_1

# Realm used for Web Service authentication
jonas.service.security.ws.realm    memrlm_1

# Registration of realm resources into JNDI
# Disable by default so configuration is not available with clients
jonas.service.security.realm.jndi.registration[]    false

In fact properties jonas.service.security.csiv2.realm and jonas.service.security.ws.realm are only useful for users that use security on top of rmi/iiop or on top of web services . in these case with memrlm_1 it is possible to make a link to the memomyrealm named memrlm_1 in the $JONAS_BASE/conf/jonas-realm.xml file and retrieve users name and roles.

Don't forget that for using security the global property jonas.security.propagation to true and that an important property related to security is jonas.security.manager see Section 2.1.4.1, “Global properties of jonas.properties”

All other security configuration related to JOnAS is done in the file jonas-realm.xml and security configuration related to web containers, certificate, etc., is done in the appropriate files. Refer to the subsection Section 2.5, “Configuring Security” for a complete description of security configuration.

The db service is an optional service that can be used to start a java database server in the same JVM as JOnAS.

By default the database used is HSQLDB.

Here is the part of jonas.properties related to db service:

###################### JOnAS DB service configuration
#
#  Set the name of the implementation class of the db service (hsql for example)
jonas.service.db.class    org.objectweb.jonas.db.hsqldb.HsqlDBServiceImpl
jonas.service.db.port    9001
jonas.service.db.dbname    db_jonas
jonas.service.db.user1    jonas:jonas
#jonas.service.db.user2    login:password

Here it is possible to customize :

The database may be used by Java EE component via JDBC resource adapters or via the dbm service. For the former case the same information (listening port, database name, login,password) must appear in the JOnAS connector deployment descriptor, in the latter they appear in the $JONAS_BASE/conf/HSQLDB1.properties. So, if these previous properties must be changed in jonas.properties, they must be also changed in these files.

Via the db service HSQLDB is configured in a default mode where the tables are not persistent and exist entirely in random access memory.

The db service has been provided in the jonas distribution mainly to run easily the JOnAS exemple, without having to set a database first. For most usages, the jonas users should remove it from the list of services and remove also HSQL1 from jonas.service.dbm.datasources property in $JONAS_BASE/conf/jonas.properties file.

For users that choose HSQLDB as database it is highly recommended to refer to the Hsqldb User Guide. It is worth to note that the default configuration file used by HSQLDB server can be found in $JONAS_BASE/work/hsqldb/jonas/db_jonas.properties directory.

The role of the discovery service is to enable domain management. It allows the management of all the servers running in the domain from the common administration point represented by the master.

The discovery service is based on IP multicast. It allows master to detect servers starting and stopping in the domain, and to discover servers there were already running in the domain.

Here is the part of jonas.properties related to discovery service:

###################### JOnAS Discovery service
#
#  Set the name of the implementation class of the discovery service
#  The server is not a discovery master, unless its name is
#  identical to the domain name
#jonas.service.discovery.master = true
#  If this is a master, the discovery client source port may be configured
#  with the property:
jonas.service.discovery.source.port=9888
#
#  Set the name of the implementation class and initialization parameters
jonas.service.discovery.class=org.objectweb.jonas.discovery.DiscoveryServiceImpl
jonas.service.discovery.multicast.address=224.224.224.224
jonas.service.discovery.multicast.port=9080
jonas.service.discovery.ttl=1

#  A multicast greeting message is sent out when discovery service is started.
#  The starting server listens at the port jonas.service.discovery.greeting.port
#  (default 9899) for a response for jonas.service.discovery.greeting.timeout miliseconds
#  (default 1000 ms). If a pre-existing server has the same server name as this one,
#  this server's discovery service will be terminated.

jonas.service.discovery.greeting.port=9899
jonas.service.discovery.greeting.timeout=1000

For the discovery service it is possible to :

The ha (High Availability) service is required in order to replicate stateful session beans (SFSBs).

The ha service uses JGroups as a group communication protocol (GCP).

Here is the part of jonas.properties related to ha service:

###################### JOnAS HA service configuration
#
# Set the name of the implementation class of the HA service.
jonas.service.ha.class    org.objectweb.jonas.ha.HaServiceImpl

# Set the group communication framework to use
jonas.service.ha.gcl jgroups

# Set the JGroups configuration file name
jonas.service.ha.jgroups.conf jgroups-ha.xml

# Set the JGroups group name
jonas.service.ha.jgroups.groupname jonas-rep

# Set the SFSB backup info timeout. The info stored in the backup node is removed when the timer expires.
jonas.service.ha.timeout 600

# Set the datasource for the tx table
jonas.service.ha.datasource jdbc_1

For the ha service it is possible to:

The dbm service (database manager service) allow access to one or more relational databases. It will create and use DataSource objects. Such a DataSource object must be configured according to the database that will be used for the persistence of a bean.

	Caution
	the recommended way to access to databases is to use the resource service deploying JDBC resource adapter

The dbm service provides a generic driver-wrapper that emulates the XADataSource interface on a regular JDBC driver.It is important to note that this driver-wrapper does not ensure a real two-phase commit for distributed database transactions. When it is necessary to use a JDBC2-XA-compliant driver access to the databases must be done via a JDBC resource adapter XA compliant (more information can be found in Section 2.6, “Configuring JDBC Resource Adapters”

Here is the part of jonas.properties related to dbm service:

###################### 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 coma-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    HSQL1

For the dbm service it is possible to:

Access to a particular database via dbm service is configured in datasource.properties files that must be located in $JONAS_BASE/conf.

jms service is a service that can be used for application that use the Java Message Service API , or that use message-driven beans (with some restrictions: it does not allow deployment of 2.1 message-driven beans ).

	Caution
	The recommended way is to use a JMS provider through the deployment of a resource adapter and to use resource service instead (seeSection 2.7, “Configuring JMS Resource Adapters” )

JOnAS integrates a third-party JMS implementation (JORAM) which is the default jms service. Other JMS providers, such as SwiftMQ and WebSphere MQ, may easily be integrated as jms services.

The jms service is used to contact (or launch) the corresponding MOM (Message Oriented Middleware) or JMS server. The JMS-administered objects used by the EJB components, such as the connection factories and the destinations, should be created prior to the EJB execution, using the proprietary JMS implementation administration facilities. JOnAS provides "wrappers" on such JMS administration APIs, allowing simple administration operations to be achieved automatically by the JOnAS server itself.

Here is the part of jonas.properties related to jms service:

###################### 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 is launched in the same JVM as Application Server
#  If set to 'false' Jms Server is launched 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
# Note : When using resource service (default configuration), topics should go in joram-admin.cfg file
jonas.service.jms.topics    sampleTopic

# Set the list of administered objecst queuess to be created at Application Server launching time
# Note : When using resource service (default configuration), queues should go in joram-admin.cfg file
jonas.service.jms.queues    sampleQueue

For the jms service it is possible to:

The jms service relies on the ejb WorkThread pool to run the MDB onMessage() methods. Here is described how to configure this thread pool.

The thread service is mandatory to use the Thread Management Framework

it must be started just after the jmx service

Here is the part of jonas.properties related to jms service:

###################### JOnAS Thread Service
#
# Set the name of the implementation class of the thread service
#
jonas.service.thread.class       org.objectweb.area.jonas.AreaService
jonas.service.thread.file        jonas_areas.xml
jonas.service.thread.ejbareaname EJB

For the thread service it is possible to:

See here for a complete description of the Thread Management Framework.

The file $JONAS_BASE/conf/jonas-realm.xml file describes:

2.5.1.1. Memory realm

The memoryrealm must be named and defines users, groups and roles in the section <jonas-memoryrealm>

<jonas-memoryrealm>
 <memoryrealm name="memrlm_1"> 
   <roles>
     <role name="jonas-admin" description="JonasAdmin role" /> 
     <role name="tomcat" description="Used in examples" />
   </roles>
   <groups>
   <group name="jonas" 
      roles="jonas-admin,tomcat,jaas,ws-security" description="All authorization" /> 
   </groups>
   <users>
     <user name="tomcat" password="tomcat" roles="tomcat,jonas-admin,manager" /> 
     <user name="jetty" password="jetty" roles="jetty" />
     <!-- Example of a crypt password : password for jadmin is : jonas -->
     <user name="jadmin" password="{MD5}nF3dVBB3NPfRgzWlJFwoaw==" roles="jonas-admin" /> 
     <user name="jps_admin" password="admin" roles="administrator" />
     <user name="supplier" password="supplier" roles="administrator" />
     <!-- Another crypt example in another format : password is jonas -->
     <!-- JonasAdmin uses name="jonas" password="jonas" -->
     <user name="jonas" password="SHA:NaLG+uYfgHeqth+qQBlyKr8FCTw=" groups="jonas" /> 
     <user name="principal1" password="password1" roles="role1" />
     <user name="principal2" password="password2" roles="role2" />
    </users>
 </memoryrealm>
</jonas-memoryrealm>

	memoryrealm must be named. This name will be used in the web container configuration file
	definition of a security role
	definition of a group of roles
	definition of a user with non encrypted password and a list of roles
	definition of a user with encrypted password (format MD5)
	definition of a user with encrypted password (format SHA)

2.5.1.2. database realm

Users, groups, and roles information are stored in a database; the configuration for accessing the corresponding database is described in the section <jonas-dsrealm>

The configuration requires the name of a datasource, the tables used, and the names of the columns.

<jonas-dsrealm>
   <dsrealm name="dsrlm_1" 
            dsName="jdbc_1" 
      userTable="realm_users" userTableUsernameCol="user_name" userTablePasswordCol="user_pass" 
      roleTable="realm_roles" roleTableUsernameCol="user_name" roleTableRolenameCol="role_name"> 
   </dsrealm>
</jonas-dsrealm>

	dsrealm must be named
	JNDI name of the dataSource for accessing the database via JDBC
	defines the name of the user table and the name of the columns for username/password
	defines the name of the role table and the name of the columns for username/rolename

to use this database a Datasource configuration with the right JNDI name for the dbm service must be set in the jonas.properties file.

Depending on the servlet container used, configuration differs.

To enable authentication mechanism in a client container it is necessary to

In the $JONAS_ROOT/examples/jaasclient directory can be found three examples of container clients using JAAS authentication as well as one java client without container client that uses also JAAS.

The JAAS configuration is made via the JAAS Login Configuration File

A login configuration file consists of one or more entries, each specifying which underlying authentication technology should be used for a particular application or applications.

The contents of the JAAS configuration file has the structure below:

Application_1 {
  LoginModuleClassA Flag Options;
  LoginModuleClassB Flag Options;
  LoginModuleClassC Flag Options;
};

Application_2  {
  LoginModuleClassB Flag Options;
  LoginModuleClassC Flag Options;
};

Other {
  LoginModuleClassC Flag Options;
  LoginModuleClassA Flag Options;
};
  

There is a flag associated with all the LoginModules to configure their behaviour in case of success or failure:

tomcat {
    org.objectweb.jonas.security.auth.spi.JResourceLoginModule required
    resourceName="memrlm_1"
    ;
};

jetty {
    org.objectweb.jonas.security.auth.spi.JResourceLoginModule required
    resourceName="memrlm_1"
    ;
};

jaasclient {
    // Login Module to use for the example jaasclient.

    org.objectweb.jonas.security.auth.spi.JResourceLoginModule required
    resourceName="memrlm_1"

    org.objectweb.jonas.security.auth.spi.ClientLoginModule  required
    globalCtx="true"
    ;
};

-Djava.security.auth.login.config=$JONAS_BASE/conf/jaas.config

The generic JDBC RAs of JOnAS provide implementations of the java.sql.Driver, javax.sql.DataSource, javax.sql.ConnectionPoolDataSource, and javax.sql.XADataSource interfaces. They are located in the $JONAS_ROOT/rars/autoload directory and thus are deployed automatically.They consist of base (or generic) RAs facilitating the build of the user JDBC RAs.

Depending on the relational database management server and the available interface in the used JDBC-compliant driver, the user JDBC RA is linked (through the RAR link feature) to a generic RA (for example, the Driver's one). In this case, the user RA contains only a jonas-ra.xml file with some specific parameters, such as the connection url, the user/password, or the JDBC-Driver class.

The remainder of this section, which describes how to define and configure JDBC RAs, is specific to JOnAS. However, the way to use these JDBC RAs in the Application Component methods is standard, i.e., via the resource manager connection factory references (refer to the example in the section "Writing Database Access Operations" of the Developing Entity Bean Guide).

An RAR file must be deployed as explained in Section 2.4.5, “resource service”.

Usually a resource Adapter contains in its rar file all the classes needed to access to the external resource. In the case of a specific JDBC RA it contains only a JOnAS specific deployment descriptor jonas-ra.xml that tell what sort of generic resource adapter to use and information related to the specific database used. The jar file of the actual JDBC driver mut be copied in the right place to be seen by the JOnAS classloader : $JONAS_BASE/lib/commons.

Changing the configuration of the RA requires extracting and editing the deployment descriptor and updating the archive file. There are several possible ways to do this:

2.6.2.2. Understanding pooling tags:

At JDBC RA deployment time, if pool-init is not null pool-init JDBC connection are created.

When a user requests a jdbc connection, the JDBC RA first checks to see if a connection is already open for its transaction. If not, it tries to get a free connection from the free list. If there are no more connections available, it creates a new jdbc connection (if pool-max is not reached).

If it cannot create new connections, the user must wait (if pool-max-waiters is not reached) until a connection is released. After a limited time (pool-max-waittime), the getConnection returns an exception.

When the user calls close() on its connection, it is put back in the free list.

Many statistics are computed (every pool-sampling-period seconds) and can be viewed by JonasAdmin. This is useful for tuning these parameters and for seeing the server load at any time

When a connection has been open for a time too long (pool-max-age), the pool will try to release it from the freelist. However, the JDBC RA always tries to keep open at least the number of connections specified in pool-min.

When the user has forgotten to close a jdbc connection, the system can automatically close it, after pool-max-opentime minutes. Note that if the user tries to use this connection later, thinking it is still open, it will return an exception (socket closed).

When a connection is reused from the freelist, it is possible to verify that it is still valid. This is configured in jdbc-check-level . For levels >1 it tries a dummy statement on the connection before returning it to the caller. This statement is configured in jdbc-test-statement.

	Note
	this previous description is not only true for JDBC RAs but also for all types of resource adapters, except jdbc-check-level and jdbc-test-statement which are specifics for JDBC.

The P6Spy tool is integrated into JOnAS and it provides an easy way to trace the SQL requests sent to the database.

To enable this tracing feature, perform the following configuration steps:

The migration of a Database.properties file to a similar Resource Adapter can be accomplished through the execution of the following RAConfig tool command. Refer to the JOnAS Commands Reference Guide for a complete description of RAConfig command.

RAConfig -dm -p MySQL1 $JONAS_ROOT/rars/autoload/JOnAS_jdbcDM MySQL_dm

Generates a MySQL_dm.rar file linked to JOnAS_jdbcDM.rar, the jonas-ra.xml file inserted is created with values coming from the ra.xml file of the JOnAS_jdbcDM.rar and values from the MySQL1.properties file

The jonas-ra.xml created by the previous command can be updated further, if desired. Once the additional properties have been configured, update the MySQL_dm.rar file using the following command:

RAConfig -path .  MySQL_dm.rar 

RAConfig -u jonas-ra.xml MySQL_dm.rar 

	Extraction of jonas-ra.xml of MySQL_dm.rar in the working directory
	update MySQL_dm.rar with jonas-ra.xml

The JORAM RA may be seen as the central authority to go through for connecting and using a JORAM platform. The RA is provided with a default deployment configuration which:

This default behaviour is strictly equivalent to the default jms service's behaviour.

The default configuration may, of course, be modified.

The JORAM integration into JOnAS is composed of 3 different parts: server, RA, and administration. Each part contains its own configuration files:

2.7.1.1. JORAM server configuration : a3servers.xml

The a3server.xml ($JONAS_BASE/conf/a3server.xml) file describes the JORAM platform, i.e., the network domain, the used transport protocol, and the reachable JORAM servers. It is used by a JORAM server at start time. By default, only one collocated JORAM server is defined (s0) based on the tcp/ip protocol. A distributed configuration example is provided in the how-to document and other examples are available in JORAM's user guide.

<config>
  <property name="Transaction" value="fr.dyade.aaa.util.NullTransaction/> 
   <server id="0" name="S0" hostname="localhost"> 
    <service class="org.objectweb.joram.mom.proxies.ConnectionManager"
             args="root root"/>
    <service class="org.objectweb.joram.mom.proxies.tcp.TcpProxyService"
             args="16010"/> 

   </server>
</config>

	This property means that the non persistent mode for JMS is choosen. In order to use persistent mode, the value must be changed to "fr.dyade.aaa.util.NTransaction"
	Here can be set the server id and the host where the server run
	args specifies the port number the JORAM server is listening on

The above configuration describes a JORAM platform made up of one unique JORAM server (id 0, name s0), running on localhost, listening on port 16010. Those values are taken into account by the JORAM server when starting. However, they should match the values set in the deployment descriptor of the RA, otherwise the adapter either will not connect to the JORAM server, or it will build improper connection factories.

The joram_raconfig command allows to modify these parameters in all the configuration files.

If used in non-collocated mode, joram can be started with the JmsServer command which loads the $JONAS_BASE/conf/a3server.xml configuration file.

2.7.1.3. JMS Applications Configuration

joramAdmin.xml file describes the configuration related to the application. It describes the administration objects in the JORAM server such as the JMS objects, the users, or the non-managed factories. In other words, it defines the JORAM objects to be (optionally) created when deploying the adapter.

In earlier version the joram-admin.cfg was used for this same purpose but it is now deprecated.

The default file provided with JOnAS creates a queue bound with the name sampleQueue, a topic bound with the name sampleTopic, sets the anonymous user, and creates and binds non-managed connection factories named JCF, JQCF and JTCF

Note

All administration tasks are performed by the server connected but may affect remote JORAM servers to which the adapter is connected through the ServerId attribute. If a queue, a topic or a user already exists on the JORAM server (for example, because the server is in persistent mode and has re-started after a crash, or because the adapter has been deployed, undeployed and is re-deployed giving access to a remote JORAM server), it will be retrieved instead of being re-created.

The format of this file is XML. Here are some examples:

• simple example:

  <?xml version="1.0"?>
        <JoramAdmin>
          <AdminModule>
            <collocatedConnect name="root" password="root"/>
          </AdminModule>
          <ConnectionFactory className="org.objectweb.joram.client.jms.tcp.TcpConnectionFactory">
            <tcp host="localhost"
                    port="16010"/>
            <jndi name="JCF"/>
          </ConnectionFactory>
          <ConnectionFactory className="org.objectweb.joram.client.jms.tcp.QueueTcpConnectionFactory">
            <tcp host="localhost"
                    port="16010"/>
            <jndi name="JQCF"/>
          </ConnectionFactory>
          <ConnectionFactory className="org.objectweb.joram.client.jms.tcp.TopicTcpConnectionFactory">
            <tcp host="localhost"
                    port="16010"/>
            <jndi name="JTCF"/>
          </ConnectionFactory>
          <User name="anonymous"
                   password="anonymous"
                   serverId="0"/>
          <Queue name="sampleQueue">
            <freeReader/>
            <freeWriter/>
            <jndi name="sampleQueue"/>
          </Queue>
          <Topic name="sampleTopic">
            <freeReader/>
            <freeWriter/>
            <jndi name="sampleTopic"/>
          </Topic>
        </JoramAdmin>

• For requesting the creation of a new object, simply add the element in the file. For example, to add a queue 'MyQueue', add the following XML element:

          <Queue name="myQueue">
            <freeReader/>
            <freeWriter/>
            <jndi name="myQueue"/>
          </Queue>

• When the JORAM is not collocated, the AdminModule must be defined as follows:

        <AdminModule>
          <connect host="localhost"
                   port="16020"
                   name="root"
                   password="root"/>
        </AdminModule>

  The port number must be set with the server port number (defined in the a3servers.xml and in the JORAM's RAR configuration ra.xml and jonas-ra.xml files).

• Possible parameters for a queue definition:

         <Queue name=""
                   serverId=""
                   className=""
                   dmq=""
                   nbMaxMsg=""
                   threshold="">
           <property name="" value=""/>
           <property name="" value=""/>
           <reader user=""/>
           <writer user=""/>
           <freeReader/>
           <freeWriter/>
           <jndi name=""/>
           </Queue>

• Possible parameters for a topic definition:

        <Topic name=""
                  parent=""
                  serverId=""
                  className=""
                  dmq="">
          <property name="" value=""/>
          <property name="" value=""/>
          <reader user=""/>
          <writer user=""/>
          <freeReader/>
          <freeWriter/>
          <jndi name=""/>
        </Topic>

• Example of a dead message queue definition:

        <DMQueue name="DMQ"
                    serverId="0">
          <reader user="anonymous"/>
          <writer user="anonymous"/>
          <freeReader/>
          <freeWriter/>
          <jndi name="DMQ"/>
        </DMQueue>

• Example of a scheduler queue definition:

        <Destination type="queue"
                        serverId="0"
                        name="schedulerQueue"
                        className="com.scalagent.joram.mom.dest.scheduler.SchedulerQueue">
          <freeReader/>
          <freeWriter/>
          <jndi name="schedulerQueue"/>
        </Destination>

• Example of a clustered queues destination:

          <Cluster>
            <Queue name="queue0"
                      serverId="0"
                      className="org.objectweb.joram.mom.dest.ClusterQueue">
              <freeReader/>
              <freeWriter/>
              <property name="period" value="10000"/>
              <property name="producThreshold" value="50"/>
              <property name="consumThreshold" value="2"/>
              <property name="autoEvalThreshold" value="false"/>
              <property name="waitAfterClusterReq" value="1000"/>
              <jndi name="queue0"/>
            </Queue>
            <Queue name="queue1"
                      serverId="1"
                      className="org.objectweb.joram.mom.dest.ClusterQueue">
              <freeReader/>
              <freeWriter/>
              <property name="period" value="10000"/>
              <property name="producThreshold" value="50"/>
              <property name="consumThreshold" value="2"/>
              <property name="autoEvalThreshold" value="false"/>
              <property name="waitAfterClusterReq" value="1000"/>
              <jndi name="queue1"/>
            </Queue>
            <Queue name="queue2"
                      serverId="2"
                      className="org.objectweb.joram.mom.dest.ClusterQueue">
              <freeReader/>
              <freeWriter/>
              <property name="period" value="10000"/>
              <property name="producThreshold" value="50"/>
              <property name="consumThreshold" value="2"/>
              <property name="autoEvalThreshold" value="false"/>
              <property name="waitAfterClusterReq" value="1000"/>
              <jndi name="queue2"/>
           </Queue>
           <freeReader/>
           <freeWriter/>
           <reader user="user0"/>
           <writer user="user0"/>
           <reader user="user1"/>
           <writer user="user1"/>
           <reader user="user2"/>
           <writer user="user2"/>
         </Cluster>

Undeploying a JORAM adapter either stops the collocated JORAM server or disconnects from a remote JORAM server. It is then possible to deploy the same adapter again. If set for running a collocated server, it will re-start it. If the running mode is persistent, then the server will be retrieved in its pre-undeployment state (with the existing destinations, users, and possibly messages). If set for connecting to a remote server, the adapter will reconnect and access the destinations it previously created.

In the collocated persistent case, if the intent is to start a brand new JORAM server, its persistence directory should be removed. This directory is located in JOnAS' running directory and has the same name as the JORAM server (for example, s0/ for server "s0").

For both container-managed or bean-managed persistence, JOnAS makes use of relational storage systems through the JDBC interface. JDBC connections are obtained from an object, the DataSource, provided at the application server level. The DataSource interface is defined in the JDBC standard extensions.

A DataSource object identifies a database and a means to access it via JDBC (a JDBC driver). An application server may request access to several databases and thus provide the corresponding DataSource objects that will be registered in JNDI registry.

This section explains how DataSource objects can be defined and configured in the JOnAS server.

JOnAS provides a generic driver-wrapper that emulates the XADataSource interface on a regular JDBC driver. It is important to note that this driver-wrapper does not ensure a real two-phase commit for distributed database transactions.

Neither the EJB specification nor the Java EE specification describe how to define DataSource objects so that they are available to a Java EE platform. Therefore, this document, which describes how to define and configure DataSource objects, is specific to JOnAS. However, the way to use these DataSource objects in the Application Component methods is standard, that is, by using the resource manager connection factory references (refer to the example in the section "Writing database access operations" of the Developing Entity Bean Guide).

A DataSource object should be defined in a file called <DataSource name>.properties (for example Oracle1.properties for an Oracle DataSource or Postgres.properties for an PostgreSQL DataSource.These files must be located in $JONAS_BASE/conf directory.

In the jonas.properties file, to define a DataSource "Oracle1.properties" add the name "Oracle1" to the line jonas.service.dbm.datasources, as follows:

jonas.service.dbm.datasources Oracle1, Sybase, PostgreSQL

The property file defining a DataSource may contain two types of information:

###################### Oracle DataSource configuration example
#


#####
#  DataSource configuration
#
datasource.name  jdbc_1
datasource.url  jdbc:oracle:thin:@<your-hostname>:1521:<your-db>
datasource.classname oracle.jdbc.driver.OracleDriver
datasource.username <your-username>
datasource.password <user-password>
datasource.mapper rdb.oracle


#####
#  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 0

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

# Maximum time (in mn) a connection can be left busy.
# If the caller has not issued a close() during this time, the connection
# will be closed automatically.
jdbc.maxopentime 60

#  Test statement
jdbc.connteststmt select * from dual

# JDBC Connection Pool size.
# Limiting the max pool size avoids errors from database.
jdbc.minconpool 10
jdbc.maxconpool 30

# Sampling period for JDBC monitoring :
# nb of seconds between 2 measures.
jdbc.samplingperiod 30

# Maximum time (in seconds) to wait for a connection in case of shortage.
# This may occur only when maxconpool is reached.
jdbc.maxwaittime 5

# Maximum of concurrent waiters for a JDBC Connection
# This may occur only when maxconpool is reached.
jdbc.maxwaiters 100

The P6Spy tool is integrated within JOnAS to provide a means for easily tracing the SQL requests that are sent to the database.

To enable this tracing feature, perform the following configuration steps:

Example of dataSource properties file:

datasource.name       jdbc_3
datasource.url        jdbc:postgresql://your_host:port/your_db
datasource.classname  com.p6spy.engine.spy.P6SpyDriver
datasource.username   jonas
datasource.password   jonas
datasource.mapper     rdb.postgres
    

Within JONAS_BASE/conf/spy.properties file:

realdriver=org.postgresql.Driver

Within JONAS_BASE/conf/trace.properties:

logger.org.objectweb.jonas.jdbc.sql.level  DEBUG

Names can be defined in a static way, through the domain.xml configuration file, or dynamically, by starting new elements in the domain. For example, when starting a JOnAS instance, the administrator can specify the server name using the -n option and the domain name by setting the domain.name environment property. The uniqueness of the starting server's name is enforced by the discovery service.

The first step is to choose a name for the domain (domainName) and to choose a server to represent the common administration point. This means install a JOnAS server if needed, then configure it as a master, namely by adding the discovery service in the JOnAS services list (jonas.services property) and setting the jonas.service.discovery.master property to true.

The domain name is not a configuration property for the master (neither for any server in the domain), but it has to be specified when starting the master.

Before starting the master, the administrator can define the domain's initial topology by editing the domain.xml configuration file.

This step is optional. It consists in defining the domain elements using the domain.xml configuration file located in the master's directory. If the administrator has no specific configuration needs, it should at least check the domain name element, and set its value to the chosen domainName. Moreover, the administrator can choose to remove the domain.xml file.

The elements that can be defined in domain.xml are:

Start the master in the domain:

jonas start -n masterName -Ddomain.name=domainName

Note that the domain name can be specified by setting a domain.name environment property.

Once started, the administrator can manage and monitor the following elements in the domain through JonasAdmin, or another JMX based administration application, running on the master:

As with other Apache modules, mod_jk should be first installed on the modules directory of the Apache Web Server and the httpd.conf file has to be updated. Moreover, mod_jk requires workers.properties file that describes the host(s) and port(s) used by the workers.

# -----------------------
# List the workers name
# -----------------------
worker.list=myloadbalancer,jkstatus

# -----------------------
# worker1
# -----------------------
worker.worker1.port=9010
worker.worker1.host=localhost
worker.worker1.type=ajp13
# Load balance factor
worker.worker1.lbfactor=1
# Define preferred failover node for worker1
#worker.worker1.redirect=worker2
# Disable worker1 for all requests except failover
#worker.worker1.disabled=True

# -----------------------
# worker2
# -----------------------
worker.worker2.port=9011
worker.worker2.host=localhost
worker.worker2.type=ajp13
# Load balance factor
worker.worker2.lbfactor=1
# Define preferred failover node for worker2
#worker.worker2.redirect=worker2
# Disable worker2 for all requests except failover
#worker.worker2.disabled=True

# -----------------------
# Load Balancer worker
# -----------------------
worker.myloadbalancer.type=lb
worker.myloadbalancer.balanced_workers=worker1,worker2
worker.mylloadbalancer.sticky_session=false
# -----------------------
# jkstatus worker
# -----------------------
worker.jkstatus.type=status

# Load mod_jk module
# Update this path to match your modules location
LoadModule jk_module modules/mod_jk.so
# Location of the workers.properties file
# Update this path to match your conf directory location (put workers.properties next to httpd.conf)
JkWorkersFile /etc/httpd/conf/workers.properties
# Location of the log file
JkLogFile /var/log/mod_jk.log
# Log level : debug, info, error or emerg
JkLogLevel info
# Select the timestamp log format
JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "
# Shared Memory Filename ( Only for Unix platform ) required by loadbalancer
JkShmFile /var/log/jk.shm
# Assign specific URL to the workers
JkMount /clusteredExample myloadbalancer
JkMount /clusteredExample/* myloadbalancer
# A mount point to the status worker
JkMount /jkmanager jkstatus
JkMount /jkmanager/* jkstatus
# Enable the Jk manager access only from localhost
<Location /jkmanager/>
    JkMount jkstatus
    Order deny,allow
    Deny from all
    Allow from 127.0.0.1
</Location>

Each member needs an AJP13 connector listening on the port defined in the workers.properties file. Moreover, the worker name (here worker1/worker2) must be used as value for the Engine's jvmRoute attribute.

Here is a chunk of server.xml configurations file for the member worker1:

<Server>
 <!-- Define the Tomcat Stand-Alone Service -->
 <Service name="Tomcat-JOnAS">
  <!-- Define a non-SSL Coyote HTTP/1.1 Connector on port 9000 -->
  <Connector port="9000" maxHttpHeaderSize="8192" maxThreads="150"
    minSpareThreads="25" maxSpareThreads="75" enableLookups="false"
    redirectPort="9043" acceptCount="100"
    connectionTimeout="20000" disableUploadTimeout="true"/>
  <!-- AJP 1.3 Connector on port 9010 for worker.worker1.port in workers.properties file -->
  <Connector port="9010" enableLookups="false" redirectPort="9043" protocol="AJP/1.3"/>

  <!-- An Engine represents the entry point
  You should set jvmRoute to support load-balancing via AJP ie :
  -->
  <Engine name="jonas" defaultHost="localhost" jvmRoute="worker1">

  </Engine>
 </Service>
<Server>

To allow cluster member discovery and dynamic cluster creation, the workers.properties file required by mod_jk should be copied to the master's JONAS_BASE/conf directory.

At start-up, the master reads the workers.properties file content. For each balanced worker it checks if there is a running server in the domain having the appropriate configuration allowing the server to play that worker role.

Suppose that the master detects a server in the domain corresponding to worker1. Then, it constructs a JkCluster named myloadbalancer. This name is given by the load balancer worker's name. At this moment, the cluster is composed of one member named worker1. The member name is given by the balanced worker's name.

After a while, a new JOnAS server is started in the domain having the configuration corresponding to the worker2. The master detects the new member named worker2 and updates the cluster's member list.

Here is the myloadbalancer JkCluster with workers started:

The concerned configuration file is the carol.properties file.

Common configuration values:

Specific configuration values:

The configuration file defines the JGroups protocol stack configuration. The default jgroups-cmi.xml file contains a UDP protocol stack based on IP multicast. Each member has to use the same multicast address and multicast port number.