Skip Navigation Links | |
Exit Print View | |
![]() |
Oracle Java CAPS JMS Reference Java CAPS Documentation |
Implementing JMS in Java CAPS Projects
To Implement JMS Following the Java CAPS Model
Creating and Configuring Message Destinations
Creating OTDs and Collaborations
Using the JMS OTD in Collaboration Definitions
Using JMS Messages in Collaboration Definitions
Database Configuration and Operation
Protected Concurrent Processing
Serial Processing Across a Destination Group
Message Redelivery and Redirection
Specifying Redelivery Options in the JMS IQ Manager
Specifying Redelivery Options in a JMS Client
Example of Producer Throttling and Unthrottling
Additional JMS Message Properties
requestReply(timeout, message)
requestReplyTo(message, destName)
requestReplyTo(timeout, message, destName)
send(message, deliveryMode, priority, timeToLive)
sendBytes(payload, deliveryMode, priority, timeToLive)
sendBytesTo(payload, destination)
sendBytesTo(payload, destination, deliveryMode, priority, timeToLive)
sendText(payload, deliveryMode, priority, timeToLive)
sendTextTo(payload, destination)
sendTextTo(payload, destination, deliveryMode, priority, timeToLive)
sendTo(message, destination, deliveryMode, priority, timeToLive)
retrieveBytesFromMessage(arg0)
retrieveStringFromMessage(arg0)
JMS IQ Manager Runtime Configuration
Accessing the Configuration Properties
Configuration Properties Interface
Per-Destination Throttling Threshold
Overview of MS Control Utility Features
To Create a Backup Archive File
To Set the MS Control Utility Timeout Period
Message Destination (Queue) Examples
Note - Modifying some properties, such as Block Size and Segment Size, requires changes to the database files. In such cases, you must manually delete the database files and restart the domain server before the changes take place. To prevent message loss, make sure that no unread messages remain before deleting the database files.
Figure 17 Segment Properties Panel
As described in JMS IQ Manager Database, the JMS IQ Manager uses the JMS IQ Manager database to store persistent messages. It also stores messages that are larger than can be kept in the JMS IQ Manager memory, which is determined by the cache size setting (by default 0.5 MBytes for Windows and 1 MByte for UNIX). You can specify several properties of this database file, as described in the following sections:
You can also specify whether or not the JMS IQ Manager controls the cache synchronization to disk by using the Sync to Disk option.
The Data Directory property specifies where the JMS IQ Manager database files are located for JMS IQ Managers. You can specify the location as an absolute path, or as a path relative to the ..\logicalhost\is\domains directory. Using an absolute path for the data directory enables you the store the JMS IQ Manager files on a different system.
If journaling is enabled, the data directory contains a journal directory, unless another location has been specified for the Journal Directory property. The journal directory holds the journaling database files. For information, refer to Journal Directory. Journaling is disabled by default.
The default setting is:..\logicalhost\is\domains\domain_1\stcms\instance_1
Data is read from and written to disk in units known as blocks. The Block Size property specifies the number of bytes per block.
You can specify 0, 512, or 1024 bytes per block. If you specify 0, the server automatically determines the value by querying the operating system.
The default is 0 bytes per block.
Note - Modifying the Block Size requires changes to the database files. You must manually delete the database files and restart the domain server before the changes take place. To prevent message loss, make sure that no unread messages remain before deleting the database files.
The JMS IQ Manager database consists of multiple memory-mapped database files known as segments. The Segment Size property specifies the total number of pages in each segment file. A page is 512 bytes on Windows and 1024 bytes on UNIX. The default segment size is 16,384 pages, which is 8 MBytes for Windows and 16 MBytes for UNIX. By default, these segments are named stcms*.dbs and reside in the message server folder on the Logical Host.
You should set the segment size to a value larger than the sum of the following items:
The anticipated number of subscribers
The anticipated maximum transaction size in bytes divided by the page size in bytes
An additional ten pages to allow for overhead
Note - The transaction size is the sum of the sizes of all messages in one transaction. If transactions span no more than one message, the maximum transaction size is equal to the size of the largest message.
For example, consider a UNIX system, where you expect no more than 100 subscribers and that messages will not exceed 100 KBytes, and that only one message will be sent/received per transaction. Since the page size on UNIX is 1 KByte, you would set the segment size to at least [100 + (100KBytes/1KByte) + 10] = 210 pages.
With this setting, only one 100,000 byte message may exist in each segment. The ideal segment size depends on the circumstances. If the slowest subscriber lags behind the fastest publisher by a certain number of messages, you can set the segment size so that this number of messages will fit a single segment.
The JMS IQ Manager cleans up the database by recycling segments for which all messages have either expired or have been retrieved by their subscribers.
A lower segment size setting results in more efficient use of the disk because smaller segments turn over more rapidly and thus provide more effective use of server memory. However, a lower segment size means that the server might need to allocate more new segments, which requires more time than freeing a cleaned-up segment. In addition, if a transaction is larger than the specified segment size, the server rolls back the transaction. You must then increase the Segment Size property to an amount larger than the message.
A high segment size setting can be advantageous in that cleanup runs less often, although each cleanup takes somewhat longer. However, cleaning up two small segments still requires more time than cleaning up one large segment. Therefore, a large segment size can increase performance on systems that are constrained by disk I/O speed rather than memory or storage space.
An integer greater than 1. Set this property to at least twice the total number of anticipated durable subscribers.
The default segment size is 16,384 pages, which is 8 MBytes for Windows and 16 MBytes for UNIX.
Note - Modifying the Segment Size requires changes to the database files. You must manually delete the existing database files and restart the domain server before the changes actually occur. To prevent message loss, make sure that no unread messages remain before deleting the database files.
The Minimum Number of Segments property specifies the minimum number of database files (segments) that the JMS IQ Manager creates initially for stable message storage. When the minimum is exceeded, the server allocates additional segments on an as-needed basis, up to the number of files specified for the Maximum Number of Segments property as described in Maximum Number of Segments.
In addition to limiting the maximum number of segments, you can also specify the size limit for segments. For more information about the Segment Size property, refer to Segment Size.
An integer from 1 through 99,999 indicating the number of segments.
The default is 4 segments.
The Maximum Number of Segments property specifies the upper limit for the number of database files (segments) that the JMS IQ Manager creates for its stable message storage. You use this property to limit the amount of disk space that the JMS IQ Manager uses. If the JMS IQ Manager attempts to write data that exceeds this limit, it exits gracefully and logs an error message in the JMS IQ Manager log.
An integer from 0 through 99,999 indicating the number of segments.
The default is 0. This value causes the JMS IQ Manager to create new files as needed, limited only by available disk space.
The Sync to Disk property specifies whether the JMS IQ Manager controls cache synchronization to disk. When you disable cache control, the operating system controls the synchronization schedule. Disabling cache control increases performance, but also increases risk of message loss in the event of system failure.
This property is disabled by default.
Figure 18 Journaling and Expiration Properties Panel
Journaling messages enables you to republish messages at a later date. You can specify several options and properties for journaling, as described in the following sections:
To republish journaled messages, you use the STC MS Control utility as described in Example 19 or Example 20. You can also use the STC MS Control utility to browse journaled messages with the -journaler flag. For information, refer to Example 9.
Use the Enable Message Expiration option to enable or disable message expiration for JMS IQ Managers. When you enable message expiration, messages are removed from the queue after the time specified for the Maximum Lifetime property has expired.
The Maximum Lifetime property specifies the maximum amount of time before a live message expires. After it expires, the message is removed from the queue regardless of whether it has been consumed. If you specify 0, the message never expires.
The default is 2592000 seconds (30 days).
Use the Enable Journal option to enable or disable journaling for JMS IQ Managers. When you enable journaling, every inbound message is automatically copied to the journal database. The message is then held in the journal database for the duration of the time to live value specified for journaled messages.
By default, the expiration time for a journaled message is 7 days. To change the time to live for journaled messages, refer to Journaling Maximum Lifetime. The time to live property for journaled messages is completely independent of when the live counterpart of the message is consumed by its publisher.
When a journaled message expires, it is not deleted from the journal database, but remains there until you back up the topics or queues. When you back up, all messages in the journal database are included in the archive, and the journal expired messages are removed from the journal database. You should back up daily when journaling is enabled; otherwise, the journal database retains journal expired messages and can grow exceedingly large. Because the journal database and the JMS IQ Manager database are located on the same system, you must guard against running out of disk space.
To back up the journal database, you use the MS Control Utility. For more information, refer to To Create a Backup Archive File.
When messages are in the journal database, you can view them but not edit them. You can use either Enterprise Manager or the STC MS Control utility to view and republish journaled messages. For more information about the MS Control utility, see JMS Provider Management.
Journaling is disabled by default.
The Journaling Maximum Lifetime property specifies the maximum amount of time that a journaled message persists before it expires. The JMS IQ Manager journals messages only when journaling is enabled as described in Enable Journal. Journaling is disabled by default.
When a journaled message expires, it is not deleted from the journal database, but remains there until you back up the topics or queues. When you back up, all messages in the journal database are included in the archive (.zip) file, and the expired messages are removed from the journal database.
The default is 604800 seconds (7 days).
The Journal directory holds the journal database files and the journaling log file. You can enter an absolute path or a path relative to the ..\logicalhost\is\domains directory. Using an absolute path for the data directory enables you to store the journal database files on a different system, for example, for backup purposes.
The JMS IQ Manager creates a journal directory only when journaling is enabled. Journaling is disabled by default. For more information, refer to Enable Journal.
An absolute path or a path relative to the ..\logicalhost\is\domains directory.
By default, the journal database files are stored in the following folder:..\logicalhost\is\domains\domain_1\stcms\instance_1\journal