13
Lightweight Configuration

The Oracle Message Broker supports two means of specifying configuration information for administration: using an LDAP Directory, and using Lightweight Configuration. With Lightweight Configuration, the Oracle Message Broker reads configuration information from a file or from Java properties when it begins its execution. The Oracle Message Broker configuration information specifies the names and configuration options for all administrative objects, such as the names and types of JMS destinations (topics or queues).

Lightweight configuration supports a variant called Zero Configuration. Zero Configuration is only supported for the AQ Driver. Zero Configuration allows the Oracle Message Broker to start with the AQ Driver as easily as a JDBC connection starts. The only configuration information required for Zero Configuration is the AQ Database Server service name, user name, and password. See "Obtaining a Connection Factory Instance (in Local Mode)" for more information on Zero Configuration.

This chapter describes Oracle Message Broker Lightweight Configuration. Refer to Chapter 4, "Administration" for a description of configuration using the Oracle Message Broker with an LDAP Directory to specify configuration information.

This chapter includes the following sections:

• Benefits of Lightweight Configuration

• Using Lightweight Configuration

• Lightweight Configuration Properties

• Sample Configuration Files

• Lightweight Configuration Constraints and Limitations

Benefits of Lightweight Configuration

Lightweight configuration allows the Oracle Message Broker to operate without using an LDAP Directory to store its administrative information. The benefits of Lightweight Configuration are:

• A smaller footprint - Use of the directory requires an installation of Oracle8i. If Oracle8i is installed on the local system, it requires significant disk resources.

• Increased availability -Using Lightweight Configuration can improve the Oracle Message Broker availability for Oracle Message Broker clients. When Oracle Message Broker clients access an Oracle Message Broker as a separate process, in Remote Mode, the Oracle Message Broker is available when both the directory server and the Oracle Message Broker process are available. When Oracle Message Broker clients use the Oracle Message Broker locally, the Oracle Message Broker is available when the directory server process is available. For both Local Mode and Remote Mode, using the Lightweight Configuration removes the requirement that the directory server process be available.

• Simplicity - installing, configuring, and running the Oracle Message Broker are less complex tasks using the Lightweight Configuration. Administration and configuration issues are simplified and the Database Server performance tuning task is eliminated (using an LDAP Directory Server, the associated Database Server may require tuning).

• Reduced startup time - the start up time, including the time required to access and process configuration information for the Oracle Message Broker is reduced using Lightweight Configuration.

• Lightweight configuration requires less overall system memory, as compared to a single system that is supporting both the Oracle Message Broker and its associated directory server.

Using Lightweight Configuration

To use Lightweight Configuration with Oracle Message Broker, application developers or administrators controlling the system need to set configuration options to control the system. The configuration information only needs to be updated when the system configuration needs to change. The reasons for a configuration change include:

• Adding or removing queues or topics.

• Adding or removing a durable subscriber.

• Modifying Oracle Message Broker resources (for example memory options).

This section describes the following:

• Configuration Changes

• Starting with Lightweight Configuration in Remote Mode

• Starting with Lightweight Configuration in Local Mode

• Deploying Using Lightweight Configuration

• Specifying Configuration Values with Lightweight Configuration

Configuration Changes

With Lightweight Configuration, if the Oracle Message Broker is running in Remote Mode, it must be shutdown and then restarted before configuration changes take effect. Dynamic updates of Oracle Message Broker configuration information are not supported using Lightweight Configuration.

With Lightweight Configuration, if the Oracle Message Broker is running in Local Mode, the client application that instantiates the Oracle Message Broker needs to stop and then restart, or the client application needs to close and restart the Oracle Message Broker, before configuration changes take effect. Refer to Chapter 5, "Oracle Message Broker Features" for information on Oracle Message Broker Local Mode operation.

Starting with Lightweight Configuration in Remote Mode

In Remote Mode, start the Oracle Message Broker using Lightweight Configuration, with the command:

% java HEAP [CONFIG] [OPT] oracle.oas.mercury.Mercury -noldap

Where the parameters are:

Op

HEAP	-mxsizem -mssizem -Doracle.oas.mercury.maxheap=size where size is: an integer, number of megabytes for JVM heap. For Java 1.2, use: -Xmxsizem -Xmssizem -Doracle.oas.mercury.maxheap=size The HEAP parameters are required.
CONFIG	-Doracle.oas.mercury.config=FILE Where FILE is: a string, representing the name of file in which configuration information is stored. The CONFIG file parameter is optional.
OPT	Other properties that specify configuration parameters.
-noldap	Specifies Oracle Message Broker Lightweight Configuration.

For example:

% java -mx10m -ms10m -Doracle.oas.mercury.maxheap=10 \

-Doracle.oas.mercury.config=config.pr oracle.oas.mercury.Mercury -noldap

