Interface ImaMessage
-
public interface ImaMessage
The ImaMessage interface defines a message within the plug-in and represents the message as known internally in the MessageSight server. A message has some header fields, a set of properties, and a body.
-
-
Field Summary
Fields Modifier and Type Field Description static String
COPYRIGHT
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
acknowledge(int rc)
Acknowledge a received message.void
acknowledge(int rc, ImaTransaction transaction)
Acknowledge a received message.ImaMessage
addProperties(Map<String,Object> props)
Add to the properties of a message.ImaMessage
clearProperties()
Clear all user message properties.byte[]
getBodyBytes()
Get the body of the message as byte array.Map<String,Object>
getBodyMap()
Get the body of the message as a Map.String
getBodyText()
Get the body of the message as a String.boolean
getBooleanProperty(String name, boolean default_value)
Get a message property as a boolean.String
getDestination()
Get the name of the destination the message was published to.ImaDestinationType
getDestinationType()
Get the type of the destination the message was published to.int
getIntPropery(String name, int default_value)
Get a message property as an integer.ImaMessageType
getMessageType()
Get the type of the message body.boolean
getPersistence()
Get the persistence of the message.Map<String,Object>
getProperties()
Get a read-only map of the user message properties.Object
getProperty(String name)
Get a message property as an Object.ImaReliability
getReliability()
Get the reliability of the message.boolean
getRetain()
Get the retain value of the message.boolean
getRetainAsPublished()
Get the retained value as published.String
getStringProperty(String name)
Get a message property as a String.Object
getUserData()
Get a user object associated with this message.boolean
propertyExists(String name)
Return whether a property exists.ImaMessage
setBodyBytes(byte[] body)
Set the body as a byte array.ImaMessage
setBodyMap(Map<String,Object> body)
Set the body as a Map.ImaMessage
setBodyText(String body)
Set the body as a String.ImaMessage
setMessageType(ImaMessageType msgtype)
Set the message type.ImaMessage
setPersistent(boolean persist)
Set the persistence of the message.ImaMessage
setReliability(ImaReliability reliability)
Set the reliability of the message.ImaMessage
setRetain(boolean retain)
Set the retain value of the message.void
setUserData(Object userdata)
Set a user object associated with this message.
-
-
-
Field Detail
-
COPYRIGHT
static final String COPYRIGHT
- See Also:
- Constant Field Values
-
-
Method Detail
-
addProperties
ImaMessage addProperties(Map<String,Object> props)
Add to the properties of a message.- Parameters:
props
- The properties to add- Returns:
- The message
-
clearProperties
ImaMessage clearProperties()
Clear all user message properties.- Returns:
- The message
-
getBodyBytes
byte[] getBodyBytes()
Get the body of the message as byte array.- Returns:
- A byte array representing the message body or null to indicate there is no body
-
getBodyMap
Map<String,Object> getBodyMap()
Get the body of the message as a Map.- Returns:
- A Map containing the body of the message, or null to indicate there is no body.
- Throws:
ImaPluginException
- if the body cannot be converted to a map.
-
getBodyText
String getBodyText()
Get the body of the message as a String. The body must contain only valid UTF-8 to be converted to a String.- Returns:
- A String containing the body of the message, or null to indicate there is no body.
- Throws:
ImaPlubinException
- if the body cannot be converted to a String.
-
getBooleanProperty
boolean getBooleanProperty(String name, boolean default_value)
Get a message property as a boolean.- Parameters:
name
- The name of the propertydefault_value
- The default if the property is missing or not a boolean- Returns:
- The value of the property as a boolean, or the defaulf_value if the property is missing or cannot be converted to a boolean.
-
getDestination
String getDestination()
Get the name of the destination the message was published to.This is guaranteed to exist and be at least one character long. This is almost always the destination to which the message was originally published, but this depends on information provided by the originator.
- Returns:
- The name of the destination.
-
getDestinationType
ImaDestinationType getDestinationType()
Get the type of the destination the message was published to.- Returns:
- The type of the destination which is either a topic or a queue.
-
getMessageType
ImaMessageType getMessageType()
Get the type of the message body.This is the indication from the originator of the message of the physical format of the message body. It is possible that the message can be converted to another format, and it is possible that the message body is not validly of the specified format.
- Returns:
- The type of the message body
-
getPersistence
boolean getPersistence()
Get the persistence of the message.The persistence value of true means that the message continues to be available even if the server fails. This is commonly implemented by writing the message to non-volatile storage.
- Returns:
- true if the message is persistent, and false if it is not
-
getReliability
ImaReliability getReliability()
Get the reliability of the message.The reliability of a message deals with the message guarantee in case of client or network failure.
- Returns:
- The reliability
-
getRetain
boolean getRetain()
Get the retain value of the message. If a message is published as retained, it is kept as part of the topic until another message is published as retained for the topic. At most one retained message is kept for each topic. Messages are not retained for queues and the retain bit is ignored when the destination is a queue.When a message is received, the setting of the retain flag is based on whether the message was delivered as part of the creation of a subscription. If the subscription is already active when a retained message is sent, it will not be seen as retained to the existing subscriptions.
- Returns:
- true if the message is from a retained source, or false if it is not from a retained source.
-
getRetainAsPublished
boolean getRetainAsPublished()
Get the retained value as published. If a message is published as retained, it is kept as part of the topic until another message is published as retained for the topic. At most one retained message is kept for each topic. Messages are not retained for queues and the retain bit is ignored when the destination is a queue.When a message is published, the retain flag indicates it should be retained and sent for any new subscriptions. This retain as published flag indicates whether retain was requested when the message was published. This can be used to set the retain flag when a message is forwarded.
- Returns:
- true if the message is published as retained, or false if it is not published as a retained message.
-
getProperties
Map<String,Object> getProperties()
Get a read-only map of the user message properties.Only named properties are returned. These are commonly the user properties. Many of the system properties are returned as other fields. The resulting map cannot be modified.
- Returns:
- A map containing the message properties.
-
getIntPropery
int getIntPropery(String name, int default_value)
Get a message property as an integer.If the message property is not an integer, attempt to convert it to an integer. If the property cannot be converted to an integer, return the default value.
- Parameters:
name
- The name of the propertydefault_value
- The default value if the property is missing or cannot be converted to an integer- Returns:
- The value of the property as an integer, or the default_value if the property is missing or cannot be converted to an integer.
-
getProperty
Object getProperty(String name)
Get a message property as an Object.As it is valid for a property to have a null value, the method propertyExists() can be used to differentiate between an existing property with a null value and a missing property.
All properties can be converted to a String, but the resulting String might not be useful in all cases.
- Parameters:
name
- The name of the property- Returns:
- The value of the property (which might be null), or null if the property does not exist.
-
getStringProperty
String getStringProperty(String name)
Get a message property as a String.As it is valid for a property to have a null value, the method propertyExists() can be used to differentiate between an existing property with a null value and a missing property.
- Parameters:
name
- The property name- Returns:
- The value of the property as a string (which might be null), or null if the property does not exist.
-
getUserData
Object getUserData()
Get a user object associated with this message.- Returns:
- An object associated with this message or null if there is none
-
propertyExists
boolean propertyExists(String name)
Return whether a property exists.- Parameters:
name
- The property name- Returns:
- true if the property exists, and false if it is missing
-
setMessageType
ImaMessage setMessageType(ImaMessageType msgtype)
Set the message type.- Parameters:
msgtype
- The messge type- Returns:
- This message
-
setBodyBytes
ImaMessage setBodyBytes(byte[] body)
Set the body as a byte array.This completely replaces any existing body.
- Parameters:
body
- The byte array to set as the body- Returns:
- The message
-
setBodyMap
ImaMessage setBodyMap(Map<String,Object> body)
Set the body as a Map. The actual format of the resulting message depends on the message type. If the message type is a known form of mapped message it will be formatted by this type, otherwise it will be encoded as a JSON string.This completely replaces any existing body.
- Parameters:
body
- The byte array to set as the body- Returns:
- The message
-
setBodyText
ImaMessage setBodyText(String body)
Set the body as a String.This completely replaces any existing body.
- Parameters:
body
- The string to set as the body.- Returns:
- The message
-
setPersistent
ImaMessage setPersistent(boolean persist)
Set the persistence of the message.The persistence value of true means that the message continues to be available even if the server fails. This is commonly implemented by writing the message to non-volatile storage.
- Parameters:
persist
- true for persistent and false for non-persistent- Returns:
- The message
-
setReliability
ImaMessage setReliability(ImaReliability reliability)
Set the reliability of the message.The reliability of a message deals with the message guarantee in case of client or network failure. To ensure message delivery in the case of a server failure the message should also be persistent.
- Parameters:
reliability
- The reliability- Returns:
- The message
-
setUserData
void setUserData(Object userdata)
Set a user object associated with this message.- Parameters:
userdata
- An object to associate with this message
-
setRetain
ImaMessage setRetain(boolean retain)
Set the retain value of the message. If a message is published as retained, it is kept as part of the topic until another message is published as retained for the topic. At most one retained message is kept for each topic. Messages are not retained for queues and the retain bit is ignored when the destination is a queue. When a subscription to a topic is created, any retained messages are sent to the subscription. If the subscription is a wildcard subscription there can be multiple retained messages.- Parameters:
retain
- true if the message should be retained, false if it should not be retained.- Returns:
- The message
-
acknowledge
void acknowledge(int rc)
Acknowledge a received message.- Parameters:
rc
- A return code, 0=good.
-
acknowledge
void acknowledge(int rc, ImaTransaction transaction)
Acknowledge a received message.- Parameters:
rc
- A return code, 0=good.
-
-