Configuration Guide

The content of this Configuration Guide is the following:

  1. JOnAS Configuration Rules
  2. Configuring JOnAS Environment
  3. Configuring the Communication Protocol and JNDI
  4. Configuring The Logging System (monolog)
  5. Configuring JOnAS services
  6. Configuring Security
  7. Configuring JDBC DataSources
  8. Configuring JDBC Resource Adapters
  9. Configuring JMS Resource Adapters

JOnAS Configuration Rules

As described in the Getting Started chapter, JOnAS is pre-configured and ready to use directly with RMI/JRMP for remote access, if visibility to classes other than those contained in the JOnAS distribution in $JONAS_ROOT/lib is not required.
To use JEREMIE or RMI/IIOP for remote access or to work with additional java classes (for example, JDBC driver classes), additional configuration tasks must be performed, such as setting a specific port number for the registry.

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_BASE

The JONAS_BASE environment variable has been introduced in JOnAS version 3.1. Starting with this version, the previous configuration rule is replaced with a very basic one:

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

There are two ways to use JONAS_BASE:

  1. Perform the following actions:
  2. Perform the following actions:

Note that the build.xml files provided with the JOnAS examples support JONAS_BASE. If this environment variable is defined prior to building and installing the examples, the generated archives are installed under the appropriate sub-directory of $JONAS_BASE. For example, the ejb-jar files corresponding to the sample examples of $JONAS_ROOT/examples/src/ are installed in $JONAS_BASE/ejbjars.

Configuring JOnAS Environment

The JOnAS configuration file

The JOnAS server is configured via a configuration file named jonas.properties. It contains a list of key/value pairs presented in the java properties file format.

Default configuration is provided in $JONAS_ROOT/conf/jonas.properties. This file holds all possible properties with their default values. This configuration file is mandatory. The JOnAS server looks for this file at start time in the $JONAS_BASE/conf directory ($JONAS_ROOT/conf if $JONAS_BASE is not defined).

Most of the properties are related to the JOnAS services that can be launched in the JOnAS server. These properties are described in detail in Configuring JOnAS services.
The property jonas.orb.port is not related to any service. It identifies the port number on which the remote objects receive calls. Its default value is 0, which means that an anonymous port is chosen. When the JOnAS server is behind a firewall, this property can be set to a specific port number.

Note that starting with the JOnAS 3.1. version, the jonas.name property no longer exists. The name of a server can be specified on the jonas command line using a specific option (-n name). If the name is not specified, the default value is jonas.

When several JOnAS servers must run simultaneously, it is beneficial to set a different name for each JOnAS server in order to administrate these servers via the JOnAS administration tools.

Also note that it is possible to define configuration properties on the command line: (java -D...).

Use the jonas check command to review the JOnAS configuration state.

Configuration scripts

The JOnAS distribution contains two configuration scripts:

Therefore, when requiring the visibility of specific .jar files, the best practice is to update the config_env file. For example, to see some of the JDBC driver classes, one or more of the variables IDB_CLASSES, ORACLE_CLASSES, POSTGRE_CLASSES,INTERBASE_CLASSES must be updated.

Another way to place an additional .jar in the classpath of your JOnAS server is to insert it at the end of the config_env file:

      CLASSPATH=<The_Path_To_Your_Jar>$SPS$CLASSPATH

Note that an additional environment variable called XTRA_CLASSPATH can be defined to load specific classes at JOnAS server start-up. Refer to Bootstrap class loader.

Configuring the Communication Protocol and JNDI

Choosing the Protocol

Typically, access to JNDI is bound to a jndi.properties file that must be accessible from the classpath. This is somewhat different within JOnAS. Starting with JOnAS 3.1.2, multi-protocol support is provided through the integration of the CAROL component. This currently provides support for RMI/JRMP, RMI/IIOP, JEREMIE, and CMI (clustered protocol) by changing the configuration. Other protocols may be supported in the future. In versions prior to JOnAS 3.1.2, it was necessary to rebuild JOnAS for switching (e.g., from RMI/JRMP to JEREMIE), and to change the value of the OBJECTWEB_ORB environment variable; OBJECTWEB_ORB is no longer used. This configuration is now provided within the carol.properties file (that includes what was provided in the jndi.properties file). This file is supplied with the JOnAS distribution in the $JONAS_ROOT/conf directory.

Supported communication protocols are the following:

The contents of the carol.properties file is:

# jonas rmi activation (jrmp, iiop, jeremie, or cmi) 
carol.protocols=jrmp
#carol.protocols=cmi
#carol.protocols=iiop
#carol.protocols=jeremie
# RMI JRMP URL
carol.jrmp.url=rmi://localhost:1099

# RMI JEREMIE URL
carol.jeremie.url=jrmi://localhost:12340

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

# CMI URL
carol.cmi.url=cmi://localhost:2001


# general rules for jndi
carol.jndi.java.naming.factory.url.pkgs=org.objectweb.jonas.naming

CAROL can be customized by editing the $JONAS_BASE/conf/carol.properties file to 1) choose the protocol through the carol.protocols property, 2) change localhost to the hostname where registry will be run, 3) change the standard port number. If the standard port number is changed, registry must be run with this port number as the argument, registry <Your_Portnumber>, when the registry is not launched inside the JOnAS server.

You can configure JOnAS 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:

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

Note: Before version 4.1, JOnAS could not support jeremie and iiop at the same time. Due to an incompatibility between Jeremie and rmi/iiop, there was no configuration option providing a choice between these two protocols when building a JOnAS server. By default, JOnAS only allowed a choice between rmi/jrmp, Jeremie or cmi. To use rmi/iiop, it was necessary to run an "ant installiiop" command under the $JONAS_ROOT directory. This was resulting in a choice between rmi/jrmp, Jeremie, rmi/iiop or cmi.

This restriction does not exist since 4.1 release. The command "ant installiiop" is no more needed. The choice can be done between rmi/jrmp, Jeremie, rmi/iiop or cmi.

Security and Transaction Context Propagation

For implementing EJB security and transactions, JOnAS typically relies on the communication layer for propagating the security and transaction contexts across the method calls. By default, the communication protocol is configured for context propagation. However, this configuration can be changed by disabling the context propagation for security and/or transaction; this is done primarily to increase performance. The context propagation can be configured in the jonas.properties file by setting the jonas.security.propagation and jonas.transaction.propagation properties to true or false:

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

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

Note that the secpropag attribute of the JOnAS ejbjar ANT task and the -secpropag option of GenIC are no longer used. They were used in JOnAS versions prior to 3.1.2 to specify that the security context should be propagated.

Multi-protocol Deployment (GenIC)

The JOnAS deployment tool (GenIC) must be notified for which protocols stubs (for remote invocation) are to be generated. Choosing several protocols will eliminate the need to redeploy the EJBs when switching from one protocol to another. The default is that GenIC generates stubs for rmi/jrmp and Jeremie. To change this configuration, call GenIC with the -protocols option specifying a comma-separated list of protocols (chosen within jeremie, jrmp, iiop, cmi), e.g.:

      GenIC -protocols jrmp,jeremie,iiop

This list of protocols can also be specified for the JOnAS ejbjar ANT task:

     <jonas destdir="${dist.ejbjars.dir}"
jonasroot="${jonas.root}"
protocols="jrmp,jeremie,iiop"
keepgenerated="true"
verbose="${verbose}"
mappernames="${mapper.names}"
additionalargs="${genicargs}">
</jonas>

Configuring the Logging System (monolog)

Starting with JOnAS 2.5, the logging system is based on Monolog, the new standard API for Objectweb projects. Configuring trace messages inside Jonas can be done in two ways:

Note the SQL requests sent to a Database can be easily traced using the JOnAS Logging system and the integrated P6Spy tool. The configuration steps are described in the "Configuring JDBC Datasources" section.

