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

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 Java EE 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 JOnAS servers having common properties within a domain. 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.

The installation directory (JONAS_ROOT) has the following structure:

JONAS_BASE has the following structure:

This directory contains configuration files in various format (properties files, 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.5.1. Global properties

#  Name of the JOnAS server
#  default value is "jonas"
jonas.name    jonas

#  Name of the JOnAS domain
#  default value is "jonas"
domain.name    jonas

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

#  Enable the Security manager
#  default value is true (if not set)
#  Setting this to false implies a collocated registry and setting in carol.properties:
#  carol.jvm.rmi.local.registry=true
jonas.security.manager    false

#  Enable csiv2
jonas.csiv2.propagation    true

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

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

#  Set to true if the server is a master
jonas.master    false

#  Set to true in order to execute the JOnAS Server in development mode.
#
#  WAR archive deployment case in development mode (for single or EAR packaged WARs):
#  Each modified WAR archive will be unpacked in the working directory of the JOnAS Server
#  in a different folder to avoid file locks. This is especially useful in a Windows environment.
jonas.development    true

	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    jtm, db, security, resource, ejb3, jaxws, web, ear, depmonitor

registry, jmx, security, jtm, db, mail, wc, dbm, wm, resource, cmi, ha, versioning, ejb2, ejb3, jaxrpc, jaxws, web, ear, depmonitor, discovery, resourcemonitor, smartclient, wsdl-publisher

2.1.5.3. Service startup policies

JOnAS will try to start declared services in the order in which they appear in the list except for the depmonitor service which is always started at the end. If some services require other ones (even non declared in the list), service requirements will be started first.

To simplify the declaration of JOnAS services and to ensure that all service requirements are fulfilled, some services declare explicitly their dependencies in order to start them automatically.

The picture below describes mandatory dependencies beetwen JOnAS services. A link between two services means that a service requires another one. Note on the right side services without dependency links.

	Caution
	Optional service dependencies are not described in this picture. They have to be declared in the list of JOnAS services when required.

• registry and jmx services can be omitted from the list because they are automatically launched.

• As an example, starting the web service involves the startup of the security service. Declaring the web service in the list of JOnAS services without declaring the security service may be a solution.

• As an example, starting the resource service involves the startup of the wm and the jtm services. Declaring the resource service in the list of JOnAS services without declaring the wm and the jtm service may be a solution.

###################### JOnAS JTM Transaction service configuration
#  Set the name of the implementation class of the jtm service
jonas.service.jtm.class    org.ow2.jonas.tm.jotm.JOTMTransactionService

#  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

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 

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.ow2.jonas.registry.carol.delegate.JacORBPRODelegate  

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. enabling clustering of RMI objects

CMI is the component to use for clustering purpose. It is embedded in the component CAROL.

CMI is just composed of wrappers and interceptors and is fully independant of the implementation of protocol. CMI relies on JGroups group-communication protocol for ensuring the replication of the cluster view. CMI provides jndi high availability, the load-balancing and fail-over at the EJB level.

For using CMI with a protocol (in addition to the activation of service cmi), a property must be added in carol.properties:

carol.jrmp.cmi=true 
carol.iiop.cmi=true
carol.irmi.cmi=false 

	Enable clustering with jrmp
	Disable clustering with imi

	Note
	By default, the property is set at true.

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=iiop,jrmp
carol.jrmp.url=rmi://localhost:1099
carol.iiop.url=iiop://localhost:2001

	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.ow2.level INFO

#logger.org.ow2.jonas.lib.ejb21.level DEBUG 

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

logger.org.ow2.jonas.generators.genic.handler.0 mesonly 
logger.org.ow2.jonas.generators.genic.additivity false 

[...]

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.

The configuration of the cmi service is available through the file $JONAS_BASE/conf/cmi-config.xml.

The CMI service can be configured in two modes:

The server mode is simpler to configure, the client mode requires to define statically a list of providers urls. The server mode starts a Group Communication Protocol instance (e.g. JGroups) and thus increases the resources consumption compare to the client mode.

	Note
	The CMI configuration file may contain two parts: a server element which corresponds to the server mode configuration and a client element for the client mode configuration. If the two are present, only the server element is loaded which means that the server mode is configured.

2.4.1.1. Server mode configuration

The server element contains the following elements:

Example 2.1. Configuring the cmi service in the server mode

  
<cmi xmlns="http://org.ow2.cmi.controller.common"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xmlns:jgroups="http://org.ow2.cmi.controller.server.impl.jgroups">
    <server>
        <jndi> 
            <protocol name="jrmp" noCmi="false" />
        </jndi>
        <viewManager  
            class="org.ow2.cmi.controller.server.impl.jgroups.JGroupsClusterViewManager"> 
            <jgroups:config 
                    delayToRefresh="60000" 
                    loadFactor="100" 
                    confFileName="jgroups-cmi.xml" 
                    recoTimeout="30000" 
                    groupName="G1"> 
                <components> 
                 <event />
                </components>
            </jgroups:config>
        </viewManager>
    </server>
</cmi>

	jndi element - optional. Enable to specify that a protocol must not be clustered with CMI (administration uses, ...). Here, the clustering of jrmp protocol can be disabled by setting true to the noCmi attribute.
	viewManager element - mandatory. Defines the view manager configuration (registry replication, refresh time, ...).
	class attribute - mandatory. Specifies the protocol implementation to use for replicating the view (CMI registry). Here the JGroups implementation is set.
	jgroups:config element - mandatory. Define the JGroups related parameters.
	delayToRefresh attribute - optional. Refresh period of the client view (in ms). For example, it expresses the maximum delay for taking into account a load-balancing parameter update.
	loadFactor attribute - optional. Specifies the initial load-factor of the current node used in the weigthed round robin policy.
	confFileName attribute - mandatory. Specifies the JGroups's stack configuration filename (found in the $JONAS_BASE/conf directory).
	recoTimeout attribute - optional. Specifies the reconnection timeout after a shunning or an error in the group communication protocol (in ms). If the timer expires, an exception is thrown.
	groupName attribute - mandatory. Specifies the JGroups channel name used by the CMI cluster view replication mechanism.
	components element - mandatory. Enable the events component into CMI. This element must not be modified.

	Note
	Refer to the clustering guide for issues related to JGroups.

  
<cmi xmlns="http://org.ow2.cmi.controller.common"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <client noCmi="false"> 
    	<jndi> 
        	<protocol name="jrmp">
            	<providerUrls> 
                	<providerUrl>rmi://localhost:1099</providerUrl>
                	<providerUrl>rmi://localhost:2001</providerUrl>
            	</providerUrls>
        	</protocol>
    	</jndi>
    </client>
</cmi>

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
#
#  Sets the name of the implementation class of the db service (hsql for example)
jonas.service.db.class   org.ow2.jonas.db.hsqldb.HsqlDBServiceImpl
jonas.service.db.port    9001
jonas.service.db.dbname  db_jonas
jonas.service.db.users   jonas:jonas

# Multiple users
#jonas.service.db.users  jonas:jonas,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.

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.

In order to launch several HSQLDB instances, the configuration needs to be duplicated and the new configuration will be prefixed by jonas.service.<mynewdbservice>.

The depmonitor service scans periodically some directories in the aim of deploying J2EE applications or OSGi bundles on a JOnAS server. By default, you have to put the application files into the $JONAS_BASE/deploy directory in order to deploy them. It is possible to parse other directories by setting the directories property in the service configuration.

The development attribute in the configuration allows to choose if the depmonitor service is in development mode or not :

As the parsed directories may contain files that must not be deployed, a list of file exclusions can be defined.

###################### JOnAS Deployment Monitor
#
# Set the name of the implementation class of the depmonitor service
#
jonas.service.depmonitor.class          org.ow2.jonas.deployablemonitor.DeployableMonitorService

# Set the execution mode (three possible values):
# - inherit: inherit of the value of the "jonas.development" property 
# - true   : development mode
# - false  : production mode
jonas.service.depmonitor.development    inherit                                      

jonas.service.depmonitor.directories                                                  
# List (comma separated) of exclusion patterns (based on names, not directories)          
jonas.service.depmonitor.exclusions     README                                       

# Monitor interval in milliseconds
jonas.service.depmonitor.monitorInterval    5000                                     

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.ow2.jonas.dbm.internal.JOnASDataBaseManagerService

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

The role of the discovery service is to enable dynamic domain management. Recall that domain management means management of all the servers running in the domain, from the common administration point represented by a master server.

The discovery service allows a master to detect servers starting and stopping in the domain. Moreover, a master can discover servers there were already running in the domain when it started.

The discovery service implements a greeting mechanism to enforce servers' name unicity in the domain. This mechanism prevents starting a new server in the domain, if a server having the same name is already running in the domain.

There are two available implementations for the discovery service: one based on IP multicast, the other based on JGroups. The former, introduced in JOnAS 4, is deprecated. The latter, has the advantage to allow for cluster daemons detection.

All servers and in the domain must choose the same implementation. The choice is made upon the implementation class name:

###################### JOnAS Discovery service
#
#  Set the name of the implementation class and initialization parameters
# JGropus implementation 
jonas.service.discovery.class=org.ow2.jonas.discovery.jgroups.JgroupsDiscoveryServiceImpl
# Uncomment this to set Multicast implementation
#jonas.service.discovery.class=org.ow2.jonas.discovery.internal.MulticastDiscoveryServiceImpl

jonas.service.discovery.multicast.address=224.224.224.224
jonas.service.discovery.multicast.port=9080
jonas.service.discovery.ttl=1
#  For a master server, configure the client source port with this property
jonas.service.discovery.source.port=9888

#  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

2.4.5.2. Configuration for JGroups based implementation

JGropups configuration being more complex, a specific configuration file have to be used. The name of this file is given by the jonas.service.discovery.jgroups.conf property. Two other properties have to be initialized:

• The name of the JGroups group used by the the discovery service to exchange messages.

  • jonas.service.discovery.group.name

• The reconnection timeout for the JGroups channel.

  • jonas.service.discovery.group.reconnection.timeout

Example:

jonas.service.discovery.jgroups.conf=jgroups-discovery.xml
jonas.service.discovery.group.name=JGroupsDiscovery
jonas.service.discovery.group.reconnection.timeout=5000

You can find in JOnAS distribution, under JONAS_ROOT/conf, a jgroups-discovery.xml file. This file containes a JGroups stack configuration for the UDP protocol.

	Note
	Refer to the clustering guide for issues related to JGroups.

  <discovery>
    <group-name>JGroupsDiscovery</group-name>
    <stack-file>jgroups-discovery.xml</stack-file>
    <start-up>true</start-up>
  </discovery>

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 ejb2 or ejb3 service for deploying the EJB containers for the included ejb-jars and the resource service for deploying the included rars.

In development mode, as all other Java EE archives ear archives can be deployed automatically as soon as they are copied under $JONAS_BASE/deploy (or under another configuration-defined directory) and undeployed as soon as they has been removed from this location.

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.ow2.jonas.ear.internal.JOnASEARService

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

# Generate stubs for all EJBs that may be accessed from the application
# In almost all cases, this is not required to be enabled as stubs can be found.
jonas.service.ear.genstub    true

# Create a child classloader when deploying EJB3 of the EAR
jonas.service.ear.useEJB3ChildClassloader    true

This service provides containers for EJB2.1 components.

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

The ejb service can (and by default does) provide monitoring options. Monitoring provides the following values at a per-EJB basis for stateful and stateless beans:

The warningThreshold option can be used to generate a warning each time a method takes more than warningThreshold milliseconds to execute. By default, warningThreshold is set to 20 seconds.

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

###################### JOnAS EJB 2 Container service configuration
#
#  Set the name of the implementation class of the ejb2 service
jonas.service.ejb2.class    org.ow2.jonas.ejb2.internal.JOnASEJBService

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

# 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.ejb2.auto-genic    true

# Arguments for the auto GenIC (-invokecmd, -verbose, etc.)
jonas.service.ejb2.auto-genic.args -invokecmd

#  Note: these two settings can be overriden by the EJB descriptor.
#
#  If EJB monitoring is enabled, statistics about method call times will be
#  collected. This is a very lightweight measurement and should not have much
#  impact on performance.
jonas.service.ejb2.monitoringEnabled true
#  If EJB monitoring is enabled, this value indicates after how many
#  milliseconds spent executing an EJB method a warning message should be
#  displayed. If 0, no warning will ever be displayed.
jonas.service.ejb2.warningThreshold 20000

For customizing the ejb2 service it is possible to:

The ejb3 service provides EJB 3 container support. This service is provided by the EasyBeans container.

The declaration of the ejb3 service is done in the jonas.properties file.

###################### JOnAS EJB 3 container service configuration
#
#  Set the name of the implementation class of the EJB 3 service.
jonas.service.ejb3.class    org.ow2.jonas.ejb.easybeans.EasyBeansService

#  List (comma separated) of JPA providers: hibernate,eclipselink
jonas.service.ejb3.jpa.providers hibernate

The jonas.service.ejb3.jpa.providers property allows to define a list of JPA providers that could be used by EasyBeans. For the moment, Hibernate and EclipseLink JPA providers are available.

EasyBeans has its own configuration file that is located in JONAS_BASE/conf folder. The name of the configuration file is easybeans-jonas.xml.

By default, EasyBeans is using only services provided by JOnAS. Thus, no additional components are required for starting EasyBeans.

<?xml version="1.0" encoding="UTF-8"?>
<easybeans xmlns="http://org.ow2.easybeans.server">

    <!-- No infinite loop (managed by JOnAS): wait="false"
         Enable MBeans: mbeans="true"
         Disable the naming: naming="false"
         Use JOnAS JACC provider: jacc="false"
         Using JOnAS monitoring: scanning="false"
         Using JOnAS JMX Connector: connector="false"
         Disable Deployer and J2EEServer MBeans: deployer="false" & j2eeserver="false"
    -->
    <config
        wait="false"
        mbeans="true"
        naming="false"
        jacc="false"
        scanning="false"
        connector="false"
        deployer="false"
        j2eeserver="false" />

    <!-- Define components that will be started at runtime -->
    <components>
        <!-- All components are launched by JOnAS -->

        <!-- RMI component will be used to access some of JNDI properties -->
        <!-- But as there are no protocols, no registry is launched. -->
        <rmi />

        <!-- Start smartclient server with a link to the rmi component-->
        <!--smart-server port="2503" rmi="#rmi" /-->
    </components>
</easybeans>

The <config> element describes EasyBeans configuration properties that may be different for each application server. The settings provided in this file are the JOnAS settings and they shouldn't be modified in almost any cases.

The <component> element defines the EasyBeans components that will be started at the startup. Here EasyBeans is integrated in JOnAS, it will thus use JOnAS services like transaction, security, naming, registry.

The smart client component provides a mechanism for downloading classes missing on the client side, from the server side. This allows to have a very small library on the client side and it downloads classes on demand. When this component is enabled, the listening port can be configured. More documentation on the Smart component can be found in EasyBeans documentation.

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.ow2.jonas.ha.internal.HaServiceImpl

# 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.gc.period 600 

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

# Reconnection timeout for JGroups Channel, if it's closed on request.
jonas.service.ha.reconnection.timeout 5000 

	Note
	Refer to the clustering guide for issues related to JGroups.

The jaxrpc service provides a JAX-RPC 1.1 support for applications using J2EE 1.4 style webservices. J2EE 1.4 style webservices are POJO or Stateless EJB 2.x exposed as webservices using old school deployment descriptors (WEB-INF/webservices.xml or META-INF/webservices.xml)

It is based on the Axis 1.x implementation.

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

###################### JOnAS JAX-RPC service configuration
#
#  Set the name of the implementation class of the jaxrpc service.
jonas.service.jaxrpc.class    org.ow2.jonas.ws.axis.AxisService

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

# Set the Generator to use with wsgen
jonas.service.jaxrpc.wsgen.generator.factory     org.ow2.jonas.generators.wsgen.generator.ews.EWSGeneratorFactory

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

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

It is possible to :

The jaxws service provides a JAX-WS 2.0 support for applications using Java EE 5 style webservices.

It is required to declare it if the configured JOnAS instance have to deploy Java EE application or modules that contains @WebService annotated classes (for the service endpoints) or if they contains @WebServiceRef / @WebServiceRefs (for client side usage of a webservice).

	Note
	If this service is not activated and deployed applications are using JAX-WS 2.0 APIs, @WebService annotated POJO or EJB 3.0 will not be exposed as webservices and @WebServiceRef fields/methods will not be injected (may conduct to NullPointerExceptions).

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

###################### JOnAS JAX-WS 2.x service configuration
#
#  Set the name of the implementation class of the jaxws service
jonas.service.jaxws.class    org.ow2.jonas.ws.cxf.CXFService

The jmx service is a mandatory service, so its automatically started in order to administrate or instrument the JOnAS server. It uses the JMX extensions provided by the current Java EE platform.

The jmx service creates at stratup, one or more JMX Remote connectors (one for each protocol configured in CAROL, seeSection 2.2, “Configuring the communication protocol and JNDI”). This allows remote management for JMX-based administration applications. A connector's address is based on the corresponding protocol's URL, the protocol name and the server name.

Let's consider the default CAROL configuration, where the RMI/JRMP protocol is used with the following URL:

carol.protocols=jrmp
carol.jrmp.url=rmi://localhost:1099

The address of the JMX Remote connector for a server named myJonas is:

service:jmx:rmi:///jndi/rmi://localhost:1099/jrmpconnector_myJonas

The jmx service can be started in secured or non-secured mode:

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.ow2.jonas.jmx.internal.JOnASJMXService

#  Set to true if the JMXRemote interface should require the client to provide
#  authentication information. That information is provided when establishing
#  the JMX connection, using the JMXConnector.CREDENTIALS key.
#
#  Note that if you enable JMX security for a server, all clients (including
#  any administration tool such as the domain master) connecting to this
#  instance via JMX must provide a valid user name and password.
jonas.service.jmx.secured                       false

#  If jonas.service.jmx.secured is set to true, defines the authentication
#  method and the method's parameter. For example, to use file-based
#  authentication using the conf/jmx.passwords file, define:
#      jonas.service.jmx.authentication.method    jmx.remote.x.password.file
#      jonas.service.jmx.authentication.parameter conf/jmx.passwords
#  You are free to use the authentication provider you wish.
jonas.service.jmx.authentication.method         jmx.remote.x.password.file
jonas.service.jmx.authentication.parameter      conf/jmx.passwords
#  You may for example choose to use JAAS LoginModule for authentication.
#  In this case define the used configuration in the JAAS configuration file
#  using the jonas.service.jmx.authentication.parameter:
#      jonas.service.jmx.authentication.method      jmx.remote.x.login.config
#      jonas.service.jmx.authentication.parameter   jaas-jmx

#  If jonas.service.jmx.secured is set to true, defines the authorization
#  method and the method's parameter. For example, to use file-based
#  authorization using the conf/jmx.access file, define:
#      jonas.service.jmx.authorization.method    jmx.remote.x.access.file
#      jonas.service.jmx.authorization.parameter conf/jmx.access
#  You are free to use the authorization provider you wish.
jonas.service.jmx.authorization.method          jmx.remote.x.access.file
jonas.service.jmx.authorization.parameter       conf/jmx.access
#  You may for example choose to use role-based authorization manager
#  configured using conf/jmx.rolebased.access file. In this case, define:
#      jonas.service.jmx.authorization.method          jmx.remote.x.access.rolebased.file
#      jonas.service.jmx.authorization.parameter       conf/jmx.rolebased.access

The jtm service is used by ejb2 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.ow2.jonas.tm.jotm.JOTMTransactionService

#  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 mail service is an optional service that may be used to send emails.

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 mails. 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.ow2.jonas.mail.internal.JOnASMailService

#  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. For example, consider two factories called MailSession1 and MailMimePartDS1. 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

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.ow2.jonas.registry.carol.CarolRegistryService

#  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 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^[6].

Resource Adapter are packaged in Java EE rar archives.

In development mode, as all other Java EE archives rar archives can be deployed automatically as soon as they are copied under $JONAS_BASE/deploy and undeployed as soon as they has been removed from this location.

For more information see Section 2.4.3, “depmonitor service configuration”.

The other ways to deploy rar archives is

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.ow2.jonas.resource.internal.JOnASResourceService

The worker thread pool used for all J2CA 1.5 Resource Adapters deployed can be configured in the Section 2.4.22, “wm service configuration” service.

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.

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”

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.ow2.jonas.security.internal.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

# Enable security context check on Remote Login Module
jonas.security.context.check    false

# Path to the keystore file
jonas.security.context.check.keystoreFile /tmp/keystore

# Pass used for the keystore file
jonas.security.context.check.keystorePass keystorepass

# Alias (stored in the keystore)
jonas.security.context.check.alias FB

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.5.1, “Global 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 smartclient lets remote clients download classes and other resources necessary for connecting to JOnAS services (JNDI context factories, EJB3 interceptors, ...) directly from the JOnAS server they're dealing with.

This way, the heavy clients only need to include a lightweight JAR file for the Smartclient client and are always guaranteed to have the good versions of all components.

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

###################### JOnAS/EasyBeans Smartclient service configuration
#
#  Set the name of the implementation class of the smartclient service.
jonas.service.smartclient.class         org.ow2.jonas.smartclient.internal.SmartclientServiceImpl
# port number the Smartclient service listens on
jonas.service.smartclient.port          2503

The wc service allows to clean up periodically the work directory of the JOnAS server. This service don't need to be defined in the list of JOnAS services as it is automatically started when JOnAS is in development mode.

During the deployment process of an application, a specific working directory is created and associated to the application. After a defined time, the clean task tries to delete working directories of applications which have been undeployed. Note that the clean task is already executed at startup of the JOnAS server.

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

###################### JOnAS WorkCleaner service configuration
#
#  Set the name of the implementation class of the wc service
jonas.service.wc.class    org.ow2.jonas.workcleaner.internal.JOnASWorkCleanerService

#  Set the clean period in seconds
jonas.service.wc.period   300                                     

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

JOnAS provides two implementations of this service: one for Jetty 6.x, one for Tomcat 6.x. It is necessary to run this service in order to use the JonasAdmin tool. A web container is created from a war file.

In development mode, as all other Java EE archives war archives can be deployed automatically as soon as they are copied under $JONAS_BASE/deploy and undeployed as soon as they has been removed from this location.

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.ow2.jonas.web.tomcat6.Tomcat6Service
#jonas.service.web.class    org.ow2.jonas.web.jetty6.Jetty6Service

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

#  If true, the onDemand feature is enabled. A proxy is listening on the http port and will make actions like starting or deploying applications.
#  The web container instance is started on another port number (that can be specified) but all access are proxified.
#  It means that the web container will be started only when a connection is done on the http port.
#  The .war file is also loaded upon request.
#  This feature cannot be enabled in production mode.
jonas.service.web.ondemand.enabled    true                               

#  The redirect port number is used to specify the port number of the http web container.
#  The proxy will listen on the http web container port and redirect all requests on this redirect port
#  0 means that a random port is used.
jonas.service.web.ondemand.redirectPort    0                             

For customizing the web service, it is possible to:

<?xml version="1.0" encoding="ISO-8859-1"?>
<jonas-web-app xmlns="http://www.objectweb.org/jonas/ns"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.objectweb.org/jonas/ns
  http://www.objectweb.org/jonas/ns/jonas-web-app_5_1.xsd">

  ...
  
  <!-- Load this application on demand (if enabled in the webcontainer service) -->
  <on-demand>true</on-demand>
</jonas-web-app>

The wm service provides a J2CA WorkManager implementation. This service don't need to be defined in the list of JOnAS services as it is automatically started when required.

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

###################### JOnAS WorkManager service configuration
#
#  Set the name of the implementation class of the wm service
jonas.service.wm.class    org.ow2.jonas.workmanager.internal.JOnASWorkManagerService

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

#  Set the maximun size of the worker thread pool
jonas.service.wm.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.wm.threadwaittimeout 60                             

The wm service is used, for example, in the resource service (J2CA 1.5 implementation) in order to provide a javax.resource.spi.work.WorkManager instance for deployed resource adapters (like JMS, ...).

The wsdl-publisher service provides a pluggable component dedicated to alternate WSDL publishing mechanisms.

By default, all the web services deployed by JOnAS have their WSDL available at a given URL location. For J2EE 1.4 webservices, the URL ends with ?JWSDL, for Java EE 5.0 webservices, the URL ends with ?WSDL.

When this default publishing mechansim is not sufficent, it is possible to add one or more custom WSDL publishers. Within JOnAS, 2 custom publishers are availables (file based and JAXR based).

Here is the part of jonas.properties concerning the wsdl-publisher service:

###################### JOnAS WSDL Publisher service configuration
#
#  Set the name of the implementation class of the WSDL Publisher service.
jonas.service.wsdl-publisher.class    org.ow2.jonas.ws.publish.internal.manager.DefaultWSDLPublisherManager

#  Set the WSDL Publishers list for WSDL publication
#  A minimum of 1 WSDLPublisher is required !
#  This property is set with a coma-separated list of WSDLPublisher properties
#  file names (without the '.properties' suffix).
#  Ex: file1,uddi (while the properties file names are
#                  file1.properties and uddi.properties)
jonas.service.wsdl-publisher.publishers    file1

# FileWSDLPublisher class
jonas.service.wsdl.class    org.ow2.jonas.ws.publish.internal.file.FileWSDLPublisher

# Directory where WSDLs will be copied
# If not set JONAS_BASE/wsdls will be used
# jonas.service.publish.file.directory    /tmp     

# Encoding of the file (In respect with the platform JOnAS is running on)
# If not set default to UTF-8
jonas.service.publish.file.encoding     UTF-8      

# RegistryWSDLPublisher class
jonas.service.wsdl.class    org.ow2.jonas.ws.publish.internal.registry.RegistryWSDLPublisher

# User name and Password to access Registry
jonas.service.publish.uddi.username                 jonas                                             
jonas.service.publish.uddi.password                 jonas                                             

# Organization name, small desc (optionnal) and primary contact name.
jonas.service.publish.uddi.organization.name        OW2                                               
jonas.service.publish.uddi.organization.desc        OW2 Consortium (http://www.ow2.org)               
jonas.service.publish.uddi.organization.person_name JOnAS                                             

# URLs where Registry can be contacted (Publish an Query APIs)
javax.xml.registry.lifeCycleManagerURL  http://localhost:9000/juddi/publish                           
javax.xml.registry.queryManagerURL      http://localhost:9000/juddi/inquiry                           

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

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

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

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/javaee5-earsample directory can be found examples of 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.ow2.jonas.security.auth.spi.JResourceLoginModule required
    resourceName="memrlm_1"
    ;
};

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

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

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

    org.ow2.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.

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

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

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.1. Defining the JOnAS Connector Deployment Descriptor: jonas-ra.xml

The jonas-ra.xml contains JOnAS specific information describing deployment information, logging, pooling, jdbc connections, and RAR config property values:

• Deployment Tags:

  property name	description	possible values
  jndiname	name the RAR will be registered as. This property is required. This value will be used in the resource-ref section of an Java EE composant.	Anyname (for example jdbc_1)
  rarlink	jndiname of a base RAR file. Useful for deploying multiple connection factories without having to deploy the complete RAR file again. When this is used, the only entry in RAR is a META-INF/jonas-ra.xml	JONASJDBC_DM JONASJDBC_DS JONASJDBC_CP JONASJDBC_XA
  native-lib	defines the path where native libraries can be found.	Any string for a path

• Logging Tags:

  property name	description	possible values
  log-enabled	determines if logging should be enabled for the RAR.	False (default value) True
  log-topic:	defines the log topic that will be used to write log messages for this rar file.	Any topic name Default value is org.objectweb.jonas.jca

• Pooling Tags

  property name	description	possible values
  pool-init	Initial size of the managed connection pool	0 (default value) n
  pool-min	Minimum size of the managed connection pool.	0 (default value) n
  pool-max	Maximum size of the managed connection pool.	n -1 = unlimited (default value)
  pool-max-age-minutes	Maximum number of minutes to keep the managed connection in the pool.	0 = an unlimited amount of time. n in minutes
  pstmt-max	Maximum number of PreparedStatements per managed connection in the pool. Only needed with the JDBC RA of JOnAS or another database vendor's RAR. Value of 0 is unlimited and -1 disables the cache.	0 = unlimited n (default value = 10) -1 = cache disabled
  pool-max-opentime	Identifies the maximum number of minutes that a managed connection can be left busy.	0 = an unlimited amount of time (default value). n in minutes
  pool-max-waiters:	identifies the maximum number of waiters for a managed connection. Default value is 0.	0 (default value) n
  pool-max-waittime	identifies the maximum number of seconds that a waiter will wait for a managed connection. Default value is 0.	0 (default value) n in seconds
  pool-sampling-period:	identifies the number of seconds that will occur between statistics samplings of the pool. Default is 30 seconds.	n in seconds (default value = 30s)

• JDBC Connection Tags:

  	Note
  	Only valid for Connection implementation of java.sql.Connection.

  property name	description	possible values
  jdbc-check-level	Level of checking that will be done for the jdbc connection.	0 : no check (default value) 1: check connection still open 2 : send the test statement before reusing a connection from the pool 3: (keep-alive feature) send the test statement on each connection every pool-sampling-period
  jdbc-test-statement	Test SQL statement sent on the connection if the jdbc-check-level is greater than 1.	A SQL statement

• Config Property Value Tags:

  Each entry must correspond to the config-property specified in the ra.xml of the RAR file. The default values specified in the ra.xml will be loaded first and any values set in the jonas-ra.xml will override the specified defaults. These tags differs dependiing on the generic JDBC RA used

  property name	description	possible values
  dsClass	Name of the class implementing java.sql.Driver, javax.sql.DataSource, javax.sql.ConnectionPoolDataSource, or javax.sql.XADataSource interfaces in the JDBC driver.	any classname representing a JDBC driver (example:org.postgresql.Driver)
  URL	Database url of the form jdbc:<database_vendor_subprotocol>. This property may be used only for JDBC RA that implements the Driver (JDBC_DM)	Any url valid for a database provider (example:jdbc:postgresql://localhost:5432/mydb)
  user	Database user name	any name
  password:	Database password	any string
  loginTimeout	Maximum time in seconds that the driver will wait while attempting to connect to a database.	no value = 0 (default value) n in seconds
  isolationLevel	Level of transaction isolation	none serializable read_committed read_uncommitted repeatable_read
  mapperName	Name of the JORM mapper	The possible values can be found in the List of available mappers in JORM documentation.
  databaseName	Name of the database	any name
  description:	Informal description	any String
  portNumber	Port Number of the database server	a number
  serverName	Name of the database server.	any name
  dbSpecificMethods	allow flexibility to call setter methods on the dsClass as required by the database provider	see below the particular syntax

• dbSpecificMethods a specific property:

  The JOnAS JDBC Resource Adapter is built as a generic connector to any database provider. The limitation of this is that each database provider may have different requirements about the methods needed to configure the dataSource class. This dbSpecificMethods property was added to allow flexibility to call setter methods on the dsClass as required by the database provider. The specific information about what additional methods should be used is documented by the database provider. The format of the value specified is:

  [:<del_char>]<method>=<value>::<value_type>:<method>=<value>::<value_type>....with:

  :	optional starting value that denotes using the next character as the delimiter instead of the default ':'
  <del_char>	delimiter character to use
  <method>	method to call followed by an = sign
  <value>	the parameter value to pass to the method being called, followed by 2 delimiter characters.If a Properties object is being passed, then the format of this value must be (name=val, name=val, ...);
  <value_type>	the parameter type used to construct the reflection call, followed by the delimiter character if additional methods are being called Boolean or bool Byte or byte Character or char Double or double Float or float Integer or int Long or long Properties or java.util.Properties Short or short String

	Note
	If this JDBC resource is used as a persistence unit, the persistence configuration defined in the persistence.xml file must be coherent to this jonas-ra.xml description, such as the datasource name and the dialect.

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

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:

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:

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

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>

>$ joram_raconfig -h localhost -p 16012 -s 0
Target JORAM Resource Adapter: /home/ ... /joram/joram_ra_for_jonas/5.2.1a/joram_ra_for_jonas-5.2.1a.rar

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 onas.service.dbm.datasources, as follows:

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

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

2.8.1.1. connection properties

property name	Description
datasource.name	JNDI name of the DataSource
datasource.url	The JDBC database URL : jdbc:<database_vendor_subprotocol>:...
datasource.classname	Name of the class implementing the JDBC driver
datasource.username	Database user name
datasource.password	Database user password
datasource.isolationLevel	Database isolation level for transactions. Possible values are: none, serializable, read_committed, read_uncommitted, repeatable_read The default depends on the database used.
datasource.mapper	JORM database mapper (for possible values see here)

	Note
	If this datasource is used as a persistence unit, the persistence configuration defined in the persistence.xml file must be coherent to those properties, such as the datasource name and the dialect.

###################### 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 RMI configuration is done using the <rmi> element.

To run EasyBeans with multiple protocols, the <protocol> element can be added more than once.

The hostname and port attributes are configurable.

Protocols could be "jrmp, jeremie, iiop, cmi". The default is jrmp.

	Note
	Some protocols may require libraries that are not packaged by default in EasyBeans.

The Transaction Component is defined by the <tm> element.

A timeout attribute, which is the transaction timeout (in seconds), can be defined on this element. The default is 60 seconds.

The implementation provided by the JOTM objectweb project is the default implementation.

The JMS component is used for JMS Message Driven Beans. Attributes are the port number and the hostname.

Also, the workmanager settings can be defined: minThreads, maxThreads and threadTimeout. The values are printed at the EasyBeans startup.

The default implementation is the implementation provided by the JORAM objectweb project.

EasyBeans can run an embedded database. Available attributes are the port number and the database name. The <hsqldb> may be duplicated in order to run several HSQLDB instances.

Users are defined through the <user> element.

This component allows the JDBC datasource to be bound into JNDI. The jndi name used is provided by the jndiName attribute.

Required attributes are username, password, url and driver.

Optional attributes are poolMin, poolMax and pstmtMax. This component provides the option to set the minimum size of the pool, the maximum size, and the size of the prepared statement cache.

Mails can be sent by using the mail component that provides either Session or MimePartDataSource factories.

This component is used by the Smart JNDI factory on the client side. This allows the client to download missing classes. The client can be run without a big jar file that provides all the classes. Classes are loaded on demand.

	Note
	Refer to the Chapter titled, Smart JNDI Factory, for more information about this feature.

A mapping file named easybeans-mapping.xml provides the information that rmi is the CarolComponent, tm is the JOTM component, and jms is the Joram component. This file is located in the org.objectweb.easybeans.server package.

The following is an extract of the easybeans-mapping.xml file.

	Note
	The mapping file is using a schema available at http://easybeans.ow2.org/xml/ns/xmlconfig/xmlconfig-mapping_10.xsd

<?xml version="1.0" encoding="UTF-8"?>
 <xmlconfig-mapping xmlns="http://easybeans.ow2.org/xml/ns/xmlconfig"
                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                    xsi:schemaLocation="http://easybeans.ow2.org/xml/ns/xmlconfig
                                        http://easybeans.ow2.org/xml/ns/xmlconfig/xmlconfig-mapping_1_0.xsd">

    <class name="org.ow2.easybeans.server.ServerConfig" alias="config">
        <attribute name="shouldWait" alias="wait" />
        <attribute name="useMBeans" alias="mbeans" />
        <attribute name="useNaming" alias="naming" />
        <attribute name="initJACC" alias="jacc" />
        <attribute name="directoryScanningEnabled" alias="scanning" />
        <attribute name="startJMXConnector" alias="connector" />
        <attribute name="registerDeployerMBean" alias="deployer" />
        <attribute name="registerJ2EEServerMBean" alias="j2eeserver" />
        <attribute name="description" />
    </class>

    <class name="org.ow2.easybeans.component.Components"
        alias="components" />

    <class name="org.ow2.easybeans.component.util.Property"
        alias="property" />

    <package name="org.ow2.easybeans.component.carol">
        <class name="CarolComponent" alias="rmi" />
        <class name="Protocol" alias="protocol">
          <attribute name="portNumber" alias="port" />
        </class>
    </package>

    <class name="org.ow2.easybeans.component.cmi.CmiComponent" alias="cmi">
        <attribute name="serverConfig" alias="config" />
        <attribute name="eventComponent" alias="event" />
    </class>

    <class
        name="org.ow2.easybeans.component.smartclient.server.SmartClientEndPointComponent"
        alias="smart-server">
        <attribute name="portNumber" alias="port" />
        <attribute name="registryComponent" alias="rmi" />
    </class>

    <class name="org.ow2.easybeans.component.jotm.JOTMComponent"
        alias="tm" />

    <class name="org.ow2.easybeans.component.joram.JoramComponent" alias="jms">
       <attribute name="topic" isList="true" getter="getTopics" setter="setTopics" element="true"/>
    </class>

    <class
        name="org.ow2.easybeans.component.jdbcpool.JDBCPoolComponent"
        alias="jdbcpool" />

    <class
        name="org.ow2.easybeans.component.remotejndiresolver.RemoteJNDIResolverComponent"
        alias="jndi-resolver">
    </class>

    <package name="org.ow2.easybeans.component.hsqldb">
        <class name="HSQLDBComponent" alias="hsqldb">
            <attribute name="databaseName" alias="dbName" />
            <attribute name="portNumber" alias="port" />
        </class>
        <class name="User" alias="user">
            <attribute name="userName" alias="name" />
        </class>
    </package>

    <package name="org.ow2.easybeans.component.quartz">
        <class name="QuartzComponent" alias="timer" />
    </package>

    <package name="org.ow2.easybeans.component.mail">
      <class name="MailComponent" alias="mail" />
      <class name="Session" alias="session">
        <attribute name="JNDIName" alias="jndiName" />
      </class>
      <class name="MimePart" alias="mimepart">
        <attribute name="subject" element="true" />
        <attribute name="JNDIName" alias="jndiName" />
      </class>
      <class name="MailAddress" alias="email" element-attribute="name" />
      <class name="Auth" alias="auth">
        <attribute name="username" alias="name" />
      </class>
    </package>

    <class name="org.ow2.easybeans.component.event.EventComponent" alias="event">
      <attribute name="eventService" alias="event-service" optional="true" />
    </class>

    <class name="org.ow2.easybeans.component.jmx.JmxComponent" alias="jmx">
      <attribute name="commonsModelerExtService" alias="modeler-service" optional="true" />
    </class>

    <class name="org.ow2.easybeans.component.statistic.StatisticComponent" alias="statistic">
        <attribute name="eventComponent" alias="event" />
        <attribute name="jmxComponent" alias="jmx" />
    </class>

    <package name="org.ow2.easybeans.component.depmonitor">
        <class name="DepMonitorComponent" alias="depmonitor">
        </class>
        <class name="ScanningMonitor" alias="scanning">
            <attribute name="waitTime" alias="period" />
        </class>
        <class name="LoadOnStartupMonitor" alias="loadOnStartup">
        </class>
    </package>


</xmlconfig-mapping>

	Note
	This mapping file is referenced by the easybeans configuration file using the XML namespace : xmlns="http://org.ow2.easybeans.server". Each element configured within this namespace will use the mapping done in the org.ow2.easybeans.server package.

Users can define their own mapping by providing a file in a package. The name of the the file must be easybeans-mapping.xml or element-mapping.xml.

Example: For the element <easybeans xmlns="http://org.ow2.easybeans.server">, the resource searched in the classloader is org/ow2/easybeans/server/easybeans-mapping.xml. And for an element <pool:max>2</pool:max> with xmlns:pool="http://org.ow2.util.pool.impl", the resource searched will be org/ow2/util/pool/impl/easybeans-mapping.xml or org/ow2/util/pool/impl/pool-mapping.xml.

EasyBeans can be configured through other configuration files as it uses a POJO configuration. If done this way, it can be configured using the Spring Framework component or other frameworks/tools.