org.huihoo.jfox.ms.jms.message
Class MessageProperties

java.lang.Object
  org.huihoo.jfox.ms.jms.message.MessageProperties

public class MessageProperties

extends java.lang.Object

Built-in facility for supporting property values.

Message properties support the following conversion table. The marked cases must be supported. The unmarked cases must throw a JMSException. The String-to-primitive conversions may throw a runtime exception if the primitive's valueOf method does not accept the String as a valid representation of the primitive.

A value written as the row type can be read as the column type.

 |        | boolean byte short int long float double String 
 |----------------------------------------------------------
 |boolean |    X                                       X
 |byte    |          X     X    X   X                  X 
 |short   |                X    X   X                  X 
 |int     |                     X   X                  X 
 |long    |                         X                  X 
 |float   |                               X     X      X 
 |double  |                                     X      X 
 |String  |    X     X     X    X   X     X     X      X 
 |----------------------------------------------------------
 

In addition to the type-specific set/get methods for properties, JMS provides the setObjectProperty and getObjectProperty methods. These support the same set of property types using the objectified primitive values. Their purpose is to allow the decision of property type to made at execution time rather than at compile time. They support the same property value conversions.

The setObjectProperty method accepts values of class Boolean, Byte, Short, Integer, Long, Float, Double, and String. An attempt to use any other class must throw a JMSException.

The getObjectProperty method only returns values of class Boolean, Byte, Short, Integer, Long, Float, Double, and String.

The order of property values is not defined. To iterate through a message's property values, use getPropertyNames to retrieve a property name enumeration and then use the various property get methods to retrieve their values.

A message's properties are deleted by the clearProperties method. This leaves the message with an empty set of properties.

Getting a property value for a name which has not been set returns a null value. Only the getStringProperty and getObjectProperty methods can return a null value. Attempting to read a null value as a primitive type must be treated as calling the primitive's corresponding valueOf(String) conversion method with a null value.

The JMS API reserves the JMSX property name prefix for JMS defined properties. The full set of these properties is defined in the Java Message Service specification. New JMS defined properties may be added in later versions of the JMS API. Support for these properties is optional. The String[] ConnectionMetaData.getJMSXPropertyNames method returns the names of the JMSX properties supported by a connection.

JMSX properties may be referenced in message selectors whether or not they are supported by a connection. If they are not present in a message, they are treated like any other absent property.

JMSX properties defined in the specification as "set by provider on send" are available to both the producer and the consumers of the message. JMSX properties defined in the specification as "set by provider on receive" are available only to the consumers.

JMSXGroupID and JMSXGroupSeq are standard properties that clients should use if they want to group messages. All providers must support them. Unless specifically noted, the values and semantics of the JMSX properties are undefined.

The JMS API reserves the JMS_vendor_name property name prefix for provider-specific properties. Each provider defines its own value for vendor_name. This is the mechanism a JMS provider uses to make its special per-message services available to a JMS client.

The purpose of provider-specific properties is to provide special features needed to integrate JMS clients with provider-native clients in a single JMS application. They should not be used for messaging between JMS clients.

Version:

Revision: 1.1 Date: 2002-12-01 21:57:33

Author:

Peter.Cheng

Constructor Summary

MessageProperties()

Method Summary

