As previously seen in the Getting Started chapter, JOnAS
is pre-configured and can be directly used if you want to work with RMI/JRMP for
remote access, and if you don't need the visibility of other classes than those that are
contained in the JOnAS distribution in $JONAS_ROOT/lib
.
If you need to use JEREMIE or RMI/IIOP for remote access, or if you
need to work with additional java classes (JDBC driver classes for example), you have to
perform specific configuration tasks. Setting a specific port number for the registry is
another configuration example.
JOnAS distribution contains a number of configuration files in
$JONAS_ROOT/conf
directory.
You can edit these files to change default configuration, but we recommend you to use a
different location for the configuration files needed by a specific application running
on JOnAS. This is achieved by using an additional environment variable called
JONAS_BASE
.
The JONAS_BASE
environment variable has been introduced in JOnAS
version 3.1.
From this version, the previous configuration rule is replaced with a very simple 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 the path to this directory.$JONAS_BASE
the following sub-directories:
$JONAS_BASE/conf
the configuration files located in
$JONAS_ROOT/conf
.
Now you can modify the configuration files according to your application's
needs as explained in the following sections.$JONAS_BASE
with a path.$JONAS_ROOT
directory, do : ant create_jonasbase
.
This will copy all the required files and create all the directories.
Please note that the build.xml
files provided with the JOnAS examples
supports JONAS_BASE
.
If you have defined this environment variable before building and installing the examples,
the generated archives are installed under the right sub-directory of
$JONAS_BASE
.
For instance, 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. JOnAS server looks for it 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. The meaning of such properties is detailed in
Configuring JOnAS services.
There is one property that is not relative to any service:
jonas.orb.port
. It indicates the
port number on which the remote objects receive calls. Its default value is 0,
which means that an anonymous port is chosen.
Setting this property to a specific port number may be used when JOnAS server is
behind a firewall.
Note that since JOnAS 3.1. version, the jonas.name
property does no
longer exist !
You can specify the name of a server on the
jonas
command line using a specific option (-n name
).
If the name is not specified, the default value is jonas.
When you need to have several JOnAS servers running simultaneously it is valuable to set a different name for each JOnAS server and so it will be possible 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...
).
Do not hesitate to use the jonas check
command to review the JOnAS configuration state.
$JONAS_ROOT/bin/unix/setenv
and $JONAS_ROOT/bin/unix/config_env
, on Unix%JONAS_ROOT%\bin\nt\setenv.bat
and %JONAS_ROOT%\bin\nt\config_env.bat
, on Windows
The former configuration script sets useful environment variables for JAVA setup ($JAVA
and
$JAVAC
),
and adds $JONAS_BASE/conf
to the $CLASSPATH
, if $JONAS_BASE
is set,
or $JONAS_ROOT/conf
, otherwise.
This script is called by almost all other scripts (jclient
, jonas
,
newbean
, registry
, GenIC
).
The latter is used to add some necessary .jar
files to the $CLASSPATH
. This script
is called by the jonas
script.
Therefore, when you need to have the visibility of specific .jar
files,
the best practice consists in updating the config_env
file.
For example, to see some JDBC driver classes you need to update in this file
one or several of the variables IDB_CLASSES
, ORACLE_CLASSES
, POSTGRE_CLASSES
,
INTERBASE_CLASSES
.
Another way to put 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 you may define an additional environment variable called
XTRA_CLASSPATH
to load specific classes at JOnAS server start-up.
See Bootstrap class loader
Usually, access to JNDI is bound to a jndi.properties
file
that must be accessible from the classpath. This is slightly different within JOnAS.
Since JOnAS 3.1.2, multi-protocol support is provided through the integration of the
CAROL component. This currently allows to
support RMI/JRMP, RMI/IIOP, JEREMIE, and CMI (clustered protocol) by just changing the
configuration. Other protocols may be supported in the future. Previously, in JOnAS
versions earlier than 3.1.2, it was neccessary to rebuild JOnAS for switching e.g. from
RMI/JRMP to JEREMIE, and to change the value of the OBJECTWEB_ORB environment variable
value ; OBJECTWEB_ORB is of no more use now. This configuration is provided within the
carol.properties
file (that includes what was provided in
the jndi.properties
file).
Such a file is supplied with the JOnAS distribution in the
$JONAS_ROOT/conf
directory.
The supported communication protocols are the following:
jonathan.xml
delivered
in $JONAS_ROOT/conf
. In general you can easily ignore
it, just make sure it was copied under
$JONAS_BASE/conf
if $JONAS_BASE
defined.
The carol.properties
file contents 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
Customization of CAROL consists in editing the
$JONAS_BASE/conf/carol.properties
file to choose the protocol through the carol.protocols
property.
You may change localhost
to the hostname where registry will be run.
You may also change the standard port number. In this case, don't forget to run
registry with this port number as argument: registry <Your_Portnumber>
,
when the registry is not launched inside the JOnAS server.
There is a current restriction due to an uncompatibility between Jeremie
and rmi/iiop.
It is therefore impossible to build a JOnAS server that allows to choose between these
two protocols through a simple configuration action. So, by default, JOnAS allows to choose
between rmi/jrmp
, Jeremie
and cmi
. If you want
to be able to use rmi/iiop
, you have to run an "ant installiiop
"
command under the $JONAS_ROOT directory. Then you will be able to choose between
rmi/jrmp
, rmi/iiop
and cmi
.
For implementing EJB security and transactions, JOnAS should rely 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 you
may change this configuration, by disabling the context propagation for security and/or
transaction; the reason for doing that is mainly to increase performance. You may configure
the context propagation 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 do not exist anymore.
They were used in JOnAS versions earlier than 3.1.2, to specify that the security
context should be propagated.
You should specify to the JOnAS deployment tool (GenIC) for which protocols you
would like stubs (for remote invocation) to be generated. You may choose several
protocols, this way you will not have to redeploy your EJBs when switching from one
protocol to another. The default is that GenIC generates stubs for rmi/jrmp
and Jeremie
. To change this configuration, you should call
GenIC with
the -protocols
option specifying a comma separated list of protocols
(choosed within jeremie, jrmp, iiop, cmi), e.g.:
GenIC -protocols jrmp,jeremie,iiop
This list of protocols may also be specified for the JOnAS ejbjar ANT task:
<jonas destdir="${dist.ejbjars.dir}" jonasroot="${jonas.root}" protocols="jrmp,jeremie,iiop" keepgenerated="true" verbose="${verbose}" mappernames="${mapper.names}" additionalargs="${genicargs}"> </jonas>
Since 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 by two ways :
A standard file is provided in
$JONAS_ROOT/conf/trace.properties
The policy to retrieve this file is to use the CLASSPATH.
You can refer to
the monolog documentation
to know in more details how you can configure logging.
Basically, we must know that monolog is build above a standard log API (currently, log4j).
You can define loggers, each one being backed on a handler.
An handler represents an output. An handler is identified by its name.
It has a type and few others properties. In
trace.properties file
two handlers have been defined:
Each handler can define the header it will use, the type of logging (console, file, rolling file), and the file name.
Note that if you specify as output filename the tag "automatic", JOnAS will
replace this tag by 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 which 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 these 4 values:
If a logger has nothing defined, it will use the properties defined for its parent.
JOnAS code is written using directly monolog API, it can use the tty handler.
Example of setting DEBUG level for the logger used in jonas_ejb module:
logger.org.objectweb.jonas_ejb.level DEBUG
Example for setting the output of JOnAS traces both on console and 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 on a file in
$JONAS_BASE/logs/
directory:
handler.logf.output automatic logger.org.objectweb.jonas.handler.0 logf
JOnAS may be seen like 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.
Here is the list of the JOnAS built-in services:
These services can be managed using the
Jadmin
administration console, which
is a Servlet based application using the
JMX technology.
Note that Jadmin can only manage available services (currently it is not possible to
launch a service via Jadmin).
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 they appear
in the list. Therefore, the following constraints should be considered:
Considering de following example:
jonas.services registry,jmx,security,jtm,dbm,resource,jms,mail,web,ejb
The registry could be omitted from the list as this service is
automatically launched if it is not already activated by another previously
started server. Same thing is true for jmx, as since JOnAS 3.1 this service
is automatically launched after the registry.
The dbm, resource, and jms services are listed after
the jtm, for the reason mentioned above.
The application components deployed on this server can use Java Messaging
and Java Mail as jms and mail are listed before ejb.
Configuration parameters for services are located in the
jonas.properties
file following a precise 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 made in
carol.properties
, see
Configuring the Communication Protocol and JNDI.
There are several Registry launching modes depending 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 JOnAS Server,remote
: the Registry has to be launched before 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 main 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 jonas.properties
file. If the file name does not
contain an absolute path name, then 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 in $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 jonas.properties
file.ejb-jar
files
using the Jadmin
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).
This service provides WEB containers for the WEB components used in
the J2EE applications.
JOnAS provides 2 implementations of this service. One for Jetty 4.2.x,
one for Tomcat 4.1.x.
It is necessary to run it when you want to use the
Jadmin
tool.
If the environment variables $JETTY_HOME
or
$CATALINA_HOME
are not set, the web container service can't
be loaded at the JOnAS startup. So a warning is displayed.
A WEB container is created from a war
file. If the file name does not contain
an absolute path name, then it should be located in the
$JONAS_BASE/webapps/
directory.
In order for JOnAS to create WEB containers, the corresponding file names
may be provided using the jonas.service.web.descriptors
property
in jonas.properties
file. In this case, the WEB containers are created when the
JOnAS server starts.
WEB containers may be also dynamically created from war
files
using the Jadmin
tool.
Example:
jonas.service.web.descriptors Bank.war
Here the WEB Container service will create a container from the
war
file named Bank.war
.
This file will be searched in $JONAS_BASE/webapps/
directory.
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 upon the WEB container service and the
EJB container service. The WEB container service is
used to provide the WEB containers for the wars
composing
the J2EE application, and the EJB container service is used to
provide the EJB containers for the ejb-jars
composing 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 Jadmin
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
Here the EAR service will deploy the ear
file
named Bank.ear
.
This file will be searched in $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.
It is a mandatory service. The Transaction service uses a
Transaction manager that may be local or launched in another JVM (a remote
Transaction manager). Typically when there are several JOnAS servers working
together, one of the Transaction service must be considered as the
master and the other as slaves. The later must be configured
as working with a remote Transaction manager.
Here is an example of configuration of two servers, one named TM in which a
stand alone Transaction service will be run, the second named EJB will be
used to deploy some 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 is the value of the transaction
time-out, in seconds, via the
jonas.service.jtm.timeout
property.
Here is the default configuration:
jonas.service.jtm.timeout 60
In order to be able to access one or several relational databases (e.g. Oracle, InstantDB, PostgreSQL, ...), JOnAS will create and use DataSource objects. You have to configure such a DataSource object according to the database you intend to use for the persistence of a bean. More details about DataSource objects and their configuration is provided in the "Configuring JDBC DataSources" chapter of the Bean Programmer's Guide.
The subsections below briefly explains how to configure a DataSource object for your database, in order to be able to run the Entity Bean example delivered with the platform.
A template Oracle1.properties file is
supplied in the installation directory. This file is used to define a
DataSource object, named Oracle1
.
You must update this template with values proper 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 you are 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.username | Database user name |
datasource.password | Database user password |
In order that the EJB platform creates the corresponding DataSource object,
you must have its name (Oracle1, not the JNDI name) in your
jonas.properties
file, on the jonas.service.dbm.datasources line:
jonas.service.dbm.datasources Oracle1
You may have several DataSource objects defined for an EJB server, in this case, you will have several dataSourceName.properties files, and the list of DataSource names on the jonas.service.dbm.datasources line of the jonas.properties file:
jonas.service.dbm.datasources Oracle1, Oracle2, InstantDB1
Your Oracle server must be running, and a JDBC driver installed (Oracle
JDBC drivers may be downloaded at their Web site).
You can then create the table used by the example with the SQL script
provided in examples/src/eb/Account.sql
.
For example:
sqlplus user/passwd SQL> @Account.sql SQL> quit
The JDBC driver classes must be accessible from the classpath. For that, you must
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. You must update this template with values proper 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
|
In order that the EJB platform creates the corresponding DataSource object,
you must have its name (InstantDB1, not the JNDI name) in your
jonas.properties
file, on the jonas.service.dbm.datasources line
jonas.service.dbm.datasources InstantDB1
InstantDB should have been properly installed and configured. You should use a version higher than 3.14. (examples have been tested with 3.25).
The JDBC driver classes must be accessible from the classpath. For that, you must
update the config_env file;
($JONAS_ROOT/bin/unix/config_env
on Unix,
or %JONAS_ROOT%\bin\nt\config_env.bat
on Windows).
You have to 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 kind of process can be used for other databases. We supply with JOnAS a template of datasource for PostgreSQL and for InterBase. Of course many other databases are currently used by the JOnAS users, e.g. Informix, Sybase, SQL Server, ... however not all JDBC drivers have been tested against JOnAS.
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 found in the EJB deployment descriptor.
Note that:
There is one property in the jonas.properties
file for configuring
the security service: the jonas.security.propagation
property
should be set to true
(which is the default value!), in order to
allow the security context propagation across method calls, see also
Security and Transaction Context Propagation.
With Tomcat 4.1.x, in the
$CATALINA_HOME/conf/server.xml
file, or
$CATALINA_BASE/conf/server.xml
replace the following line:
<Realm className="org.apache.catalina.realm.UserDatabaseRealm" debug="0" resourceName="UserDatabase"/>
By the line:
<Realm className="org.objectweb.security.catalina41.realm.UserDatabaseRealm" debug="0" resourceName="UserDatabase"/>
There is in the package org.objectweb.security.catalina41.realm a MemoryRealm, UserDatabaseRealm, JDBCRealm and a JNDI realm. You can pick up the realm that you need.
For using Jetty interceptors in your web application you must:
web-jetty.xml
file under WEB-INF
directory in the .war
file in which it specified that the
security interceptor org.objectweb.security.jetty.realm.JonasRealm
for JOnAS must be used instead of the default one.jettyRealm.properties
file that is used by
Jetty for authentication. You will find under $JONAS_ROOT/conf
an
example of such a file currently initialized for using jadmin
,
earsample
example and alarm
demo.JOnAS relies on the
jonas-users.properties
file for the access control to
the methods of EJB components. This is a simple properties file where
each property has the following
syntax: <principal> = <list of roles>
where
<principal>
is a string identifying the user. It can
be an email address
(joe.bar@foo.com
) or a login (barj
) or
whatever identifying the user.
<list of roles>
is a list of roles separated by
commas (e.g.: administrator, user
). These roles will
be used in the deployment descriptor of the EJB component.It has to be noted that to use Tomcat to identify and authenticate
the users, the principals defined in the jonas-users.properties
must be the same that those in the
$CATALINA_BASE/conf/tomcat-users.xml
file for Tomcat 4.1.x.
However, the roles defined in these two files may be
the same but it is not mandatory:
tomcat-users.xml
file
are used in Tomcat.jonas-users.properties
file are used in JOnAS.For Jetty the corresponding configuration file is jettyRealm.properties
in which users passwords and roles are defined for each web application. You can
find in $JONAS_ROOT/conf
a default jettyRealm.properties
file.
JOnAS uses a third party JMS implementation (currently the
Joram opensource is
integrated and delivered with JOnAS, the SwiftMQ
product may also be used, other JMS provider implementations may easily be integrated).
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
previously to the EJB execution, by the way of the proprietary JMS implementation
administration facilities. JOnAS provides "wrappers" upon 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.
Here are the properties that may 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 JOnAS Server (this is
the default value), if set to false it is launched in a separate JVM in
this case the jonas.service.jms.url
must be set with the connexion 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 what class must be used to perform
administrative operations. This class is the wrapper to the actual JMS provider
implementation. The default one is org.objectweb.jonas_jms.JmsAdminForJoram
that must be used for Joram.
You may get a com.swiftmq.appserver.jonas.JmsAdminForSwiftMQ class from the
SwiftMQ site if you intend to use the SwiftMQ product.
The Connector Architecture Resources service is an optional service that must be started as soon as EJB components have to 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 Connector Architecture Resources 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 way to configure the Connector Architecture Resources service is one of the following methods:
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.
In each resource adapter a jonas specific resource adapter configuration xml file must be included. This file reflects the values of all configuration properties declared in the deployment descriptor for the resource adapter. See Using a Connector Architecture Resource Adapter with JOnAS for additional information.
The JMX service must be started in order to administrate or instrument
JOnAS server via
Jadmin
. This is not a mandatory service
but if it is needed, it must be launched first. Its configuration consists in
choosing one of the two supported JMX implementations, SUN RI or MX4J. The choice
is done based on the value of the jonas.service.jmx.class
property
in the JOnAS configuration file. The two possible values are:
org.objectweb.jonas.jmx.sunri.JmxServiceImpl
, for choosing the SUN RIorg.objectweb.jonas.jmx.mx4j.Mx4jJmxServiceImpl
, for choosing MX4JThe Mail service is an optional service that may be used to send email.
It is based upon
JavaMailTM
and on JavaBeansTM Activation Framework (JAF) API.
In order to be able to send or receive mails we need a mail factory,
JOnAS provides two types of mail factories: javax.mail.Session
and javax.mail.internet.MimePartDataSource
.
MimePartDataSource
factories allow you to send mails with
a subject and recipients already set.
Mail factory objects must be configured accordingly to their type.
The subsections below briefly explain how to configure Session
and MimePartDataSource
mail factory objects,
in order to be able 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
.
You must update this template with values proper to your installation.
See the section "Configuring a mail factory" 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
.
You must update this template with values proper to your installation.
You'll find in the section "Configuring a mail factory" the list of
available properties.
Let's see before, how to configure JOnAS in order to create the mail factory objects
you need.
In order for JOnAS to create mail factory objects,
you must name them. In the mailsb example, we defined 2 factories called
MailSession1 and MailMimePartDS1.
For each factory we provided a configuration file named with the name of the
factory and having the .properties
extension
(MailSession1.properties
for the MailSession1 factory).
Also, the jonas.properties
file must define the
jonas.service.mail.factories
property. In the case of our
example, we have:
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(see 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 isn't 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 isn't 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 |