This document describes all of the items that can be included in the $OPENJMS_HOME/config/openjms.xml file to configure the OpenJMS server.
The <Configuration> element is the root element of
the OpenJMS server configuration file. The following table lists all
of the possible child elements. Child elements with children are then
documented further in subsequent sections.
| Element | Description | Required |
|---|---|---|
| DatabaseConfiguration | Describes the database connection properties. | Yes |
| AdminConfiguration | Contains attributes to enable the OpenJMS Administrator GUI to administer OpenJMS. | Yes |
| ServerConfiguration | Configuration options for the OpenJMS server core. | No |
| Connectors | Specifies the connectors which may be used to connect to OpenJMS. | No |
| TcpConfiguration | Configuration options for the TCP connector. | No |
| TcpsConfiguration | Configuration options for the TCPS connector. | No |
| RmiConfiguration | Configuration options for the RMI connector. | No |
| HttpConfiguration | Configuration options for the HTTP connector. | No |
| HttpsConfiguration | Configuration options for the HTTPS connector. | No |
| JndiConfiguration | Specifies the JNDI properties, when using an external JNDI provider. | No |
| MessageManagerConfiguration | Specifies options for the Message Manager, which handles message processing. | No |
| SchedulerConfiguration | Specifies options for the Scheduler service. | No |
| GarbageCollectionConfiguration | Specifies options for the Garbage Collection service. | No |
| LoggerConfiguration | Specifies options to configure logging. | No |
| SecurityConfiguration | Specifies options to configure security. | No |
| Users | This allows users to be registered when the server is started. | No |
| AdministeredDestinations | This allows administered Topic and Queue objects to be registered when the server is started. This avoids the need to create them programmatically, or via the OpenJMS Administrator GUI. | No |
This element specifies the database configuration for OpenJMS.
| Element | Description | Required |
|---|---|---|
| RdbmsDatabaseConfiguration | Specifies the database configuration for a JDBC 2.0 compliant database. | Yes |
This element specifies the configuration for connecting to a JDBC 2.0 compliant database.
| Attribute | Description | Required |
|---|---|---|
| class |
The connection manager, which pools connections to the underlying
database. This is a fully qualified class name, and defaults
to
"org.exolab.jms.persistence.DBCPConnectionManager"
if a value is not set.
|
No |
| driver | The class name of JDBC driver, used to access the database. | Yes |
| url | The JDBC URL. | Yes |
| user | The user name. | Yes |
| password | The user password. | Yes |
| maxActive | The maximum no. of active connections that can be allocated from the connection pool. Use "0" for no limit. Defaults to "10". | No |
| maxIdle | The maximum no. of connections that can sit idle in the connection pool, before connections are evicted. Defaults to "10". | No |
| minIdleTime | The minimum time, in seconds, that a connection may remain idle before it may be evicted. The default value of "0" disables eviction of idle connections. Must be used in conjunction with evictionInterval. | No |
| evictionInterval | The interval, in seconds, between checking idle connections for eviction. Idle connections are removed after minIdleTime seconds, or if testQuery is specified and the query fails. | No |
| testQuery | Specifies an SQL query to validate connections. This query should return at least one row, and be fast to execute. By default, no connection is validated. | No |
| testBeforeUse | If "true", each connection is tested before being used, using testQuery. If a connection fails, it is discarded, and another connection allocated. This ensures a higher reliability, at the cost of performance. Defaults to "false". | No |
This element specifies attribute to enable the OpenJMS Administrator GUI to administer OpenJMS.
| Attribute | Description | Required |
|---|---|---|
| script |
The shell command to start the OpenJMS server. E.g, on Windows:
${openjms.home}\bin\startup.bat
${openjms.home}/bin/startup.sh
|
Yes |
| config |
The path to the OpenJMS server configuration file.
If not specified, it defaults to
"${openjms.home}/config/openjms.xml"
|
No |
This element specifies configuration options for the OpenJMS server core.
| Attribute | Description | Required |
|---|---|---|
| host |
The host address of the OpenJMS server.
This is used by the server when registering connection factories
in JNDI, to enable clients to locate the server.
If a value isn't specified or is set to
"localhost", it defaults to the local host's IP
address.
If the host machine has multiple NICs, then the host will need
to be specified.
|
No |
| embeddedJNDI |
This specifies whether to use an embedded (or internal) JNDI
provider, or an external one. If "false", then the
JndiConfiguration element
must be specified.
If a value isn't specified, it defaults to "true".
|
No |
This element specifies the connectors which may be used to connect to the OpenJMS server.
OpenJMS can support multiple connectors simultaneously.
| Element | Description | Required |
|---|---|---|
| Connector | Specifies the type of communication to use, between clients and the OpenJMS server. One or more connectors may be configured. | Yes |
This element specifies the type of communication to use, between clients and the OpenJMS server.
| Attribute | Description | Required |
|---|---|---|
| scheme | Specifies the connector to use. Valid values are: | Yes |
| Element | Description | Required |
| ConnectionFactories |
Specifies the ConnectionFactory objects which will
use the connector.
|
Yes |
Connection factories are bound in JNDI by the OpenJMS server. This element defines the type and binding of the factories.
Multiple connection factories may be specified for each type.
Each connection factory must have a unique name.
| Element | Description | Required |
|---|---|---|
| ConnectionFactory |
Specifies to bind a ConnectionFactory in JNDI.
|
No |
| QueueConnectionFactory |
Specifies to bind a QueueConnectionFactory in JNDI.
|
No |
| TopicConnectionFactory |
Specifies to bind a TopicConnectionFactory in JNDI.
|
No |
| XAQueueConnectionFactory |
Specifies to bind a XAQueueConnectionFactory in
JNDI.
|
No |
| XATopicConnectionFactory |
Specifies to bind a XATopicConnectionFactory in
JNDI.
|
No |
This element specifies the name of a ConnectionFactory, to
be used when binding it in JNDI.
| Attribute | Description | Required |
|---|---|---|
| name | The name of the ConnectionFactory |
Yes |
This element specifies the name of an XAConnectionFactory,
to be used when binding it in JNDI.
| Attribute | Description | Required |
|---|---|---|
| name | The name of the XAConnectionFactory |
Yes |
This element specifies the name of a
QueueConnectionFactory, to be used when binding it
in JNDI.
| Attribute | Description | Required |
|---|---|---|
| name | The name of the QueueConnectionFactory |
Yes |
This element specifies the name of a
TopicConnectionFactory, to be used when binding it
in JNDI.
| Attribute | Description | Required |
|---|---|---|
| name | The name of the TopicConnectionFactory |
Yes |
This element specifies the name of a
XAQueueConnectionFactory, to be used when binding it
in JNDI.
| Attribute | Description | Required |
|---|---|---|
| name | The name of the XAQueueConnectionFactory |
Yes |
This element specifies the name of a
XATopicConnectionFactory, to be used when binding it
in JNDI.
| Attribute | Description | Required |
|---|---|---|
| name | The name of the XATopicConnectionFactory |
Yes |
This elements specifies the configuration of the TCP connector.
| Attribute | Description | Required |
|---|---|---|
| internalHost | This is only applicable when the OpenJMS server is behind a NAT firewall. It becomes the internal address the server is known by and the host address in ServerConfiguration is the external address. Clients will attempt to connect to host first. If that fails, they will try to connect to internalHost. | No |
| port | The port number that the server listens on. | Yes |
| jndiPort |
The JNDI port, if an embedded JNDI provider is being used.
It defaults to "0" if a value isn't specified,
indicating that the value of port should be used.
|
No |
| adminPort |
The administration service port. It defaults to "0"
if a value isn't specified, indicating that the value of
port should be used.
|
No |
| bindAll |
If "false", can be used on a multi-homed host to
only accept connect requests on the address specified by
ServerConfiguration/host.
If "true", it will accept connections on any/all
local addresses. It defaults to "true".
|
No |
If no <TcpConfiguration> element is specified, the following is used:
<TcpConfiguration port="3035" jndiPort="0" adminPort="0" bindAll="true" />
This elements specifies the configuration of the TCPS connector.
| Attribute | Description | Required |
|---|---|---|
| internalHost | This is only applicable when the OpenJMS server is behind a NAT firewall. It becomes the internal address the server is known by and the host address in ServerConfiguration is the external address. Clients will attempt to connect to host first. If that fails, they will try to connect to internalHost. | No |
| port | The port number that the server listens on. | Yes |
| jndiPort |
The JNDI port, if an embedded JNDI provider is being used.
It defaults to "0" if a value isn't specified,
indicating that the value of port should be used.
|
No |
| adminPort |
The administration service port. It defaults to "0"
if a value isn't specified, indicating that the value of
port should be used.
|
No |
| bindAll |
If "false", can be used on a multi-homed host to
only accept connect requests on the address specified by
ServerConfiguration/host.
If "true", it will accept connections on any/all
local addresses. It defaults to "true".
|
No |
| keyStore |
The path to the keystore. If not specified, it defaults to
"${openjms.home}/config/openjms.keystore".
|
No |
| keyStorePassword |
The keystore password. If not specified, it defaults to
"openjms".
|
No |
| keyStoreType |
The keystore type. If not specified, it defaults to
"JKS".
|
No |
| trustStore |
The path to the trustStore. If not specified, it defaults to
the value of keyStore
|
No |
| trustStorePassword |
The truststore password. If unset, this defaults to the value
of keyStorePassword.
|
No |
| trustStoreType |
The truststore type. If not specified, it defaults to
"JKS".
|
No |
| needClientAuth |
Determines if connections which are accepted must include client
authentication. If "false", clients do not need to
provide authentication information. If "true",
clients must authenticate themselves.
Defaults to "false".
|
No |
If no <TcpsConfiguration> element is specified, the following is used:
<TcpsConfiguration port="3035" jndiPort="0" adminPort="0" bindAll="true"
keyStore="${openjms.home}/config/openjms.keystore"
keyStorePassword="openjms"
keyStoreType="JKS"
trustStoreType="JKS"
needClientAuth="false"/>
This elements specifies the configuration of the RMI connector.
| Attribute | Description | Required |
|---|---|---|
| embeddedRegistry |
This specifies whether to use an embedded (or internal) RMI
registry, or an external one. If no value is specified, it
defaults to "true"
|
No |
| registryHost |
The RMI registry host. This is only applicable if an external
RMI registry is being used, i.e., embeddedRegistry is
"false".
|
No |
| registryPort |
The RMI registry port. It defaults to "1099" if a
value isn't specified.
|
No |
If no <RmiConfiguration> element is specified, the following is used:
<RmiConfiguration embeddedRegistry="true"
registryHost="localhost"
registryPort="1099"/>
This elements specifies the configuration of the HTTP connector.
| Attribute | Description | Required |
|---|---|---|
| port | The port number that the server listens on. | Yes |
| jndiPort |
The JNDI port, if an embedded JNDI provider is being used.
It defaults to "0" if a value isn't specified,
indicating that the value of port should be used.
|
No |
| adminPort |
The administration service port. It defaults to "0"
if a value isn't specified, indicating that the value of
port should be used.
|
No |
| bindAll |
If "false", can be used on a multi-homed host to
only accept connect requests on the address specified by
ServerConfiguration/host.
If "true", it will accept connections on any/all
local addresses. It defaults to "true".
|
No |
| webServerHost |
The web server host. It defaults to "localhost"
if no value is set.
|
No |
| webServerPort | The web server port. | Yes |
| servlet |
The tunnel servlet path. It defaults to
"/openjms-tunnel/tunnel" if a value isn't specified.
|
No |
If no <HttpConfiguration> element is specified, the following is used:
<HttpConfiguration port="3030" jndiPort="0" adminPort="0" bindAll="true"
webServerHost="localhost" webServerPort="80"
servlet="/openjms-tunnel/tunnel"/>
This elements specifies the configuration of the HTTPS connector.
| Attribute | Description | Required |
|---|---|---|
| port | The port number that the server listens on. | Yes |
| jndiPort |
The JNDI port, if an embedded JNDI provider is being used.
It defaults to "0" if a value isn't specified,
indicating that the value of port should be used.
|
No |
| adminPort |
The administration service port. It defaults to "0"
if a value isn't specified, indicating that the value of
port should be used.
|
No |
| bindAll |
If "false", can be used on a multi-homed host to
only accept connect requests on the address specified by
ServerConfiguration/host.
If "true", it will accept connections on any/all
local addresses. It defaults to "true".
|
No |
| webServerHost |
The web server host. It defaults to "localhost"
if no value is set.
|
No |
| webServerPort | The web server port. | Yes |
| servlet |
The tunnel servlet path. It defaults to
"/openjms-tunnel/tunnel" if a value isn't specified.
|
No |
If no <HttpsConfiguration> element is specified, the following is used:
<HttpsConfiguration port="3030" jndiPort="0" adminPort="0" bindAll="true"
webServerHost="localhost" webServerPort="443"
servlet="/openjms-tunnel/tunnel"/>
This element defines the properties used when constructing an InitialContext. This only needs to be specified if an external JNDI provider is being used.
See Configuring JNDI for more details.
| Element | Description | Required |
|---|---|---|
| property |
A name and value pair used in the creation of the InitialContext.
E.g:
<property name="java.naming.factory.initial"
value="com.sun.jndi.rmi.registry.RegistryContextFactory"/>
|
No |
This element defines items specific to the Message Manager, which
is responsible for message processing.
This is not currently used.
This element defines items specific to the Scheduler service.
| Attribute | Description | Required |
|---|---|---|
| maxThreads | The maximum number of worker threads that the scheduler uses. | Yes |
This element defines items specific to the Garbage Collection service.
| Attribute | Description | Required |
|---|---|---|
| memoryCheckInterval |
This indicates how often the server will check the memory
utilization of the server.
It will check to ensure that the ratio of free memory to total
memory doesn't fall below the lowWaterThreshold.
The value is specified in seconds, and defaults to
"30" seconds if not set.
|
No |
| lowWaterThreshold |
This is the ratio of free memory to total memory, specified as a
percentage, which will trigger garbage collection.
The default value of "20" indicates that when free
memory falls below 20% of total memory (i.e. total VM memory)
then garbage collection will be triggered. The range of valid
values is "10"-"50".
|
No |
| garbageCollectionInterval |
This indicates how often the garbage collector will run to remove
processed messages from the cache. A value of "0"
will disable this capability.
The value is specified in seconds, and defaults to
"600" seconds if a value is not set.
|
No |
| garbageCollectionThreadPriority |
This is the priority assigned to the garbage collection thread.
It ranges from "1"-"10", and defaults to
"5" if a value is not set.
|
No |
This element specifies the file to initialise logging with. The OpenJMS server uses log4j for logging.
| Attribute | Description | Required |
|---|---|---|
| file | The path to an XML file conforming to log4j.dtd | Yes |
This element specifies options to configure security.
| Attribute | Description | Required |
|---|---|---|
| securityEnabled |
This specifies whether to enable security. If
"true", then security is enabled.
If a value isn't specified, it defaults to "false".
|
No |
This element is used to bootstrap the creation of users.
| Element | Description | Required |
|---|---|---|
| User | This element defines an user. Zero or more users may be specified. | No |
This element is used to create an user.
| Attribute | Description | Required |
|---|---|---|
| name | The name of the user. | Yes |
| password | The password of the user. | Yes |
This element is used to bootstrap the creation of administered topics and queues. It also allows the client to register durable subscribers for administered topics.
| Element | Description | Required |
|---|---|---|
| AdministeredTopic | This element defines an administered topic, and any durable subscribers. Zero or more topics may be specified. | No |
| AdministeredQueue | This element defines an administered queue, and any durable subscribers. Zero or more queues may be specified. | No |
This element defines an administered topic, and any durable subscribers.
| Attribute | Description | Required |
|---|---|---|
| name | The name of the topic. This must be unique. | Yes |
| Element | Description | Required |
| Subscriber | This defines a durable subscriber to an administered topic. Zero or more subscribers may be specified. | No |