Message selectors

A message contains a built-in facility to support application-defined property values. In effect, this provides a mechanism to add application-specific header fields to a message. Properties allow an application, via message selectors, to have a JMS provider select or filter messages on its behalf, using application-specific criteria. Application-defined properties must obey the following rules:
  • Property names must obey the rules for a message selector identifier.
  • Property values can be boolean, byte, short, int, long, float, double, and String.
  • The JMSX and JMS_ name prefixes are reserved.
Property values are set before sending a message. When a client receives a message, the message properties are read-only. If a client attempts to set properties at this point, a MessageNotWriteableException is thrown. If clearProperties() is called, the properties can then be both read from, and written to.

A property value may duplicate a value in a message's body, or it may not. JMS does not define a policy for what should or should not be made into a property. However, for best performance, applications should only use message properties when they need to customize a message's header. The primary reason for doing this is to support customized message selection. A JMS message selector allows a client to specify the messages that it is interested in by using the message header. Only messages whose headers match the selector are delivered. Message selectors cannot reference message body values. A message selector matches a message when the selector evaluates to true when the message's header field and property values are substituted for their corresponding identifiers in the selector.

A message selector is a String, which can contain:
Literals
  • A string literal is enclosed in single quotes. A doubled single quote represents a single quote. Examples are 'literal' and 'literal''s'. Like Java™ string literals, these use the Unicode character encoding.
  • An exact numeric literal is a numeric value without a decimal point, such as 57, -957, +62. Numbers in the range of Java long are supported.
  • An approximate numeric literal is a numeric value in scientific notation, such as 7E3 or -57.9E2, or a numeric value with a decimal, such as 7., -95.7, or +6.2. Numbers in the range of Java double are supported. Note that rounding errors may affect the operation of message selectors including approximate numeric literals.
  • The boolean literals TRUE and FALSE.
Identifiers
  • An identifier is an unlimited length sequence of Java letters and Java digits, the first of which must be a Java letter. A letter is any character for which the method Character.isJavaLetter returns true. This includes "_" and "$". A letter or digit is any character for which the method Character.isJavaLetterOrDigit returns true.
  • Identifiers cannot be the names NULL, TRUE, or FALSE.
  • Identifiers cannot be NOT, AND, OR, BETWEEN, LIKE, IN, and IS.
  • Identifiers are either header field references or property references.
  • Identifiers are case-sensitive.
  • Message header field references are restricted to:
    • JMSDeliveryMode
    • JMSPriority
    • JMSMessageID
    • JMSTimestamp
    • JMSCorrelationID
    • JMSType
    JMSMessageID, JMSTimestamp, JMSCorrelationID, and JMSType values may be null, and if so, are treated as a NULL value.
  • Any name beginning with "JMSX" is a JMS-defined property name
  • Any name beginning with "JMS_" is a provider-specific property name
  • Any name that does not begin with "JMS" is an application-specific property name
  • If there is a reference to a property that does not exist in a message, its value is NULL. If it does exist, its value is the corresponding property value.
White space
This is the same as is defined for Java, space, horizontal tab, form feed, and line terminator.
Logical operators
Currently supports AND only.
Comparison operators
  • Only equals ('=') is currently supported.
  • Only values of the same type can be compared.
  • If there is an attempt to compare different types, the selector is always false.
  • Two strings are equal if they contain the same sequence of characters.
  • The IS NULL comparison operator tests for a null header field value, or a missing property value. The IS NOT NULL comparison operator is not supported.
Note that Arithmetic operators are not currently supported.

The following message selector selects messages with a message type of car and a colour of blue: "JMSType ='car 'AND colour ='blue'"

When selecting Header fields MQe will interpret exact numeric literals so that they match the type of the field in question, that is a selector testing the JMSPriority or JMSDeliveryMode Header fields will interpret an exact numeric literal as an int, whereas a selector testing JMSExpiration or JMSTimestamp will interpret an exact numeric literal as a long. However, when selecting message properties MQe will always interpret an exact numeric literal as a long and an approximate numeric literal as a double. Application specific properties intended to be used for message selection should therefore be set using the setLongProperty and setDoubleProperty methods respectively.


Terms of use | WebSphere software

(c) Copyright IBM Corporation 2004, 2005. All rights reserved.