For this example, the file config.pr must be present in the current working directory.

Starting with Lightweight Configuration in Local Mode

When starting a client that uses a local Oracle Message Broker, start the Java interpreter with the following flags:

-mxmemm (for Java 1.1.x)

-Xmxmemm (for Java 1.2)

-msmemm (for Java 1.1.x)

-Xmsmemm (for Java 1.2

-Doracle.oas.mercury.maxheap=mem

Where mem is the memory, in megabytes, that you want to allocate to the process. The mem value should be at least 8, specifying 8 megabytes per instance. If max_memory is set in the msg_broker entry, the mem value, as shown above, must be greater than or equal to the value of max_memory.

Deploying Using Lightweight Configuration

Using Lightweight Configuration, there are two deployment options for an Oracle Message Broker application:

1. Deploying with Lightweight Configuration in Remote Mode

2. Deploying with Lightweight Configuration in Local Mode

For each deployment option, an Oracle Message Broker application must perform the following tasks:

1. Obtain a connection factory instance.

2. Obtain a destination instance for a topic or a queue.

3. Cleanup and shutdown.

This section covers these steps for both Local Mode and Remote Mode Oracle Message Brokers.

Obtaining a ConnectionFactory Instance (in Remote Mode)

When the Oracle Message Broker, using Lightweight Configuration, runs in Remote Mode it writes its IOR as a UTF string to a file. The name of the IOR file is JMSProviderkey, where the property oracle.oas.mercury.key specifies the value for the key (see Table 13-3 for more details). Oracle Message Broker writes the JMSProviderkey file containing the IOR in the directory where the Oracle Message Broker runs.

In Remote Mode, Oracle Message Broker clients access the IOR stored in the JMSProvider file to obtain a connection factory instance. The Oracle Message Broker provides Mercury package method to access the IOR for this purpose.

The method Mercury.getRemoteConnectionFactory creates an Oracle Message Broker MercuryConnectionFactory for a given IOR file. The MercuryConnectionFactory can be cast to either a TopicConnectionFactory or a QueueConnectionFactory.

The method Mercury.getRemoteConnectionFactory creates a connection factory that returns connections to a Remote Mode Oracle Message Broker. This method is usually used to establish connections to a Remote Mode Oracle Message Broker that has been configured using Lightweight Configuration.

Obtaining Remote Connection Factory Instance

Given the Oracle Message Broker JMSProvider file, the API for the JMS getRemoteConnectionFactory access method is:

package oracle.oas.mercury.Mercury;
import javax.jms.*;

class Mercury {
public static MercuryConnectionFactory 
              getRemoteConnectionFactory(String iorFile,String driverName, 
                                         String clientId) 
throws JMSException
}

Where Table 13-1 shows the parameters for the getRemoteConnectionFactory method.

The method getRemoteConnectionFactory returns a MercuryConnectionFactory that can be used to create instances of javax.jms.QueueConnection and javax.jms.TopicConnection.

It throws a JMSException if the IOR is invalid or the ORB cannot be started.

Table 13-1  Connection Factory Access Method Parameters

Parameter	Description
ior_file	The name of the file in which the Oracle Message Broker IOR is stored. This file should only contain the string that represents the IOR. An Oracle Message Broker that is started with Lightweight Configuration writes the IOR as a UTF string into JMSProviderkey file. Oracle Message Broker clients should use this file to connect to the Oracle Message Broker when running in Remote Mode. When the Oracle Message Broker is running in Local Mode, the client does not need to read the IOR from a file.
driver_name	This is one of the following: `aq', `mq', `vol', `mcast', `rv'. This specifies the name of the driver for which connections are created. A connection factory is limited to creating connections for one driver type.
client_id	This specifies the value to use for the connection id. Each JMS connection can have a connection id set using a call to javax.jms.Connection.setClientID(String). The value specified by the client_id parameter is used to implicitly call setClientID() if client_id is not null.

Obtaining Destinations

To obtain destinations, the Oracle Message Broker client can use created or configured destinations. There are two types of destinations, created destinations and configured destinations. Created destinations are destinations for which an Oracle Message Broker client provides all the configuration information when the client creates an instance of the created destination Table 13-2 lists the methods that support created destinations (these are defined in the package oracle.oas.mercury.MercurySession). These methods allow client programs to locate and use topics and queues with Lightweight configuration (without JNDI). Configured destinations are destinations for which the Oracle Message Broker has been configured. Part of the configuration information is the name by which the broker knows the destination. This name is not necessarily the same as the name by which the message store identifies the destination (refer to Table 13-6 for more information on destination properties).

Using Created Destinations

Oracle Message Broker calls the destinations returned from the methods shown in Table 13-2 created destinations.

The methods in Table 13-2 are equivalent to TopicSession.createTopic and QueueSession.createQueue found in javax.jms. The methods in Table 13-2 create an instance of javax.jms.Destination.

Table 13-2 shows the methods for creating destinations, topics or queues, using Lightweight Configuration. These methods are equivalent to createTopic and createQueue, but they do not require a specially formatted string to identify the destination.

Table 13-2  Created Destination Methods for Topics and Queues

Method	Description
createAQTopic	Locate and create an AQ topic
createAQQueue	Locate and create an AQ queue
createVolatileTopic	Locate and create an Volatile topic
createVolatileQueue	Locate and create an Volatile queue
createMQQueue	Locate and create an MQSeries queue

Note: The methods shown in Table 13-2 can be used regardless of the technique used to configure the Oracle Message Broker, either an LDAP Directory or Lightweight Configuration.

When the Oracle Message Broker is started using an LDAP Directory in either Local Mode or Remote Mode, created destinations can only be used as the argument in a call to send or publish. They cannot be used to create a message producer or message consumer.

Configured Destinations

Configured destinations are destinations that are returned using a JNDI lookup or with a call to the MercuryQueue or MercuryTopic constructors shown below. To obtain configured destinations, instances of javax.jms.Topic or javax.jms.Queue, when an LDAP Directory is not used, use one of the following constructors:

oracle.oas.mercury.MercuryQueue(String queue_name) 
oracle.oas.mercury.MercuryTopic(String topic_name)

Where:

queue_name	is the name of the queue
topic_name	is the name of the topic

To use these constructors, Oracle Message Broker needs to be using Lightweight Configuration.

Shutting Down

When a client is done with the Oracle Message Broker, it should call shutdownClient. This shuts down the ORB and performs certain cleanup operations. Clients call this method as follows:

oracle.oas.mercury.Mercury.shutdownClient()

Note: The shutdownClient method is not part of the JMS specification. It assists the Oracle Message Broker in cleanup, and allow clients to exit and cleanup.

After the Oracle Message Broker is shut down, keep the following in mind:

• The ORB cannot be restarted after it is shut down. Thus a client should not call shutdownClient and then attempt to access a remote Oracle Message Broker by obtaining a connection factory.

Obtaining a Connection Factory Instance (in Local Mode)

When the Oracle Message Broker, using Lightweight Configuration and running in Local Mode, obtain a ConnectionFactory Instance for the Oracle Message Broker by calling one of the getLocalConnectionFactory methods:

• oracle.oas.mercury.Mercury.getLocalConnectionFactory()

• oracle.oas.mercury.Mercury.getLocalAQConnectionFactory()

Using getLocalConnectionFactory

The method getLocalConnectionFactory starts an Oracle Message Broker that uses any supported driver. The method getLocalConnectionFactory requires configuration properties for an Oracle Message Broker to be added to System properties. Configuration properties can also be loaded from a file when using Mercury.getLocalConnectionFactory.

Call the following method to start a local Oracle Message Broker using configuration information specified with Lightweight Configuration:

package oracle.oas.mercury;
import javax.jms.*;

Mercury.getLocalConnectionFactory(String driver_name, String broker_id, 
                                  String client_id);

Where the arguments are:

driver_name	the driver name
broker_id	the broker ID
client_id	the client ID

Use this method when you want to start the Oracle Message Broker in local mode using Lightweight Configuration and you have either stored the configuration properties in a file or inserted them into the System properties.

The getLocalConnectionFactory method starts a local Oracle Message Broker without an LDAP Directory and without using JNDI. When a client executes this method it creates an active OMB Instance in the client's JVM.

Using getLocalAQConnectionFactory

The method getLocalAQConnectionFactory starts an Oracle Message Broker that uses the JDBC based AQ driver. This method does not require any configuration properties set in System properties and it does not load configuration properties from a configuration file. This variant of lightweight configuration is called Zero Configuration. Zero Configuration is only supported for the AQ Driver. Zero Configuration allows the Oracle Message Broker to start with the AQ Driver as easily as a JDBC connection starts.

This method allows the Oracle Message Broker to start with no Oracle Message Broker-specific configuration. The information required to use start the Oracle Message Broker is: service_name, admin_user, admin_password. If properties are set in System properties, the Oracle Message Broker started using getLocalAQConnectionFactory can start other Oracle Message Broker drivers, in addition to the AQ Driver.

The API for the getLocalAQConnectionFactory access method is:

package oracle.oas.mercury;
import javax.jms.*;

Mercury.getLocalAQConnectionFactory(String service_name, String admin_user, 
                                    String admin_password, String client_id);
throws JMSException;
};