trace.properties syntax

A standard file is provided in $JONAS_ROOT/conf/trace.properties. Use the CLASSPATH to retrieve this file.

The the monolog documentation provides more details about how to configure logging. Monolog is built over a standard log API (currently, log4j). Loggers can be defined, each one being backed on a handler.
A handler represents an output, is identified by its name, has a type, and has some additional properties. Two handlers have been defined in the trace.properties file:

Each handler can define the header it will use, the type of logging (console, file, rolling file), and the file name.

Note that if the tag "automatic" is specified as the output filename, JOnAS will replace this tag with a file pointing to $JONAS_BASE/logs/<jonas_name_server>-<timestamp>.log.
The logf handler, which is bundled with JOnAS, uses this "automatic" tag.

Loggers are identified by names that are structured as a tree. The root of the tree is named root.

Each logger is a topical logger, i.e. is associated with a topic. Topic names are usually based on the package name. Each logger can define the handler it will use and the trace level among the following four values:

If nothing has been defined for a logger, it will use the properties defined for its parent.

JOnAS code is written using the monolog API and it can use the tty handler.

Example of setting DEBUG level for the logger used in the jonas_ejb module:

logger.org.objectweb.jonas_ejb.level DEBUG

Example for setting the output of JOnAS traces to both the console and a file /tmp/jonas/log:

handler.logf.output /tmp/jonas.log
logger.org.objectweb.jonas.handler.0 tty
logger.org.objectweb.jonas.handler.1 logf

Example for setting the output of JOnAS traces to a file in the $JONAS_BASE/logs/ directory:

handler.logf.output automatic
logger.org.objectweb.jonas.handler.0 logf

Configuring JOnAS Services

JOnAS may be viewed as a number of manageable built-in services started at server launching time. JOnAS is also able to launch external services, which can be defined as explained in the JOnAS service chapter.

The following is a list of the JOnAS built-in services:

These services can be managed using the JonasAdmin administration console, which is a Servlet-based application using the JMX technology. Note that JonasAdmin can only manage available services (currently, it is not possible to launch a service after the server start-up).

The services available in a JOnAS server are those specified in the JOnAS configuration file. The jonas.services property in the jonas.properties file must contain a list of the required service names. Currently, these services will be started in the order in which they appear in the list. Therefore, the following constraints should be considered:

Example:

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

The registry can be omitted from the list because this service is automatically launched if it is not already activated by another previously started server. This is also true for jmx, since, beginning with JOnAS 3.1, this service is automatically launched after the registry.
The dbm, resource, and jms services are listed after the jtm.
The application components deployed on this server can use Java Messaging and Java Mail because jms and mail are listed before ejb.

Configuration parameters for services are located in the jonas.properties file, adhering to 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
    

Configuring Registry Service

This service is used for accessing the RMI registry, Jeremie registry, CMI registry, or the CosNaming (iiop), depending on the configuration of communication protocols specified in carol.properties, refer to the section "Configuring the Communication Protocol and JNDI."

There are several Registry launching modes based on the value of the JOnAS property jonas.service.registry.mode. The possible values of the jonas.service.registry.mode property are:

The port number on which the Registry is launched is defined in the carol.properties file.

Configuring EJB Container Service

This is the primary JOnAS service, providing EJB containers for EJB components.

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

JOnAS also allows for loading unpacked EJB components. The name of the xml file containing the EJB's deployment descriptor must be listed in the jonas.service.ejb.descriptors property. Note that the JOnAS server must have access to the component's classes, which may be achieved using the XTRA_CLASSPATH environment variable (see Bootstrap class loader).

Configuring WEB Container Service

This service provides WEB containers for the WEB components used in the J2EE applications.
JOnAS provides two implementations of this service: one for Jetty 5.0.x, one for Tomcat 5.0.x.
It is necessary to run this service to use the JonasAdmin tool.

If the environment variable $JETTY_HOME or $CATALINA_HOME is not set, the web container service cannot be loaded at JOnAS startup and a warning is displayed.

A WEB container is created from a war file. If the file name does not contain an absolute path name, it must be located in the $JONAS_BASE/webapps/ directory.

JOnAS can create WEB containers when the JOnAS server starts, by providing the corresponding file names via the jonas.service.web.descriptors property in the jonas.properties file.
Example:

     jonas.service.web.descriptors  Bank.war

In this example the WEB Container service will create a container from the war file named Bank.war. It will search for this file in the $JONAS_BASE/webapps/ directory.

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

WEB containers can be also dynamically created from war files using the JonasAdmin tool.

Configuring WebServices Service

A. Choose a Web Service Engine

   

At this time, only 1 implementation for WebServices is available : the Axis implementation. But in the future, a Glue implementation can be made easily.

jonas.properties :

#...

# the fully qualifier name of the service class
jonas.service.ws.class org.objectweb.jonas.ws.AxisWSServiceImpl

#...

B. Choose one or more WSDL Handler(s)

    WSDL Handlers are used to locate and publish all your WSDL documents. You can use several WSDL Handlers, the only thing to do is to define them in the jonas.properties.

    Example : if you want to publish a WSDL into the local FileSystem, use the FileWSDLHandler

jonas.properties :
#...

# a list of comma separated WSDL Handlers
jonas.service.ws.wsdlhandlers file1
# Configuration of the file WSDL Handler
jonas.service.ws.file1.class org.objectweb.jonas.ws.handler.FileWSDLHandler
# Specify String params for WSDLHandler creation jonas.service.ws.file1.params location
# Make sure that user that run JOnAS have rad/write access in this directory
jonas.service.ws.file1.location /path/to/directory/where/store/wsdls

#...

Configuring EAR Service

The EAR service allows deployment of complete J2EE applications (including both ejb-jar and war files packed in an ear file). This service is based on the WEB container service and the EJB container service. The WEB container service is used to deploy the wars included in the J2EE application; the EJB container service is used to deploy the EJB containers for the ejb-jars included in the J2EE application.

This service may be configured by setting the jonas.service.ear.descriptors property in jonas.properties file. This property provides a list of ears that must be deployed when JOnAS is launched.

The JonasAdmin tool can be used to dynamically deploy the J2EE application components from an ear file.

When using relative paths for ear file names, the files should be located in the $JONAS_BASE/apps/ directory.
Example:

     jonas.service.ear.descriptors  Bank.ear

In this example the EAR service will deploy the ear file named Bank.ear. It will search for this file in the $JONAS_BASE/apps/ directory.

Configuring Transaction Service

The Transaction service is used by the Container service in order to provide transaction management for EJB components as defined in the deployment descriptor. This is a mandatory service. The Transaction 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 Transaction 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.
The following is an example of the configuration for two servers: one named TM in which a standalone Transaction service will be run, one named EJB that will be used to deploy an EJB container:

     jonas.name               TM
jonas.services jtm
jonas.service.jtm.remote false

and

     jonas.name                    EJB
jonas.services jmx,security,jtm,dbm,ejb
jonas.service.jtm.remote true
jonas.service.ejb.descriptors foo.jar

Another possible configuration option is the value of the transaction time-out, in seconds, via the jonas.service.jtm.timeout property.
The following is the default configuration:

      jonas.service.jtm.timeout   60

Configuring Database Service

The description of the new JDBC Resource Adapters as a replacement for the Database service is located in Configuring JDBC Resource Adapters.

To allow access to one or more relational databases (e.g. Oracle, InstantDB, PostgreSQL, ...), JOnAS 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. More details about DataSource objects and their configuration are provided in the "Configuring JDBC DataSources" section.

The following subsections briefly explain how to configure a DataSource object for your database, to be able to run the Entity Bean example delivered with your specific platform.

Note that the SQL requests sent to the Database can be easily traced using the JOnAS Logging system and the integrated P6Spy tool. The configuration steps are described in the "Configuring JDBC Datasources" section.