void	clearProperties() Clear any values contained in the properties section of the message.
boolean	getBooleanProperty(java.lang.String name) Returns the value of the boolean property with the specified name.
byte	getByteProperty(java.lang.String name) Returns the value of the byte property with the specified name.
double	getDoubleProperty(java.lang.String name) Returns the value of the double property with the specified name.
float	getFloatProperty(java.lang.String name) Returns the value of the float property with the specified name.
int	getIntProperty(java.lang.String name) Returns the value of the int property with the specified name.
long	getLongProperty(java.lang.String name) Returns the value of the long property with the specified name.
java.lang.Object	getObjectProperty(java.lang.String name) Returns the value of the Java object property with the specified name.
java.util.Enumeration	getPropertyNames() Returns an Enumeration of all the property names.
short	getShortProperty(java.lang.String name) Returns the value of the short property with the specified name.
java.lang.String	getStringProperty(java.lang.String name) Returns the value of the String property with the specified name.
boolean	propertyExists(java.lang.String name) Determine if the specified property exists.
void	setBooleanProperty(java.lang.String name, boolean value) Sets a boolean property value with the specified name into the message.
void	setByteProperty(java.lang.String name, byte value) Sets a byte property value with the specified name into the message.
void	setDoubleProperty(java.lang.String name, double value) Sets a double property value with the specified name into the message.
void	setFloatProperty(java.lang.String name, float value) Sets a float property value with the specified name into the message.
void	setIntProperty(java.lang.String name, int value) Sets an int property value with the specified name into the message.
void	setLongProperty(java.lang.String name, long value) Sets a long property value with the specified name into the message.
void	setObjectProperty(java.lang.String name, java.lang.Object value) Sets a Java object property value with the specified name into the message.
void	setShortProperty(java.lang.String name, short value) Sets a short property value with the specified name into the message.
void	setStringProperty(java.lang.String name, java.lang.String value) Sets a String property value with the specified name into the message.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MessageProperties

public MessageProperties()

Method Detail

setBooleanProperty

public void setBooleanProperty(java.lang.String name,
                               boolean value)
                        throws javax.jms.JMSException

Sets a boolean property value with the specified name into the message.

Parameters:

name - the name of the boolean property

value - the boolean property value to set

Throws:

javax.jms.JMSException - if the JMS provider fails to set the property due to some internal error.

getBooleanProperty

public boolean getBooleanProperty(java.lang.String name)
                           throws javax.jms.JMSException

Returns the value of the boolean property with the specified name.

Parameters:

name - the name of the boolean property

Returns:

the boolean property value for the specified name

Throws:

javax.jms.JMSException - if the JMS provider fails to get the property value due to some internal error.

javax.jms.MessageFormatException - if this type conversion is invalid.

setByteProperty

public void setByteProperty(java.lang.String name,
                            byte value)
                     throws javax.jms.JMSException

Sets a byte property value with the specified name into the message.

Parameters:

name - the name of the byte property

value - the byte property value to set

Throws:

javax.jms.JMSException - if the JMS provider fails to set the property due to some internal error.

getByteProperty

public byte getByteProperty(java.lang.String name)
                     throws javax.jms.JMSException

Returns the value of the byte property with the specified name.

Parameters:

name - the name of the byte property

Returns:

the byte property value for the specified name

Throws:

javax.jms.JMSException - if the JMS provider fails to get the property value due to some internal error.

javax.jms.MessageFormatException - if this type conversion is invalid.

setShortProperty

public void setShortProperty(java.lang.String name,
                             short value)
                      throws javax.jms.JMSException

Sets a short property value with the specified name into the message.

Parameters:

name - the name of the short property

value - the short property value to set

Throws:

javax.jms.JMSException - if the JMS provider fails to set the property due to some internal error.

getShortProperty

public short getShortProperty(java.lang.String name)
                       throws javax.jms.JMSException

Returns the value of the short property with the specified name.

Parameters:

name - the name of the short property

Returns:

the short property value for the specified name

Throws:

javax.jms.JMSException - if the JMS provider fails to get the property value due to some internal error.

javax.jms.MessageFormatException - if this type conversion is invalid.

setIntProperty

public void setIntProperty(java.lang.String name,
                           int value)
                    throws javax.jms.JMSException

Sets an int property value with the specified name into the message.

Parameters:

name - the name of the int property

value - the int property value to set

Throws:

javax.jms.JMSException - if the JMS provider fails to set the property due to some internal error.

getIntProperty

public int getIntProperty(java.lang.String name)
                   throws javax.jms.JMSException

Returns the value of the int property with the specified name.

Parameters:

name - the name of the int property

Returns:

the int property value for the specified name

Throws:

javax.jms.JMSException - if the JMS provider fails to get the property value due to some internal error.

javax.jms.MessageFormatException - if this type conversion is invalid.

setLongProperty

public void setLongProperty(java.lang.String name,
                            long value)
                     throws javax.jms.JMSException

Sets a long property value with the specified name into the message.

Parameters:

name - the name of the long property

