JavaScript is required to for searching.
Skip Navigation Links
Exit Print View
Oracle Java CAPS JMS Reference     Java CAPS Documentation
search filter icon
search icon

Document Information

Java CAPS JMS Reference

Introduction to JMS

JMS and Java CAPS

Java Message Service

JMS Message Servers

JMS Message Destinations

JMS Clients

JMS Object Type Definitions

JMS Library File

Implementing JMS in Java CAPS Projects

Integration Model

To Implement JMS Following the Java CAPS Model

Creating and Configuring Message Destinations

Creating OTDs and Collaborations

Configuring JMS Clients

Configuring Message Servers

Creating Component Mappings

Using the JMS OTD in Collaboration Definitions

Using JMS Messages in Collaboration Definitions

Inside the JMS IQ Manager

JMS Messaging Features

Message Delivery Order

Message Producer Priorities

Distributed Transactions

Security

Runtime Management

JMS IQ Manager Database

Database Files

Database Location

Database Configuration and Operation

Message Processing Order

JMS IQ Manager Delivery Modes

Fully Concurrent Processing

Protected Concurrent Processing

Fully Serialized Processing

Serial Processing Across a Destination Group

JMS Client Delivery Modes

Message Producer Priorities

Message Redelivery and Redirection

Redelivery Options

Progressive Delay

Example 1

Example 2

Delay and Redirect

Example 3

Example 4

Delay and Delete

Example 5

Specifying Redelivery Options in the JMS IQ Manager

Specifying Redelivery Options in a JMS Client

Enqueued Message Properties

Enqueue Time

Sequence Number

Performance Issues

Throttling Producers

Example of Producer Throttling and Unthrottling

JMS Object Type Definitions

Message Types

JMS Message Properties

JMS Message Header Properties

Additional JMS Message Properties

JMS OTD Methods

createBytesMessage()

Description

Parameters

Return Value

Exceptions

createBytesMessage(msg)

Description

Parameters

Return Value

Exceptions

createMapMessage()

Description

Parameters

Return Value

Exceptions

createMessage()

Description

Parameters

Return Value

Exceptions

createMessage(msg)

Description

Parameters

Return Value

Exceptions

createStreamMessage()

Description

Parameters

Return Value

Exceptions

createTextMessage()

Description

Parameters

Return Value

Exceptions

createTextMessage(msg)

Description

Parameters

Return Value

Exceptions

getDeliveryMode()

Description

Parameters

Return Value

Exceptions

getDestination()

Description

Parameters

Return Value

Exceptions

Also Accessible From

getMessageServerURL()

Description

Parameters

Return Value

Exceptions

getPriority()

Description

Parameters

Return Value

Exceptions

getTimeToLive()

Description

Parameters

Return Value

Exceptions

receive(timeout)

Description

Parameters

Return Value

Exceptions

receive(timeout, destination)

Description

Parameters

Return Value

Exceptions

receiveNoWait()

Description

Parameters

Return Value

Exceptions

receiveNoWait(destination)

Description

Parameters

Return Value

Exceptions

requestReply(message)

Description

Parameters

Return Value

Exceptions

requestReply(timeout, message)

Description

Parameters

Return Value

Exceptions

requestReplyTo(message, destName)

Description

Parameters

Return Value

Exceptions

requestReplyTo(timeout, message, destName)

Description

Parameters

Return Value

Exceptions

send(message)

Description

Parameters

Return Value

Exceptions

send(message, deliveryMode, priority, timeToLive)

Description

Parameters

Return Value

Exceptions

sendBytes(payload)

Description

Parameters

Return Value

Exceptions

sendBytes(payload, deliveryMode, priority, timeToLive)

Description

Parameters

Return Value

Exceptions

sendBytesTo(payload, destination)

Description

Parameters

Return Value

Exceptions

sendBytesTo(payload, destination, deliveryMode, priority, timeToLive)

Description

Parameters

Return Value

Exceptions

sendText(payload)

Description

Parameters

Return Value

Exceptions

sendText(payload, deliveryMode, priority, timeToLive)

Description

Parameters

Return Value

Exceptions

sendTextTo(payload, destination)

Description

Parameters

Return Value

