JMSAppender

Send messages to a message queue by using the Java Message Service (JMS) interfaces.

Valid in:

XML configuration

Table of Contents

Syntax

</layout>

</appender>

Syntax Description

class="JMSAppender" name="appender-name"

specifies the user-assigned name for this instance of JMSAppender.

Default	None
Requirement	These element attributes are required.

name="ClassPath" value="class-path"

specifies the path for classes that are included in this appender configuration.

Default	None
Requirement	This parameter is not required.
Interaction	When JMSAppender searches for classes to load, the CLASSPATH environment variable takes precedence over the ClassPath parameter, and the ClassPath parameter takes precedence over the JARs that are provided by SAS.

name="MaxBufferedEvents" value="maximum-buffered-events"

specifies the maximum number of events that can be waiting to be sent to the message queue. JMSAppender stores events in an internal list that is bounded by the number that is specified in this parameter. A worker thread removes events from the list and sends them to the message queue. In the meantime, SAS can continue processing without waiting for the JMS provider. When the list contains the specified number of events, the appender blocks further events until the list can accommodate them.

Tip

A high number favors performance over reliability. A catastrophic error could cause events in the list to be lost. A high number also increases the memory usage of the appender.

Tip

A low number favors reliability and memory usage over performance.

Default	Infinite
Requirement	This parameter is not required.

name="Persistent" value="TRUE | FALSE"

specifies whether the persistent delivery mode is to be used to send messages to the queue.

TRUE: specifies the use of the persistent delivery mode to send messages to the queue. This mode instructs the JMS provider to store messages after they are sent to ensure that they are not lost in transit if a provider failure occurs.

FALSE: specifies the use of the nonpersistent delivery mode to send messages to the queue. If you specify this mode, the JMS provider is not required to store messages or otherwise guarantee that they will be preserved if the provider fails.

Tip

The nonpersistent delivery mode can improve performance and reduce storage overhead on the message queue server. However, you should use this mode only if it is acceptable for messages to be missed.

Default	TRUE
Requirement	This parameter is not required.

name="Factory" value="factory"

specifies the name of a connection factory that is administered through the Java Naming and Directory Interface (JNDI) and that is to be used to connect to the message queue.

Default	None
Requirement	This parameter is required.

name="Queue" value="queue-name"

specifies the name of the JNDI-administered queue to which messages are to be sent.

Alias	name="Destination"
Default	None
Requirement	This parameter is required.

name="Username" value="user-name"

specifies the user name that is to be used to connect to the message queue.

Default	If a user name is not specified, then the user name of the process owner is used to connect to the message queue.
Requirement	This parameter is not required.

name="SASEncodedPassword" value="SAS-encoded-password"

specifies the password that is to be used with user-name to connect to the message queue. You can specify a plain-text password or a password that has been encoded by using sas001, sas002, or sas003 encoding. If the password is encoded, JMSAppender converts it to plain text before connecting to the queue.

Tip

For information about how to obtain the encoded password, see PWENCODE Procedure in Base SAS Procedures Guide.

Default	None.
Requirement	This parameter is not required.

name="Prioritize" value="TRUE | FALSE"

specifies whether messages are to be prioritized based on the level of the event.

TRUE

sets the message priority based on the level of the event, as follows:

Level	Assigned Message Priority
Trace	2
Debug	3
Info	4
Warn	5
Error	6
Fatal	7

Some message queueing systems, such as IBM WebSphere MQ, might return events with a higher priority to a caller before events with a lower priority, regardless of when the events were added to the queue.

FALSE: sets the message priority to 4 for all events.

Default	FALSE
Requirement	This parameter is not required.
Interaction	If both the Prioritize parameter and the Priority parameter are specified, then the Priority parameter takes precedence.

name="Priority" value="priority"

specifies an integer that is to be assigned as the message priority for each message that is written to the queue.

Default	None. If this parameter is not specified, then the Prioritize parameter determines how priorities are assigned.
Range	0 – 9
Requirement	This parameter is not required.
Interaction	If both the Prioritize parameter and the Priority parameter are specified, then the Priority parameter takes precedence.