value - the long property value to set

Throws:

javax.jms.JMSException - if the JMS provider fails to set the property due to some internal error.

getLongProperty

public long getLongProperty(java.lang.String name)
                     throws javax.jms.JMSException

Returns the value of the long property with the specified name.

Parameters:

name - the name of the long property

Returns:

the long property value for the specified name

Throws:

javax.jms.JMSException - if the JMS provider fails to get the property value due to some internal error.

javax.jms.MessageFormatException - if this type conversion is invalid.

setFloatProperty

public void setFloatProperty(java.lang.String name,
                             float value)
                      throws javax.jms.JMSException

Sets a float property value with the specified name into the message.

Parameters:

name - the name of the float property

value - the float property value to set

Throws:

javax.jms.JMSException - if the JMS provider fails to set the property due to some internal error.

getFloatProperty

public float getFloatProperty(java.lang.String name)
                       throws javax.jms.JMSException

Returns the value of the float property with the specified name.

Parameters:

name - the name of the float property

Returns:

the float property value for the specified name

Throws:

javax.jms.JMSException - if the JMS provider fails to get the property value due to some internal error.

javax.jms.MessageFormatException - if this type conversion is invalid.

setDoubleProperty

public void setDoubleProperty(java.lang.String name,
                              double value)
                       throws javax.jms.JMSException

Sets a double property value with the specified name into the message.

Parameters:

name - the name of the double property

value - the double property value to set

Throws:

javax.jms.JMSException - if the JMS provider fails to set the property due to some internal error.

getDoubleProperty

public double getDoubleProperty(java.lang.String name)
                         throws javax.jms.JMSException

Returns the value of the double property with the specified name.

Parameters:

name - the name of the double property

Returns:

the double property value for the specified name

Throws:

javax.jms.JMSException - if the JMS provider fails to get the property value due to some internal error.

javax.jms.MessageFormatException - if this type conversion is invalid.

setStringProperty

public void setStringProperty(java.lang.String name,
                              java.lang.String value)
                       throws javax.jms.JMSException

Sets a String property value with the specified name into the message.

Parameters:

name - the name of the String property

value - the String property value to set

Throws:

javax.jms.JMSException - if the JMS provider fails to set the property due to some internal error.

getStringProperty

public java.lang.String getStringProperty(java.lang.String name)
                                   throws javax.jms.JMSException

Returns the value of the String property with the specified name.

Parameters:

name - the name of the String property

Returns:

the String property value for the specified name; if there is no property by this name, a null value is returned

Throws:

javax.jms.JMSException - if the JMS provider fails to get the property value due to some internal error.

javax.jms.MessageFormatException - if this type conversion is invalid.

setObjectProperty

public void setObjectProperty(java.lang.String name,
                              java.lang.Object value)
                       throws javax.jms.JMSException

Sets a Java object property value with the specified name into the message.

Note that this method works only for the objectified primitive object types (Integer, Double, Long ...) and String objects.

Parameters:

name - the name of the Java object property

value - the Java object property value to set

Throws:

javax.jms.JMSException - if the JMS provider fails to set the property due to some internal error.

javax.jms.MessageFormatException - if the object is invalid

getObjectProperty

public java.lang.Object getObjectProperty(java.lang.String name)
                                   throws javax.jms.JMSException

Returns the value of the Java object property with the specified name.

This method can be used to return, in objectified format, an object that has been stored as a property in the message with the equivalent setObjectProperty method call, or its equivalent primitive settypeProperty method.

Parameters:

name - the name of the Java object property

Returns:

the Java object property value with the specified name, in objectified format (for example, if the property was set as an int, an Integer is returned); if there is no property by this name, a null value is returned

Throws:

javax.jms.JMSException - if the JMS provider fails to get the property value due to some internal error.

clearProperties

public void clearProperties()

Clear any values contained in the properties section of the message.

See Also:

Message

propertyExists

public boolean propertyExists(java.lang.String name)

Determine if the specified property exists.

See Also:

Message

getPropertyNames

public java.util.Enumeration getPropertyNames()

Returns an Enumeration of all the property names.

Returns:

an enumeration of all the names of property values