Exceptions

sendTextTo(payload, destination, deliveryMode, priority, timeToLive)

Description

Parameters

Return Value

Exceptions

sendTo(message, destination)

Description

Parameters

Return Value

Exceptions

sendTo(message, destination, deliveryMode, priority, timeToLive)

Description

Parameters

Return Value

Exceptions

setDeliveryMode(arg0)

Description

Parameters

Return Value

Exceptions

setDestination(arg0)

Description

Parameters

Return Value

Exceptions

Also Accessible From

setMessageServerURL(arg0)

Description

Parameters

Return Value

Exceptions

setPriority(arg0)

Description

Parameters

Return Value

Exceptions

setTimeToLive(arg0)

Description

Parameters

Return Value

Exceptions

JMS Message Methods

countMapMessage()

Description

Parameters

Return Value

Exceptions

countStreamMessage()

Description

Parameters

Return Value

Exceptions

countUserProperty()

Description

Parameters

Return Value

Exceptions

getBytesMessage()

Description

Parameters

Return Value

Exceptions

getJMSMessageType()

Description

Parameters

Return Value

Exceptions

getMapMessage()

Description

Parameters

Return Value

Exceptions

getMapMessage(arg0)

Description

Parameters

Return Value

Exceptions

getMessageProperties()

Description

Parameters

Return Value

Exceptions

getStreamMessage()

Description

Parameters

Return Value

Exceptions

getStreamMessage(arg0)

Description

Parameters

Return Value

Exceptions

getTextMessage()

Description

Parameters

Return Value

Exceptions

getUserProperty()

Description

Parameters

Return Value

Exceptions

getUserProperty(arg0)

Description

Parameters

Return Value

Exceptions

retrieveBytesFromMessage()

Description

Parameters

Return Value

Exceptions

retrieveBytesFromMessage(arg0)

Description

Parameters

Return Value

Exceptions

retrieveMapMessage(arg0)

Description

Parameters

Return Value

Exceptions

retrieveMapMessageList()

Description

Parameters

Return Value

Exceptions

retrieveStringFromMessage()

Description

Parameters

Return Value

Exceptions

retrieveStringFromMessage(arg0)

Description

Parameters

Return Value

Exceptions

retrieveUserProperty(arg0)

Description

Parameters

Return Value

Exceptions

retrieveUserPropertyList()

Description

Parameters

Return Value

Exceptions

setBytesMessage(arg0)

Description

Parameters

Return Value

Exceptions

setJMSMessageType(arg0)

Description

Parameters

Return Value

Exceptions

setStreamMessage(arg0, arg1)

Description

Parameters

Return Value

Exceptions

setTextMessage(arg0)

Description

Parameters

Return Value

Exceptions

storeMapMessage(arg0, arg1)

Description

Parameters

Return Value

Exceptions

storeUserProperty(arg0, arg1)

Description

Parameters

Return Value

Exceptions

getTimeToWait()

Description

Parameters

Return Value

Exceptions

setTimeToWait(arg0)

Description

Parameters

Return Value

Exceptions

JMS Client Configuration

Categories

Consumers

Action

Allowed Values

Default Value

Concurrency

Default Value

Delay

Allowed Values

Default Value

Durable Subscriber Name

Durability

Allowed Values

Default Value

Message Selector

Move/Delete After N Times

Allowed Values

Default Value

Move to Queue/Topic

Allowed Values

Default Value

Move to Destination Name

Allowed Values

Default Value

Server Session Batch Size

Server Session Pool Size

Allowed Values

Default Value

Producers

Delivery Mode

Default Value

Idle Timeout

Default Value

Maximum Pool Size

Default Value

Maximum Wait Time

Default Value

Priority

Allowed Values

Default Value

Steady Pool Size

Default Value

Transaction Mode

Allowed Values

Default Value

JMS IQ Manager Runtime Configuration

Accessing the Configuration Properties

Configuration Properties Interface

Stable Storage Page

Segment Properties

Data Directory

Default Location

Block Size

Allowed Values

Default Value

Segment Size

Allowed Values

Default Value

Minimum Number of Segments

Allowed Values

Default Value

Maximum Number of Segments

Allowed Values