Configuring Oracle for the supplied example

A template Oracle1.properties file is supplied in the installation directory. This file is used to define a DataSource object, named Oracle1. This template must be updated with values appropriate to your installation. The fields are the following:

datasource.name JNDI name of the DataSource:
The name used in the example is jdbc_1.
datasource.url The JDBC database URL: for the Oracle JDBC "Thin" driver it is
jdbc:oracle:thin:@hostname:sql*net_port_number:ORACLE_SID
If using an Oracle OCI JDBC driver, the URL is
jdbc:oracle:oci7: or jdbc:oracle:oci8:
datasource.classname Name of the class implementing the Oracle JDBC driver:
oracle.jdbc.driver.OracleDriver
datasource.mapper Adapter (JORM), mandatory for CMP2.0 only (more details in Configuring JDBC DataSources): rdb.oracle8 for Oracle 8 and prior versions
datasource.username Database user name
datasource.password Database user password

For the EJB platform to create the corresponding DataSource object, its name (Oracle1, not the JNDI name) must be in the jonas.properties file, on the jonas.service.dbm.datasources line:

    jonas.service.dbm.datasources      Oracle1

There may be several DataSource objects defined for an EJB server, in which case there will be several dataSourceName.properties files and a list of the DataSource names on the jonas.service.dbm.datasources line of the jonas.properties file:

    jonas.service.dbm.datasources      Oracle1, Oracle2, InstantDB1

To create the table used in the example with the SQL script provided in examples/src/eb/Account.sql, the Oracle server must be running with a JDBC driver installed (Oracle JDBC drivers may be downloaded at their Web site).
For example:

    sqlplus user/passwd
    SQL> @Account.sql
    SQL> quit
    

The JDBC driver classes must be accessible from the classpath. To do this, update the config_env file; ($JONAS_ROOT/bin/unix/config_env on Unix, or %JONAS_ROOT%\bin\nt\config_env.bat on Windows).

Configuring InstantDB for the supplied example

A template InstantDB1.properties file is supplied in the installation directory. This file is used to define a Datasource object named InstantDB1. This template must be updated with values appropriate to your installation. The fields are the following:

datasource.name JNDI name of the DataSource:
The name used in the example is jdbc_1.
datasource.url The JDBC database URL: for InstantDB it is
jdbc:idb=db1.prp.
datasource.classname Name of the class implementing the JDBC driver:
org.enhydra.instantdb.jdbc.idbDriver

To have the EJB platform create the corresponding DataSource object, its name (InstantDB1, not the JNDI name) must be in the jonas.properties file, on the jonas.service.dbm.datasources line.

    jonas.service.dbm.datasources            InstantDB1

InstantDB must have been properly installed and configured, using a version higher than 3.14. (examples have been tested with 3.25).

The JDBC driver classes must be accessible from the classpath. To do this, update the config_env file; ($JONAS_ROOT/bin/unix/config_env on Unix, or %JONAS_ROOT%\bin\nt\config_env.bat on Windows).

Create the Account database using the utility provided with InstantDB:

    cd examples/src/eb
. $JONAS_ROOT/bin/unix/config_env
java org.enhydra.instantdb.ScriptTool Account.idb

Configuring other databases

The same type of process can be used for other databases. A template of datasource for PostgreSQL and for InterBase is supplied with JOnAS. Although many other databases are currently used by the JOnAS users (e.g. Informix, Sybase, SQL Server), not all JDBC drivers have been tested against JOnAS.

Configuring Security Service

There is one property in the jonas.properties file for configuring the security service: the jonas.security.propagation property should be set to true (which is the default value), to allow the security context propagation across method calls. Refer also to the "Security and Transaction Context Propagation" section. 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 "Configuring Security" for a discussion of security configuration.

Configuring JMS Service (not compliant with 2.1 MDBs)

Until JOnAS release 4.1, the only way to provide the JMS facilities was by setting a JMS service when configuring JOnAS. The JMS service still is a default setting in the jonas.properties config file, however this JMS service won't allow to deploy 2.1 MDBs, and will eventually become deprecated in later JOnAS versions.

The new way to integrate a JMS platform is by deploying a J2EE1.4 compliant resource adapter. How to do it is described in the Configuring JMS resource adapters section.

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

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

jms service is an optional service that must be started before the ejb container service.

Following are the properties that can be set in jonas.properties file for jms service:

Some additional information about JMS configuration (in particular, several JORAM advanced configuration aspects) is provided in the "JMS Administration" and "Running an EJB performing JMS operations" sections of the Using JMS in application components chapter.

Information related to using WebSphere MQ is provided in the Using WebSphere MQ JMS howto.

Configuring Resource Service

The Resource service is an optional service that must be started as soon as EJB 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 EJB components.

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

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

Configuring JMX Service

The JMX service must be started in order to administrate or instrument the JOnAS server via JonasAdmin. This service is mandatory and will be started even if it is not present in the list of services. It is configured by choosing one of the two supported JMX implementations, SUN RI or MX4J. The choice is made based on the value of the jonas.service.jmx.class property in the JOnAS configuration file. The two possible values are:

Configuring Mail Service

The Mail service is an optional service that may be used to send email.
It is based on JavaMailTM and on JavaBeansTM Activation Framework (JAF) API.

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

Mail factory objects must be configured accordingly 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.

Configuring Session mail factory

The template MailSession1.properties file supplied in the installation directory defines a mail factory of Session type. The JNDI name of the mail factory object is mailSession_1. This template must be updated with values appropriate to your installation.
See the section "Configuring a mail factory" below for the list of available properties.

Configuring MimePartDataSource mail factory

The template MailMimePartDS1.properties file supplied in the installation directory defines a mail factory of MimePartDSMailer type. The JNDI name of the mail factory object is mailMimePartDS_1. This template must be updated with values appropriate to your installation.
The section "Configuring a mail factory" contains a list of the available properties.

The following subsection provides information about configuring JOnAS in order to create the required mail factory objects.

Configuring JOnAS

Mail factory objects created by JOnAS must be given a name. In the mailsb example, two factories called MailSession1 and MailMimePartDS1 are defined.
Each factory must have a configuration file whose name is the name of the factory with the .properties extension (MailSession1.properties for the MailSession1 factory).
Additionally, the jonas.properties file must define the jonas.service.mail.factories property. For this example, it is:

    jonas.service.mail.factories MailSession1,MailMimePartDS1

Configuring a mail factory

The fields are the following:

Required properties
mail.factory.name JNDI name of the mail factory
mail.factory.type The type of the factory. This property can be javax.mail.Session or
javax.mail.internet.MimePartDataSource.
 
 
Optional properties
 
Authentication properties
mail.authentication.username Set the username for the authentication.
mail.authentication.password Set the password for the authentication.
 
javax.mail.Session.properties (refer to JavaMail documentation for more information)
mail.authentication.username Set the username for the authentication.
mail.authentication.password Set the password for the authentication.
mail.debug The initial debug mode. Default is false.
mail.from The return email address of the current user, used by the InternetAddress method getLocalAddress.
mail.mime.address.strict The MimeMessage class uses the InternetAddress method parseHeader to parse headers in messages. This property controls the strict flag passed to the parseHeader method. The default is true.
mail.host The default host name of the mail server for both Stores and Transports. Used if the mail.protocol.host property is not set.
mail.store.protocol Specifies the default message access protocol. The Session method getStore() returns a Store object that implements this protocol. By default the first Store provider in the configuration files is returned.
mail.transport.protocol Specifies the default message access protocol. The Session method getTransport() returns a Transport object that implements this protocol. By default, the first Transport provider in the configuration files is returned.
mail.user The default user name to use when connecting to the mail server. Used if the mail.protocol.user property is not set.
mail.<protocol>.class Specifies the fully- qualified class name of the provider for the specified protocol. Used in cases where more than one provider for a given protocol exists; this property can be used to specify which provider to use by default. The provider must still be listed in a configuration file.
mail.<protocol>.host The host name of the mail server for the specified protocol. Overrides the mail.host property.
mail.<protocol>.port The port number of the mail server for the specified protocol. If not specified, the protocol's default port number is used.
mail.<protocol>.user The user name to use when connecting to mail servers using the specified protocol. Overrides the mail.user property.
 
