Overview

This document describes all of the items that can be included in the $OPENJMS_HOME/config/openjms.xml file to configure the OpenJMS server.

Configuration

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.

ElementDescriptionRequired
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

DatabaseConfiguration

This element specifies the database configuration for OpenJMS.

ElementDescriptionRequired
RdbmsDatabaseConfiguration Specifies the database configuration for a JDBC 2.0 compliant database. Yes

RdbmsDatabaseConfiguration

This element specifies the configuration for connecting to a JDBC 2.0 compliant database.

AttributeDescriptionRequired
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

AdminConfiguration

This element specifies attribute to enable the OpenJMS Administrator GUI to administer OpenJMS.

AttributeDescriptionRequired
script The shell command to start the OpenJMS server. E.g, on Windows:
${openjms.home}\bin\startup.bat
              

On Unix:
${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

ServerConfiguration

This element specifies configuration options for the OpenJMS server core.

AttributeDescriptionRequired
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

Connectors

This element specifies the connectors which may be used to connect to the OpenJMS server.

OpenJMS can support multiple connectors simultaneously.

ElementDescriptionRequired
Connector Specifies the type of communication to use, between clients and the OpenJMS server. One or more connectors may be configured. Yes

Connector

This element specifies the type of communication to use, between clients and the OpenJMS server.

AttributeDescriptionRequired
scheme Specifies the connector to use. Valid values are: Yes
ElementDescriptionRequired
ConnectionFactories Specifies the ConnectionFactory objects which will use the connector. Yes

ConnectionFactories

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.

ElementDescriptionRequired
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

ConnectionFactory

This element specifies the name of a ConnectionFactory, to be used when binding it in JNDI.

AttributeDescriptionRequired
name The name of the ConnectionFactory Yes

XAConnectionFactory

This element specifies the name of an XAConnectionFactory, to be used when binding it in JNDI.

AttributeDescriptionRequired
name The name of the XAConnectionFactory Yes

QueueConnectionFactory

This element specifies the name of a QueueConnectionFactory, to be used when binding it in JNDI.

AttributeDescriptionRequired
name The name of the QueueConnectionFactory Yes

TopicConnectionFactory

This element specifies the name of a TopicConnectionFactory, to be used when binding it in JNDI.

AttributeDescriptionRequired
name The name of the TopicConnectionFactory Yes

XAQueueConnectionFactory

This element specifies the name of a XAQueueConnectionFactory, to be used when binding it in JNDI.

AttributeDescriptionRequired
name The name of the XAQueueConnectionFactory Yes

XATopicConnectionFactory

This element specifies the name of a XATopicConnectionFactory, to be used when binding it in JNDI.

AttributeDescriptionRequired
name The name of the XATopicConnectionFactory Yes

TcpConfiguration

This elements specifies the configuration of the TCP connector.

AttributeDescriptionRequired
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" />
               
        

TcpsConfiguration

This elements specifies the configuration of the TCPS connector.

AttributeDescriptionRequired
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"/>
               
        

RmiConfiguration

This elements specifies the configuration of the RMI connector.

AttributeDescriptionRequired
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"/>
               
        

HttpConfiguration

This elements specifies the configuration of the HTTP connector.

AttributeDescriptionRequired
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"/>
               
        

HttpsConfiguration

This elements specifies the configuration of the HTTPS connector.

AttributeDescriptionRequired
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"/>
               
        

JndiConfiguration

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.

ElementDescriptionRequired
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

MessageManagerConfiguration

This element defines items specific to the Message Manager, which is responsible for message processing.

This is not currently used.

SchedulerConfiguration

This element defines items specific to the Scheduler service.

AttributeDescriptionRequired
maxThreads The maximum number of worker threads that the scheduler uses. Yes

GarbageCollectionConfiguration

This element defines items specific to the Garbage Collection service.

AttributeDescriptionRequired
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

LoggerConfiguration

This element specifies the file to initialise logging with. The OpenJMS server uses log4j for logging.

AttributeDescriptionRequired
file The path to an XML file conforming to log4j.dtd Yes

SecurityConfiguration

This element specifies options to configure security.

AttributeDescriptionRequired
securityEnabled This specifies whether to enable security. If "true", then security is enabled. If a value isn't specified, it defaults to "false". No

Users

This element is used to bootstrap the creation of users.

ElementDescriptionRequired
User This element defines an user. Zero or more users may be specified. No

User

This element is used to create an user.

AttributeDescriptionRequired
name The name of the user. Yes
password The password of the user. Yes

AdministeredDestinations

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.

ElementDescriptionRequired
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

AdministeredTopic

This element defines an administered topic, and any durable subscribers.

AttributeDescriptionRequired
name The name of the topic. This must be unique. Yes
ElementDescriptionRequired
Subscriber This defines a durable subscriber to an administered topic. Zero or more subscribers may be specified. No

Subscriber

This element define a durable subscriber to an administered topic.

AttributeDescriptionRequired
name The name of the durable subscriber. This must be unique. Yes

AdministeredQueue

This element defines an administered queue.

AttributeDescriptionRequired
name The name of the queue. This must be unique. Yes