Chapter 2. Configuring a JOnAS instance
Prev		Next

Configuring a JOnAS instance

Table of Contents

JOnAS is pre-configured and ready to be used directly. The Getting Started book has shown that a very sample example may be run after JOnAS installation without any configuration task. But as soon as your application needs to use resources specific to the execution environment, configuration is mandatory.

In this chapter we will see in a first part where are the configuration files and then what that can be configured

2.1. Configuring JOnAS Environment

JOnAS distribution contains a number of configuration files in $JONAS_ROOT/conf directory. These files can be edited to change the default configuration. However, it is recommended that the configuration files needed by a specific application running on JOnAS be placed in a separate location. This is done by using an additional environment variable called JONAS_BASE.

JOnAS configuration files are read from the $JONAS_BASE/conf directory. If JONAS_BASE is not defined, it is automatically initialized to $JONAS_ROOT.

2.1.1. JONAS_ROOT structure

The installation directory (JONAS_ROOT) has the following structure:

the deploy/ directory

The main location used for deployment.

At JOnAS startup, all deployment plans, Java EE archives and OSGi bundles are deployed in the following order:
1. Deployment plan repositories
2. OSGi bundles
3. RAR archives
4. Deployment plan resources
5. EJB archives
6. WAR archives
7. EAR archives
  
  Note
  
  For each category, file names are chosen in alphabetical order
This directory is periodically polled in order to deploy new archives. For more information have a look at the depmonitor service configuration
the bin/ directory

contains the scripts used to launch JOnAS (Unix and Windows scripts).
the conf/ directory

contains the JOnAS configuration files.
the examples/ directory

this sub tree containing all the JOnAS examples that are described in ???

the lib/ directory ^[1]

Used for extending class loaders. It contains five sub directories:

Directory	Description
`bootstrap/`	Jars loaded by the JOnAS bootstrap
`common/`	Legacy directory where Ant tasks are stored
`endorsed/`	Jars overridding JVM libraries
`ext/`	For non-bundle extensions
`internal-ee-tld/`	Internal use only !

the logs/ directory

where the log files are created at run-time (when the JONAS_ROOT is used as a JONAS_BASE)
the templates/ directory

this sub tree contains the following subdirectories used by JOnAS during the generation process (eg, JONAS_BASE generation).
- conf/ is an empty template of the JONAS_BASE structure used by tools able to create a JONAS_BASE environment.
- newjb/ contains the configuration files for creating a JONAS_BASE environment.
- newjc/ contains the configuration files for creating a cluster environment.
the repositories/ directory

this sub tree contains the following repositories used to store OSGi bundles, Java EE applications and deployment plans.
- maven2-internal/ contains both OSGi bundles and applications (jonasAdmin, documentation, ...) for JOnAS. It is used for internal purpose and should not be modified. This directory is structured as a Maven2 repository.
- url-internal/ contains the deployment plans of each JOnAS services. It is used for internal purpose and should not be modified.
- <repository-id>/ contains archives downloaded through deployment plans from this repository.

2.1.2. JONAS_BASE structure

JONAS_BASE has the following structure:

the conf/ directory

contains JOnAS configuration files.
the deploy/ directory

is the main location used for deployment.

At JOnAS startup time all the deployment plans, Java EE archives and OSGi bundles are deployed in the following order:
1. Deployment plan repositories
2. OSGi bundles
3. RAR archives
4. Deployment plan resources
5. EJB archives
6. WAR archives
7. EAR archives
  
  Note
  
  For each category, file names are chosen in alphabetical order
Then this directory is periodically polled in order to deploy new archives. For more information have a look at the depmonitor service configuration
the lib/ directory ^[2]

Used for extending class loaders. It contains one sub directory:

directory description

ext For non-bundle extensions
the logs/ directory

where the log files are created at run-time
the work/ directory

a working directory for JOnAS
the repositories/ directory

this sub tree contains the following repositories used to store OSGi bundles and Java EE applications. Archives located in these repositories are priority in case they are also located in JONAS_ROOT/repositories
- maven2-internal/ this directory is created during the building process of a JONAS_BASE environment. It may contain the JORAM resource adapter for JOnAS. It is used for internal purpose and should not be modified. This directory is structured as a Maven2 repository.
- <repository-id>/ contains archives downloaded through deployment plans from this repository.