MimePartDataSource properties (Only used if mail.factory.type is javax.mail.internet.MimePartDataSource)
mail.to Set the list of primary recipients ("to") of the message.
mail.cc Set the list of Carbon Copy recipients ("cc") of the message.
mail.bcc Set the list of Blind Carbon Copy recipients ("bcc") of the message.
mail.subject Set the subject of the message.

Configuring DB Service (hsql)

The DB service is an optional service that may be used to start a java database server in the same JVM that JOnAS.
The listening port and the database name can be set :

jonas.service.db.port   9001
jonas.service.db.dbname  db_jonas

There is a file HSQL1.properties in $JONAS_ROOT/conf which can be used with these default values.
The users are declared by the following way :

jonas.service.db.user<1..n>   login:password

ie : jonas.service.db.user1 jonas:jonas A user with name jonas and password jonas has access to this database. This login and this password (jonas/jonas) are used in HSQL1.properties file.

Configuring Security

Configure JAAS security for certificate authentication

The Security service is used by the Container service to provide security for EJB components. The Container service provides security in two forms: declarative security and programmatic security. The Security service exploits security roles and method permissions located in the EJB deployment descriptor.

Note that:

There is one property in the jonas.properties file for configuring the security service: the jonas.security.propagation property should be set to true (which is the default value), to allow the security context propagation across method calls. Refer also to the "Security and Transaction Context Propagation" section.

Using web container Tomcat 5.0.x interceptors for authentication

With Tomcat 5.0.x, in the $JONAS_ROOT/conf/server.xml file,
or $JONAS_BASE/conf/server.xml file,
or $CATALINA_HOME/conf/server.xml file,
or $CATALINA_BASE/conf/server.xml replace the following line:

    <Realm className="org.apache.catalina.realm.UserDatabaseRealm"
                 debug="0" resourceName="UserDatabase"/>
  

By the line:

    <Realm className="org.objectweb.jonas.security.realm.web.catalina50.JACC"
                      debug="99" resourceName="memrlm_1"/>
  

A memory, Datasource, or LDAP resource can be used for the authentication, with the correct name of the specified resource as resourceName, that is: memrlm_1, memrlm_2, dsrlm_1, ldaprlm_1, etc.

Using web container Jetty 5.0.x interceptors for authentication

To use Jetty interceptors in a web application, provide a web-jetty.xml file under the WEB-INF directory in the .war file, in which it is specified that the security interceptor org.objectweb.jonas.security.realm.web.jetty50.Standard for JOnAS be used instead of the default one. Such as, for the earsample example:

  <Call name="setRealmName">
    <Arg>Example Basic Authentication Area</Arg>
  </Call>
  <Call name="setRealm">
    <Arg>
      <New class="org.objectweb.jonas.security.realm.web.jetty50.Standard">
        <Arg>Example Basic Authentication Area</Arg>
        <Arg>memrlm_1</Arg>
      </New>
    </Arg>
  </Call>

Several web-jetty.xml examples are located in the earsample example and alarm demo.

Configuring mapping principal/roles

JOnAS relies on the jonas-realm.xml file for access control to the methods of EJB components.
Example of a secured bean with the role jonas.

  <assembly-descriptor>
<security-role>
<role-name>jonas</role-name>
</security-role>

<method-permission>
<role-name>jonas</role-name>
<method>
<ejb-name>Bean</ejb-name>
<method-name>*</method-name>
</method>
</method-permission>
...
...
</assembly-descriptor>

The following subsections describe how to configure the different resources for performing authentication if it is necessary to add a user that has the specified role (jonas) and is authorized to call methods, etc.

Configuring Memory resource in jonas-realm.xml file

To add the role 'jonas', place this example role in the <roles> section:

  <roles>
<role name="jonas" description="Role used in the sample security howto" />
</roles>
Then, add a user with the specified role.
Add a user with the 'jonas' role in the <users> section:
  <users>
<user name="jonas_user" password="jonas_password" roles="jonas" />
</users>

The <groups> section permits grouping roles.
Example : A developer makes two applications, one which need the role role1 and the second application which need the role role2. Instead of declaring two users, user1 with role1 and user2 with role2, a group can be declared. This group will have two roles, role1 and role2.

<groups>
  <group name="myApplications" roles="role1,role2" description="Roles for my applications" />
</groups>

Then a user named 'john' can be added with the group 'myApplications'. This user must be add in the section <users>...</users> of section <memoryrealm name="...">...</memoryrealm> of the jonas-realm.xml file.

<user name="john" password="john_password" groups="myApplications" />
This user will have two roles, role1 and role2 as these roles are in the group called 'myApplications'.
Another user 'joe' can be declared with the same group.
<user name="joe" password="joe_password" groups="myApplications" />

Of course, joe user can be in another group, for example group 'otherApplications'.
<user name="joe" password="joe_password" groups="myApplications,otherApplications" />
If joe must be able to authenticate on jonasAdmin web application, he need the role 'jonas'
<user name="joe" password="joe_password" groups="myApplications,otherApplications" roles="jonas" />
So, a user can have many groups and many roles defined.
Now, if the developer add a third application which need the role 'role3', the developer just have to add this role in the group named 'myApplications' and all the users from the group 'myApplications' will have this new role.
<groups>
  <group name="myApplications" roles="role1,role2,role3" description="Roles for my applications" />
</groups>


Add the memory resource in the jonas-realm.xml file:
Note : [...] means that it can be existing memory realms as several memoryrealm can be declared in the section <jonas-memoryrealm>
One memory-realm can be used for Tomcat, another for Jetty, or different realms can be assigned for specific contexts (in server.xml for Tomcat or web-jetty.xml, jetty.xml for Jetty).
  <jonas-memoryrealm>
[...]
<memoryrealm name="howto_memory_1">
<roles>
<role name="jonas" description="Role used in the sample security howto" />
</roles>

<users>
<user name="jonas_user" password="jonas_password" roles="jonas" />
</users>
</memoryrealm>
[...]
</jonas-memoryrealm>

Note that it's better to use jonasAdmin web application to add/delete user, group, role than editing the jonas-realm.xml by the hand. It can avoid some errors of configuration.

Configuring Datasource resource in the jonas-realm.xml file

First, build the tables in which the users and roles will be stored.
Example of tables :
realm_users : Add a user jonas_user with the password jonas_password

user_name user_pass
... ...
jonas_user jonas_password
... ...

Note that the table can contain more than two columns.


realm_roles : Add the role jonas to the user jonas_user
user_name role_name
... ...
jonas_user jonas
... ...

Now, declare the resource in the jonas-realm.xml file.
The dsName element describes the JNDI name of the datasource to use.
Thus, a Datasource configuration with the right JNDI name for the dbm service must be set in the jonas.properties file.
The datasource resource to add in the jonas-realm.xml file is:

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

Configuring LDAP resource in the jonas-realm.xml file

The user is added in the LDAP server.
In this case, all the users are on the ou=people,dc=jonas,dc=objectweb,dc=org DN.
For example, the unique name will be: DN uid=jonas_user,ou=people,dc=jonas,dc=objectweb,dc=org for the user 'jonas_user'.
The role jonas will be added on the ou=groups,dc=jonas,dc=objectweb,dc=org DN.
In this case: DN cn=jaas,ou=groups,dc=jonas,dc=objectweb,dc=org
The user is added to the role by adding a field uniquemember to the role. uniquemember = uid=jonas,ou=people,dc=jonas,dc=objectweb,dc=org
LDIF format for the user:

  # jonas_user, people, jonas, objectweb, org
