Message Properties

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.

The getXXXProperty() Methods

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.

The setXXXProperty() Methods

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.

Miscellaneous Methods

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.



Professional JMS
Professional JMS
ISBN: 1861004931
EAN: 2147483647
Year: 2000
Pages: 154

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net