Message properties are similar to message headers apart from the fact that message properties are optional whereas message headers are always available. Message properties provide a way of adding application-specific header values to the messages. Message properties are also useful for JMS clients to filter out the messages they receive using message selectors. Message selectors are explained in detail later in this chapter and a reference is provided in Appendix B. Message properties can be of any of the Java primitives or Java string type.
JMS defines three types of properties:
Application specific properties
Application specific properties can be set by JMS clients for implementing application specific logic.
Standard properties
Standard properties define a set of standard properties, and property names starting with the string ‘JMSX' are reserved for standard properties. These properties are almost the same as the header fields apart from the fact that these properties are optional. As we have already seen in the last chapter you can use the connection metadata to get a list of standard properties supported by the provider. Standard properties are explained in detail later.
Provider properties
Provider properties are normally used for integrating JMS clients with the provider's non-JMS clients. Property names starting with the string JMS_vendor_name are reserved for provider properties where vendor_name is specific to the provider.
The interface javax.jms.Message defines a set of methods for setting and getting properties of different types as well as methods for iterating through the property names and clearing the set properties.
All the getXXXProperty() methods defined by javax.jms.Message return a property as a value, only if the value can be converted into the appropriate primitive:
Method | Description |
---|---|
boolean getBooleanProperty (String name) throws JMSException, MessageFormatException | Returns the property whose name is specified by the argument name, as a boolean |
byte getByteProperty (String name) throws JMSException, MessageFormatException | Returns the property whose name is specified by the argument name, as a byte |
double getDoubleProperty (String name) throws JMSException, MessageFormatException | Returns the property whose name is specified by the argument name, as a double |
float getFloatProperty (String name) throws JMSException, MessageFormatException | Returns the property whose name is specified by the argument name, as a float |
int getIntProperty (String name) throws JMSException, MessageFormatException | Returns the property whose name is specified by the argument name, as an integer |
long getLongProperty (String name) throws JMSException, MessageFormatException | Returns the property whose name is specified by the argument name, as a long |
short getShortProperty (String name) throws JMSException, MessageFormatException | Returns the property whose name is specified by the argument name, as a short |
String getStringProperty (String name) throws JMSException, MessageFormatException | Returns the property whose name is specified by the argument name, as a String |
Object getObjectProperty (String name) throws JMSException, MessageFormatException | The only objects that can be set are of types Java primitive wrapper classes like java.lang.Integer, java.lang.Short, etc |
These methods may throw a MessageFormatException if the value is not convertible to the appropriate Java primitive or a JMSException if the method call fails due to some internal error.
For each getXXXProperty() method in the table above, there is a corresponding setXXXProperty() method. Below is a selection, and those that are missing can be extrapolated from the methods already described:
Method | Description |
---|---|
void setBooleanProperty (String name, boolean value) throws JMSException, MessageNotWritableException | Sets a Boolean property by the name specified by the argument name and value specified by the argument value |
void setByteProperty (String name, byte value) throws JMSException, MessageNotWritableException | Sets a byte property by the name specified by the argument name and value specified by the argument value |
void setDoubleProperty (String name, double value) throws JMSException, MessageNotWritableException | Sets a double property by the name specified by the argument name and value specified by the argument value |
These methods may throw a MessageNotWritableException if the property is read-only. When a client receives a message, its properties are in read-only mode. A JMSException is thrown if the method call fails due to some internal error.
Method | Description |
---|---|
public void clearProperties() throws JMSException | Clears all the properties set for the message |
public Enumeration getPropertyNames (String name) throws JMSException | Returns an enumeration of available property names |
public boolean propertyExists (String name) throws JMSException | Checks whether the message contains the specified property |
All these methods throw JMSException if they fail to return due to some internal error.