Where:

service_name	is the name of the net service name used to create JDBC connections
admin_user	is the name of the Database Server user
admin_password	is the password for the Database Server user
client_id	specifies the client identifier to use for the connection

Obtaining Destinations (in Local Mode)

The methods to obtain destinations in Local Mode are the same as those available in Remote Mode. Refer to "Obtaining Destinations" for details.

Shutting Down (in Local Mode)

A client program running Oracle Message Broker in Local Mode shuts down the Oracle Message Broker when it finishes. The close() method associated with a MercuryConnectionFactory initiates the shutdown for the Local Mode Oracle Message Broker.

For example, local clients can call the following method to stop Oracle Message Broker:

oracle.oas.mercury.MercuryConnectionFactory.close()

Where MercuryConnectionFactory is a connection factory instance, as shown in "Obtaining a Connection Factory Instance (in Local Mode)". This method initiates the shutdown for the Oracle Message Broker.

The client program can also shut down the Oracle Message Broker using the method Mercury.shutdownClient, as shown in "Shutting Down".

Specifying Configuration Values with Lightweight Configuration

Lightweight configuration uses Java properties to specify configuration values. Properties are specified on the command line or in a file (or both, see "Property Evaluation Precedence Rules"). The file containing Oracle Message Broker configuration properties is specified on the command line using the property oracle.oas.mercury.config (see Table 13-3 for details on this property). The Oracle Message Broker reads this file once, when it starts.