directory	description
`ext`	For non-bundle extensions

2.1.3. JONAS_BASE creation

To create a JONAS_BASE template from scratch :

Unix

export JONAS_BASE=~/my_jonas_base
cd $JONAS_ROOT/templates/newjb
ant -f build-jb.xml create_jonas_base

Windows

set JONAS_BASE=my_jonas_base
cd %JONAS_ROOT%/templates/newjb
ant -f build-jb.xml create_jonas_base

This will copy all the required files and create all the needed directories.

Another way to create a JONAS_BASE template from scratch :

$JONAS_ROOT/bin must be set in the system path:

Unix
```
export JONAS_BASE=~/my_jonas_base
newjb
```
Windows
```
set JONAS_BASE=my_jonas_base
newjb
```
The JONAS_BASE content created with the newjb command is well suited to run the JOnAS JEE conformance test suite and the example applications without any additional configuration.

In order to customize a JONAS_BASE with specific property values (port numbers, services, protocols etc...), you must edit the $JONAS_ROOT/templates/newjb/build-jb.properties file or $HOME/jb.config/conf/jonas-newjb.properties file before running newjb.

For further customization that cannot be performed by newjb you should modify the generated files in $JONAS_BASE/conf. For more information see the description of the newjb command in Commands Reference Guide.

2.1.4. JONAS_BASE/conf description

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

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

Templates for configuring access to databases for the dbm service, (Oracle, PostgreSQL, Sybase, DB2, MySQL, HSQLDB, InterBase, FirebirdSQL, Mckoi SQL, InstantDB ) respectively in Oracle1.properties, PostgreSQL1.properties,etc... All these databases have been tested with JOnAS.
Mail resources templates : MailMimePartDS1.properties, MailSession1.properties
JORAM configuration files : a3debug.cfg, a3servers.xml, joramAdmin.xml
EasyBeans ejb3 container configuration file is named easybeans-jonas.xml.
carol.properties, jacorb.properties for configuring the RMI implementation used through CAROL.
Configuration files for clustering : cmi-config.xml, clusterd.xml, domain.xml, jgroups-discovery.xml, jgroups-ha.xml, jgroups-cmi.xml.
Configuration files related to security: jaas.config, java.policy, jonas-realm.xml
Web container configuration files:
- tomcat6-server.xml, tomcat6-context.xml, tomcat6-web.xml for Tomcat,
- jetty6.xml jetty6-web.xml for Jetty.
Web services configuration files:uddi.properties, file1.properties.
Client container configuration file: jonas-client.properties
JOnAS traces configurations files: trace.properties, traceclient.properties
Transaction recovery configuration file : jotm.properties
P6Spy options file: spy.properties
Java Service Wrapper configuration file: wrapper.conf
Deployment plan initial repositories are stored in initial-repositories.xml file.
jmx.access, jmx.passwords and jmx.rolbased.access are configuration files used to secure the JMX connector access.
jndi-interceptors.xml is used by the JNDI Interceptors allowing for example to automatically close the JDBC connections if they're not closed by the application.
classloader-default-filtering.xml allows to hide to applications some classes exported by the Application Server.
banner.txt allows to change the banner of the JOnAS scripts.

Most of these files are described in following sections.

2.1.5. Server and services configuration

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

This file is used for:

setting some global properties for the JOnAS instance
choosing the list of JOnAS services to be launched at startup
customizing each services

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

2.1.5.2. List of JOnAS services

Here is the list of default services activated at starting time:

jonas.services    jtm, db, security, resource, ejb3, jaxws, web, ear, depmonitor

The possible services are:

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

