com.ibm.websphere.sib

Interface SIMessage

  • All Superinterfaces:
    java.lang.Cloneable, java.io.Serializable


    public interface SIMessage
    extends java.lang.Cloneable, java.io.Serializable
    The SIMessage interface is the public interface to an SIBus message for use by Mediations as well as other SIBus components.
    • Method Summary

      Methods 
      Modifier and Type Method and Description
      void clearMessageProperties()
      Delete all the Properties from the Message.
      void clearReplyFields()
      Clear the four ReplyXxxx fields in the message header.
      void clearUserProperties()
      Delete all the User Properties from the Message.
      java.lang.Object clone()
      Obtain a new SIMessage which is a clone of this SIMessage.
      void deleteMessageProperty(java.lang.String name)
      Delete the Property with the given name from the Message.
      void deleteUserProperty(java.lang.String name)
      Delete the User Property with the given name from the Message.
      java.lang.String getApiMessageId()
      Get the contents of the ApiMessageId field from the message API Meta-Data.
      java.lang.String getCorrelationId()
      Get the contents of the CorrelationId field from the message API Meta-Data.
      commonj.sdo.DataGraph getDataGraph()
      Return the SDO DataGraph which contains the SIMessage content in a tree representation using the existing Data Mediator.
      byte[] getDataGraphAsBytes()
      Provide access to the message payload information in the form of a new byte array.
      long getDeliveryDelay()
      Get the value of the DeliveryDelay field from the message header.
      java.lang.String getDiscriminator()
      Get the contents of the topic Discriminator field from the message header.
      java.lang.String getFormat()
      Get the contents of the Format field from the message API Meta-Data.
      java.util.List getForwardRoutingPath()
      Get the contents of the ForwardRoutingPath for this SIMessage.
      java.io.Serializable getMessageProperty(java.lang.String name)
      Return the Property stored in the Message under the given name.
      commonj.sdo.DataGraph getNewDataGraph(java.lang.String format)
      Return a new SDO DataGraph which contains a copy of the SIMessage content in the tree representation specified by the format field.
      int getPriority()
      Get the value of the Priority field from the message header.
      int getRedeliveredCount()
      Get the value of the RedeliveredCount field from the message header.
      Reliability getReliability()
      Get the value of the Reliability field from the message header.
      long getRemainingTimeToLive()
      Get the remaining time in milliseconds before the message expires.
      java.lang.String getReplyDiscriminator()
      Get the contents of the ReplyDiscriminator field from the message header.
      int getReplyPriority()
      Get the value of the ReplyPriority field from the message header.
      Reliability getReplyReliability()
      Get the value of the ReplyReliability field from the message header.
      long getReplyTimeToLive()
      Get the value of the ReplyTimeToLive field from the message header.
      java.util.List getReverseRoutingPath()
      Get the contents of the ReverseRoutingPath for this SIMessage.
      java.lang.String getSystemMessageId()
      Get the unique System Message Id from the message header.
      long getTimeToLive()
      Get the value of the TimeToLive field from the message header.
      java.lang.String getUserId()
      Get the contents of the UserId field from the message API Meta-Data.
      java.io.Serializable getUserProperty(java.lang.String name)
      Return the User Property stored in the Message under the given name.
      java.util.List getUserPropertyNames()
      Get a list of the names of the User Properties in the message.
      boolean isWellFormed()
      Check if the DataGraph currently set in the message is valid.
      void setApiMessageId(java.lang.String value)
      Set the contents of the ApiMessageId field in the message API Meta-Data.
      void setCorrelationId(java.lang.String value)
      Set the contents of the CorrelationId field in the message API Meta-Data.
      void setDataGraph(commonj.sdo.DataGraph newDataGraph, java.lang.String format)
      Set the SIMessage content to a a new SDO DataGraph tree representation.
      void setDeliveryDelay(long value)
      Set the value of the DeliveryDelay field in the message header.
      void setDiscriminator(java.lang.String value)
      Set the contents of the topic Discriminator field in the message header.
      void setForwardRoutingPath(java.util.List value)
      Set the ForwardRoutingPath for this SIMessage.
      void setMessageProperty(java.lang.String name, java.io.Serializable item)
      Add an item to the Message Properties under the given name.
      void setPriority(int value)
      Set the value of the Priority field in the message header.
      void setReliability(Reliability value)
      Set the value of the Reliability field in the message header.
      void setRemainingTimeToLive(long value)
      Set the remaining time in milliseconds before the message should expire.
      void setReplyDiscriminator(java.lang.String value)
      Set the contents of the ReplyDiscriminator field in the message header.
      void setReplyPriority(int value)
      Set the value of the ReplyPriority field in the message header.
      void setReplyReliability(Reliability value)
      Set the value of the ReplyReliability field in the message header.
      void setReplyTimeToLive(long value)
      Set the value of the ReplyTimeToLive field in the message header.
      void setReverseRoutingPath(java.util.List value)
      Set the ReverseRoutingPath for this SIMessage.
      void setTimeToLive(long value)
      Set the value of the TimeToLive field in the message header.
      void setUserId(java.lang.String value)
      Set the contents of the UserId field in the message API Meta-Data.
      void setUserProperty(java.lang.String name, java.io.Serializable item)
      Add User Property to the message under the given name.
    • Method Detail

      • clone

        java.lang.Object clone()
                               throws java.lang.CloneNotSupportedException
        Obtain a new SIMessage which is a clone of this SIMessage.
        Returns:
        Object A clone of the original SIMessage.
        Throws:
        java.lang.CloneNotSupportedException - The clone of the SIBusSdoMessage failed - see the exception text.
      • getDataGraph

        commonj.sdo.DataGraph getDataGraph()
                                           throws SIDataGraphSchemaNotFoundException,
                                                  SIMessageException
        Return the SDO DataGraph which contains the SIMessage content in a tree representation using the existing Data Mediator. The SDO version of a DataGraph contained in the SIMessage is Version 1. A Datagraph provided by the SIMessage can only be provided to other SIMessage objects.
        Returns:
        DataGraph The SDO DataGraph representing the SIMessage. null is returned if the format of the SIMessage is SIApiConstants.JMS_FORMAT
        Throws:
        SIDataGraphSchemaNotFoundException - is thrown if a schema needed to parse the message is not available.
        SIMessageException - is thrown if the message can not be parsed for any other reason. The linked Exception(s) indicate the underlying problem.
      • getNewDataGraph

        commonj.sdo.DataGraph getNewDataGraph(java.lang.String format)
                                              throws SIMessageDomainNotSupportedException,
                                                     SIDataGraphSchemaNotFoundException,
                                                     SIDataGraphFormatMismatchException,
                                                     SIMessageException
        Return a new SDO DataGraph which contains a copy of the SIMessage content in the tree representation specified by the format field. The SDO version of a DataGraph contained in the SIMessage is Version 1. A Datagraph provided by the SIMessage can only be provided to other SIMessage objects.
        Parameters:
        format - A formatted String containing the Data Mediator indicator and any necessary meta-data.
        Returns:
        DataGraph A new SDO DataGraph representing the SIMessage. null is returned only if the format of the message AND the requested are both SIApiConstants.JMS_FORMAT.
        Throws:
        java.lang.NullPointerException - is thrown if the format parameter is null.
        SIMessageDomainNotSupportedException - is thrown if the message domain indicated by the format is not supported.
        SIDataGraphSchemaNotFoundException - is thrown if a schema needed to parse the message is not available.
        SIDataGraphFormatMismatchException - is thrown if the format requested is not compatible with the data in the message.
        SIMessageException - is thrown if the message can not be parsed for any other reason. The linked Exception(s) indicate the underlying problem.
      • setDataGraph

        void setDataGraph(commonj.sdo.DataGraph newDataGraph,
                        java.lang.String format)
                          throws SIMessageDomainNotSupportedException,
                                 SIDataGraphSchemaNotFoundException,
                                 SIDataGraphFormatMismatchException,
                                 SIMessageException
        Set the SIMessage content to a a new SDO DataGraph tree representation. The SDO version of the DataGraph passed to the SIMessage must be Version 1. The DataGraph provided to the SIMessage can only come from another SIMessage or have been constructed using the SIDataGraphFactory.
        Parameters:
        newDataGraph - The SDO DataGraph which the SIMessage is to contain. Must be specified as null if the format parameter is SIApiConstants.JMS_FORMAT
        format - The message format describing the DataGraph model.
        Throws:
        java.lang.NullPointerException - is thrown if either the newDataGraph or format parameter is null. Note that this exception is not thrown if the newDataGraph is null and the format parameter is SIApiConstants.JMS_FORMAT
        SIMessageDomainNotSupportedException - is thrown if the message domain indicated by the format is not supported.
        SIDataGraphSchemaNotFoundException - may be thrown if a schema indicated by the given format is not available.
        SIDataGraphFormatMismatchException - may be thrown if the given format is not compatible with the given DataGraph.
        SIMessageException - is thrown if the DataGraph can not be set into the message for any other reason. The linked Exception(s) indicate the underlying problem.
      • isWellFormed

        boolean isWellFormed()
        Check if the DataGraph currently set in the message is valid. If the DataGraph is not valid the message will not be able to be sent through the SIbus or stored in the message store.
        Returns:
        true if the message contains a well formed DataGraph.
      • getDataGraphAsBytes

        byte[] getDataGraphAsBytes()
                                   throws SIMessageException,
                                          SIDataGraphSchemaNotFoundException
        Provide access to the message payload information in the form of a new byte array. The contents of the byte will depend upon the format of this message instance.
        Returns:
        a new byte array containing a serialized rendering of the message payload
        Throws:
        SIMessageException - is thrown if the message can not be parsed for any other reason. The linked Exception(s) indicate the underlying problem.
        SIDataGraphSchemaNotFoundException - is thrown if a schema needed to parse the message is not available.
      • getMessageProperty

        java.io.Serializable getMessageProperty(java.lang.String name)
                                                throws java.io.IOException,
                                                       java.lang.ClassNotFoundException
        Return the Property stored in the Message under the given name.

        Message Properties are stored as name-value pairs where the value may be any Object which implements java.io.Serializable. This method may be used to get the accessable system (SI_) properties, JMS properties and user properties, however user property names must be prefixed by "user." when passed into this method.

        The reference returned is to a copy of the Object stored in the Message, so any changes made to it will not be reflected in the Message.

        Parameters:
        name - The name of the Property to be returned. For a user property, the name must include the "user." prefix.
        Returns:
        Serializable A reference to the Message Property. Null is returned if there is no such item.
        Throws:
        java.io.IOException - De-serialization of the Property failed.
        java.lang.ClassNotFoundException - De-serialization of the Property failed because a necessary Java Class could not be found.
      • setMessageProperty

        void setMessageProperty(java.lang.String name,
                              java.io.Serializable item)
                                throws java.io.IOException
        Add an item to the Message Properties under the given name.

        Message Properties are stored as name-value pairs where the value may be any Object which implements java.io.Serializable. This method may be used to set the modifyable system (SI_) properties, JMS properties and user properties, however user property names must be prefixed by "user." when passed into this method.

        If a Property with the given name already exists in the Message, it will be replaced by the Object passed in to this method.

        If the given name is null, no data will be stored. If the Object passed in is null, this will have the effect of deleting the Property completely.

        Parameters:
        name - A String value used to access the Property in future. For a user property, the name must include the "user." prefix.
        item - An Object which implements java.io.Serializable
        Throws:
        java.io.IOException - Serialization of the Property failed.
      • deleteMessageProperty

        void deleteMessageProperty(java.lang.String name)
        Delete the Property with the given name from the Message.

        This method may be used to delete the modifyable system (SI_) properties, JMS properties and user properties, however user property names must be prefixed by "user." when passed into this method.

        If the given name is null, no data will be deleted.

        Parameters:
        name - The String value of the Property to be deleted. For a user property, the name must include the "user." prefix.
      • clearMessageProperties

        void clearMessageProperties()
        Delete all the Properties from the Message.

        This method deletes all the modifyable properties from the message. Note that some of the system (SI_) and JMS properties are not modifyable and therefore not clearable.

      • getUserProperty

        java.io.Serializable getUserProperty(java.lang.String name)
                                             throws java.io.IOException,
                                                    java.lang.ClassNotFoundException
        Return the User Property stored in the Message under the given name.

        Message Properties are stored as name-value pairs where the value may be any Object which implements java.io.Serializable. This method may only be used to retrieve user properties, and not to retrieve system (SI_) or JMS properties. The property name passed into the method should not include the "user." prefix.

        The reference returned is to a copy of the Object stored in the Message, so any changes made to it will not be reflected in the Message.

        Parameters:
        name - The name of the Property to be returned.
        Returns:
        Serializable A reference to the Message Property. Null is returned if there is no such item.
        Throws:
        java.io.IOException - De-serialization of the Property failed.
        java.lang.ClassNotFoundException - De-serialization of the Property failed because a necessary Java Class could not be found.
      • setUserProperty

        void setUserProperty(java.lang.String name,
                           java.io.Serializable item)
                             throws java.io.IOException
        Add User Property to the message under the given name.

        Message Properties are stored as name-value pairs where the value may be any Object which implements java.io.Serializable. This method may only be used to set user properties, and not to set system (SI_) or JMS properties. The property name passed into the method should not include the "user." prefix.

        If a Property with the given name already exists in the Message, it will be replaced by the Object passed in to this method.

        If the given name is null, no data will be stored. If the Object passed in is null, this will have the effect of deleting the Property completely.

        Parameters:
        name - A String value used to access the Property in future.
        item - An Object which implements java.io.Serializable
        Throws:
        java.io.IOException - Serialization of the Property failed.
      • deleteUserProperty

        void deleteUserProperty(java.lang.String name)
        Delete the User Property with the given name from the Message.

        This method may only be used to delete user properties, and not to delete system (SI_) or JMS properties. The property name passed into the method should not include the "user." prefix.

        If the given name is null, no data will be deleted.

        Parameters:
        name - The String value of the Property to be deleted.
      • clearUserProperties

        void clearUserProperties()
        Delete all the User Properties from the Message.

        This method deletes all the user properties from the message.

      • getUserPropertyNames

        java.util.List getUserPropertyNames()
        Get a list of the names of the User Properties in the message.

        This method returns a list of the names of the User Properties in the message. The names do not include the "user." prefix.

        Returns:
        List A List containing the String names of the User Properties. An empty list is returned if there are no user properties.
      • getForwardRoutingPath

        java.util.List getForwardRoutingPath()
        Get the contents of the ForwardRoutingPath for this SIMessage. The List returned is a copy of the ForwardRoutingPath so changes to it will not affect the SIMessage itself.
        Returns:
        A List containing the ForwardRoutingPath which is a set of SIDestinationAddresses. Null is returned if the field was not set.
      • setForwardRoutingPath

        void setForwardRoutingPath(java.util.List value)
        Set the ForwardRoutingPath for this SIMessage.
        Parameters:
        value - A List containing the ForwardRoutingPath which is a set of SIDestinationAddresses.
        Throws:
        java.lang.IllegalArgumentException - The List contains one or more entries which are not SIDestinationAdddresses.
        java.lang.NullPointerException - The List contains one or more null entries.
      • getReverseRoutingPath

        java.util.List getReverseRoutingPath()
        Get the contents of the ReverseRoutingPath for this SIMessage. The List returned is a copy of the ReverseRoutingPath so changes to it will not affect the SIMessage itself.
        Returns:
        A List containing the ReverseRoutingPath which is a set of SIDestinationAddresses. Null is returned if the field was not set.
      • setReverseRoutingPath

        void setReverseRoutingPath(java.util.List value)
        Set the ReverseRoutingPath for this SIMessage.
        Parameters:
        value - A List containing the ReverseRoutingPath which is a set of SIDestinationAddresses.
        Throws:
        java.lang.IllegalArgumentException - The List contains one or more entries which are not SIDestinationAdddresses.
        java.lang.NullPointerException - The List contains one or more null entries.
      • getPriority

        int getPriority()
        Get the value of the Priority field from the message header.
        Returns:
        An int containing the Priority of the message.
      • setPriority

        void setPriority(int value)
        Set the value of the Priority field in the message header.
        Parameters:
        value - An int containing the Priority of the message.
        Throws:
        java.lang.IllegalArgumentException - The value given is outside the permitted range.
      • getReliability

        Reliability getReliability()
        Get the value of the Reliability field from the message header.
        Returns:
        The Reliability instance representing the Reliability of the message (i.e. Express, Reliable or Assured). Reliability.UNKNOWN is returned if the field is not set.
      • setReliability

        void setReliability(Reliability value)
        Set the value of the Reliability field in the message header.
        Throws:
        java.lang.NullPointerException - Null is not a valid Reliability.
      • getTimeToLive

        long getTimeToLive()
        Get the value of the TimeToLive field from the message header. The value represents the time in milliseconds for the message to live counting from when it was orginally sent. A value of 0 indicates that the message will never expire.
        Returns:
        A long containing the TimeToLive of the message. The default value of 0 is returned if the field was not set.
      • setTimeToLive

        void setTimeToLive(long value)
        Set the value of the TimeToLive field in the message header. The value represents the time in milliseconds for the message to live counting from when it was orginally sent. A value of 0 indicates that the message should never expire.
        Parameters:
        value - A long containing the TimeToLive of the message.
        Throws:
        java.lang.IllegalArgumentException - The value given is less than 0 or greater than 290,000,000 years.
      • setDeliveryDelay

        void setDeliveryDelay(long value)
        Set the value of the DeliveryDelay field in the message header. The value represents the time in milliseconds that must elapse after a message is sent before the JMS provider may deliver the message to a consumer. A value of 0 indicates that there is no delivery delay
        Parameters:
        value - A long containing the TimeToLive of the message.
        Throws:
        java.lang.IllegalArgumentException - The value given is less than 0 or greater than 290,000,000 years.
      • getDeliveryDelay

        long getDeliveryDelay()
        Get the value of the DeliveryDelay field from the message header. The value represents the time in milliseconds that must elapse after a message is sent before the JMS provider may deliver the message to a consumer. * A value of 0 indicates that the message will never expire.
        Returns:
        A long containing the TimeToLive of the message. The default value of 0 is returned if the field was not set.
      • getRemainingTimeToLive

        long getRemainingTimeToLive()
        Get the remaining time in milliseconds before the message expires.
        Returns:
        A long containing the remaining time, in milliseconds, before the message expires. A negative number indicates that the message will never expire.
      • setRemainingTimeToLive

        void setRemainingTimeToLive(long value)
        Set the remaining time in milliseconds before the message should expire.
        Parameters:
        value - A long containing the remaining time, in milliseconds, before the message should expire. A negative number indicates that the message should never expire.
        Throws:
        java.lang.IllegalArgumentException - The resulting Time To Live is less than 0 or greater than 290,000,000 years.
      • getReplyPriority

        int getReplyPriority()
        Get the value of the ReplyPriority field from the message header.
        Returns:
        An Integer containing the Priority for any reply. The default value of 4 is returned if the field was not set.
      • setReplyPriority

        void setReplyPriority(int value)
        Set the value of the ReplyPriority field in the message header.
        Parameters:
        value - An int containing the Priority for any reply.
        Throws:
        java.lang.IllegalArgumentException - The value given is outside the permitted range.
      • getReplyReliability

        Reliability getReplyReliability()
        Get the value of the ReplyReliability field from the message header.
        Returns:
        The Reliability instance representing the Reliability for any reply message (i.e. Express, Reliable or Assured). Reliability.UNKNOWN is returned if the field is not set.
      • setReplyReliability

        void setReplyReliability(Reliability value)
        Set the value of the ReplyReliability field in the message header.
        Throws:
        java.lang.NullPointerException - Null is not a valid Reliability.
      • getReplyTimeToLive

        long getReplyTimeToLive()
        Get the value of the ReplyTimeToLive field from the message header. A value of 0 indicates that the reply message will never expire.
        Returns:
        A Long containing the TimeToLive for any reply. The default value of 0 is returned if the field was not set.
      • setReplyTimeToLive

        void setReplyTimeToLive(long value)
        Set the value of the ReplyTimeToLive field in the message header. A value of 0 indicates that the reply message should never expire.
        Parameters:
        value - A long containing the TimeToLive for any reply.
        Throws:
        java.lang.IllegalArgumentException - The value given is less than 0 or greater than 290,000,000 years.
      • clearReplyFields

        void clearReplyFields()
        Clear the four ReplyXxxx fields in the message header.
      • getDiscriminator

        java.lang.String getDiscriminator()
        Get the contents of the topic Discriminator field from the message header.
        Returns:
        A String containing the Discriminator for Pub/Sub Null is returned if the field was not set.
      • setDiscriminator

        void setDiscriminator(java.lang.String value)
        Set the contents of the topic Discriminator field in the message header.
        Parameters:
        value - A String containing the Discriminator for Pub/Sub The Discriminator is a simplified XPATH expression without wild cards. It is considered valid if the following expression is true: java.util.regex.Pattern.matches("([^:./*][^:/*]*)(/[^:./*][^:/*]*)*",value);
        Throws:
        java.lang.IllegalArgumentException - The value given contains wild cards or is otherwise invalid.
      • getReplyDiscriminator

        java.lang.String getReplyDiscriminator()
        Get the contents of the ReplyDiscriminator field from the message header.
        Returns:
        A String containing the Discriminator for any reply. Null is returned if the field was not set.
      • setReplyDiscriminator

        void setReplyDiscriminator(java.lang.String value)
        Set the contents of the ReplyDiscriminator field in the message header.
        Parameters:
        value - A String containing the Discriminator for any reply. The Discriminator is a simplified XPATH expression without wild cards. It is considered valid if the following expression is true: java.util.regex.Pattern.matches("([^:./*][^:/*]*)(/[^:./*][^:/*]*)*",value);
        Throws:
        java.lang.IllegalArgumentException - The value given contains wild cards or is otherwise invalid.
      • getSystemMessageId

        java.lang.String getSystemMessageId()
        Get the unique System Message Id from the message header.
        Returns:
        A String containing the system message id. Null is returned if the field has not yet been set.
      • getRedeliveredCount

        int getRedeliveredCount()
        Get the value of the RedeliveredCount field from the message header.
        Returns:
        An int representation of the RedeliveredCount of the message.
      • getApiMessageId

        java.lang.String getApiMessageId()
        Get the contents of the ApiMessageId field from the message API Meta-Data.
        Returns:
        A String containing the ApiMessageId. Null is returned if the field has not been set.
      • setApiMessageId

        void setApiMessageId(java.lang.String value)
        Set the contents of the ApiMessageId field in the message API Meta-Data.
        Parameters:
        value - A String containing the ApiMessageId.
        Throws:
        java.lang.IllegalArgumentException - The value given must be of the form ID:xxxx where xxxx represents an even number of hexadecimal digits.
      • getCorrelationId

        java.lang.String getCorrelationId()
        Get the contents of the CorrelationId field from the message API Meta-Data.
        Returns:
        A String containing the CorrelationId. Null is returned if the field has not been set.
      • setCorrelationId

        void setCorrelationId(java.lang.String value)
        Set the contents of the CorrelationId field in the message API Meta-Data.
        Parameters:
        value - A String containing the CorrelationId.
        Throws:
        java.lang.IllegalArgumentException - The value given must be either be of the form ID:xxxx, where xxxx represents an even number of hexadecimal digits, or must be an arbitrary String which does not start with ID:.
      • getUserId

        java.lang.String getUserId()
        Get the contents of the UserId field from the message API Meta-Data.
        Returns:
        A String containing the UserId. Null is returned if the field has not been set.
      • setUserId

        void setUserId(java.lang.String value)
        Set the contents of the UserId field in the message API Meta-Data.
        Parameters:
        value - A String containing the UserId.
      • getFormat

        java.lang.String getFormat()
        Get the contents of the Format field from the message API Meta-Data.
        Returns:
        A String containing the Format. Null is returned if the field has not been set.
IBM WebSphere Application ServerTM
Release 9.0