Specifying Properties

The syntax for specifying properties on the command line is:

-Dproperty_name=property_value

To use properties in a file, you must set the property oracle.oas.mercury.config which specifies the name of the file that contains configuration values. This is specified on the command line. Using a file rather than command line properties may be more appropriate for the following reasons:

• Command lines only allow a limited number of properties to be set.

• Using a file prevents a user from having to enter and possibly reenter long command lines.

The syntax for properties specified in a file is:

property_name=property_value
property_name=property_value
.
.
.

In Java, property names are case sensitive. This may lead to confusion when a user types a property name that is equivalent, except for case. To prevent confusion, Oracle Message Broker converts all property names to lower case internally, so that the property name case, from a users point of view, is not significant.

When properties are read from a file, do not include trailing blanks after the specified property_value. Trailing blanks may be interpreted as part of the value. For example, `oracle.oas.mercury.maxMemory=3' is correct, since there are not any trailing blanks, but `oracle.oas.mercury.maxMemory=3 ' is incorrect.

Properties that are specified on the command line are stored with the JVM's system properties. These properties can be retrieved using a call to java.lang.System.getProperty(String). Oracle Message Broker properties that are read from a configuration file are not stored as system properties.

Property Evaluation Precedence Rules

The Oracle Message Broker uses the following precedence rules for property values:

1. Retrieve the names of all system properties.

2. Store these properties in a first hash table after converting names to lower case.

3. Read all properties stored in the configuration file specified by oracle.oas.mercury.config.

4. Store these in second has table after converting all names to lower case.

5. For each property that a user can specify, do the following, in order:
   1. Convert the name to lower case.

   2. If the property is stored in the first hash table, use its value. Otherwise, if the property is stored in the local hash table, use the value from the second hash table. As indicated, the value in system hash table takes precedence.

      Note: This implies that if a property appears in both the system properties and in the configuration file, the system properties value is used.

Lightweight Configuration Properties

This section describes the Oracle Message Broker configuration properties. The set of all valid Oracle Message Broker configuration property names cannot be determined in advance, since the values for some properties determines the valid names for other properties.

For example, using Lightweight Configuration, you can add a destination named myQueue with the property oracle.oas.mercury.destinations. If myQueue is specified as a destination, then the property oracle.oas.mercury.dest.myQueue.isTopic is also a valid property name.

In Table 13-4, Table 13-5, and Table 13-6, parameterized values appear as part of a property names when the value is a property value, that is used to generate other valid property names.

Oracle Message Broker Lightweight Configuration property values can be one of four types: an integer, a string, a list of strings, or boolean. Strings are not quoted. A list of strings is comma-delimited and is of the form: string [,string]*. The string and list of string syntax does not allow for spaces. Valid boolean values are true and false and strings equivalent to `true' or `false', ignoring case.

Table 13-3 describes the general configuration properties for Oracle Message Broker Lightweight Configuration.

In Table 13-3, Table 13-4, Table 13-5, and Table 13-6, all property names begin with oracle.oas.mercury. Optional properties are enclosed in brackets, "[]".

Table 13-3  Broker Configuration Properties