cmi: this service provides support for the clustering of RMI objects.
db: this service is used for launching a Java database implementation. By default, HSQLDB java database is used.
dbm: this service is needed by application components that require access to one or several relational databases. It may be an alternative to the usage of a JDBC resource adapter via the resource service.
depmonitor: this service is used to control the application's deployment process in JOnAS.
discovery: this service allows dynamic administration of management domains.
ear: this service provides support for Java EE applications (.ear files).
ejb2: this service provides support for EJB 2.x components (EjbJars).
ejb3: this service provides supports for EJB 3.0 components (EjbJars).
ha: this service provides high-availability replication mechanims for stateful session beans (EJB 2.x only).
jaxrpc: this service provides support for JAX-RPC 1.1 webservices (J2EE 1.4 style, based on webservices.xml deployment descriptors).
jaxws: this service provides support for JAX-WS 2.0 webservices (Java EE 5.0 style based on JWS annotations).
jmx: this service is needed in order to administrate the JOnAS servers and the JOnAS services via a JMX-based administration console. It is automatically launched before all the other services when starting JOnAS.
jtm: this service provides support of distributed transactions management.
mail: this service is required by applications that need to send e-mail messages.
registry: this service is used for binding remote objects and resources that will later be accessed via JNDI. It is automatically launched before all the other services when starting JOnAS.
resource: this service provides support for resource adapters conformant to the Java EE Connector Architecture Specification.
resourcemonitor: this service is related to the deployment plans. It allows to reload resources deployed through deployment plans by checking periodically repositories where are located original resources.
smartclient: this service 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.
security: this service is needed for enforcing security at runtime.
versioning: this service has been designed for dynamic redeployment of applications,without any application downtime and without users' sessions being lost.
wc: this service cleans up periodically the work directory of the JOnAS server.
web: this service provides support for web components (as Servlets and JSP). JOnAS provides two implementations of this service, one based on Tomcat and another on Jetty.
wm: this service provides a JCA WorkManager implementation (offering a manageable Thread Pool for resource adapters components).
wsdl-publisher: this service provides an alternate WSDL publishing mechanism (compared to the usual URL based publishing).

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.

2.1.5.4. Customizing services

Configuration parameters for services follow a strict naming convention: a service XX will be configured via a set of properties:

jonas.service.XX.foo something

jonas.service.XX.bar else

each service XX must contain the property jonas.service.XX.class indicating the name of the java class that implements the service:

jonas.service.XX.class aa.bb.XXImpl

This allow experimented user to replace built-in service by an alternative implementation.

For example here is the part of jonas.properties file related to the customization of 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

see Section 2.4, “Configuring JOnAS Services” for a complete description of the services configuration.

2.1.5.5. Development vs Production mode

JOnAS may be configured to be in development mode and in production mode. This can be defined by setting the jonas.development global property. Activating one of this mode changes some server behaviours as described in the following section.

2.1.5.5.1. Development mode

This is the default mode.

Starts automatically the workcleaner (wc) service.

Allows to start automatically services which are required to initiate the deployment of the Java EE archives. Ex: deploying the sample.war will trigger the startup of the web service.

List of services that may be started dynamically depending on the deployed Java EE archives:

web (WARs), ejb2 (EJB2s), ejb3 (EJB3s), resource (RARs), ear (EARs)

	Note
	Known limitations: if an application needs some additional services to work like for example Web Services support (jarxrpc or jaxws services), the administrator have to add those kind of services manually in the static description of JOnAS services.

In case of the development property of the depmonitor service is set to inherit, the period scan of directories managed by the depmonitor (by default the deploy/directory) service will be enabled.
WAR archive deployment case (for single or EAR packaged WARs). Each WAR archive is 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.
Necessary to enable the onDemand feature of the web service.

2.1.5.5.2. Production mode

This mode is recommended in industrial production context.

In case of the development property of the depmonitor service is set to inherit, the period scan of directories managed by the depmonitor (by default the deploy/directory) service will be disabled.
WAR archive deployment case (for single or EAR packaged WARs). Each WAR archive is unpacked in the working directory of the JOnAS server in the same folder.
Force the disabling of the onDemand feature of the web service.

^[1]see Understanding class loader hierarchy for a complete description of the classloader mechanism.

^[2]see Understanding class loader hierarchy for a complete description of the classloader mechanism.

Prev		Next
1.2.6. Cluster	Home	2.2. Configuring the communication protocol and JNDI

	Note
	For each category, file names are chosen in alphabetical order