The content of this Configuration Guide is the following:
jonas-realm.xml
fileAs 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
.
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
:
$JONAS_BASE
with a path.$JONAS_ROOT
directory, enter: ant
create_jonasbase
. This will copy all the required files and
create all the directories.$JONAS_BASE
with a path.newjb
tool (new JONAS_BASE). See newjb for a full description of the command.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
.
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.
$JONAS_ROOT/bin/unix/setenv
on Unix and
%JONAS_ROOT%\bin\nt\setenv.bat
on Windows
This configuration script sets useful environment variables for JAVA
setup ($JAVA
and $JAVAC
). It adds
$JONAS_BASE/conf
to the $CLASSPATH
if
$JONAS_BASE
is set, otherwise it adds
$JONAS_ROOT/conf
. This script is called by almost all other
scripts (jclient
,
jonas
,newbean
,registry
,GenIC
).
$JONAS_ROOT/bin/unix/config_env
on Unix and
%JONAS_ROOT%\bin\nt\config_env.bat
on Windows
This script is used to add some required .jar
files to
the $CLASSPATH
. This script is called by the
jonas
script.
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.
-Ddomain.name
configuration property on the
jonas start
command line.-n name
option.domain.xml
located in the master
$JONAS_BASE/conf
directory. See domain management configuration
for details.
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:
jonathan.xml
delivered in
$JONAS_ROOT/conf
. Typically, no
modifications are necessary; just make sure it is copied under
$JONAS_BASE/conf
if
$JONAS_BASE
is defined.$JONAS_BASE/conf/jacorb.properties
file.
Since version 4.3.1, JOnAS no longer uses the JRE ORB implementation; it uses the JacORB implementation.
The default iiop model now used is
the POA model.
Thus, GenIC should be relaunched on all previously generated beans.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. Note that Jeremie is now deprecated and could be removed in a future version (jonas 4.7 ?)
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 resulted in
a choice between rmi/jrmp
, Jeremie
,
rmi/iiop
or cmi
.
This restriction does not exist starting with 4.1
release. The command "ant installiiop
" is no longer needed. The
choice can be made between rmi/jrmp
, Jeremie
,
rmi/iiop
or cmi
.
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.
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}"
additionalargs="${genicargs}">
</jonas>
Since 4.3.1 version, the default iiop model used is the POA model. Thus, GenIC should be relaunched on all previously generated beans.
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:
trace.properties
file to configure the traces
statically, before the JOnAS Server is runNote 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.
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
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
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:
collocated
: the Registry is launched in the same JVM as
the JOnAS Server,remote
: the Registry must be launched before the JOnAS
Server in a separate JVM,automatic
: the Registry is launched in the same JVM as
JOnAS Server, if not already started. This is the default value.The port number on which the Registry is launched is defined in the
carol.properties
file.
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:
ejb-jar
file name is listed in the
jonas.service.ejb.descriptors
property in the
jonas.properties
file. If the file name does not contain an
absolute path name, it should be located in the
$JONAS_BASE/ejbjars/
directory. The container is
created when the JOnAS server starts. jonas.service.ejb.descriptors Bank.jar
ejb-jar
file named Bank.jar
. This file will
be searched for in the $JONAS_BASE/ejbjars/
directory.ejb-jar
files in an autoload
directory. The name of this directory is specified using the
jonas.service.ejb.autoloaddir
property in the
jonas.properties
file.ejb-jar
files using the JonasAdmin
tool.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).
Automatic Downloading of Stubs from Clients :
JOnAS can be configured to allow dynamic Stubs downloads with the property
jonas.service.ejb.codebase.use
. Possible values are
true/false
.
Important : This functionnality works only in local mode (server +
client must be in the same filesystem)
Note that clients must have a SecurityManager set to download Stubs (if you
use jclient see jclient
script options).
When using Client Container :
Example : java -Djava.security.manager
-Djava.security.policy=/url/to/java.policy -jar /path/to/client.jar
app-client.jar
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 you are not using a JOnAS/WebContainer package, 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
JONAS_BASE/webapps/autoload
directoryJONAS_BASE/webapps/autoload/jonasAdmin
jonasAdmin.war
file to this directoryWEB containers can be also dynamically created from war
files
using the JonasAdmin
tool.
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 :
#...
|
#... |
#... |
jonas.service.ws.url-prefix
)
is used when you want to enforce the URL to be used for your deployed endpoints.
This is clearly interesting when there is a cluster of JOnAS instances and an HTTP frontend
(Apache HTTP for load balancing). You want all your web services endpoint to use the
http://www.mywebserver.com
URL instead of the usual http://localhost:9000
(that has a meaning only at local level).
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.
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
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.
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 |
datasource.isolationLevel | Database isolation level for transactions. Default is to let the database default value. Note that this setting is useful only when the container has a database lock-policy or has the shared flag set to true. |
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).
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
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.
The discovery service was added to JOnAS services in order to support domain management.
In order to enable domain management, all the servers in the domain must start the discovery service
by adding discovery
in the services list (jonas.services
property).
All the servers in the domain must have a unique name. Unicity is enforced by multicasting a "greeting" message.
By default, a server running the discovery service is a slave, but discovery service can be configured to make a server play the role of master. All the slave servers in the domain can be administered by a management application deployed on a master server. However, a management application can be deployed on a slave in order to administer it individually.
The discovery service is based on a communication infrastructure (curretly IP Multicast) allowing message broadcasting in order to publish the connector-server addresses and state changes of the servers in the domain. The master servers listen to these discovery messages. Moreover, they are able to broadcast messages asking the servers in the domain to indentify themselves. See JSR 160 support in JOnAS for more details about JMX Remote connectors.
The default configuration of the discovery service provides the IP Multicast configuration. The following two properties must have identical values for all the servers in the domain:
jonas.service.discovery.multicast.address = 224.224.224.224 jonas.service.discovery.multicast.port = 9080
The greeting mechanism can be configured by changing the default values of the two corresponding properties:
jonas.service.discovery.greeting.port = 9899 jonas.service.discovery.greeting.timeout = 1000
To start a server as a master, uncomment the following line:
jonas.service.discovery.master = true
The configuration of a master server must also define an additional port number by setting the following property:
jonas.service.discovery.source = 9888
In a management domain, at least one server must be started as master. But, any slave server
can be dynamically promoted to be a master. This is allowed by a management operation exposed by the
MBean associated to the discovery service (startDiscoveryMaster operation).
Note that the discovery service management was integrated to
the JonasAdmin
application.
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.
Until JOnAS release 4.1, the only way to provide the JMS facilities was by
setting a JMS service when configuring JOnAS. Now in the default setting, the JMS service
is disabled in the jonas.properties
config file. Note that
this JMS service does not allow deployment of 2.1 MDBs and will
become deprecated.
The new way to integrate a JMS platform is by deploying a J2EE 1.4-compliant resource adapter. This process 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:
jonas.service.jms.collocated
for setting the JMS
server launching mode. If set to true, it is launched in the
same JVM as the JOnAS Server (this is the default value). If set to
false, it is launched in a separate JVM, in which case the
jonas.service.jms.url
must be set with the connection url to
the JMS server.jonas.service.ejb.mdbthreadpoolsize
is used for setting
the default thread pool used Message Driven Beans (10 is the default
value).jonas.service.jms.queues
and
jonas.service.jms.topics
are used for setting lists of
administered objects queues or topics at launching
time.jonas.service.jms.mom
is used to indicate which class must
be used to perform administrative operations. This class is the wrapper
to the actual JMS provider implementation. The default class is
org.objectweb.jonas_jms.JmsAdminForJoram, which is required for Joram. For the SwiftMQ
product, obtain a com.swiftmq.appserver.jonas.JmsAdminForSwiftMQ
class from the SwiftMQ site. For
WebSphere MQ, the class to use is
org.objectweb.jonas_jms.JmsAdminForWSMQ.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.
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:
RAR
file name is listed in the
jonas.service.resource.resources
property in
jonas.properties
file. If the file name does not contain an
absolute path name, then it should be located in the
$JONAS_BASE/rars/
directory. jonas.service.resource.resources MyEIS
$JONAS_BASE/rars/
directory. This property is a
comma-separated list of resource adapter file names ('.rar' suffix
is optional).RAR
files in an
autoload directory. The name of this directory is specified using
the jonas.service.resource.autoloaddir
property in
jonas.properties
file. This directory is relative to the
$JONAS_BASE/rars/
directory. 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.
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 currently based on
MX4J JMX implementations, and does not require any specific configuration.
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.
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.
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.
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
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. |
The DB service is an optional service that can be used to start a
java database server in the same JVM as JOnAS.
The listening port and the database name can be set as follows:
jonas.service.db.port 9001 jonas.service.db.dbname db_jonas
There is a file HSQL1.properties
in
$JONAS_ROOT/conf
that can be used with these default values.
The users are declared in 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 the HSQL1.properties
file.
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:
$JONAS_ROOT/conf/jonas-realm.xml
:
<jonas-memoryrealm>.
<jonas-dsrealm>
of the
$JONAS_ROOT/conf/jonas-realm.xml
file.<jonas-ldaprealm>
of the
$JONAS_ROOT/conf/jonas-realm.xml
file.providerUrl
element is not set, the default
value is ldap://localhost:389.
jonas-realm_1_0.dtd
DTD file to see the default
values.org.objectweb.jonas.security.realm.web.catalina55.JACC
org.objectweb.jonas.security.realm.web.jetty50.Standard
jonas-realm.xml
file.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.
With Tomcat 5.5.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"
resourceName="UserDatabase"/>
By the line:
<Realm className="org.objectweb.jonas.security.realm.web.catalina55.JACC"
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.
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.
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.
jonas-realm.xml
fileTo add the role 'jonas
', place this example role in the
<roles>
section:
<roles>Then, add a user with the specified role.
<role name="jonas" description="Role used in the sample security howto" />
</roles>
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'.
<user name="joe" password="joe_password" groups="myApplications" />
<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.
<groups> <group name="myApplications" roles="role1,role2,role3" description="Roles for my applications" /> </groups>
jonas-realm.xml
file:<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.
[...]
<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>
jonas-realm.xml
fileFirst, 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.
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>
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>
In order to set up the client authentication based on client certificate in a Web container, do the following:
Configure the Realm the Web container will have to use.
Configure an SSL listener on the Web container.
Configure the Web application to make it ask a client certificate.
Configure the JAAS LoginModules.
Populate the Realm access list.
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.
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.catalina55.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.
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.
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.
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.
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 both Tomcat and Jetty, ensure that the restricted Web
application area is configured in the web.xml
file in the
.war
file with a security-constraint
declaration.
For both Tomcat and Jetty, ensure that the Web application is always accessed with SSL, unless the Web container will not get a certificate and will not be able to authenticate the user.
For both Tomcat and Jetty, when authentication is enabled on client certificate, the user's Web browser receives the list of the trusted (by your Web application) Certification Authorities. A connection will be established with the client only if it has a certificate issued by a trusted Certification Authorities, otherwise its certificate will be rejected.
In Jetty, the certificates of all the trusted Certification Authorities must be imported inside the keystore specified in the SSL listener.
In Tomcat, the certificates of all the trusted Certification
Authorities must be imported in the
$JAVA_HOME/jre/lib/security/cacerts
keystore file
(customize the SSL listener to modify this location).
For Jetty, if the parameter NeedClientAuth
in the
jetty.xml
file is set to true, all Web applications accessed with SSL
will ask the user to present a certificate. Use different SSL listeners
on different ports to have both Web applications that require client
certificate and those that do not.
For Jetty, remember to set the same realm-name
as the
one in the web-jetty.xml
file.
For Jetty, refer to http://jetty.mortbay.org/jetty/doc/ClientCert.htmlfor
more information.
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 LoginModule
s to use in your Web container to authenticate
the users.
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 :
resourceName
: the name of the entry in the
"jonas-realm.xml " file being used; this entry represents how and where
the authentication information is stored.
certCallback
: Specify this optional parameter if
you want this login module to ask for a certificate callback. By
default it is set to false. It should be set to true when using JAAS
realms with certificates.
CRLsResourceName
: this parameter specifies how
the CRLs are stored:
"Directory"
: if the CRL files are stored in a
directory on the machine; another parameter pointing to that
directory must be specified:
CRLsDirectoryName
: the directory
containing the CRL files (the extension for these files must be
.crl).
"LDAP"
: if your CRL files are stored in a LDAP
repository; this functionality is experimental; two additional
parameters must be specified:
address
: the address of the server that
hosts the LDAP repository
port
: the port used by the LDAP
repository; CRLs are retrieved from an LDAP directory using the
LDAP schema defined in RFC 2587.
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.configThe contents of the JAAS configuration file follows that structure:
Application_1 {Sample of a configuration file with CRL directory:
LoginModuleClassA Flag Options;
LoginModuleClassB Flag Options;
LoginModuleClassC Flag Options;
};
Application_2 {
LoginModuleClassB Flag Options;
LoginModuleClassC Flag Options;
};
Other {
LoginModuleClassC Flag Options;
LoginModuleClassA Flag Options;
};
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:
required
- The LoginModule is required to succeed.
If it succeeds or fails, authentication still proceeds through the
LoginModule list.
requisite
- The LoginModule is required to
succeed. If it succeeds, authentication continues through the LoginModule
list. If it fails, control immediately returns to the application
(authentication does not proceed through the LoginModule list).
sufficient
- The LoginModule is not required to
succeed. If it does succeed, control immediately returns to the
application (authentication does not proceed through the LoginModule
list). If it fails, authentication continues through the LoginModule
list.
optimal
- The LoginModule is not required to
succeed. If it succeeds or fails, authentication still proceeds through
the LoginModule 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=ORGE : Email Address
Subject
in a certificate contains the main attributes and
may include additional ones, such as Title, Street Address, Postal Code,
Phone Number.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" />
This section describes how to configure the Datasources for connecting the application to databases.
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 |
datasource.isolationLevel | Database isolation level for transactions. Possible values are none , serializable , read_committed , read_uncommitted , repeatable_read .The default depends on the database you use. |
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.
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 |
|
Each Datasource is implemented as a connection manager and manages a pool
of JDBC connections. The pool 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. All these attributes can be reconfigured when jonas is
running, with the jonas console (JonasAdmin
).
property name | description | default value |
---|---|---|
jdbc.connchecklevel | JDBC connection checking level:
|
1 |
jdbc.connteststmt | test statement in case jdbc.connchecklevel = 2. | select 1 |
jdbc.connmaxage | nb of minutes a connection can be kept in the pool. After this time, the connection will be closed, if minconpool limit has not been reached. |
1440 mn (= 1 day) |
jdbc.maxopentime | Maximum time (in mn) a connection can be left busy. If the caller has not issued a close() during this time, the connection will be closed automatically. | 1440 mn (= 1 day) |
jdbc.minconpool | Minimum number of connections in the pool. Setting a positive value here ensures that the pool size will not go below this limit during the datasource lifetime. |
0 |
jdbc.maxconpool | Maximum number of connections in the pool. Limiting the max pool size avoids errors from the database. |
no limit. |
jdbc.samplingperiod | Sampling period for JDBC monitoring. nb of seconds between 2 measures. |
60 sec |
jdbc.maxwaittime | Maximum time (in seconds) to wait for a connection in case of
shortage. This is valid only if maxconpool has been set. |
10 sec |
jdbc.maxwaiters | Maximum of concurrent waiters for a JDBC Connection. This is valid only if maxconpool has been set. |
1000 |
When a user requests a jdbc connection, the dbm connection manager first
checks to see if a connection is already open for its transaction. If not, it
tries to get a free connection from the free list. If there are no more
connections available, the dbm connection manager creates a new jdbc
connection (if jdbc.maxconpool is not reached). If it cannot create
new connections, the user must wait (if jdbc.maxwaiters is not
reached) until a connection is released. After a limited time
(jdbc.maxwaittime), the getConnection returns an exception. When the
user calls close() on its connection, it is put back in the free list. Many
statistics are computed (every jdbc.samplingperiod seconds) and can
be viewed by JonasAdmin
. This
is useful for tuning these parameters and for seeing the server load at any
time.
When a connection has been open for too long a time (jdbc.connmaxage), the pool will try to release it from the freelist. However, the dbm connection manager always tries to keep open at least the number of connections specified in jdbc.minconpool.
When the user has forgotten to close a jdbc connection, the system can automatically close it, after jdbc.maxopentime minutes. Note that if the user tries to use this connection later, thinking it is still open, it will return an exception (socket closed).
When a connection is reused from the freelist, it is possible to verify that it is still valid. This is configured in jdbc.connchecklevel. The maximum level is to try a dummy statement on the connection before returning it to the caller. This statement is configured in jdbc.connteststmt.
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
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.
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 (see JDBC 3.0). They are located in the $JONAS_ROOT/rars/autoload directory and thus are deployed automatically. They consist of base (or generic) RAs facilitating the build of the user JDBC RAs. Depending on the relational database management server and the available interface in the used JDBC-compliant driver, the user JDBC RA is linked (through the RAR link feature) to a generic RA (e.g. the DriverManager's one). In this case, the user RA contains only a jonas-ra.xml file with some specific parameters, such as the connection url, the user/password, or the JDBC-Driver class.
Resource adapter provided with JOnAS | description | jndi name |
---|---|---|
rars/autoload/JOnAS_jdbcDS.rar | Generic resource adapter that implements the DataSource interface | JOnASJDBC_DS |
rars/autoload/JOnAS_jdbcDM.rar | Generic resource adapter that implements the DriverManager interface | JOnASJDBC_DM |
rars/autoload/JOnAS_jdbcCP.rar | Generic resource adapter that implements the PooledConnection interface | JOnASJDBC_CP |
rars/autoload/JOnAS_jdbcXA.rar | Generic resource adapter that implements the XAConnection interface | JOnASJDBC_XA |
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.resources
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.resources 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:
<?xml version = "1.0" encoding = "UTF-8"?> <jonas-connector xmlns="http://www.objectweb.org/jonas/ns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.objectweb.org/jonas/ns http://www.objectweb.org/jonas/ns/jonas-connector_4_2.xsd" > <jndi-name>jdbc_1</jndi-name> <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> </jonas-connector>
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:
<?xml version = "1.0" encoding = "UTF-8"?> <jonas-connector xmlns="http://www.objectweb.org/jonas/ns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.objectweb.org/jonas/ns http://www.objectweb.org/jonas/ns/jonas-connector_4_2.xsd" > <jndi-name>jdbc_2</jndi-name> <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> </jonas-connector>
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:
<?xml version = "1.0" encoding = "UTF-8"?> <jonas-connector xmlns="http://www.objectweb.org/jonas/ns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.objectweb.org/jonas/ns http://www.objectweb.org/jonas/ns/jonas-connector_4_2.xsd" > <jndi-name>jdbc_3</jndi-name> <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> </jonas-connector>
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.
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 |
|
Each RAR uses a connection manager that can be configured through the jonas-ra.xml file. The pool parameters are described in the ConnectionManager Pool chapter. The following table describes the JDBC parameters. These settings all have default values and they are not required.
property name | description | default value |
---|---|---|
jdbc-check-level | JDBC connection checking level :
|
0 (no check) |
jdbc-test-statement | jdbc-test-statement is not used when jdbc-check-level is equal to 0 or 1 | select 1 |
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:
<?xml version = "1.0" encoding = "UTF-8"?> <jonas-connector xmlns="http://www.objectweb.org/jonas/ns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.objectweb.org/jonas/ns http://www.objectweb.org/jonas/ns/jonas-connector_4_2.xsd" > <jndi-name>jdbc_3</jndi-name> <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-connector>
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
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
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 functionalities 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 and access a JMS server. 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 functionalities to JOnAS components and applications.
The JORAM resource adapter archive (joram_for_jonas_ra.rar
)
is provided with the JOnAS distribution. It is located in the
$JONAS_ROOT/rars/autoload
directory and thus is deployed automatically.
Note that jms must not appear in the list of services of the jonas.properties file because the JORAM's rar and the jms service are exclusive.
jonas.services registry,jmx,jtm,dbm,security,resource,ejb,web,ear
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:
a3server.xml
file located in the
$JONAS_BASE/conf
directory and the jonas-ra.xml
file located within the RA.
ConnectionFactory
instances and binds
them with the names CF, QCF, and
TCF.
joramAdmin.xml
, located in the
$JONAS_BASE/conf
directory; those objects are bound with the
names sampleQueue, sampleTopic,
JCF, JQCF, and
JTCF.
This default behaviour is strictly equivalent to the default JMS service's behaviour.
The default configuration may, of course, be modified.
The JORAM into JOnAS is composed of 3 different parts: server, RA, and administration. Each part contains its own configuration files:
a3server.xml
is the JORAM platform configuration file, i.e.
the server part. The file is located in the $JONAS_BASE/conf directory.ra.xml and jonas-ra.xml
are the resource adapter
configuration files. They are embedded in the resource adapter (META-INF directory).joramAdmin.xml
contains the administration
tasks to perform by the JORAM server such as the JMS objects to create.
It is located in the $JONAS_BASE/conf directory
The a3server.xml
($JONAS_BASE/conf/a3server.xml) file describes the JORAM platform, i.e.
the network domain, the used transport protocol, and the reachable JORAM servers. It is used by a starting JORAM server
By default, only one collocated JORAM server is defined (s0) based on the tcp/ip protocol. A distributed configuration
example is provided in the how-to document and others examples
are available in JORAM's user guide.
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 up of one unique JORAM server (id 0, name s0), running on localhost, listening on port 16010. Those values are taken into account by the JORAM server when starting. However, they should match the values set in the deployment descriptor of the RA, otherwise the adapter either will not connect to the JORAM server, or it will build improper connection factories. The joram_raconfig allows modification to these parameters in all the configuration files.
If used in non-collocated mode, the $JONAS_BASE/conf/a3server.xml file is not used.
The ra.xml
file is the standard deployment descriptor for
the JORAM adapter and the jonas-ra.xml
file is the JOnAS-specific
deployment descriptor for the JORAM adapter. These files set the central configuration of the
adapter, define and set managed connection factories for outbound communication, and define a
listener for inbound communication. jonas-ra.xml
contains specific parameters
such as pool parameters or jndi names, but also may redefine the parameters of some ra.xml files and override
their values. Globally, a good way to proceed is to keep the original ra.xml file
with the default values and to customize the configuration only in the jonas-ra.xml file.
Changing the configuration of the RA requires extracting and editing the deployment descriptor and updating the archive file. There are several possible ways to do this:
With the RAConfig
utility (refer to
RAConfig description for a
complete description).
To extract jonas-ra.xml
, do the following:
RAConfig -path . joram_for_jonas_ra.rar
Then, to update the archive, do the following:
RAConfig -u jonas-ra.xml joram_for_jonas_ra.rar
Through the jonasAdmin
console (refer to
Administration guide for a
complete description).
In the jonasAdmin's tree, the Resource Adapter Module
node (under the
deployment
node) contains a configure
tab that allows editing of
both the ra.xml file and the jonas-ra.xml file of the undeployed RA.
Through the joram_raconfig
utility (refer to
joram_raconfig description for a
complete description).
This tool allows easy modification to the network parameters of the JORAM server in all the configuration files.
The following properties are related to the central configuration of the adapter:
property name | description | possible values |
---|---|---|
CollocatedServer | Running mode of the JORAM server to which the adapter gives access. |
|
PlatformConfigDir | Directory where the a3servers.xml and
joramAdmin.xml files are located. |
|
PersistentPlatform | Persistence mode of the collocated JORAM server. - not taken into account if the JORAM server is set as non collocated. - If true, set the property 'Transaction' to 'fr.dyade.aaa.util.NTransaction' before launching the JORAM server. - If false, set the property 'Transaction' to 'fr.dyade.aaa.util.NullTransaction' before launching the JORAM server. - Warning, if the 'Transaction' property is set in the a3server.xml file, this value is ignored. |
|
ServerId | Identifier of the JORAM server to start (not taken into account if the JORAM server is set as non-collocated). |
|
ServerName | Name of the JORAM server to start. If the JORAM server is non-collocated, it must be set to the name of the already started JORAM server (this is necessary for management purpose). |
|
AdminFileXML | Name of the file describing the administration tasks to be performed by the JORAM server, i.e. JMS destinations to create, users to create, ... If the file does not exist, or is not found, no administration task is performed. |
|
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. |
|
ServerPort | Port the JORAM server is listening on, used for accessing a remote JORAM server (non-collocated mode), and for building appropriate connection factories. |
|
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. |
|
UserName | Default user name that will be used for opening JMS connections. |
|
UserPassword | Default user password that will be used for opening JMS connections. |
|
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). |
|
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. |
|
The common parameters are described in the Common parameters chapter.
joramAdmin.xml
file (former joram-admin.cfg
file) describes the configuration
relating to the application. It describes the administration objects in the JORAM server such as the
JMS objects, the users, or the non-managed factories. In others words, it defines the JORAM objects
to be (optionally) created when deploying the adapter.
The new file format enables new capabilities since the former version (joram-admin.cfg) file, such as the ability to specify a different name for the JMS destination and its JNDI name, or the ability to define dead message queues, cluster queues, scheduler queues, and so on.
If the two files are present in the configuration (joram-admin.cfg, joramAdmin.xml), the two are loaded and object conflicts must be resolved otherwise a failure will occur. Note that joram-admin.cfg is now deprecated.
A dynamic reloading can be performed through the class org.objectweb.joram.client.jms.admin.AdminModule.executeXMLAdmin() method.
The default file provided with JOnAS creates a queue bound with the name sampleQueue, a topic bound with the name sampleTopic, sets the anonymous user, and creates and binds non-managed connection factories named JCF, JQCF and JTCF.
To be noted:
The new format is XML and a simple example is given below:
<?xml version="1.0"?> <JoramAdmin> <AdminModule> <collocatedConnect name="root" password="root"/> </AdminModule> <ConnectionFactory className="org.objectweb.joram.client.jms.tcp.TcpConnectionFactory"> <tcp host="localhost" port="16010"/> <jndi name="JCF"/> </ConnectionFactory> <ConnectionFactory className="org.objectweb.joram.client.jms.tcp.QueueTcpConnectionFactory"> <tcp host="localhost" port="16010"/> <jndi name="JQCF"/> </ConnectionFactory> <ConnectionFactory className="org.objectweb.joram.client.jms.tcp.TopicTcpConnectionFactory"> <tcp host="localhost" port="16010"/> <jndi name="JTCF"/> </ConnectionFactory> <User name="anonymous" password="anonymous" serverId="0"/> <Queue name="sampleQueue"> <freeReader/> <freeWriter/> <jndi name="sampleQueue"/> </Queue> <Topic name="sampleTopic"> <freeReader/> <freeWriter/> <jndi name="sampleTopic"/> </Topic> </JoramAdmin>
For requesting the creation of a new object, simply add the element in the file. For example, to add a queue 'MyQueue', add the following XML element:
<Queue name="myQueue"> <freeReader/> <freeWriter/> <jndi name="myQueue"/> </Queue>
When the JORAM is not collocated, the AdminModule must be defined as follows:
<AdminModule> <connect hostName="localhost" port="16020" name="root" password="root"/> </AdminModule>
The port number must be set with the server port number (defined in the a3server.xml
and in the JORAM's RAR configuration ra.xml
and jonas-ra.xml
files).
Possible parameters for a queue definition:
<Queue name="" serverId="" className="" dmq="" nbMaxMsg="" threshold=""> <property name="" value=""/> <property name="" value=""/> <reader user=""/> <writer user=""/> <freeReader/> <freeWriter/> <jndi name=""/> </Queue>
Possible parameters for a topic definition:
<Topic name="" parent="" serverId="" className="" dmq=""> <property name="" value=""/> <property name="" value=""/> <reader user=""/> <writer user=""/> <freeReader/> <freeWriter/> <jndi name=""/> </Topic>
Example of a dead message queue definition:
<DMQueue name="DMQ" serverId="0"> <reader user="anonymous"/> <writer user="anonymous"/> <freeReader/> <freeWriter/> <jndi name="DMQ"/> </DMQueue>
Example of a scheduler queue definition:
<Destination type="queue" serverId="0" name="schedulerQueue" className="com.scalagent.joram.mom.dest.scheduler.SchedulerQueue"> <freeReader/> <freeWriter/> <jndi name="schedulerQueue"/> </Destination>
Example of a clustered queues destination:
<Cluster> <Queue name="queue0" serverId="0" className="org.objectweb.joram.mom.dest.ClusterQueue"> <freeReader/> <freeWriter/> <property name="period" value="10000"/> <property name="producThreshold" value="50"/> <property name="consumThreshold" value="2"/> <property name="autoEvalThreshold" value="false"/> <property name="waitAfterClusterReq" value="1000"/> <jndi name="queue0"/> </Queue> <Queue name="queue1" serverId="1" className="org.objectweb.joram.mom.dest.ClusterQueue"> <freeReader/> <freeWriter/> <property name="period" value="10000"/> <property name="producThreshold" value="50"/> <property name="consumThreshold" value="2"/> <property name="autoEvalThreshold" value="false"/> <property name="waitAfterClusterReq" value="1000"/> <jndi name="queue1"/> </Queue> <Queue name="queue2" serverId="2" className="org.objectweb.joram.mom.dest.ClusterQueue"> <freeReader/> <freeWriter/> <property name="period" value="10000"/> <property name="producThreshold" value="50"/> <property name="consumThreshold" value="2"/> <property name="autoEvalThreshold" value="false"/> <property name="waitAfterClusterReq" value="1000"/> <jndi name="queue2"/> </Queue> <freeReader/> <freeWriter/> <reader user="user0"/> <writer user="user0"/> <reader user="user1"/> <writer user="user1"/> <reader user="user2"/> <writer user="user2"/> </Cluster>
Others samples are provided with the JORAM source code.
The joram_raconfig
tool aims to facilitate changes to the parameters (host, port, server id) in the JORAM configuration files.
JORAM relies on several configuration files: a3server.xml, joramAdmin.xml, jonas-ra.xml. With joram_raconfig, all these configuration
files are updated and thus the consistency is ensured.
Usage :
joram_raconfig [-p <port>] [-h <host>] [-s <serverid>] with port : listening port of the JORAM server host : IP address of the JORAM server serverid : server id of the JORAM server
A pool of ManagedConnection is defined for each factory (connection definition) specified in the ra.xml file. See the pool parameters in the ConnectionManager Pool chapter.
The JORAM RA manages a pool of session/thread for each connection and, by default, the maximum number of parallel sessions is set to 10.
When linked with an MDB, this maximum number of entries in the pool corresponds to the maximum number of messages that can be processed in parallel per MDB. A session is released to the pool just after the message processing (onMessage()). When the maximum is reached, the inquiries for a session creation are blocked until a session becomes available in the pool.
The maxNumberOfWorks property can be set in the MDB JOnAS-specific deployment descriptor. For example, the code below can be added to limit the number of parallel session to 100 (default value is 10).
<activation-config-property> <activation-config-property-name>maxNumberOfWorks</activation-config-property-name> <activation-config-property-value>10</activation-config-property-value> </activation-config-property>
Undeploying a JORAM adapter either stops the collocated JORAM server or disconnects from a remote JORAM server. It is then possible to deploy the same adapter again. If set for running a collocated server, it will re-start it. If the running mode is persistent, then the server will be retrieved in its pre-undeployment state (with the existing destinations, users, and possibly messages). If set for connecting to a remote server, the adapter will reconnect and access the destinations it previously created.
In the collocated persistent case, if the intent is to start a brand new
JORAM server, its persistence directory should be removed. This directory is
located in JOnAS' running directory and has the same name as the JORAM server
(for example, s0/
for server "s0").
The resource service of JOnAS creates a connection manager for each connection definition described in the deployed RAR file. Each connection manager instance owns its managed connection pool.
Only one connection definition can be defined in a JCA 1.0-compliant RAR, while JCA 1.5 allows several connection definitions to be defined for a single RAR file.
The pool parameters may be defined in the jonas-ra.xml file (embedded in the resource adapter archive) either at the root level (jonas-connector element) or at the connection definition level (see the XML schema). The values defined at the connection-definition level override the values defined at the root level.
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 seconds to keep the connection in the pool | 0 (unlimited) |
pstmt-max | Maximum number of PreparedStatements cached per connection, -1 to disable | 10 |
pool-max-opentime | Maximum open time in minutes for a connection in the pool. The timed out active connection is automatically closed. | 0 (infinite) |
pool-max-waiters | Maximum number of waiters (threads) allowed to wait for a Connection. When the threshold is reached, an exception 'no more connections' is thrown. | 0 |
pool-max-waittime | Maximum number of seconds to wait for a connection when the pool is full. When timeout occurs, an exception 'no more connections' is thrown. If 0 is set, the default value is used. | 10 (seconds) |
pool-sampling-period | Pool statistics sampling period in seconds | 30 (seconds) |
Example:
jonas-ra.xml file content with a pool definition at the jonas-connector level
<jonas-connector xmlns="http://www.objectweb.org/jonas/ns" ... <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>0</pstmt-max> <pool-max-opentime>0</pool-max-opentime> <pool-max-waiters>0</pool-max-waiters> <pool-max-waittime>0</pool-max-waittime> <pool-sampling-period>30</pool-sampling-period> </pool-params> ... </jonas-connector>
jonas-ra.xml file content with a pool definition at the connection-definition level
<jonas-connector xmlns="http://www.objectweb.org/jonas/ns" ... <jonas-connection-definition> <description>...</description> <jndi-name>...</jndi-name> <jonas-config-property> ... </jonas-config-property> ... <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>0</pstmt-max> <pool-max-opentime>0</pool-max-opentime> <pool-max-waiters>0</pool-max-waiters> <pool-max-waittime>0</pool-max-waittime> <pool-sampling-period>30</pool-sampling-period> </pool-params> ... </jonas-connection-definition> </jonas-connector>
The jonas-ra.xml
may contain the optional rarlink
element.
It allows a base resource adapter definition to be used, overriding only a subset of the specific parameters. Typically,
it enables a JDBC resource adapter to be defined, relying on the generic resource adapter provided with JOnAS. In this
case, the new RA package may only contain the META-INF/jonas-ra.xml file.
property name | description | default value |
---|---|---|
rarlink | Jndi name of the base RA | none |
Example:
jonas-ra.xml file content with a rar link to the generic JDBC RAR 'JOnASJDBC_DM'
<jonas-connector xmlns="http://www.objectweb.org/jonas/ns" ... <rarlink>JOnASJDBC_DM</rarlink> ... </jonas-connector>
The jonas-ra.xml
may contain the optional parameters log-enabled
and log-topic
in order to define the logging properties for the resource adapter.
The first one, log-enabled
, specifies whether the logging must be turned on for the resource adapter software.
If yes, by default the topic that is used is 'org.objectweb.jonas.jca', and this value may be overriden by the second
parameter, log-topic
.
property name | description | default value |
---|---|---|
log-enabled | Turn on/off the logging for the resource adapter | false |
log-topic | Logging topic used for the resource adapter logging | org.objectweb.jonas.jca |
Example:
jonas-ra.xml file content with logging parameters'
<jonas-connector xmlns="http://www.objectweb.org/jonas/ns" ... <log-enabled>true</log-enabled> <log-topic>mypackage</log-topic> ... </jonas-connector>