Oracle Message Broker Adminstration Guide Release 2.0.1.0 Part Number A65435-01 |
|
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:
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:
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:
This section describes the following:
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.
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
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.
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
.
Using Lightweight Configuration, there are two deployment options for an Oracle Message Broker application:
For each deployment option, an Oracle Message Broker application must perform the following tasks:
This section covers these steps for both Local Mode and Remote Mode Oracle Message Brokers.
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.
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.
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).
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.
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 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.
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()
After the Oracle Message Broker is shut down, keep the following in mind:
shutdownClient
and then attempt to access a remote Oracle Message Broker by obtaining a connection factory.
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:
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.
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:
The methods to obtain destinations in Local Mode are the same as those available in Remote Mode. Refer to "Obtaining Destinations" for details.
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".
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.
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:
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.
The Oracle Message Broker uses the following precedence rules for property values:
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-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-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').
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.
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.
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.
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.
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.
The following scenario demonstrates this failure:
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.
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.
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
|
![]() Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
|