ImaMessage (Eclipse Amlen Javadoc Reference)

Package com.ibm.ima.plugin

## 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 property
        `default_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 property
        `default_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.