dn: uid=jonas_user,ou=people,dc=jonas,dc=objectweb,dc=org
objectClass: inetOrgPerson
uid: jonas_user
sn: jonas_user
cn: JOnAS user
userPassword:: jonas_password

LDIF format for the role:

  # jonas, groups, jonas, objectweb, org
dn: cn=jonas,ou=groups,dc=jonas,dc=objectweb,dc=org
objectClass: groupOfUniqueNames
uniqueMember: uid=jonas_user,ou=people,dc=jonas,dc=objectweb,dc=org
cn: jonas

Now the jonas-realm.xml file can be customized by adding a LDAP resource.
There are two methods for the authentication: the bind or the compare method.

By default, the bind method is used.
All the elements of the configuration for the ldap resource can be found on the jonas-realm_1_0.dtd DTD file.

For this sample, it is assumed that the LDAP server is on the same computer and is on the default port (389). It takes all the default values of the DTD.
The datasource resource to add in the jonas-realm.xml file is:

<jonas-ldaprealm>
[...]
<ldaprealm name="howto_ldap_realm1"
baseDN="dc=jonas,dc=objectweb,dc=org" />
[...]
</jonas-ldaprealm>

Configuring client authentication based on client certificate in the web container

1. Introduction

In order to set up the client authentication based on client certificate in a Web container, do the following:

It is mandatory to possess a X.509 certificate for your Web container on each external interface (IP address) that accepts secure connections. This one can be digitally signed by a Certification Authority or can be autosigned.

2. Configure the Realm the Web container will have to use

If you use Tomcat

If the JOnAS-Tomcat package is installed, skip this paragraph.

With Tomcat 5.0.x, in the $JONAS_ROOT/conf/server.xml file,
or $JONAS_BASE/conf/server.xml file,
or $CATALINA_HOME/conf/server.xml file,
or $CATALINA_BASE/conf/server.xml replace the current Realm by the following :

<Realm className="org.objectweb.jonas.security.realm.web.catalina50.JAAS" />
The class specified uses the JAAS model to authenticate the users. Thus, to choose the resource in which to look for authentication data, configure JAAS.
If you use Jetty

Edit the web-jetty.xml file under WEB-INF directory in the .war file to declare a Realm name and a Realm:

<Configure class="org.mortbay.jetty.servlet.WebApplicationContext">
...
!-- Set the same realm name as the one specified in <realm-name> in <login-config> in the web.xml file of your web application -->
<Call name="setRealmName">
<Arg>Example Authentication Area</Arg>
</Call>
<!-- Set the class Jetty has to use to authenticate the user and a title name for the pop-up window -->
<Call name="setRealm">
<Arg>
<New class="org.objectweb.jonas.security.realm.web.jetty50.JAAS">
<Arg>JAAS on Jetty</Arg>
</New>
</Arg>
</Call>
...
</Configure>

The class specified uses the JAAS model to authenticate the users. Thus, to choose the resource in which to look for authentication data, configure JAAS.


3. Configure an SSL listener on the Web container

For Tomcat

Uncomment the following section in the server.xml file:

  <Connector className="org.apache.catalina.connector.http.HttpConnector" port="9043"
minProcessors="5" maxProcessors="75" enableLookups="true" acceptCount="10"
debug="0" scheme="https" secure="true">
<Factory className="org.apache.catalina.net.SSLServerSocketFactory" clientAuth="false" protocol="TLS"/>
</Connector>

Important : set the clientAuth parameter to false, otherwise all Web applications will request a client certificate if they need SSL. The client authentication will be configured later in the web.xml file in the specific .war files.

For more information, refer to http://jakarta.apache.org/tomcat/tomcat-5.0-doc/ssl-howto.html.

For Jetty

In the global deployment descriptor of Jetty (the jetty.xml file), that is in the $JETTY_HOME/conf or $JONAS_BASE/conf directory (depending on whether using Jetty is being used in standalone or not), set:

<Configure class="org.mortbay.jetty.Server">
...
<Call name="addListener">
<Arg>
<New class="org.mortbay.http.SunJsseListener">
<Set name="Port">9043</Set>
<Set name="Keystore">
<SystemProperty name="jonas.base" default="."/>/conf/keystore</Set>
<Set name="Password">changeit</Set>
<Set name="KeyPassword">jettykeypassword</Set>
<Set name="NeedClientAuth">true</Set>
</New>
</Arg>
</Call>
...
</configure>

The Jetty certificate is stored in a repository called the keystore. This is the certificate that will present Jetty when a connection is about to be established.

For more information, refer to http://jetty.mortbay.org/jetty/doc/SslListener.html.


4. Configure your Web application to make it request a client certificate

Add the following lines to the web.xml file of the .war file of the Web application:

<login-config>
<auth-method>CLIENT-CERT</auth-method>
<realm-name>Example Authentication Area</realm-name>
</login-config>

Important:


For Jetty, refer to http://jetty.mortbay.org/jetty/doc/ClientCert.htmlfor more information.


5. Configure the JAAS LoginModules

This authentication process is built on the JAAS technology. This means that authentication is performed in a pluggable way and the desired authentication technology is specified at runtime. Therefore, you must choose the LoginModules to use in your Web container to authenticate the users.

Choose the LoginModules
org.objectweb.jonas.security.auth.spi.JResourceLoginModule

This is the main LoginModule. It is highly recommended that this be used in every authentication, as it verifies the user authentication information in the specified resource.
It requires only one parameter :

org.objectweb.jonas.security.auth.spi.CRLLoginModule
This LoginModule contains authentication based on certificates. However, when enabled, it will also permit non-certificate based accesses. It verifies that the certificate presented by the user has not been revoked by the Certification Authority that signed it. To use it, the directory in which to store the revocation lists (CRLs) files or a LDAP repository must exist.

It can take the following parameters:



Specify the configuration parameters

The JAAS configuration sits on a file in which the login module to use for authentication is described. This file is located in $JONAS_BASE/conf and named jaas.config. To change its location and name, edit the $JONAS_BASE/bin/jonas.sh script and modify the following line:

-Djava.security.auth.login.config=$JONAS_BASE/conf/jaas.config
The contents of the JAAS configuration file follows that structure:
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;
};
Sample of a configuration file with CRL directory:
tomcat {
org.objectweb.jonas.security.auth.spi.CRLLoginModule required
CRLsResourceName="Directory"
CRLsDirectoryName="path_to/CRLs";

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

There can be multiple entries in this file, specifying different configurations that JOnAS can use. There are two requirements: the entry dedicated to Tomcat must be named tomcat, and the entry for Jetty, jetty. Note that everything in this file is case-sensitive.

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



6. Populate the Realm access list

Now, users will not have to enter a login/password. They will just present their certificates and authentication is performed transparently by the browser (after the user has imported his certificate into it). Therefore, the identity presented to the server is not a login, but a Distinguished Name: that is the name identifying the person to whom the certificate belongs.

This name looks like the following:

CN=Someone Unknown, OU=ObjectWeb, O=JOnAS, C=ORG
E : Email Address
CN : Common Name
OU : Organizational Unit
O : Organization
L : Locality
ST : State or Province Name
C : Country Name

The Subject in a certificate contains the main attributes and may include additional ones, such as Title, Street Address, Postal Code, Phone Number.

Previously in the jonas-realm.xml, a memory realm might contain:
<user name="jps_admin" password="admin" roles="administrator"/>

To enter a certificate-based user access, now the user's DN preceded by the String: ##DN## must be entered, as shown in the following example:

<user name="##DN##CN=whale, OU=ObjectWeb, O=JOnAS, L=JOnAS, ST=JOnAS, C=ORG" 
      password="" roles="jadmin" />

Configuring JDBC DataSources

This section describes how to configure the Datasources for connecting the application to databases.

Configuring DataSources

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 2.0 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. Available DataSource objects can be added on the platform; they must be defined in the jonas.properties file. This section explains how DataSource objects can be defined and configured in the JOnAS server.

To support distributed transactions, JOnAS requires the use of a JDBC2-XA-compliant driver. Such drivers that implement the XADataSource interface are not always available for all relational databases. 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.

JOnAS's generic driver-wrapper provides an implementation of the DataSource interface that allows DataSource objects to be defined using a JDBC1-compliant driver for some relational database management server products, such as Oracle, PostGres, or InstantDB.

Neither the EJB specification nor the J2EE specification describe how to define DataSource objects so that they are available to a J2EE 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 and InstantDB1.properties for an InstantDB DataSource, as delivered with the platform).

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

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

