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.
    • 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.