Property Name	Description
[oracle.oas.mercury. config]	This property specifies the configuration file. If the Oracle Message Broker cannot open the specified file an exception is thrown and the Oracle Message Broker does not start. Default: no default value Type: String
[oracle.oas.mercury. key]	The property value is used to construct the name of the file in which the IOR is stored. The name for this file is constructed as JMSProviderkey, where key is the string provided by this property. Default: If no value is specified, the Oracle Message Broker uses the value of the system property, user.name, if the user.name is not set, `_default' is used. Type: String
[oracle.oas.mercury. maxConcurrent]	The minimum value is 5. The maximum value is 10000. When the Oracle Message Broker is used in Remote Mode, this value sets the number of generic ORB threads which can handle requests. It is also used to limit the number of concurrent blocking calls to a value less than the number of generic ORB threads. This prevents all of the threads from being stuck in blocking calls. Blocking calls are calls to create subscribers, destroy subscribers, and some variants of receive. When setting this parameter, keep in mind that each thread consumes resources (the resources consumed by a thread includes a 64k stack). Default: 10 Type: integer
[oracle.oas.mercury. maxHeap]	The minimum value is 4. The maximum value is java.lang.Integer.MAX_VALUE. This property represents the maximum size of the JVM heap, in megabytes, for the Oracle Message Broker process. When a JVM is started, it has a maximum and initial heap size. The actual size of the JVM heap will be less than or equal to the maximum size. The actual size of the JVM heap can be determined at runtime, but the maximum size cannot. The Oracle Message Broker uses the maxHeap value to prevent the Oracle Message Broker process from running out of memory. Default: 4 Type: integer
[oracle.oas.mercury. maxMemory]	The minimum value is 4. The maximum value is 4096. This property represents the number of megabytes of the JVM heap that the Oracle Message Broker can use. This value must be less than or equal to oracle.oas.mercury.maxHeap. When calls are made that might cause the Oracle Message Broker to consume memory, it checks the amount of memory in use and throws an exception if too much memory is in use. Too much memory is in use when more than (.7 * maxHeap)megabytes of the JVM heap are in use. See the oracle.oas.mercury.maxHeap property for more information). Default: 4 Type: integer
[oracle.oas.mercury. maxPropRecv]	This property determines the number of threads used to receive messages for propagation jobs. Propagation is not supported using Oracle Message Broker Lightweight Configuration. Default: 1 Type: integer
[oracle.oas.mercury. maxPropSend]	This property determines the number of threads used to send messages for propagation jobs. Propagation is not supported using Oracle Message Broker Lightweight Configuration. Default: 1 Type: integer
[oracle.oas.mercury. propJobFile]	This is ignored using Lightweight Configuration. Default: no default value Type: String

Subscriber Configuration Properties

Table 13-4 describes the subscriber properties for Oracle Message Broker Lightweight Configuration. The parameter sub_name indicates that the subscriber name should be included as part of the property name.

Table 13-4  Subscriber Configuration Properties

Property Name	Description
[oracle.oas.mercury. subscribers]	The Oracle Message Broker creates a durable subscription for each subscriber on the list if the other required properties for the subscriber are also specified. For the following properties, the names in the string list are substituted for sub_name. Default: is an empty list Type: list of strings.
[oracle.oas.mercury. subscriber.sub_name.clientID]	If this property is specified, it will be used as the client ID for the durable subscription. Default: no default value Type: String
[oracle.oas.mercury. subscriber.sub_name.selector]	If this property is specified, it will be used as the message selector for the durable subscription. Default: no default value Type: String
oracle.oas.mercury. subscriber.sub_name.topic	This is the name of the topic for which the durable subscription is created. The topic must also be defined for the subscription to be created. Default: no default value Type: String

Driver Properties

Table 13-5 describes the driver properties. Some properties are particular to an individual driver. Those properties include the name of the driver rather than driver_name. Properties that can be specified for any driver include driver_name in the name of the property. The driver_name should be replaced by the name of the driver (`aq', `mq', `vol', `rv', `mcast').

Table 13-5  Driver Configuration Properties

