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.