The property file defining a DataSource should contain the following information:

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 

A DataSource object for Oracle (for example, Oracle1), named jdbc_1 in JNDI, and using the Oracle thin JDBC driver, would be described in a file called Oracle1.properties, as in the following example:

datasource.name       jdbc_1
datasource.url        jdbc:oracle:thin:@malte:1521:ORA1
datasource.classname  oracle.jdbc.driver.OracleDriver
datasource.username   scott
datasource.password   tiger
    

In this example, "malte" is the hostname of the server running the Oracle DBMS, 1521 is the SQL*Net V2 port number on this server, and ORA1 is the ORACLE_SID.

This example makes use of the Oracle "Thin" JDBC driver. If your application server is running on the same host as the Oracle DBMS, you can use the Oracle OCI JDBC driver; depending on the Oracle release, the URL to use for this would be jdbc:oracle:oci7, or jdbc:oracle:oci8. Oracle JDBC drivers may be downloaded at the Oracle Web site.

To create an InstantDB DataSource object (for example, InstantDB1) named jdbc_2 in JNDI, describe it as follows (in a file InstantDB1.properties):

datasource.name       jdbc_2 
datasource.url        jdbc:idb=db1.prp
datasource.classname  jdbc.idbDriver
datasource.username   useless
datasource.password   useless
    

To create a PostGreSQL DataSource object named jdbc_3 in JNDI, describe it as follows (in a file PostGreSQL.properties):

datasource.name       jdbc_3 
datasource.url        jdbc:postgresql://your_host/your_db
datasource.classname  org.postgresql.Driver
datasource.username   useless
datasource.password   useless
    

Properties having the "useless" value are not used for this type of persistence storage.

The database user and password can be placed in the DataSource description (<DataSource name>.properties file) and have the Application Components use the getConnection() method, or not placed in the DataSource description and have the Application Components use the getConnection(String username, String password) method. In the resource reference of the associated datasource in the standard deployment descriptor, the <res-auth> element should have the corresponding value, i.e. Container or Application.

CMP2.0/JORM

For implementing the EJB 2.0 persistence (CMP2.0), JOnAS relies on the JORM framework. JORM must adapt its object-relational mapping to the underlying database and makes use of adapters called "mappers" for this purpose. Thus, for each type of database (and more precisely for each JDBC driver), the corresponding mapper must be specified in the DataSource. This is the purpose of the datasource.mapper property.

property name description possible values
datasource.mapper JORM database mapper
  • rdb: generic mapper (JDBC standard driver ...)
  • rdb.postgres: mapper for PostgreSQL
  • rdb.oracle8: mapper for Oracle 8 and lesser versions
  • rdb.oracle: mapper for Oracle 9
  • rdb.mckoi: mapper for McKoi Db
  • rdb.mysql: mapper for MySQL

ConnectionManager Configuration

Each Datasource is implemented as a connection manager that can be configured via some additional properties described in the following table. Refer to the Oracle1.properties file to see an example of settings. All these settings have default values and are not required.

property name description default value
jdbc.connchecklevel JDBC connection checking level: 0 (no check), 1 (check connection), higher (call the test statement) 1
jdbc.connmaxage max age for jdbc connections 30mn
jdbc.connteststmt test statement select 1
jdbc.minconpool Minimum number of connections in the pool 0
jdbc.maxconpool Maximum number of connections in the pool -1 (no max boundary)

jdbc.connteststmt is not used when jdbc.connchecklevel is equal to 0 or 1.

jdbc.minconpool is used at DataSource creation time, and a modification is not taken into account for an already created DataSource.

jdbc.maxconpool can be dynamically increased or decreased.

Tracing SQL Requests through P6Spy

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

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

Example:

Datasource properties file content:

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

Within JONAS_BASE/conf/spy.properties file:

   realdriver=org.postgresql.Driver
    

Within JONAS_BASE/conf/trace.properties:

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

Configuring JDBC Resource Adapters

Instead of using the JOnAS "Database Service" for configuring DataSources, it is also possible to use the JOnAS "Resource Service" and JDBC connectors that are compliant to the J2EE Connector Architecture specification. The resulting functionality is the same, and the benefit is the management of pools of JDBC PrepareStatements. This section describes how the JDBC Resource Adapters should be configured to connect the application to databases.

Configuring Resource Adapters

For both container-managed or bean-managed persistence, the JDBC Resource Adapter(RA) makes use of relational storage systems through the JDBC interface. JDBC connections are obtained from a JDBC RA. The JDBC RA implements the J2EE Connector Specification using the DataSource interface as defined in the JDBC 2.0 standard extensions. An RA is configured to identify a database and a means to access it via a JDBC driver. Multiple JDBC RAs can be deployed either via the jonas.properties file or included in the autoload directory of the resource service. For complete information about RAs in JOnAS, refer to J2EE Connector Programmer's Guide. The following section explains how JDBC RARs can be defined and configured in the JOnAS server.

To support distributed transactions, the JDBC RA requires the use of at least a JDBC2-XA-compliant driver. Such drivers implementing the XADataSource interface are not always available for all relational databases. The JDBC RA 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.

The generic JDBC RAs of JOnAS provide implementations of the DriverManager, DataSource, PooledConnection, and XAConnection interfaces. These can be configured using a JDBC-compliant driver for some relational database management server products, such as Oracle, PostGres, or MySQL.

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

An RAR file must be configured and deployed (e.g., Oracle1.rar for an Oracle RAR and MySQL1.rar for a MySQL RAR, as delivered with the platform).

To define a Resource "Oracle1" in the jonas.properties file, add its name "Oracle1" (name of the RAR file) to the line jonas.service.resource.services or just include it in the autoload directory. For more information about deploying an RAR, refer to J2EE Connector Programmer's Guide.

jonas.service.resource.services Oracle1,MySQL1,PostgreSQL1

The jonas-ra.xml file that defines a DataSource should contain the following information:

jndiname JNDI name of the RAR 
URL  The JDBC database URL: jdbc:<database_vendor_subprotocol>:...
dsClass Name of the class implementing the JDBC driver
user  Database user name 
password  Database user password 

