Sonic Message Queuing

Topics:

Reference:

Sonic Message Queuing delivers a high performance and high reliability messaging system and provides certified Java Message Service Queue (JMSQ) implementation that includes both Queue Point-to-Point messaging and Publish/Subscribe messaging. It has an extended client/server feature that enables hierarchical security management. Sonic Message Queuing guarantees message persistence over the Internet. It contains message security, encryption, and certificate management.

The Sonic patent-pending Dynamic Routing Architecture (DRA) enables enterprises to participate in global e-Business exchanges through a single broker. When trading domains come online, Sonic dynamically discovers destinations and delivers messages between the servers on an optimized routing path. The Sonic architecture sets a foundation for high-throughput e-Business integration by robustly providing the following e-Business essentials: scalability, availability, and reliability.

The iWay Adapter for Sonic MQ provides bidirectional capability to and from Sonic destinations.

This topic describes how to:

To redirect output to a destination, see iWay Adapter for Sonic Emitter Functionality.

Queuing Messages With Sonic

The iWay Adapter for Sonic MQ enables Service Manager to read messages arriving on a named queue or topic and route the messages to either another queue or topic, or to a non-Sonic destination. Similarly, messages received through any of the other iWay protocol adapter listeners can be directed to a Sonic queue. During the message flow, Service Manager can apply standard document analysis, validation, transformation, and business logic capabilities to the document.

The iWay Adapter for Sonic MQ provides bidirectional support for Sonic queues (a listener and an emitter). The adapter provides support for topics for a TopicSession in the Publish and Subscribe domain, as well as queue support (for a QueueSession in the PTP domain). Support is provided for persistent and non-persistent messages. The persistent option prevents messages from being lost in the event of a network or system failure. The iWay Adapter for Sonic MQ can operate over TCP, SSL, or HTTP(S).

The iWay Adapter for Sonic MQ includes high availability features. The adapter monitors the connection for an exception and re-establishes the connection if it was dropped. The adapter also supports load balancing. With load balancing enabled, a connect request can be redirected to another broker with a Sonic cluster. Similarly, failover capability is implemented. The adapter can redirect the message to another broker if it is unable to connect to the original broker.

Registering Sonic Client JAR Files

The following tables list the required .jar files for registration.

For instructions on registering JAR files, see iWay Service Manager Protocol Guide.

For Listeners:

Type

JAR Files

SSL

  • Sonic_Client.jar

    Found at %Sonic_Home%/lib/.

    Add the Sonic_Client to the Path Settings PreClassPath section.

  • Sonic_Crypto.jar
  • jsafe.jar
  • sonic_SSL.jar
  • certj.jar
  • sslj.jar

Add the files to the Path Settings PreClassPath section.

SSL Client Certificate

  • Sonic_Client.jar

    Found at %Sonic_Home%/lib/.

    Add the Sonic_Client to the Path Settings PreClassPath section.

  • Sonic_Crypto.jar
  • jsafe.jar
  • sonic_SSL.jar
  • certj.jar
  • sslj.jar

For Emitters:

Type

JAR Files

TCP or HTTP

Sonic_Client.jar

Found at %Sonic_Home%/lib/.

Add the Sonic_Client to the Path Settings PreClassPath section.

SSL

  • Sonic_Client.jar
  • jsafe.jar
  • sonic_SSL.jar
  • certj.jar
  • sslj.jar

Found at %Sonic_Home%/lib.

Add the JAR files to the Path Settings PreClassPath section.

For instructions on registering JAR files, see iWay Service Manager Protocol Guide.

iWay Adapter for Sonic MQ Listener Capability

How to:

Sonic supports standard Internet protocols including Secure Socket Layer (SSL), HTTP, encryption, TCP, and security. iWay Service Manager can listen on Sonic queues using TCP, SSL, HTTP, and HTTPS protocols. Each protocol requires setup specific to the unique protocol. This topic details configuration information for each individual protocol.

Procedure: How to Configure Reconnect Support

  1. Click the Server link at the top left of the Service Manager console.
  2. Under Settings in the left pane, click General Settings.
  3. In the Retry Interval entry field, enter a value to enable the listeners to retry the connection if it fails for external causes.

    The default value is 120 seconds.

    The retry interval is a global property that controls the configured listeners. It marks the frequency in seconds in which Service Manager attempts to reconnect to a broker if the connection is lost or cannot be established.

Configuring a Sonic Listener Using TCP or HTTP

Topics:

The Transport Control Protocol (TCP) is a connection-oriented protocol that establishes a connection with another host before it sends data. Before a connection is started between two hosts, control messages called a handshake are sent out to initiate the connection. TCP is the default protocol of a Sonic broker installation. Client applications that are Internet-enabled generally use TCP/IP protocols.

Hypertext Transfer Protocol (HTTP), the underlying protocol used by the World Wide Web, defines how messages are formatted and transmitted and the actions web servers and browsers must take in response to various commands.

HTTP operates over TCP connections. After a successful connection, the client transmits a request message to the server, which returns a reply message.

By server design or by company security policy, proxy servers and firewalls frequently allow only HTTP-based traffic to pass through. You can establish a direct connection to a Sonic broker using HTTP tunneling as the protocol. However, because the HTTP tunneling protocol is significantly slower than TCP or SSL, this option is recommended only when TCP and SSL protocols are not available.

You require JAR files supplied by Sonic to emit messages to a Sonic message queue.

Sonic Listener Properties for TCP or HTTP

The following table lists and describes the Sonic listener properties for TCP or HTTP. For instructions on creating a listener, see Configuring Listeners.

Property Name

Property Description

Form of Input

TOPIC

Is for a TopicSession in the Publish and Subscribe domain.

QUEUE

Is for a QueueSession in the PTP domain.

Receiver Name (required)

The name of the queue on which input documents will be received for processing by Service Manager.

Default Output Form

The topic or queue target.

Standard Reply To

The queue or topic to which the system writes response messages. The property may be overwritten by the configuration properties.

Broker URL (required)

The URL (address) used by the listener to connect to the Sonic broker. The format of the URL is Protocol://host:port. If Service Manager is listening on a Sonic broker configured to listen on TCP, the format of the URL is tcp://host:port. The default TCP port on which Sonic listens is 2506. This value is configured in the Sonic broker.ini file. When Service Manager listens to Sonic, the URL is in the form of http://host:port where the HTTP port is defined in the Sonic broker.ini file.

The Sonic listener supports failover if unable to reach a particular broker. You must provide a comma-separated list of broker URLs. The client attempts to connect to brokers in the list, for example, tcp://host:port, tcp://host:port.

Pending Queue

If system resources are down or temporarily unavailable, requests that cannot be completed can be placed into the pending system for later execution. When listening on a TOPIC, the iWay adapter uses a Sonic queue for pending.

Form of Acknowledgment

Acknowledgment mode support: the session acknowledgment mode is either Transactional (to send and receive a series of messages and then explicitly commit or roll back the group) or in one of the following acknowledgment modes:

Client Provides - An explicit acknowledge on a message acknowledges the receipt of all messages that were produced and consumed by the session that gives the acknowledgment. When a session is forced to recover, it restarts with its first unacknowledged message.

Duplicates Permitted - The session lazily acknowledges the delivery of messages to consumers, possibly allowing some duplicate messages after a system outage.

Auto Acknowledge - The session automatically acknowledges the client receipt of a message by successfully returning from a call to receive (synchronous mode) or when the session message listener successfully returns (asynchronous mode). The last message can be delivered again.

Send Persistently

The support for persistent and non-persistent messages. In the event of a network or system failure, the persistent option prevents messages from being lost.

In the event of a broker or Service Manager failure, non-persistent messages are volatile. Persistent messages are saved to disk.

Durable Topic Subscriber

The support for durable topic subscribers. In Publish and Subscribe messaging, messages are not stored for later delivery unless the client establishes a subscription name that is associated with its user identity on the message broker.

False (Non-Durable Subscribers) - A client uses a topic subscriber to receive messages that were published to a topic. A regular topic subscription is not durable. Messages are delivered when active but never retained.

True (Durable Subscribers) - If a client must receive all messages published on a topic including those published while the subscriber is inactive, it uses a durable TopicSubscriber.

The message broker retains a record of this durable subscription and ensures that all messages from the topic publishers are retained until they are either acknowledged by this durable subscriber or expire. Sessions with durable subscribers must always provide the same client identifier. In addition, each client must specify a name that uniquely identifies (within the client identifier) each durable subscription it creates. Within a session, durable topic subscribers must be uniquely named.

Message Priority

The Sonic broker attempts to deliver messages with a higher priority ahead of messages with lower values. Priority is suggested to the JMSQ provider and can only order the delivery of undelivered messages. JMSQ defines ten levels of message priority with values 0 through 9, where 0 is the lowest, and 9 is the highest. Zero through four are considered normal settings and five through nine, expedited. The Message Priority field is the default priority value set in the JMSQ header.

Set Reply Correlation Id

If set to a value, that value is used as the correlation ID of the response.

Load Balance

If set to true, the load balancing option is enabled on the Service Manager listener. With load balancing enabled, a connect request can be redirected to another broker within a Sonic cluster, if load balancing was not disabled on the broker side.

Duplicates Detect

You can configure the broker to commit transactions to index a universally unique, 64-character identifier (UUID) supplied by the sender. The sender then uses a commit method that commits the transacted messages, unless a previously sent transaction identifier is still unexpired. Otherwise, the method forces a rollback of the transaction.

For more information, see the INDEXED_TXN_ server properties in the installation section of the Sonic MQ V5 Configuration and Administration Guide.

User

A valid user ID defined to Sonic. You can use the Sonic Explorer Users option (found under message broker) to display users defined to Sonic. The user ID is required only when Sonic security is enabled.

Password

A valid user ID and password combination defined to Sonic. Use the Sonic Explorer Users option (found under message broker) to display users defined to Sonic.

Client ID

The broker retains messages for durable subscriber, using the userName and clientID of the connection plus the subscriptionName to index the subscription. The Client ID is a unique identifier that can prevent conflicts for durable subscriptions when many clients use the same user name and the same subscription name.

Connection ID

Identifies the connection. When combined with Client ID, must be unique at the broker.

Subscription Name

A subscription name always includes the name of the topic. To distinguish different message selectors used in subscriptions, you can include a string that helps identify the message selector. For example, you can use a subscription named Atlas_priority4 for a subscription to the Atlas topic with selector JMSPriority=4. This construct enables you to create many durable subscriptions that are easily understood and nonconflicting.

Message Selector

In PTP domains, all message selection takes place on the server. However, in Pub/Sub domains, all messages for a subscribed topic are delivered by default to the subscriber, and then, the filter is applied to decide what is consumed. Message selectors can consist of:

  • Literals and indefinites
  • Operators and expressions
  • Comparison tests
  • Parentheses
  • White space

Output Message Type

Select Bytes, Text, or Dynamic.

Prefetch Count

Only applies to queue messages. Does not apply to topic messages. Prefetch count is the number of messages buffered locally. A worker (thread) prefetches messages to this limit. Injudicious use of this configuration can result in unbalanced thread use and appear to cause worker starvation. For example, if a prefetch count is set to 3 and two workers are defined and three messages are in the queue, the first worker prefetches all three messages. The second worker finds the queue empty and awaits the arrival of yet another message. Thus, it appears that the first worker processes three messages while the second does no work. To achieve balance, set the prefetch count to 1 and the prefetch threshold to 0. Use of prefetch count and threshold can result in improved performance through overall reduction in network traffic to the broker.

Prefetch Threshold

Fewer messages cause prefetch to be initiated. For additional information, see the description of the Prefetch Count property.

Duration

The maximum time a document can remain in the retry pending queue.

Retry

The interval between retrying pending requests.

Preserve Undelivered

The preserve messages that are not retrieved to a dead letter queue.

Notify Undelivered

Notify the broker administrator if undelivered messages are preserved.

Sequential

Determines the order in which the connection to the brokers is made when multiple brokers are listed. If this property is enabled, connection occurs sequentially. If disabled, connection occurs in a random manner.

Fault Tolerant

Determines whether the listener is connecting to the Sonic Broker as a fault tolerant client or not. The default value is false, that is, the listener is not connecting as a fault tolerant client.

This feature is supported only when the Sonic Broker is installed with a Sonic Fault Tolerance license code.

Reconnect Fault Timeout

Sets the interval, in seconds, of how long to wait before attempting to reconnect to the broker if the session is lost.

Initial Connect Timeout

Sets the interval, in seconds, of how long to wait before attempting to connect to the broker, or to another broker on the list, if connection fails when the listener is first started.

Whitespace Normalization

Specifies how the parser treats whitespace in Element content. Choose preserve to turn off all normalization as prescribed by the XML Specification. Choose condense to remove extra whitespace in pretty printed documents and for compatibility with earlier versions.

Accepts non-XML (flat) only

If set to true, then non-XML input is expected. If enabled, XML input still can be passed to the listener. Preparsers do not run.

Optimize Favoring

Use this option to customize listener performance. For smaller transactions, select performance. For large payloads that could monopolize the amount of memory used by Service Manager, select memory.

Multithreading

The number of worker threads. (Equivalent to the number of requests that Service Manager can handle in parallel.) Setting this to a value of greater than 1 enables the listener to handle a second request while an earlier request is being processed. The total throughput of a system can depend on the number of threads operating.

Default: 1 Max value: 99

Execution Time Limit

The maximum time a request can take to complete. A request that takes longer to complete terminates. Prevents runaway requests.

Note: The kill interval property checks for runaway requests that have exceeded their maximum life. Default is 60 (seconds). Duration is xxhxxmxxs, for example, 1h2m3s = one hour, two minutes, and three seconds.

Polling Interval

Indicates frequency in seconds that the listener returns control to Service Manager to determine if a stop listener was requested. Listener is constantly connected to the queue to retrieve incoming messages. The default value is 2.0.