Property Name	Description
[oracle.oas.mercury. drivers]	The set of strings that can be on the list are {`vol', `aq', 'aqlite, `mq', `rv', `mcast'}. Additional properties can be specified for each driver that is named in drivers. The names specified in drivers should be substituted for `driver_name' in the following properties. Default: vol Type: String
[oracle.oas.mercury. driver.driver_name.maxSharedSessions]	Some drivers use this property to control their resources. This value is ignored by the drivers: vol, rv, mcast, and mq. The AQ Driver uses this parameter as the number of JDBC connections that are created in a pool and used internally for administrative purposes. Administrative uses include creating and destroying AQ queues and subscriptions. The AQ Driver in the OCI mode creates one connection per JMS session to provide operational access to AQ queues. The AQ Driver in the JDBC mode creates one JDBC connection per JMS session to provide operational access to AQ queues. The minimum value is 2. There is no maximum value. Default: 8 Type: integer
[oracle.oas.mercury. driver.driver_name.maxPrivateSessions]	The minimum value is 2. There is no maximum value. This property is used by some drivers to control resources. This value is ignored by the drivers: vol, mcast. The rv driver limits the number of JMS sessions to this value (approximately). The mq driver limits the number of JMS sessions to this value. The aq driver uses this to set the maximum number of concurrent JMS sessions that the driver allows to be created. The Database Server should be configured to support more than maxPrivateSessions. Default: 8 Type: integer
[oracle.oas.mercury. driver.driver_name.numPushSessions]	The minimum value is 2. There is no maximum value. This determines the number of threads started by the Oracle Message Broker to push messages to message listeners. There will be at most numPushSessions concurrent pushes to listeners from a particular driver. Default: 10 Type: integer
[oracle.oas.mercury. driver.driver_name.propSessions]	The minimum value is 0. There is no maximum value. This determines the number propagation threads started by the Oracle Message Broker for the specified driver. Default: 10 Type: integer
[oracle.oas.mercury. driver.driver_name.queryInterval]	The minimum value is 10. There is no maximum value. It is the number of milliseconds that the per-driver query thread will sleep in between queries. The query thread queries all queues and topics for which message listeners have been created to determine the count of available messages. If this value is too small the Oracle Message Broker may consume too much CPU time performing the queries. If this value is too large clients may see a delay between the time at which a message is available and the time at which the Oracle Message Broker determines that a message is available. Default: 1000 Type: integer
oracle.oas.mercury. driver.driver_name.propSendLogQueue	It is the name of the queue that is used by propagation for logging by send threads. It can be the same as propRecvLogQueue. Propagation is not supported using Oracle Message Broker Lightweight Configuration. Default: no default value Type: String
oracle.oas.mercury. driver.driver_name.propRecvLogQueue	It is the name of the queue that is used by propagation for logging by receive threads. It can be the same as propSendLogQueue. Propagation is not supported using Oracle Message Broker Lightweight Configuration. Default: no default value Type: String
oracle.oas.mercury. driver.aq.serviceName	It is required when thinJdbc is false or useJdbc is false. It is the service name used to create OCI connections. It is also used to create JDBC connections when the OCI based JDBC driver is used. The URL in the call to java.sql.DriverManager.getConnection is `jdbc:oracle:oci8:@serviceName ' after the value of serviceName is substituted for `serviceName'. Default: no default value Type: String
[oracle.oas.mercury. driver.aq.thinJdbc]	This determines whether the thin or OCI based JDBC driver should be used. The thin JDBC driver is used when thinJdbc is true. The OCI based JDBC driver is used when thinJdbc is false. Default: false Type: boolean
oracle.oas.mercury. driver.aq.thinJdbcConnString	It is required when thinJdbc is true. This is used to determine the URL in the call to java.sql.DriverManager.getConnection. The URL is `jdbc:oracle:thin:@thinJdbcConnString' after the value of thinJdbcConnString is substituted for `thinJdbcConnString'. Default: no default value Type: String
oracle.oas.mercury. driver.aq.adminUser	It is the name used to authenticate DBMS connections by the AQ Driver. The OCI based AQ Driver performs all Oracle8 access with this identity. The JDBC based AQ Driver performs all administrative access with this identity. Administrative access includes: create subscription, destroy subscription, create queue, destroy queue. The JDBC based AQ Driver also uses this as the default identity when an Oracle Message Broker client creates a JMS connection without supplying a name and password. Otherwise, the name and password supplied by the Oracle Message Broker client will be used to authenticated the JDBC connection. Default: no default value Type: String
oracle.oas.mercury. driver.aq.adminPassword	This property specifies the password used to authenticate DBMS connections by the AQ Driver. It is used in association with oracle.oas.mercury.driver.aq.adminUser. Default: no default value Type: String
[oracle.oas.mercury. driver.aq.useJdbc]	It determines whether the JDBC based AQ Driver or the OCI based AQ Driver is started when the Oracle Message Broker uses the AQ Driver. The JDBC based AQ Driver is started when the value is `true'. Default: false Type: boolean
[oracle.oas.mercury. driver.aqlite.dbname]	The name of the AQ Lite database. In case where the name is null, use the default database. Default: null Type: String
[oracle.oas.mercury. driver.aqlite.dbpasswd]	The password to connect to the AQ Lite database. When the password is null no password is used. Default: null Type: String
oracle.oas.mercury. driver.rv.certified	When true TIBCO provides a higher quality of service for message delivery. Default: false Type: boolean
[oracle.oas.mercury. driver.rv.service]	It determines the name of the TIBCO service to use when creating TIBCO sessions. Default: null (default service) Type: String
[oracle.oas.mercury. driver.rv.network]	It determines the network interface to use when creating TIBCO sessions. Default: null (default network interface) Type: String
[oracle.oas.mercury. driver.rv.daemon]	It determines the name of the TIBCO daemon to connect to when creating TIBCO sessions. Default: null (local daemon) Type: String
oracle.oas.mercury. driver.mcast.ip	It determines the IP multicast address to use for multicast communication. The valid range is between 225.0.0.0 and 239.255.255.255, inclusive. Default: no default value Type: String
oracle.oas.mercury. driver.mcast.port	The valid range is between 1024 and 65535, inclusive. It determines the IP multicast port number to use for multicast communication. Default: no default value Type: integer
[oracle.oas.mercury. driver.mcast.network]	It determines the local IP address of the network interface used by the mcast driver. Default: null (default network interface) Type: String

Destination Properties

Some properties must be specified for each topic or queue. These include `dest_name' in the name of the property. `dest_name' should be replaced by the name of the destination when this property name is used. Some properties are only applicable when a particular driver is used. Those properties include the name of the driver in the property name.