An RAR for Oracle configured as jdbc_1 in JNDI and using the Oracle thin DriverManger JDBC driver, should be described in a file called Oracle1_DM.rar, with the following properties configured in the jonas-ra.xml file:

          
  <jndiname>jdbc_1</jndiname>
  <rarlink>JOnASJDBC_DM</rarlink>
  .
  .
  <jonas-config-property>
    <jonas-config-property-name>user</jonas-config-property-name>
    <jonas-config-property-value>scott</jonas-config-property-value>
  </jonas-config-property>
  <jonas-config-property>
    <jonas-config-property-name>password</jonas-config-property-name>
    <jonas-config-property-value>tiger</jonas-config-property-value>
  </jonas-config-property>
  <jonas-config-property>
    <jonas-config-property-name>loginTimeout</jonas-config-property-name>
    <jonas-config-property-value></jonas-config-property-value>
  </jonas-config-property>
  <jonas-config-property>
    <jonas-config-property-name>URL</jonas-config-property-name>
    <jonas-config-property-value>jdbc:oracle:thin:@malte:1521:ORA1</jonas-config-property-value>
  </jonas-config-property>
  <jonas-config-property>
    <jonas-config-property-name>dsClass</jonas-config-property-name>
    <jonas-config-property-value>oracle.jdbc.driver.OracleDriver</jonas-config-property-value>
  </jonas-config-property>
  <jonas-config-property>
    <jonas-config-property-name>mapperName</jonas-config-property-name>
    <jonas-config-property-value>rdb.oracle</jonas-config-property-value>
  </jonas-config-property>

In this example, "malte" is the hostname of the server running the Oracle DBMS, 1521 is the SQL*Net V2 port number on this server, and ORA1 is the ORACLE_SID.

This example makes use of the Oracle "Thin" JDBC driver. For an application server running on the same host as the Oracle DBMS, you can use the Oracle OCI JDBC driver; in this case, the URL to use is jdbc:oracle:oci7: or jdbc:oracle:oci8:, depending on the Oracle release. Oracle JDBC drivers can be downloaded from the Oracle Web site.

To create a MySQL RAR configured as jdbc_2 in JNDI, it should be described in a file called MySQL2_DM.rar, with the following properties configured in the jonas-ra.xml file:

          
  <jndiname>jdbc_2</jndiname>
  <rarlink>JOnASJDBC_DM</rarlink>
  .
  .
  <jonas-config-property>
    <jonas-config-property-name>user</jonas-config-property-name>
    <jonas-config-property-value></jonas-config-property-value>
  </jonas-config-property>
  <jonas-config-property>
    <jonas-config-property-name>password</jonas-config-property-name>
    <jonas-config-property-value></jonas-config-property-value>
  </jonas-config-property>
  <jonas-config-property>
    <jonas-config-property-name>loginTimeout</jonas-config-property-name>
    <jonas-config-property-value></jonas-config-property-value>
  </jonas-config-property>
  <jonas-config-property>
    <jonas-config-property-name>URL</jonas-config-property-name>
    <jonas-config-property-value>jdbc:mysql://malte/db_jonas</jonas-config-property-value>
  </jonas-config-property>
  <jonas-config-property>
    <jonas-config-property-name>dsClass</jonas-config-property-name>
    <jonas-config-property-value>org.gjt.mm.mysql.Driver</jonas-config-property-value>
  </jonas-config-property>
  <jonas-config-property>
    <jonas-config-property-name>mapperName</jonas-config-property-name>
    <jonas-config-property-value>rdb.mysql</jonas-config-property-value>
  </jonas-config-property>

To create a PostGreSQL RAR configured as jdbc_3 in JNDI, it should be described in a file called PostGreSQL3_DM.rar, with the following properties configured in the jonas-ra.xml file:

          
  <jndiname>jdbc_3</jndiname>
  <rarlink>JOnASJDBC_DM</rarlink>
  .
  .
  <jonas-config-property>
    <jonas-config-property-name>user</jonas-config-property-name>
    <jonas-config-property-value>jonas</jonas-config-property-value>
  </jonas-config-property>
  <jonas-config-property>
    <jonas-config-property-name>password</jonas-config-property-name>
    <jonas-config-property-value>jonas</jonas-config-property-value>
  </jonas-config-property>
  <jonas-config-property>
    <jonas-config-property-name>loginTimeout</jonas-config-property-name>
    <jonas-config-property-value></jonas-config-property-value>
  </jonas-config-property>
  <jonas-config-property>
    <jonas-config-property-name>URL</jonas-config-property-name>
    <jonas-config-property-value>jdbc:postgresql:/malte:5432/db_jonas</jonas-config-property-value>
  </jonas-config-property>
  <jonas-config-property>
    <jonas-config-property-name>dsClass</jonas-config-property-name>
    <jonas-config-property-value>org.postgresql.Driver</jonas-config-property-value>
  </jonas-config-property>
  <jonas-config-property>
    <jonas-config-property-name>mapperName</jonas-config-property-name>
    <jonas-config-property-value>rdb.mpostgres</jonas-config-property-value>
  </jonas-config-property>
 

The database user and password can be handled in one of two ways: 1) put it in the jonas-ra.xml file in the RAR file and have the Application Components use the getConnection() method, or 2) not have it in the RAR file and have the Application Component use the getConnection(String username, String password) method.

CMP2.0/JORM

For implementing the EJB 2.0 persistence (CMP2.0), JOnAS relies on the JORM framework. JORM must adapt its object-relational mapping to the underlying database, and makes use of adapters called "mappers" for this purpose. Thus, for each type of database (and more precisely for each JDBC driver), the corresponding mapper must be specified in the jonas-ra.xml file of the deployed RAR. The mapperName element is provided for this purpose.

property name description possible values
mapperName JORM database mapper
  • rdb: generic mapper (JDBC standard driver ...)
  • rdb.postgres: mapper for PostgreSQL
  • rdb.oracle8: mapper for Oracle 8 and lesser versions
  • rdb.oracle: mapper for Oracle 9
  • rdb.mckoi: mapper for McKoi Db
  • rdb.mysql: mapper for MySQL
  • rdb.sqlserver: mapper for MS SQL Server
  • Refer to JORM documentation for a complete updated list.

ConnectionManager Configuration

Each RAR uses a connection manager that can be configured via the additional properties described in the following table. The Postgres1.jonas-ra.xml file provides an example of the settings. These settings all have default values and they are not required.

pool-params elements
property name description default value
pool-init Initial number of connections 0
pool-min Minimum number of connections 0
pool-max Maximum number of connections -1 (unlimited)
pool-max-age Number of milliseconds to keep the connection 0 (unlimited)
pstmt-max Maximum number of PreparedStatements cached per connection 10

jdbc-conn-params elements
property name description default value
jdbc-check-level JDBC connection checking level 0 (no check)
jdbc-test-statement test statement

jdbc-test-statement is not used when jdbc-check-level is equal to 0 or 1.

Tracing SQL Requests through P6Spy

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

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

Example:

jonas-ra.xml file content:

       
<jonas-resource>
<jndiname>jdbc_3</jndiname>
<rarlink>JOnASJDBC_DM</rarlink>
<native-lib></native-lib>
<log-enabled>true</log-enabled>
<log-topic>org.objectweb.jonas.jdbc.DMPostgres</log-topic>
<pool-params>
  <pool-init>0</pool-init>
  <pool-min>0</pool-min>
  <pool-max>100</pool-max>
  <pool-max-age>0</pool-max-age>
  <pstmt-max>10</pstmt-max>
</pool-params>
<jdbc-conn-params>
  <jdbc-check-level>0</jdbc-check-level>
  <jdbc-test-statement></jdbc-test-statement> 
</jdbc-conn-params>
<jonas-config-property>
  <jonas-config-property-name>user</jonas-config-property-name>
  <jonas-config-property-value>jonas</jonas-config-property-value>
</jonas-config-property>
<jonas-config-property>
  <jonas-config-property-name>password</jonas-config-property-name>
  <jonas-config-property-value>jonas</jonas-config-property-value>
</jonas-config-property>
<jonas-config-property>
  <jonas-config-property-name>loginTimeout</jonas-config-property-name>
  <jonas-config-property-value></jonas-config-property-value>
</jonas-config-property>
<jonas-config-property>
  <jonas-config-property-name>URL</jonas-config-property-name>
  <jonas-config-property-value>jdbc:postgresql://your_host:port/your_db</jonas-config-property-value>