Default Value

Sync to Disk

Default Condition

Journaling and Expiration Properties

Enable Message Expiration

Maximum Lifetime

Default Value

Enable Journal

Default Condition

Journaling Maximum Lifetime

Default Value

Journal Directory

Allowed Values

Default Value

Messaging Behavior Page

Throttling Properties

Per-Destination Throttling Threshold

Allowed Values

Default Value

Server Throttling Threshold

Allowed Values

Default Value

Throttling Lag

Allowed Values

Default Value

Special FIFO Mode Properties

Fully Serialized Queues

Allowed Values

Protected Concurrent Queues

Allowed Values

FIFO Expiration Time

Default Value

Time Dependency Properties

Allowed Values

Access Control Page

Security Options

Default Condition

Diagnostics Page

Diagnostic Properties

Logging Level

Default Setting

Logging Level of Journaler

Default Condition

Maximum Log File Size

Allowed Values

Default value

Number of Backup Log Files

Allowed Values

Default value

Miscellaneous Page

Enable Alert Option

Default Condition

JMS Provider Management

Overview of MS Control Utility Features

MS Control Utility Details

Flags and Arguments

Syntax

Using the MS Control Utility

To Change Message Contents

To Create a Backup Archive File

To Access an Archive File

To Set the MS Control Utility Timeout Period

To Shut the Server Down

Command/Response Examples

Message Server Example

Message Destination (Queue) Examples

Message Destination (Topic) Examples

Message Examples

Troubleshooting

Timestamp Errors

Index

JMS Client Configuration

This topic describes the configuration properties for JMS Client connectors.

Categories

The following tables list the JMS client configuration properties as displayed in the NetBeans IDE configuration dialogs. These tables provide a cross-reference to the property descriptions in the following section, which are categorized by consumer and producer, and presented alphabetically.

Table 7 Root Properties

Property
Applies to
Description
Durable Subscriber Name
Topic subscribers

Table 8 Basic Properties

Property
Applies to
Description
Concurrency
Topic subscribers

Queue receivers

Delivery mode
Topic publishers

Queue senders

Idle timeout
Topic publishers

Queue senders

Maximum pool size
Topic publishers

Queue senders

Maximum wait time
Topic publishers

Queue senders

Message selector
Topic subscribers

Queue receivers

Priority
Topic publishers

Queue senders

Steady pool size
Topic publishers

Queue senders

Transaction mode
Topic publishers

Queue senders

Table 9 Redelivery Handling Properties

Property
Applies to
Description
Delay
Topic subscribers

Queue receivers

Move/Delete After N Times
Topic subscribers

Queue receivers

Action
Topic subscribers

Queue receivers

Move to Queue/Topic
Topic subscribers

Queue receivers

Move to Destination Name
Topic subscribers

Queue receivers

Table 10 Advanced Properties

Property
Applies to
Description
Durability
Topic subscribers
Server session batch size
Topic subscribers

Queue receivers

Server session pool size
Topic subscribers

Queue receivers

The sections below describe the JMS client connector properties in detail, and supplement the information given in Configuring JMS Clients.

Consumers

Action

The Action property specifies the action to take following a specified number of unsuccessful attempts to deliver a message. This property specifies whether to move (redirect) or delete the message after the number of retries specified in Delay. See Message Redelivery and Redirection for additional information.

Allowed Values

The allowed values are move, delete, and no final action.

Default Value

The default is no final action, which specifies continued retries until the message is received.

Concurrency

The Concurrency property specifies whether the message consumers use connection consumer or serialized processing. To use concurrent processing for a connection, select the Connection consumer setting. To use serial execution, select the Serial mode setting. This property applies to topic subscribers and queue receivers, and is specified in the Basic properties dialog.

You can configure JMS clients to use connection consumers to improve message throughput through concurrent processing. Connection consumers consume messages that are specified by a destination and an optional message selector. See Message Selector.

To start processing, a connection consumer gets a server session from its pool and loads the session with a message. Server sessions associate a JMS session with a thread. The server session pool is a set of server sessions provided to a connection consumer to process its messages.