Table 13-6  Destination Configuration Properties

Property Name	Description
[oracle.oas.mercury. destinations]	This list contains the names of the queues and topics the Oracle Message Broker can access. Other properties must be specified for each name on this list. The other properties follow. Default: empty list Type: String
[oracle.oas.mercury. destination.dest_name.isTopic]	This can be specified for each destination in the string lists for topics and queues. `dest_name' is a topic when this is true. Otherwise, `dest_name' is a queue. Default: true Type: boolean
oracle.oas.mercury. destination.dest_name.driver	It must be one of: `aq', `aqlite, `mcast', `mq', `rv', `vol'. This determines the driver that is used to access the topic or queue. Access to this destination will fail if the driver cannot be started or if the driver has not been configured to start. Default: no default value Type: String
[oracle.oas.mercury. destination.dest_name.vol.maxMsgs]	The minimum value is: 10. The maximum value is: java.lang.Integer.MAX_VALUE. This determines the maximum number of messages that can be stored in a volatile queue or volatile topic. The Oracle Message Broker may not have enough memory to store the number of messages specified by this limit. Messages that have been received in a transaction are counted against this limit until the transaction is committed. The count of messages in a volatile topic is incremented once for each subscriber that can receive the message. If a message is published to a topic, and there are 100 subscribers to the topic, then the count of messages in the topic will be incremented by 100. Default: java.lang.Integer.MAX_VALUE Type: integer
[oracle.oas.mercury. destination.dest_name.aq.internalName]	Type: String It is the name of the AQ queue as used within the Oracle8i Database Server (single-consumer or multi-consumer), which does not have to be the same as `dest_name'. The name must not include the schema prefix. Default: `dest_name' Type: String
[oracle.oas.mercury. destination.dest_name.aq.aqRules]	When this is true the AQ rules engine is used to implement message selectors for topic subscribers. When this is false, the Oracle Message Broker message selector engine is used to implement message selectors for topic subscribers. The Oracle Message Broker message selector engine is always used to implement message selectors for queue consumers. Note: This property is only valid for topics. Default: false Type: boolean
oracle.oas.mercury. destination.dest_name.aq.schema	This is the schema in which the AQ queue resides. Default: no default value Type: String
oracle.oas.mercury. destination.dest_name. aqlite.owner	Specifies the owner of the AQLite queue or topic. Default: default user Type: String
oracle.oas.mercury. destination.dest_name. aqlite.message.grouping	Specifies the grouping of messages in AQ Lite. Valid values: NONE or TRANSACTIONAL Default: NONE Type: String
oracle.oas.mercury. destination.dest_name.aqlite.storage_clause	The storage clause used to create the AQ Lite queue table. If the storage clause is null then no storage clause is used. Default: null Type: String
[oracle.oas.mercury. destination.dest_name.mq.internalName]	It is the name of the MQSeries queue, which does not have to be the same as `dest_name' Default: `dest_name' Type: String
[oracle.oas.mercury. destination.dest_name.mq.isNative]	When it is false, JMS messages are serialized and stored as a stream of bytes on an MQSeries queue. Some fields from the MQSeries header are used to set values in the JMS message. When it is true, only text messages and bytes messages can be stored on the queue and the body of the text or bytes message is stored as the body of the MQSeries message. The properties from the JMS message are not stored in the MQSeries message. Default: false Type: boolean
[oracle.oas.mercury. destination.dest_name.mcast.internalName]	It is the name of the mcast topic, which does not have to be the same as `dest_name'. Default: `dest_name' Type: String
[oracle.oas.mercury. destination.dest_name.rv.internalName]	It is the name of the rv topic, which does not have to be the same as `dest_name'. Default: `dest_name' Type: String
[oracle.oas.mercury. destination.dest_name.rv.isNative]	When it is true, JMS messages are stored in a TIBCO specific format. When it is true, JMS messages are stored as a serialized stream of bytes that can only be accessed by the Rv driver. Default: false Type: boolean