</jonas-config-property>
<jonas-config-property>
  <jonas-config-property-name>dsClass</jonas-config-property-name>
  <jonas-config-property-value>com.p6spy.engine.spy.P6SpyDriver</jonas-config-property-value>
</jonas-config-property>
<jonas-config-property>
  <jonas-config-property-name>mapperName</jonas-config-property-name>
  <jonas-config-property-value>rdb.postgres</jonas-config-property-value>
</jonas-config-property>
<jonas-config-property>
  <jonas-config-property-name>logTopic</jonas-config-property-name>
  <jonas-config-property-value>org.objectweb.jonas.jdbc.DMPostgres</jonas-config-property-value>
</jonas-config-property>
</jonas-resource>

In $JONAS_BASE/conf/spy.properties file:

   realdriver=org.postgresql.Driver
    

In $JONAS_BASE/conf/trace.properties:

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

Migration from dbm service to the JDBC RA

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 RAConfig description for a complete description.

   RAConfig -dm -p MySQL $JONAS_ROOT/rars/autoload/JOnAS_jdbcDM MySQL

This command will create a MySQL.rar file based on the MySQL.properties file, as specified by the -p parameter. It will also include the <rarlink> to the JOnAS_jdbcDM.rar, as specified by the -dm parameter.

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.rar file using the following command:

   RAConfig -u jonas-ra.xml MySQL 

Configuring JMS Resource Adapters

Instead of using the JOnAS "JMS Service" for configuring a JMS platform, it is possible to use the JOnAS "Resource Service" and JMS adapters that are compliant to the J2EE Connector Architecture specification. The provided functionnalities are the same, with the extra benefit of allowing the deployment of 2.1 MDBs.

JMS connections are obtained from a JMS RA, which is configured to identify a JMS server and access it. Multiple JMS RAs can be deployed, either via the jonas.properties file, or via the JonasAdmin tool, or included in the autoload directory of the resource service. For complete information about RAs in JOnAS, refer to J2EE Connector Programmer's Guide.

This section describes how JMS Resource Adapters should be configured to provide messaging functionnalities to JOnAS components and applications.

JORAM Resource Adapter

The JORAM resource adapter archive (joram_for_jonas_ra.rar) is provided with the JOnAS distribution. It may be found in the $JONAS_ROOT/rars directory. For deploying it, the archive file may be declared in the jonas.properties file, as follows:

jonas.service.resource.resources	joram_for_jonas_ra

jms must be removed from the list of services:

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

The archive may also be deployed through the JonasAdmin tool, or put in JOnAS' rars/autoload directory.

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

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

The default configuration may of course be modified.

Configuring the JORAM adapter

jonas-ra.xml is the JOnAS specific deployment descriptor that configures the JORAM adapter. Changing the configuration of the RA requires to extract the deployment descriptor, edit it, and update the archive file. To do so, the RAConfig utility is provided (refer to RAConfig description for a complete description). Extracting jonas-ra.xml is done as follows:

	RAConfig joram_for_jonas_ra.rar

Updating the archive is then done as follows:

	RAConfig -u jonas-ra.xml joram_for_jonas_ra.rar

The jonas-ra.xml file sets the central configuration of the adapter, defines and sets managed connection factories for outbound communication, and defines a listener for inbound communication.

The following properties are related to the central configuration of the adapter:

property name description possible values
CollocatedServer Running mode of the JORAM server the adapter gives access to.
  • True: when deploying, the adapter starts a collocated JORAM server.
  • False: when deploying, the adapter connects to a remote JORAM server.
  • Nothing (default True value is then set).
PlatformConfigDir Directory where the a3servers.xml and joram-admin.cfg files are located.
  • Any String describing an absolute path (ex: /myHome/myJonasRoot/conf).
  • Empty String, files will be searched in $JONAS_ROOT/conf.
  • Nothing (default empty string is then set).
PersistentPlatform Persistence mode of the collocated JORAM server (not taken into account if the JORAM server is set as non collocated).
  • True: starts a persistent JORAM server.
  • False: starts a non persistent JORAM server.
  • Nothing (default False value is then set).
ServerId Identifier of the JORAM server to start (not taken into account if the JORAM server is set as non collocated).
  • Identifier corresponding to the server to start described in the a3servers.xml file (ex: 1).
  • Nothing (default 0 value is then set).
ServerName Name of the JORAM server to start (not taken into account if the JORAM server is set as non collocated).
  • Name corresponding to the server to start described in the a3servers.xml file (ex: s1).
  • Nothing (default s0 name is then set).
AdminFile Name of the file describing the administration tasks to perform; if the file does not exist, or is not found, no administration task is performed.
  • Name of the file (ex: myAdminFile.cfg).
  • Nothing (default joram-admin.cfg name is then set).
HostName Name of the host where the JORAM server runs, used for accessing a remote JORAM server (non collocated mode), and for building appropriate connection factories.
  • Any host name (ex: myHost).
  • Nothing (default localhost name is then set).
ServerPort Port the JORAM server is listening on, used for accessing a remote JORAM server (non collocated mode), and for building appropriate connection factories.
  • Any port value (ex: 16030).
  • Nothing (default 16010 value is then set).

The jonas-connection-definition tags wrap properties related to the managed connection factories:

property name description possible values
jndi-name Name used for binding the constructed connection factory.
  • Any name (ex: myQueueConnectionFactory).
UserName Default user name that will be used for opening JMS connections.
  • Any name (ex: myName).
  • Nothing (default anonymous name will be set).
UserPassword Default user password that will be used for opening JMS connections.
  • Any name (ex: myPass).
  • Nothing (default anonymous password will be set).
Collocated Specifies if the connections that will be created from the factory should be TCP or local-optimized connections (the collocated mode can only be set if the JORAM server is collocated; such factories will only be usable from within JOnAS).
  • True (for building local-optimized connections).
  • False (for building TCP connections).
  • Nothing (default TCP mode will be set).

The jonas-activationspec tag wraps a property related to inbound messaging:

property name description possible values
jndi-name Binding name of a JORAM object to be used by 2.1 MDBs.
  • Any name (ex: joramActivationSpec).

Configuring a collocated JORAM server

The a3servers.xml file describes a JORAM platform configuration and is used by a starting JORAM server (thus, it is never used if JORAM is in non collocated mode).

The default file provided with JOnAS is the following:

<?xml version="1.0"?>
<config>
    <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>

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

Specifying administration tasks

The joram-admin.cfg file describes administered objects to be (optionaly) created when deploying the adapter.

The default file provided with JOnAS creates a queue bound with name sampleQueue, a topic bound with name sampleTopic, sets the anonymous user, and creates and binds non managed connection factories named JCF, JQCF and JTCF. It also defines a host name and server port, which have the same meanings than the parameters set in the jonas-ra.xml file. Their goal is to allow easy change of host and port values without having to edit the deployment descriptor.

For requesting the creation of a queue with name "myQueueName", simply add the following line:

Queue	myQueueName

For requesting the creation of a topic with name "myTopicName", simply add the following line:

Topic	myTopicName

For requesting the creation of the user "myName" - "myPass", simply add the following line:

User	myName myPass

For requesting the creation of a non managed ConnectionFactory, to be bound with name "myCF", simply add the following line:

CF	myCF

For requesting the creation of a non managed QueueConnectionFactory, to be bound with name "myQCF", simply add the following line:

QCF	myQCF

For requesting the creation of a non managed TopicConnectionFactory, to be bound with name "myTCF", simply add the following line:

TCF	myTCF

To be noted:

Undeploying and deploying again a JORAM adapter

Undeploying a JORAM adapter either stops the collocated JORAM server, or disconnects from a remote JORAM server. It is then possible to deploy again the same adapter. 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 maybe 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 it is wanted to start a bright 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");