The use of connection consumers increases message processing performance by enabling concurrent processing using multiple threads. You can specify the number of message driven beans (MDBs) or server session pool to assign to a JMS Collaboration to process messages concurrently. When you use connection consumer with fully concurrent or protected concurrent FIFO processing, this setting allows the integration server to assign multiple threads to execute the Collaboration on a particular message destination.

For queues, you can also use connection consumers for concurrent processing on multiple CPUs and application servers on a single system. This configuration does affect FIFO processing. For information, refer to Message Processing Order.

You specify the maximum number of threads per server session pool as described in Server Session Pool Size. By default, the maximum number of threads is 5.

The maximum number of messages that a connection consumer can load into a server session at one time is set at 1 and cannot be changed (see Server Session Batch Size).

Default Value

The default JMS client concurrency mode is Serial mode.

Delay

The Delay property specifies the delay(s) to apply following a specified number of unsuccessful attempts to deliver a message. The format is retries:delay, where the number of retries is counted from the original rollback and the delay time is in milliseconds. Progressive delays can be specified by concatenating retry:delay pairs separated by a comma and a space:

retry:delay, retry:delay, …, retry:delay

This property applies to topic subscribers and queue receivers, and is specified in the Redelivery Handling properties dialog. See Message Redelivery and Redirection for additional information.

Allowed Values

The maximum allowed delay is five seconds (5000 ms).

Default Value

By default, no value is specified.

Durable Subscriber Name

The Durable Subscriber Name property, which is specified in the root JMS Client properties dialog, both provides a name for the JMS client and identifies it as being a durable subscriber.

A durable subscription is one that is not dependent upon a client’s connection with a message server. Therefore, it is tolerant of disconnections, whether they are intentional or not. When a durable subscriber is disconnected from the message server, the server stores messages until the subscriber reconnects. It then delivers all accumulated messages that have not expired. This process is also known as store-and-forward messaging.


Note - Once set, the Durable Subscriber Name does not get autogenerated, and can only be changed manually. Copies of the Connectivity Map also retain this name.


Durability

The Durability property specifies whether or not the subscriber to this JMS connection is durable. When a subscriber is nondurable, the client sees messages on a topic only when the subscriber is active. If messages are published when the subscriber is inactive, the messages are lost. This property applies to topic subscribers only, and is specified in the Basic properties dialog.

When a subscriber is durable, messages are not lost even when the subscriber is inactive because the message server retains the messages until they are retrieved by the subscriber or until the messages expire. A durable subscriber registers with the message server as a durable subscriber with the name source_destination, for example, topicA_CollaborationA. When a subscriber becomes inactive, the message server retains the unexpired messages for a subsequent subscriber object with the same identity to resume the subscription. Note that there is a trade-off in performance.

Allowed Values

Durable or Nondurable.

Default Value

By default, JMS client connections are Durable.

Message Selector

The Message selector property specifies message selectors for the JMS client. This property applies to topic subscribers and queue receivers, and is specified in the Basic properties dialog.

To specify a message selector, enter a message selector String according to the JMS specification syntax. For example:

JMSType =’car’ AND color =’blue’

Identifier start characters must be characters for which the Character.isJavaIdentifierStart method returns true according to the JMS specification. If the identifier is invalid, the Java CAPS Monitor might show invalid message property names.

Move/Delete After N Times

The Move/Delete After N Times property specifies the number of retries to allow before redirecting or deleting the message, as specified in Action. The action is taken on the retry number entered for the property value.

This property applies to topic subscribers and queue receivers, and is specified in the Redelivery Handling properties dialog. See Message Redelivery and Redirection for additional information.

Allowed Values

Any number.

Default Value

By default, no value is specified.

Move to Queue/Topic

The Move to Queue/Topic property specifies whether to redirect the message to a queue or a topic, following the number of retries specified in Move/Delete After N Times.

This property applies to topic subscribers and queue receivers, and is specified in the Redelivery Handling properties dialog. See Message Redelivery and Redirection for additional information.

Allowed Values

The allowed values are queue, topic, and auto, which specifies the same kind of message destination as the message producer.

Default Value

By default, the destination is specified as auto.

Move to Destination Name

The Move to Destination Name property specifies a queue or topic name to which the message is to be redirected. The special character $ specifies the original destination name.