Default Java File Encoding

The default encoding if incoming message is not self-declaring (that is, XML).

Agent Precedence

Sets the order by which Service Manager selects agents. Service Manager selects the agent(s) to process the document by searching through the configuration dictionary. Usually, it looks for a document entry in the configuration and when a match is found, the agent specified in that document entry is selected. If a matching document entry is not found or no agent is specified, the engine looks in the input protocol configuration (listener). To have the processing agent taken directly from the listener (thus ignoring the document entry), use <listener> overrides <document>.

<document> overrides <listener> is the default value.

Always reply to listener default

If set to true, the default reply definition is used in addition to defined destinations.

Error Documents treated normally

If set to true, error documents are processed by configured preemitters.

Listener is Transaction Manager

If set to true, agents run in a local transaction. Agents can roll back uncompleted transactions.

Record in Activity Log(s)

If set to true, activity on this channel will be recorded in the activity logs, else the activity will not be recorded.

Note: The Sonic listener supports streaming. Streaming is used for large documents or documents for which the application needs to split the input into sections under the same transaction. For more information on streaming and configuring streaming preparsers, see the iWay Service Manager Component and Functional Language Reference Guide.

Sonic TCP Listener Configuration Example

You would like to listen on a Sonic MQ queue named SampleQ2, hosted by a broker on machine iwxfoc, which listens on default Sonic MQ port 2056. You would also like to output messages to the queue SampleQ4 on the same broker. The broker does not have security enabled.

To configure the components needed to support this scenario, you need to configure the following in Service Manager:

Note: For information on the steps required to accomplish these tasks, see the iWay Service Manager User’s Guide.

  • Copy the Default Channel provided with SM installation and rename it as sonic_lsn_channel.
  • Create a listener of type Sonic, and call it jsm_sm_lsn_sonic. The listener will connect to Sonic MQ on iwxfoc machine (tcp://iwxfoc:2506). It will get messages from SampleQ2 queue and output them into a queue named SampleQ4 at the same broker.
  • Add the listener to an Inlet.
  • Add the Inlet to the Channel.

The other parts of the channel will stay the same as default channel. After building and deploying the sonic_lsn_channel, you can see messages being transferred from SampleQ2 to SampleQ4 on the iwxfoc Sonic MQ broker.

Specify the listener values as follows. Leave default values for all other fields.

  • Type: Sonic
  • Form of Input: queue
  • Receiver Name: SampleQ2
  • Standard Reply To: SampleQ4
  • Broker URL: tcp://iwxfoc :2506

The following image shows the Sonic listener configuration pane.

Configuring a Sonic Listener Using SSL

Topics:

Secure Sockets Layer (SSL) provides authentication and encryption techniques that require the broker to set the appropriate properties and certificates on a security-enabled database. The client also must have the appropriate libraries and properties to call an SSL connection. A complete implementation sample is provided in the Protocols section of the Sonic MQ V5 Configuration and Administration Guide.

Note: You must have SSL libraries installed from RSA with the appropriate Sonic license or from supported third-parties such as Institute for Applied Information Processing and Communications (IAIK) or Java Secure Socket Extension (JSSE).

The manner in which you configure SSL for your application depends on whether you implement client authentication with a user name and password or with a client certificate.

When the Sonic broker is configured with the SSL property SSL_CLIENT_AUTHENTICATION=FALSE in the broker.ini configuration file, no client certificate is required, and the client is authenticated with a user name and password. The client reads the user name and password and then passes them to the broker.

The following diagram shows Step 1, in which the broker sends the certificate to the client to authenticate itself; Step 2, in which the client presents its certificate information to authenticate the connection; and Step 3, in which an SSL connection is established.

You must add JAR files, supplied by Sonic, to emit messages to a Sonic message queue using the SSL protocol. For more information, see Registering Sonic Client JAR Files.

Setting Java System Properties for Sonic SSL

For instructions on setting Java system properties, see the iWay Service Manager Protocol Guide.

In the Property field, type SSL_CA_CERTIFICATES_DIR. In the Value field, type the location of the CA certificate to be used by Service Manager.

The default certificate shipped with the Sonic product is located in:

%SONIC_HOME%\certs\ca

Sonic Listener Properties for SSL

The following table lists and describes the Sonic listener properties for SSL. For instructions on creating a listener, see Configuring Listeners.

Property Name

Property Description

Form of Input

TOPIC

Is for a TopicSession in the Publish and Subscribe domain.

QUEUE

Is for a QueueSession in the PTP domain.

Receiver Name (required)

The name of the queue on which input documents will be received for processing by Service Manager.

Default Output Form

The topic or queue target.

Standard Reply To

The queue or topic to which the system writes response messages. The property may be overridden by the configuration properties.

Broker URL (required)

The URL (address) used by the listener to connect to the Sonic broker. The format of the URL is Protocol://host:port. If Service Manager is listening on a Sonic broker configured to listen on SSL, the URL would be in the format of ssl://host:port. This value is configured in the Sonic broker.ini file. The Sonic listener supports failover if unable to reach a particular broker. You must provide a comma-separated list of broker URLs. The client attempts to connect to brokers in this list, for example, ssl://host:port.

Pending Queue

Requests that cannot be completed because system resources are down or temporarily unavailable can be placed into the pending system for later execution. When listening on a TOPIC, the adapter uses a Sonic queue for pending.

Form of Acknowledgment

Acknowledgment mode support: The session acknowledgment mode is either Transactional (to send and receive a series of messages and then explicitly commit or rollback the group) or one of the available acknowledgment modes.

Client Provides - An explicit acknowledge on a message acknowledges the receipt of all messages that are produced and consumed by the session that gives the acknowledgment. When a session is forced to recover, it restarts with its first unacknowledged message.

Duplicates Permitted - The session lazily acknowledges the delivery of messages to consumers, possibly allowing some duplicate messages after a system outage.

Auto Acknowledge - The session automatically acknowledges the client receipt of a message by successfully returning from a call to receive it (synchronous mode) or when the session message listener successfully returns the receipt (asynchronous mode). The last message can be delivered again.

Send Persistently

Support for persistent and non-persistent messages. In the event of a network or system failure, the persistent option prevents messages from being lost.

In the event of a broker or iWay Service Manager failure, non-persistent messages are volatile. Persistent messages are saved to disk.

Durable Topic Subscriber

Support for durable topic subscribers. In Publish and Subscribe messaging, messages are not stored for later delivery unless the client establishes a subscription name that is associated with its user identity on the message broker.

False (Non-durable subscribers) - A client uses a topic subscriber to receive messages that have been published to a topic. A regular topic subscription is not durable. Messages are delivered when active but never retained.

True (Durable subscribers) - If a client must receive all the messages published on a topic including those published while the subscriber is inactive, it uses a durable TopicSubscriber.

The message broker retains a record of this durable subscription and ensures that all messages from the topic publishers are retained until they are either acknowledged by this durable subscriber or expire. Sessions with durable subscribers must always provide the same client identifier. In addition, each client must specify a name that uniquely identifies (within the client identifier) each durable subscription it creates. Within a session, durable topic subscribers must be uniquely named.

Message Priority

The Sonic broker attempts to deliver messages with a higher priority ahead of messages with lower values. Priority is suggested to the JMSQ provider, and only orders delivery of undelivered messages. JMSQ defines ten levels of message priority with values 0 through 9, where 0 is the lowest and 9 is the highest. Zero through four are considered normal settings and five through nine, expedited. The Message Priority field is the default priority value set in the JMSQ header.

Set Reply Correlation Id

If set to a value, that value used as the correlation ID of the response.

Load Balance

Select true to enable the load balancing option on the Service Manager listener. With load balancing enabled, a connect request can be redirected to another broker within a Sonic cluster, if load balancing was not disabled on the broker side.

Duplicates Detect

You can configure the broker to commit transactions such that they index a universally unique, 64-character identifier (UUID) supplied by the sender. The sender then uses a commit method that commits the transacted messages, unless a previously sent transaction identifier is still unexpired. Otherwise, the method forces a rollback of the transaction.

For more information, see the INDEXED_TXN_ server properties in the installation section of the Sonic MQ V5 Configuration and Administration Guide.

User

A valid user ID defined to Sonic. You can use the Sonic Explorer Users option (found under message broker) to display users defined to Sonic. The user ID is required when listening on a Sonic queue with client authentication.

Password

A valid user ID and password combination defined to Sonic. You can use the Sonic Explorer Users option (found under message broker) to display users defined to Sonic. The password is required when listening on a Sonic queue with client authentication.

Client ID

The broker retains messages for durable subscriber, using the userName and clientID of the connection, plus the subscriptionName to index the subscription. The Client ID is a unique identifier that can prevent conflicts for durable subscriptions when many clients are using the same user name and the same subscription name.

Connection ID

The identifies the connection. When combined with Client ID, must be unique at the broker.

Subscription Name

A subscription name always includes the name of the topic. To distinguish different message selectors used in subscriptions, you can include a string that helps identify the message selector. For example, you can use a subscription named Atlas_priority4 for a subscription to the Atlas topic with selector JMSPriority=4. This construct enables you to create many durable subscriptions that are easily understood and non-conflicting.

Message Selector

In PTP domains, all message selection takes place on the server. However, in Pub/Sub domains, all messages for a subscribed topic are by default delivered to the subscriber and then, the filter is applied to decide what is consumed. Message selectors can consist of:

  • Literals and indefinites
  • Operators and expressions
  • Comparison tests
  • Parentheses
  • White space

Output Message Type

Select Bytes, Text, or Dynamic.

Prefetch Count

Only applies to queue messages; does not apply to topic messages. Prefetch count is the number of messages buffered locally. A worker (thread) prefetches messages to this limit. Injudicious use of this configuration can result in unbalanced thread use and appear to cause worker starvation. For example, if a prefetch count is set to 3 and two workers are defined and three messages are in the queue, the first worker prefetches all three messages. The second worker finds the queue empty and awaits the arrival of yet another message. Thus, it appears that the first worker processes three messages while the second does no work. To achieve balance, set the prefetch count to 1 and the prefetch threshold to 0. Use of prefetch count and threshold can result in improved performance through overall reduction in network traffic to the broker.

Prefetch Threshold

Fewer messages cause prefetch to be initiated. For additional information, see the description of the Prefetch Count property.

Duration

The maximum time that a document can remain in the retry pending queue.

Retry

The interval between retrying pending requests.

Preserve Undelivered

The preserve messages that are not retrieved to a dead letter queue.

Notify Undelivered

Notifies the broker administrator if undelivered are preserved.

Sequential

Determines the order in which the connection to the brokers is made when multiple brokers are listed. If this property is enabled, connection occurs sequentially. If disabled, connection occurs in a random manner.

Fault Tolerant

Determines whether the listener is connecting to the Sonic Broker as a fault tolerant client or not. The default value is false, that is, the listener is not connecting as a fault tolerant client.

This feature is supported only when the Sonic Broker is installed with a Sonic Fault Tolerance license code.

Reconnect Fault Timeout

Sets the interval, in seconds, of how long to wait before attempting to reconnect to the broker if the session is lost.

Initial Connect Timeout

Sets the interval, in seconds, of how long to wait before attempting to connect to the broker, or to another broker on the list, if connection fails when the listener is first started.

Whitespace Normalization

Specifies how the parser treats whitespace in Element content. Choose preserve to turn off all normalization as prescribed by the XML Specification. Choose condense to remove extra whitespace in pretty printed documents and for compatibility with earlier versions.

Accepts non-XML (flat) only

If set to true, non-XML input is expected. If enabled, XML input still can be passed to the listener. Preparsers do not run.

Optimize Favoring

Use this option to customize listener performance. For smaller transactions, select performance. For large payloads that could monopolize the amount of memory used by Service Manager, select memory.

Multithreading

The number of worker threads. (Equivalent to the number of requests that Service Manager can handle in parallel.) Setting this to a value of greater than 1 enables the listener to handle a second request while an earlier request is being processed. The total throughput of a system is affected by the number of threads operating.

Default: 1 Max value: 99

Execution Time Limit

The maximum time a request can take to complete. A request that takes longer to complete terminates. Prevents runaway requests.

Note: The kill interval property checks for runaway requests that exceed their maximum life. Default is 60 (seconds). Duration is xxhxxmxxs, for example, 1h2m3s = one hour, two minutes, and three seconds.

Polling Interval

Indicates frequency in seconds that the listener returns control to Service Manager to determine if a stop listener was requested. The listener is constantly connected to the queue to retrieve incoming messages. The default value is 2.0.

Default Java File Encoding

The default encoding if incoming message is not self-declaring (that is, XML).

Agent Precedence

Sets the order by which Service Manager selects agents. Service Manager usually looks for a document entry in the configuration dictionary and when a match is found, the agent specified in that document entry is selected. If a matching document entry is not found or no agent is specified, the engine looks in the input protocol configuration (listener). To have the processing agent taken directly from the listener (thus ignoring the document entry), use <listener> overrides <document>.

<document> overrides <listener> is the default value.

Always reply to listener default

If set to true, the default reply definition is used in addition to defined destinations.

Error Documents treated normally

If set to true, error documents are processed by configured preemitters.

Listener is Transaction Manager

If set to true, agents run in a local transaction. Agents can roll back uncompleted transactions.

Record in Activity Log(s)

If set to true, activity on this channel will be recorded in the activity logs, else the activity will not be recorded.

Note: The Sonic listener supports streaming. Streaming is used for large documents or documents for which the application needs to split the input into sections under the same transaction. For more information on streaming and configuring streaming preparsers, see the iWay Service Manager Component and Functional Language Reference Guide.

Reference: Sonic Listener Special Registers

The following table lists and describes the special registers (SREGs) available on the Sonic listener.

Name

Level

Type

Description

correlid

Document

String

The correlation ID.

destination

Document

String

The default destination for reply (from message).

iwayconfig

System

String

The current active configuration name.

msgid

Document

String

The message ID.

msgsize

Document

Integer

The physical length of the message payload.

name

System

String

The assigned name of the master (listener).

priority

Document

String

The priority of this message.

protocol

System

String

The protocol on which this message was received.

source

Document

String

The queue or topic on which message was received.

tid

Document

String

Unique transaction ID.

Configuring a Sonic Listener Using SSL Client Certificate

Topics:

Reference:

When you configure the Sonic broker with the SSL property SSL_CLIENT_AUTHENTICATION=TRUE, you can achieve authentication by exchanging digital certificates between Service Manager and the Sonic broker. In addition to this mutual authentication, Service Manager can present a user name and password to the broker at run time (optional).

The following diagram shows Step 1, in which the broker sends the certificate to the client to authenticate itself; Step 2, in which the client presents its certificate information to authenticate the connection; and Step 3, in which an SSL connection is established.

JAR files supplied by Sonic are required to emit messages to a Sonic message queue using the SSL protocol. For more information, see Registering Sonic Client JAR Files.

Reference: JVM Options for SSL With Certificates

The following table lists and describes the properties required to configure the appropriate environment for communication to Sonic using SSL with certificates.

For instructions on setting Java system properties, see the iWay Service Manager Protocol Guide. Complete the Property and Value fields as described here.

Property

Description

SSL_CA_CERTIFICATES_DIR
SSL_CA_CERTIFICATES_DIR={certs/ca|path}
SSL_CA_CERTIFICATES_DIR_n={certs/ca|path}

Specifies the location of the Certificate Authority (CA) certificate. The path must be fully qualified or relative to the Service Manager installation directory.

The default directory is certs/ca.

SSL_CERTIFICATE_CHAIN
SSL_CERTIFICATE_CHAIN={certs/server.p7c|path}
SSL_CERTIFICATE_CHAIN_n={certs/server.p7c|path}

Specifies the location of the file containing the client keystore certificate chain for SSL. The path must be fully qualified or relative to the Service Manager installation directory.

The default directory is certs/server.p7c.

SSL_CERTIFICATE_CHAIN_FORM
SSL_CERTIFICATE_CHAIN_FORM={LIST|PKCS12|PKCS7}
SSL_CERTIFICATE_CHAIN_FORM_n={LIST|PKCS12|PKCS7}

Specifies the format of the file containing the certificate chain.

PKCS7 is the default value, a comma-delimited list of path names that point to files containing each individual certificate in the chain.

SSL_PRIVATE_KEY
SSL_PRIVATE_KEY={serverKey.pkcs8|path}
SSL_PRIVATE_KEY_n={serverKey.pkcs8|path}

Provides the location of the file containing the client encrypted private key for SSL. This path must be fully qualified or relative to the Service Manager installation directory.

The default value is serverKey.pkcs8.

SSL_PRIVATE_KEY_PASSWORD
SSL_PRIVATE_KEY_PASSWORD={password|password}
SSL_PRIVATE_KEY_PASSWORD_n={password|password}

Provides the password that encrypts the private key for SSL.

The default value is password.

Sonic Listener Properties for SSL With Client Certificate

The following table lists and describes the Sonic listener properties for SSL with client certificate. For instructions on creating a listener, see Configuring Listeners.

Property Name

Property Description

Form of Input

TOPIC

Is for a TopicSession in the Publish and Subscribe domain.

QUEUE

Is for a QueueSession in the PTP domain.

Receiver Name (required)

The name of the queue on which input documents will be received for processing by Service Manager.

Default Output Form

The topic or queue target.

Standard Reply To

The queue or topic to which the system writes response messages. The property may be overwritten by the configuration properties.

Broker URL (required)

The URL (address) used by the listener to connect to the Sonic broker. The format of the URL is Protocol://host:port. If Service Manager is listening on a Sonic broker configured to listen on TCP, the format of the URL is tcp://host:port. The default TCP port on which Sonic listens is 2506. This value is configured in the Sonic broker.ini file. When iWay Service Manager listens to Sonic, the URL is in the form of http://host:port where the HTTP port is defined in the Sonic broker.ini file.

The Sonic listener supports failover if unable to reach a particular broker. You must provide a comma-separated list of broker URLs. The client attempts to connect to brokers in this list, for example, tcp://host:port, tcp://host:port.

Pending Queue

If the system resources are down or temporarily unavailable, requests that cannot be completed can be placed into the pending system for later execution. When listening on a TOPIC, the iWay adapter uses a Sonic queue for pending.

Form of Acknowledgment

Acknowledgment mode support: The session acknowledgment mode is either Transacted (to send and receive a series of messages and then explicitly commit or roll back the group) or in one of the available acknowledgment modes.

Client Acknowledge - An explicit acknowledge on a message acknowledges the receipt of all messages that are produced and consumed by the session that gives the acknowledgment. When a session is forced to recover, it restarts with its first unacknowledged message.

Duplicates OK Acknowledge - The session lazily acknowledges the delivery of messages to consumers, possibly allowing some duplicate messages after a system outage.

Auto Acknowledge - The session automatically acknowledges the client receipt of a message by successfully returning from a call to receive (synchronous mode) or when the session message listener successfully returns (asynchronous mode). The last message can be delivered again.

Send Persistently

The support for persistent and non-persistent messages. The persistent option prevents messages from being lost in the event of a network or system failure.

In the event of a broker or Service Manager failure, non-persistent messages are volatile. Persistent messages are saved to disk.

Durable Topic Subscriber

Support for durable topic subscribers.

In Publish and Subscribe messaging, messages are not stored for later delivery unless the client establishes a subscription name that is associated with its user identity on the message broker.

False (Non-Durable Subscribers). A client uses a topic subscriber to receive messages that are published to a topic. A regular topic subscription is not durable. Messages are delivered when active but never retained.

True (Durable Subscribers). If a client must receive all the messages published on a topic including those published while the subscriber is inactive, it uses a durable TopicSubscriber.

The message broker retains a record of this durable subscription and ensures that all messages from the topic publishers are retained until they are either acknowledged by this durable subscriber or expire. Sessions with durable subscribers must always provide the same client identifier. In addition, each client must specify a name that uniquely identifies (within the client identifier) each durable subscription it creates. Within a session, durable topic subscribers must be uniquely named.

Message Priority

The Sonic broker attempts to deliver messages with a higher priority ahead of messages with lower values. Priority is suggested to the JMSQ provider and can only order the delivery of undelivered messages. JMSQ defines ten levels of message priority with values 0 through 9, where 0 is the lowest and 9 is the highest. Zero through four are considered normal settings and five through nine, expedited. The Message Priority field is the default priority value set in the JMSQ header.

Set Reply Correlation Id

If set to a value, that value is used as the correlation ID of the response.

Load Balance

Select the load balancing option on the Service Manager listener for load balancing. With load balancing enabled, a connect request can be redirected to another broker within a Sonic cluster, if load balancing was not disabled on the broker side.

Duplicates Detect

You can configure the broker to commit transactions to index a universally unique, 64-character identifier (UUID) supplied by the sender. The sender then uses a commit method that commits the transacted messages, unless a previously sent transaction identifier is still unexpired. Otherwise, the method forces a rollback of the transaction.

For more information, see the INDEXED_TXN_ server properties in the installation section of the Sonic MQ V5 Configuration and Administration Guide.

User

A valid user ID defined to Sonic. You can use the Sonic Explorer Users option (under message broker) to display users defined to Sonic. User ID only required if Sonic security is enabled.

Password

A valid user ID and password combination defined to Sonic. Use the Sonic Explorer Users option (under message broker) to display users defined to Sonic.

Client ID

The broker retains messages for durable subscriber, using the userName and clientID of the connection plus the subscriptionName to index the subscription. The Client ID is a unique identifier that can prevent conflicts for durable subscriptions when many clients are using the same user name and the same subscription name.

Connection ID

Identifies the connection. When combined with Client ID, must be unique at the broker.

Subscription Name

A subscription name always includes the name of the topic. To distinguish between different message selectors used in subscriptions, you can include a string that helps identify the message selector. For example, you can use a subscription named Atlas_priority4 for a subscription to the Atlas topic with selector JMSPriority=4. This construct lets you create many durable subscriptions that are easily understood and nonconflicting.

Message Selector

In PTP domains, all message selection takes place on the server. However, in Pub/Sub domains, all messages for a subscribed topic are delivered by default to the subscriber, and then, the filter is applied to decide what is consumed. Message selectors can consist of:

  • Literals and indefinites
  • Operators and expressions
  • Comparison tests
  • Parentheses
  • White space

Output Message Type

Select Bytes, Text Message, or Dynamic.

Prefetch Count

Only applies to queue messages; does not apply to topic messages. Prefetch count is the number of messages buffered locally. Any worker (thread) prefetches messages to this limit. Injudicious use of this configuration can result in unbalanced thread use and appear to cause worker starvation. For example, if a prefetch count is set to 3 and two workers are defined and three messages are in the queue, the first worker prefetches all three messages. The second worker finds the queue empty and awaits the arrival of yet another message. Thus, it appears that the first worker processes three messages while the second does no work. To achieve balance, set the prefetch count to 1 and the prefetch threshold to 0. Use of prefetch count and threshold can result in improved performance through overall reduction in network traffic to the broker.

Prefetch Threshold

Fewer messages cause prefetch to be initiated. For additional information, see the Prefetch Count property.

Duration

The maximum time that a document can remain in the retry pending queue.

Retry

The interval between retrying pending requests.

Preserve Undelivered

Preserves messages that are not retrieved to a dead letter queue.

Notify Undelivered

Notifies the broker administrator if undelivered are preserved.

Sequential

Determines the order in which the connection to the brokers is made when multiple brokers are listed. If this property is enabled, connection occurs sequentially. If disabled, connection occurs in a random manner.

Fault Tolerant

Determines whether the listener is connecting to the Sonic Broker as a fault tolerant client or not. The default value is false, that is, the listener is not connecting as a fault tolerant client.

This feature is supported only when the Sonic Broker is installed with a Sonic Fault Tolerance license code.

Reconnect Fault Timeout

Sets the interval, in seconds, of how long to wait before attempting to reconnect to the broker if the session is lost.

Initial Connect Timeout

Sets the interval, in seconds, of how long to wait before attempting to connect to the broker, or to another broker on the list, if connection fails when the listener is first started.

Accepts non-XML (flat) only

The select if non-XML input is expected. If enabled, XML input still can be passed to the listener. Preparsers do not run.

Optimize Favoring

Use this option to customize listener performance. For smaller transactions, select performance. For large payloads that could monopolize the amount of memory used by Service Manager, select memory.

Multithreading

The number of worker threads. (Equivalent to the number of requests that Service Manager can handle in parallel.) Setting this to a value of greater than 1 enables the listener to handle a second request while an earlier request is being processed. The total throughput of a system can depend on the number of threads operating. Default: 1 Max value: 99

Execution Time Limit

The maximum time a request can take to complete. A request that takes longer to complete terminates. Prevents runaway requests.

Note: The kill interval property checks for runaway requests that exceed their maximum life. Default is 60 (seconds). Duration is xxhxxmxxs, for example, 1h2m3s = one hour, two minutes, and three seconds.

Polling Interval

Indicates frequency in seconds that the listener returns control to Service Manager to determine if a stop listener was requested. The listener is constantly connected to the queue to retrieve incoming messages. The default value is 2.0.

Default Java File Encoding

The default encoding if incoming message is not self-declaring (that is, XML).

Agent Precedence

Sets the order by which Service Manager selects agents. Service Manager selects the agent or agents to process the document by searching through the configuration dictionary. Usually, it looks for a document entry in the configuration and when a match is found, the agent specified in that document entry is selected. If a matching document entry is not found or no agent is specified, the engine looks in the input protocol configuration (listener). To have the processing agent taken directly from the listener (thus ignoring the document entry), use <listener> overrides <document>.

<document> overrides <listener> is the default value.

Always reply to listener default

If set to true, the default reply definition is used in addition to defined destinations.

Error Documents treated normally

If set to true, error documents are processed by configured preemitters.

Listener is Transaction Manager

If set to true, agents run in a local transaction. Agents can roll back uncompleted transactions.

Initialization Agent

The name (parameters) of the processing module called at listener start up.

Note: The Sonic listener supports streaming. Streaming is used for large documents or documents for which the application needs to split the input into sections under the same transaction. For more information on streaming and configuring streaming preparsers, see the iWay Service Manager Component and Functional Language Reference Guide.

Configuring a Sonic Listener Using HTTPS

To configure the Sonic listener for SSL (the user ID or certificate depending on how the broker is configured), modify the destination address to specify an HTTPS URL.

The format of the destination property is queue@url. When emitting to Sonic queues over HTTPS, the format is queue@https://host:port. The HTTP port is configured in the Sonic broker.ini file. To send a message to iWay.Reply hosted on a Sonic broker on your localhost, the URL is iWay.Reply@https://localhost:2507.

For instructions on creating a listener, see Configuring Listeners.

iWay Adapter for Sonic Emitter Functionality

To route an output document or error message to a protocol other than that of the listener, you must configure an emitter. An emitter sends documents outbound either on the same protocol that the document arrived on or across protocols. You can return a processed document to one or more alternate destinations. By default, an output document is returned using the same protocol on which it was received. For example, an application may send input over TCP but want to route the output to a Sonic queue. In this case, you would configure an emitter.

Note: Configuring a Sonic emitter is not required if the emitter protocol used in the outlet of the channel is the same as the listener protocol used in the inlet of the channel. For more information on inlets and outlets, see the iWay Service Manager User’s Guide.

Sonic supports standard Internet protocols including Secure Socket Layer (SSL), HTTP, encryption, TCP, and security. Service Manager can send responses to Sonic queues through TCP, SSL, HTTP, and HTTPS protocols. Each protocol requires specific set up. This topic describes configuration information for each protocol.

Configuring a Sonic Emitter Using TCP or HTTP

Topics:

The Transport Control Protocol (TCP) is a connection-oriented protocol that establishes a connection with another host before it sends its data. Before a connection is started between two hosts, control messages called a handshake are sent to initiate the connection. TCP is the default protocol of a Sonic broker installation. Client applications that are Internet-enabled generally use TCP/IP protocols.

Hypertext Transfer Protocol (HTTP), the underlying protocol used by the World Wide Web, defines how messages are formatted and transmitted, and the actions web servers and browsers must take in response to various commands.

HTTP operates over TCP connections. After a successful connection, the client transmits a request message to the server, which sends a reply message back.

By server design or by company security policy, proxy servers and firewalls frequently allow only HTTP-based traffic to pass through. You can establish a direct connection to a Sonic broker using HTTP tunneling as the protocol. However, because the HTTP tunneling protocol is significantly slower than TCP or SSL, this option is only recommended when TCP and SSL protocols are not available.

To emit messages to Sonic, JAR files supplied by Sonic are required. For more information, see Registering Sonic Client JAR Files.

Sonic Emitter Properties for TCP or HTTP

The following table lists and describes the Sonic emitter properties.

A Sonic message consists of a JMSQ header, body, and user-defined properties.

Property Name

Property Description

Destination (required)

The destination to which the message is delivered. The format of the destination property is queue@url. When emitting to a Sonic broker configured to listen over TCP, the format is queue@tcp://host:port. The default TCP port on which Sonic listens is 2506. This value is configured in the Sonic broker.ini file. To send a message to iWay.Reply hosted on a Sonic broker on your localhost, the URL is iWay.Reply@tcp://localhost:2506.

For HTTP, the URL is in the format queue@http://host:port. The default HTTP port on which Sonic listens is 2580.

To send a message to iWay.Reply hosted on a Sonic broker on your localhost, the URL is iWay.Reply@http://localhost:2580

Form of Output

TOPIC

Is for a TopicSession in the Publish and Subscribe domain.

QUEUE

Is for a QueueSession in the PTP domain.

User

A valid user ID defined to Sonic. You can use the Sonic Explorer Users option (under the message broker) to display users defined to Sonic. User ID is only required if Sonic security is enabled.

Password

A valid user ID and password combination defined to Sonic. You can use the Sonic Explorer Users option (under message broker) to display users defined to Sonic.

Send Persistently

Support for persistent and non-persistent messages. In the event of a network or system failure, the persistent option prevents messages from being lost.

In the event of a broker or Service Manager failure, non-persistent messages are volatile. Persistent messages are saved to disk.

Load Balance

Select true to enable the load balancing option on the Service Manager listener. With load balancing enabled, a connect request can be redirected to another broker within a Sonic cluster, if load balancing was not disabled on the broker side.

Duplicates Detect

You can configure the broker to commit transactions that index a universally unique, 64-character identifier (UUID) supplied by the sender. The sender then uses a commit method that commits the transacted messages, unless a previously sent transaction identifier is still unexpired. Otherwise, the method forces a rollback of the transaction.

For more information, see the INDEXED_TXN_ server properties in the Installation section of the Sonic MQ V5 Configuration and Administration Guide.

Set Reply Correlation Id

If set to a value, that value is used as the correlation ID of the response.

Duration

The maximum time that a document can remain in the retry pending queue.

Message Priority

The Sonic broker attempts to deliver messages with a higher priority ahead of messages with lower values. Priority is suggested to the JMSQ provider and can only order delivery of undelivered messages. JMSQ defines ten levels of message priority with values 0 through 9, where 0 is the lowest and 9 is the highest. Zero through four are considered normal settings and five through nine, expedited. The Message Priority field is the default priority value set in the JMSQ header.

Output Message Type

Select Bytes, Text, or Dynamic.

Preserve Undelivered

Preserves messages that are not retrieved to a dead letter queue.

Notify Undelivered

Notifies the broker administrator if undelivered are preserved.

Sequential

Determines the order in which the connection to the brokers is made when multiple brokers are listed. If this property is enabled, connection occurs sequentially. If disabled, connection occurs in a random manner.

Fault Tolerant

Determines whether the listener is connecting to the Sonic Broker as a fault tolerant client or not. The default value is false, that is, the listener is not connecting as a fault tolerant client.

This feature is supported only when the Sonic Broker is installed with a Sonic Fault Tolerance license code.

Reconnect Fault Timeout

Sets the interval, in seconds, of how long to wait before attempting to reconnect to the broker if the session is lost.

Initial Connect Timeout

Sets the interval, in seconds, of how long to wait before attempting to connect to the broker, or to another broker on the list, if connection fails when the listener is first started.

Sonic Emitter Configuration Example

You would like to read a file from its local file system and place it as a message on iWay.Reply queue defined at the Sonic broker, which listens on default Sonic MQ port on a machine named iwxfoc. The broker does not have security enabled.

To configure the components needed to support this scenario, you would need to do the following in Service Manager:

Note: For information on the steps required to accomplish these tasks, see the iWay Service Manager User’s Guide.

  • Copy the default file1 channel that is provided with the iSM installation and rename it to sonic_emit_channel.
  • Create an emitter, named sonic_emit, that will place a message obtained from a file listener on iWay.Reply queue defined at the Sonic broker on iwxfoc.

    The sonic_emit_channel will use the default file1 inlet, which is actually a file listener also named file1. In addition, it will use an outlet that contains the sonic_emit emitter.

  • Assign the emitter as an outlet of the channel.

After building and deploying channel you can see the file dropped into file1 pickup folder being placed on iWay.Reply queue on iwxfoc Sonic MQ broker.

Specify the emitter properties as follows:

  • Destination: iWay.Reply@tcp://iwxfoc:2506
  • Form of Output: Queue

    Leave default values for the remaining properties.

The following image shows the Sonic emitter configuration pane.

Configuring a Sonic Emitter Using SSL

Topics:

How to:

Reference:

SSL provides authentication and encryption techniques that require that the broker configure appropriate properties and certificates on a security-enabled database. Also, the client must have the appropriate libraries and properties to call its side of an SSL connection. A complete implementation sample is provided in the protocol section of the Sonic MQ V5 Configuration and Administration Guide. You must have SSL libraries installed from RSA, with the appropriate Sonic license or from supported third-parties, such as the Institute for Applied Information Processing and Communications (IAIK) or Java Secure Socket Extension (JSSE).

The manner in which you configure SSL for your application depends on whether you implement client authentication with a user name and password or with a client certificate. When the Sonic broker is configured with the SSL property SSL_CLIENT_AUTHENTICATION=FALSE in the broker.ini configuration file, no client certificate is required, and the client is authenticated with a user name and password. The client reads the user name and password, then passes them to the broker.

When the Sonic broker is configured with the SSL property SSL_CLIENT_AUTHENTICATION=TRUE, authentication is achieved through the exchange of Digital Certificates between Service Manager and the Sonic broker. In addition to this mutual authentication, Service Manager can present a user name and password to the broker at run time (optional).

JAR files supplied by Sonic are required to emit messages to a Sonic message queue using the SSL protocol. For more information, see Registering Sonic Client JAR Files.

Reference: JVM Options for SSL With Certificates

The following table lists and describes the properties required to configure the appropriate environment for communication to Sonic using SSL with certificates. For instructions on configuring JVM options, see Setting Java System Properties for Sonic SSL.

Property

Description

SSL_CA_CERTIFICATES_DIR
SSL_CA_CERTIFICATES_DIR={certs/ca|path}
SSL_CA_CERTIFICATES_DIR_n={certs/ca|path}

Specifies the location of the Certificate Authority (CA) certificate. Path must be fully qualified or relative to the Service Manager installation directory.

The default directory is certs/ca.

SSL_CERTIFICATE_CHAIN
SSL_CERTIFICATE_CHAIN={certs/server.p7c|path}
SSL_CERTIFICATE_CHAIN_n={certs/server.p7c|path}

Specifies the location of the file containing the client keystore certificate chain for SSL. Path must be fully qualified or relative to the Service Manager installation directory.

The default directory is certs/server.p7c.

SSL_CERTIFICATE_CHAIN_FORM
SSL_CERTIFICATE_CHAIN_FORM={LIST|PKCS12|PKCS7}
SSL_CERTIFICATE_CHAIN_FORM_n={LIST|PKCS12|PKCS7}

Specifies the format of the file containing the certificate chain.

PKCS7 is the default value, a comma-delimited list of path names that point to files containing each individual certificate in the chain.

SSL_PRIVATE_KEY
SSL_PRIVATE_KEY={serverKey.pkcs8|path}
SSL_PRIVATE_KEY_n={serverKey.pkcs8|path}

Provides the location of the file containing the client encrypted private key for SSL. Path must be fully qualified or relative to the Service Manager installation directory.

The default value is serverKey.pkcs8.

SSL_PRIVATE_KEY_PASSWORD
SSL_PRIVATE_KEY_PASSWORD={password|password}
SSL_PRIVATE_KEY_PASSWORD_n={password|password}

Provides the password that encrypts the private key for SSL.

The default value is password.

Sonic Emitter Properties for SSL With Certificate

The following table lists and describes the Sonic emitter properties for SSL with certificate.

A Sonic message consists of a JMSQ header, body, and user-defined properties.

HTTPS is similar to HTTP except that data is transmitted over a Secure Socket Layer (SSL) instead of a normal socket connection. Web servers listen for HTTP requests on one port while another listens for HTTPS requests.

Property Name

Property Description

Destination (required)

The destination to which the message is delivered. The format of the destination property is queue@url. When emitting to Sonic queues over SSL, the format is queue@ssl://host:port. The SSL port is configured in the Sonic broker.ini file. To send a message to iWay.Reply hosted on a Sonic broker on your localhost, the URL is iWay.Reply@ssl://localhost:2507.

Form of Output

TOPIC

Is for a TopicSession in the Publish and Subscribe domain.

QUEUE

Is for a QueueSession in the PTP domain.

User

You must specify the common name AUTHENTICATED from the certificate as the user name. The password is not required because you authenticate the client using the client certificate in this example. When Service Manager emits to a Sonic queue it can specify a user name and password to the broker (optional). The broker authenticates this user name and password if they are specified, but otherwise uses the information in the client certificate to identify the user.

Password

This property is optional and is only required if a user ID is specified.

Send Persistently

The support for persistent and non-persistent messages. In the event of a network or system failure, the persistent option prevents messages from being lost.

In the event of a broker or Service Manager failure, non-persistent messages are volatile. Persistent messages are saved to disk.

Load Balance

If set to true, then this enables the load balancing option on the Service Manager listener. With load balancing enabled, a connect request can be redirected to another broker within a Sonic cluster, if load balancing was not disabled on the broker side.

Duplicates Detect

You can configure the broker to commit transactions that index a universally unique, 64-character identifier (UUID) supplied by the sender. The sender then uses a commit method that commits the transacted messages, unless a previously sent transaction identifier is still unexpired. Otherwise, the method forces a rollback of the transaction.

For more information, see the INDEXED_TXN_ server properties in the Installation section of the Sonic MQ V5 Configuration and Administration Guide.

Set Reply Correlation Id

If set to a value, that value is used as the correlation ID of the response.

Duration

The maximum time that a document can remain in the retry pending queue.

Message Priority

The Sonic broker attempts to deliver messages with a higher priority ahead of messages with lower values. Priority is suggested to the JMSQ provider and can only order delivery of undelivered messages. JMSQ defines ten levels of message priority with values 0 through 9, where 0 is the lowest and 9 is the highest. Zero through four are considered normal settings and five through nine, expedited. The Message Priority field is the default priority value set in the JMSQ header.

Output Message Type

Select Bytes, Text, or Dynamic.

Preserve Undelivered

Preserves messages that are not retrieved to a dead letter queue.

Notify Undelivered

Notifies the broker administrator if undelivered are preserved.

Sequential

Determines the order in which the connection to the brokers is made when multiple brokers are listed. If this property is enabled, connection occurs sequentially. If disabled, connection occurs in a random manner.

Fault Tolerant

Determines whether the listener is connecting to the Sonic Broker as a fault tolerant client or not. The default value is false, that is, the listener is not connecting as a fault tolerant client.

This feature is supported only when the Sonic Broker is installed with a Sonic Fault Tolerance license code.

Reconnect Fault Timeout

Sets the interval, in seconds, of how long to wait before attempting to reconnect to the broker if the session is lost.

Initial Connect Timeout

Sets the interval, in seconds, of how long to wait before attempting to connect to the broker, or to another broker on the list, if connection fails when the listener is first started.

Procedure: How to Configure Sonic Emitter Properties Using HTTPS

To configure Sonic emitter properties using HTTPS:

  1. Refer to the values defined in Sonic Emitter Properties for SSL With Certificate (user ID or certificate, depending on how the broker is configured) when creating the emitter.
  2. Modify the destination address to specify an HTTPS URL.

    The format of the destination property is queue@url. When emitting to Sonic queues over HTTPS, the format is queue@https://host:port. The HTTP port is configured in the Sonic broker.ini file. To send a message to iWay.Reply hosted on a Sonic broker on your localhost, the URL is iWay.Reply@https://localhost:2507.

Sonic Message Queuing Troubleshooting

When using a Sonic listener, if the system cannot find the queue specified, you receive the following message:

Cannot emit reply to .XDSonicEmit<no dead letter path>: XD[FAIL] in emit 
() error create queue.

Using Sonic Explorer, verify that the queue exists, that the name is spelled correctly, and that the name is in the correct case, as the Sonic listener is case-sensitive.