Sample Configuration Files

Refer to "Starting with Lightweight Configuration in Remote Mode" for a sample command line showing how to start the Oracle Message Broker using Lightweight Configuration. The Oracle Message Broker includes lightweight configuration samples in $OMB_HOME/samples/client/java/lightweight, or on Windows NT systems, %OMB_HOME%\samples\client\java\lightweight.

Lightweight Configuration Constraints and Limitations

1. Durable Subscriber Limitations

   When running the Oracle Message Broker with the LDAP Directory, the Oracle Message Broker stores information about durable subscribers in directory entries. The directory entries for durable subscribers are updated at runtime as they are created and unsubscribed. With Lightweight Configuration, the Oracle Message Broker does not record the durable subscription, except the message store (creation subscription to AQ is durable by itself).

   If a client creates a durable subscriber, and that durable subscriber has not been read during startup with Lightweight Configuration, the Oracle Message Broker does not maintain or update a persistent record of the new durable subscriber (the Oracle Message Broker does not write Lightweight Configuration information, it only reads it).

   The Oracle Message Broker uses its knowledge of existing subscribers, as it is provided at startup, or during runtime, to determine when to perform an implicit unsubscribe when processing a subscribe request. The Oracle Message Broker performs an implicit unsubscribe when a request is made to create a subscriber, and there is an existing subscription to that topic with the same subscriber name, and the existing subscription uses a message selector that is different than the message selector specified with the subscribe request. This is only an issue for the AQ Driver since durable subscribers to AQ multiconsumer queues survive Oracle Message Broker failures. If AQRules is enabled, Oracle Message Broker queries the message selector stored in the DBMS to see if the new selector is different. If AQRules are not enabled, Oracle Message Broker assumes the message selector is the same as long as the Oracle8i Database Server does not contain a selector for the subscribe.

   The Oracle Message Broker creates durable subscribers specified in the configuration information at startup. However, there is not an administrative mechanism in Lightweight Configuration that causes the Oracle Message Broker to unsubscribe to a durable subscriber. Unsubscribes only occur when an Oracle Message Broker client requests an unsubscribe.

2. Prerequisite Knowledge

   The Oracle Message Broker can be configured to use more resources, memory, DBMS connections, than resource providers (virtual memory system, DBMS) have been configured to provide. The person specifying configuration values is responsible for ensuring that appropriate values are specified.

   A DBMS that is used by both Oracle Message Broker to access Oracle AQ and Oracle Internet Directory must support the resource requirements of both systems.

3. Security Issues

   Some of the information that the Oracle Message Broker accesses using Lightweight Configuration is private. Passwords that are used to authenticate DBMS connections can be specified using Lightweight Configuration. It is the responsibility of the Oracle Message Broker user to protect access to both the command line and the Lightweight Configuration file when they contain sensitive information such as passwords.

4. If a durable subscriber for an AQ multi-consumer queue is created at runtime, and that subscriber is not specified in the configuration information processed at startup, and the AQ rules engine is not used to implement message selectors, then the Oracle Message Broker will not know when to perform an implicit unsubscribe. This will cause behavior that violates the JMS specification.

   The following scenario demonstrates this failure:

   1. The Oracle Message Broker is started using lightweight configuration.

   2. No durable subscribers are specified using lightweight configuration.

   3. A durable subscriber with no message selector is created to an AQ multi-consumer queue at runtime.

   4. Messages are enqueued to the AQ multi-consumer queue.

   5. The Oracle Message Broker is stopped.

   6. The Oracle Message Broker is restarted.

   7. A durable subscriber with a message selector and the same name as the durable subscriber in step c is created to the same AQ multi-consumer queue.

   If any messages enqueued in step d satisfy the message selector specified in step g, these message can be received by durable subscriber created in step g. But the JMS specification requires that an unsubscribe be done at step g since the subscriber is created with a different message selector. Since the subscriber had not been recorded in the configuration information, the Oracle Message Broker has no way to determine that this is the case. When the AQ rules engine is used, the Oracle Message Broker will query the existing rule used by an durable subscriber and this problem will not occur.

5. Command Line Limits

   There are limits on the size of a Java command line. Due to this limitation, users may not be able to specify all of the configuration data that is required on a command line. This limit may be smaller than 1024 characters. If you reach this limit, use a configuration file to specify configuration data.

6. Property Limitation

   Avoid setting the following combination of property values:

   oracle.oas.mercury.driver.aq.useJDBC=true 
   oracle.oas.mercury.driver.aq.thinJDBC=true
   

   These property values conflict, and results are unpredictable.

   With the value of useJDBC set to true, the only value supported for thinJDBC is false:

   oracle.oas.mercury.driver.aq.useJDBC=true 
   oracle.oas.mercury.driver.aq.thinJDBC=false