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.

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 opti ons 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.

Element Description Required
RdbmsDatabaseConfiguration Specifies the database configuration for a JDBC 2.0 compliant database. No
JdbmDatabaseConfiguration Specifies the database configuration for the JDBM database.

WARNING: support for this database will be removed after the 0.7.6 final release.

No

RdbmsDatabaseConfiguration

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

JdbmDatabaseConfiguration

This element specifies the configuration for connecting to the JDBM database.

WARNING: support for this database will be removed after the 0.7.6 final release.

Attribute Description Required
name The database path name. Yes
cacheSize The size of the database cache. This defaults to "512" if a value isn't specified. No

AdminConfiguration

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
              

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.

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 (o r 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.

Element Description Required
Connector Specifies the type of communication to use, between clients and the OpenJMS server. One or more connectors must be configured. Yes

Connector

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

OpenJMS can support multiple connectors simultaneously.

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

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.

Element Description Required
QueueConnectionFactory Specifies to bind a QueueConnectionFactory in JNDI. Yes
TopicConnectionFactory Specifies to bind a TopicConnectionFactory in JNDI. Yes
XAQueueConnectionFactory Specifies to bind a XAQueueConnectionFactory in JNDI. No
XATopicConnectionFactory Specifies to bind a XATopicConnectionFactory in JNDI. No

QueueConnectionFactory

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

TopicConnectionFactory

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

XAQueueConnectionFactory

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

XATopicConnectionFactory

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

Attribute Description Required
name The name of the XATopicConnectionFactory Yes

TcpConfiguration

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. It defaults to "3030" if a value isn't specified. No
jndiPort The JNDI port, if an embedded JNDI provider is being used. It defaults to "3035" if a value isn't specified. No

TcpsConfiguration

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 runs on. It defaults to "3030" if a value isn't specified. No
jndiPort The JNDI port, if an embedded JNDI provider is being used. It defaults to "3035" if a value isn't specified. No

RmiConfiguration

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., embe ddedRegistry is "false" . No
registryPort The RMI registry port. It defaults to "1099" if a value isn't specified. No
clientPingInterval The client ping interval, specified in seconds. If set to "0" , the ping is disabled. It defaults to "15" if a value isn't specified. No

HttpConfiguration

This elements specifies the configuration of the HTTP connector .

Attribute Description Required
host The web server host. It defaults to "localhost" if no value is set. No
port The web server port. It defaults to "8080" if no value is set. No
proxyHost The proxy host used to connect back to clients. No
proxyPort The proxy port used to connect back to clients. No
clientPingInterval The client ping interval, specified in seconds. If set to "0" , the ping is disabled. It defaults to "15" if a value isn't specified. No
serverServlet The OpenJMS server servlet path. Defaults to "/openjms/OpenJMSServer" if a value isn't specified. No

HttpsConfiguration

This elements specifies the configuration of the HTTPS connector .

Attribute Description Required
host The web server host. It defaults to "localhost" if no value is set. No
port The web server port. It defaults to "8080" if no value is set. No
proxyHost The proxy host used to connect back to clients. No
proxyPort The proxy port used to connect back to clients. No
clientPingInterval The client ping interval, specified in seconds. If set to "0" , the ping is disabled. It defaults to "15" if a value isn't specified. No
serverServlet The OpenJMS se rver servlet path. Defaults to "/openjms/OpenJMSServer" if a value isn't specified. No

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.

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

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.

Attribute Description Required
maxThreads The maximum number of worker threads that the scheduler uses. Yes

GarbageCollectionConfiguration

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 th e 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.

Attribute Description Required
file The path to an XML file conforming to log4j.dtd Yes

SecurityConfiguration

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

Users

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

User

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

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.

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

AdministeredTopic

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

Subscriber

This element define a durable subscriber to an administered topic.

Attribute Description Required
name The name of the durable subscriber. This must be unique. Yes

AdministeredQueue

This element defines an administered queue.

Attribute Description Required
name The name of the queue. This must be unique. Yes