name="TimeToLive" value="time-to-live"

specifies the message time-to-live in milliseconds. When a message is sent, JMS computes the message’s expiration time by adding the time-to-live value to the current Greenwich Mean Time. If time-to-live is specified as zero, the message does not expire.

Default	0
Requirement	This parameter is not required.

name="ConversionPattern" value="conversion-pattern"

specifies how the log message is written to the queue.

Default	None. If a conversion pattern is not specified, then the log event produces an empty string.
Requirement	This parameter is not required.
See	Pattern Layouts

Details

If additional JNDI parameters (for example, java.naming.factory.initial or java.naming.provider.url) are needed by your messaging provider, you can include them in the appender configuration. Any parameters that JMSAppender does not recognize are passed to the javax.naming.InitialContext constructor in the JNDI initial context as part of the Hashmap parameter.

Note: You can also use the JREOPTIONS system option to pass JNDI parameters directly to SAS. See:

JREOPTIONS System Option: Windows in SAS Companion for Windows
JREOPTIONS System Option: UNIX in SAS Companion for UNIX Environments
JREOPTIONS= System Option: z/OS in SAS Companion for z/OS

Depending on the provider, you might be able to use other methods to specify these parameters.

Tip

By default, JMSAppender uses the Java class com.sas.logging.appenders.JMSAppender. If you want events to be handled by a custom Java class, use JavaAppender.

Tip

When the Java Runtime Environment attempts to append messages to a message queue, additional events might be generated. These events are captured by the App.tkjni logger and are ignored by JMSAppender. If you want to log these events, specify a different appender (for example, FileAppender) for the App.tkjni logger in your logging configuration.

Examples

Example 1: Sending Events to IBM WebSphere MQ

The following instance of JMSAppender writes messages to a queue called TEST.Q that is managed by IBM WebSphere MQ. The JNDI objects are located in the folder C:\JNDI on the local machine.

<appender name="java" class="JMSAppender">
   <!-- Common properties for all Java Appender configurations -->
 
   <!-- Properties specific to the Default JMSAppender implementation -->
   <param name="persistent" value="true"/>
 
   <!-- This is an example configuration for WebSphere MQ. -->
   <!-- This example assumes that the Websphere MQ classes -->
   <!-- are in your classpath environment variable.        -->
   <param name="java.naming.factory.initial"
       value="com.sun.jndi.fscontext.RefFSContextFactory"/>
   <param name="java.naming.provider.url" value="file:/c:/JNDI"/>
   <param name="factory" value="TEST.FACTORY"/>
   <param name="destination" value="TEST.Q"/>
 
   <layout>
      <param name="ConversionPattern" value="%d - %c -%m"/>
   </layout>
</appender>

Example 2: Sending Events to Apache ActiveMQ

The following instance of JMSAppender writes messages to a queue called TEST.Q that is managed by Apache ActiveMQ:

<appender class="JMSAppender" name="java">
   <!-- Common properties for all Java Appender configurations -->
   <param name="classpath" value="C:\Program
       Files\apache-activemq-5.2.0\activemq-all-5.2.0.jar"/>
 
   <!-- Properties specific to the Default JMSAppender implementation -->
   <param name="persistent" value="true"/>
 
   <!-- Active MQ example configuration -->
   <param name="java.naming.factory.initial"
       value="org.apache.activemq.jndi.ActiveMQInitialContextFactory"/>
   <param name="java.naming.provider.url" value="tcp://localhost:61616"/>
   <param name="factory" value="ConnectionFactory"/>
   <param name="destination" value="TEST.Q"/>
   <!-- An additional property is required only for Active MQ to map
        the queue name into the JNDI namespace. Use the form
        <param name="queue.[jndiName]" value="[physicalName]"/>.
        See http://activemq.apache.org/jndi-support.html. -->
   <param name="queue.TEST.Q" value="TEST.Q"/>
 
   <layout>
      <param name="ConversionPattern" value="%d - %c - %m"/>
   </layout>
</appender>