This property applies to topic subscribers and queue receivers, and is specified in the Redelivery Handling properties dialog. See Message Redelivery and Redirection for additional information.

Allowed Values

Any string.

Default Value

By default, no value is specified.

Server Session Batch Size

The Server session batch size property specifies the maximum number of messages that a connection consumer can load into a server session at one time. This property applies to topic subscribers and queue receivers, and is specified in the Advanced properties dialog. By default, this property is set to 1 and cannot be changed.

Server Session Pool Size

The Server session pool size property specifies the maximum number of threads per ServerSessionPool to be used for concurrent processing. This property applies to topic subscribers and queue receivers, and is specified in the Advanced properties dialog.

This property is used in conjunction with the connection consumer setting of the Concurrency property, as described in Concurrency). You can specify the number of message driven beans (MDBs) or server session pool to assign to a JMS Collaboration to process messages concurrently. When you use connection consumer with fully concurrent or protected concurrent FIFO processing, this connection consumer configuration allows the integration server to assign multiple threads to execute the Collaboration on a particular message destination.

For an overview about message processing, refer to Message Processing Order.

Allowed Values

An integer of 1 or larger, depending on the capability of the system, indicating the number of threads.

Default Value

By default, the maximum number of threads per server session pool is 5.

Producers

Delivery Mode

The Delivery mode property specifies whether the messages for this JMS connection are persistent or non-persistent. This property applies to topic publishers and queue senders, and is specified in the Basic properties dialog.

Non-persistent delivery mode is the most efficient delivery mode, because it does not require messages to be saved to permanent storage. Per JMS specification, the message destination delivers non-persistent messages with an at-most-once guarantee. The message is only delivered once, even if it is lost. This mode involves a trade-off between performance and reliability. Non-persistence offers better performance but if a message server fails, messages may be lost due to a power outage.

When messages are persistent, the message server places the message in permanent storage to ensure the message is not lost in transit if the message server fails. Persistent messages are delivered once, and only once.

For the JMS IQ Manager, persistent messages are stored in the message server database files.

Default Value

The default delivery mode is Persistent.

Idle Timeout

The Idle timeout property specifies the amount of time, in seconds, to wait before returning a connection to the pool. This property applies to topic publishers and queue senders, and is specified in the Basic properties dialog.

Default Value

The default timeout is 30 seconds.

Maximum Pool Size

The Maximum pool size property specifies the maximum number of connections to be made to the message server. This property applies to topic publishers and queue senders, and is specified in the Basic properties dialog.

Default Value

The default size is 32.

Maximum Wait Time

The Maximum wait time property specifies the maximum amount of time, in milliseconds, to wait for acquiring a connection before throwing an exception. This property applies to topic publishers and queue senders, and is specified in the Basic properties dialog.

Default Value

The default time is 30000 milliseconds.

Priority

The Priority property specifies the message priority level for the JMS client. The message priority level that you specify causes all messages produced by this client to have that same priority level. For example, if you set the priority level to 2, all messages sent by that client have message priority level 2. This property applies to topic publishers and queue senders, and is specified in the Basic properties dialog.

You can also specify message priorities in Collaborations with the JMS OTD with the setPriority method. Collaboration message priorities override JMS client message priorities. For more information, refer to Configuring JMS Clients.

Allowed Values

An integer between 0 and 9, where 0 through 4 is normal priority and 5 through 9 is expedited priority.

Default Value

The default delivery mode is 4.

Steady Pool Size

The Steady pool size property specifies the minimum, and initial, number of connections maintained in the pool. This property applies to topic publishers and queue senders, and is specified in the Basic properties dialog.

Default Value

The default is 4 connections.

Transaction Mode

The Transaction mode property specifies the transaction mode used for message producers. For consumers, this mode is always XA. This property applies to topic publishers and queue senders, and is specified in the Basic properties dialog.

The Transaction mode property specifies whether messages for this JMS client use one of the following transaction modes:

Allowed Values

Transacted or XA.

Default Value

The default transaction mode is XA.


Note - Documentation on distributed transaction processing using XA is available at no charge from The Open Group at http://www.opengroup.org (search on “XA”).