Package org.eclipse.hono.util

Class MessageHelper

  • public final class MessageHelper
extends Object
    Utility methods for working with Proton Messages.

    • Field Detail

      • ANNOTATION_X_OPT_APP_CORRELATION_ID

        public static final String ANNOTATION_X_OPT_APP_CORRELATION_ID
        The name of the AMQP 1.0 message annotation that is used to indicate the type of the correlation-id.
        See Also:
        Constant Field Values

      • ANNOTATION_X_OPT_RETAIN

        public static final String ANNOTATION_X_OPT_RETAIN
        The name of the AMQP 1.0 message annotation that is used to indicate that the sender of the message intended the message to be retained in the MQTT sense. The value of the property is a boolean. If a message does not contain this annotation, then a consumer must process the message as if the annotation exists and has a value of false.
        See Also:
        Constant Field Values

      • APP_PROPERTY_CACHE_CONTROL

        public static final String APP_PROPERTY_CACHE_CONTROL
        The name of the AMQP 1.0 message application property containing the caching directive to follow for the body of the message.
        See Also:
        Constant Field Values

      • APP_PROPERTY_DEVICE_ID

        public static final String APP_PROPERTY_DEVICE_ID
        The name of the AMQP 1.0 message application property containing the id of the device that has reported the data belongs to.
        See Also:
        Constant Field Values

      • APP_PROPERTY_DEVICE_TTD

        public static final String APP_PROPERTY_DEVICE_TTD
        The name of the AMQP 1.0 message application property containing the time until disconnect of the device that is available for receiving an upstream message for the given number of seconds (short for Time til Disconnect).
        See Also:
        Constant Field Values

      • APP_PROPERTY_GATEWAY_ID

        public static final String APP_PROPERTY_GATEWAY_ID
        The name of the AMQP 1.0 message application property containing the id of the gateway that wants to report data on behalf of another device.
        See Also:
        Constant Field Values

      • APP_PROPERTY_ORIG_ADDRESS

        public static final String APP_PROPERTY_ORIG_ADDRESS
        The name of the AMQP 1.0 application property that is used to convey the address that a message has been originally published to by a device.
        See Also:
        Constant Field Values

      • APP_PROPERTY_ORIG_ADAPTER

        public static final String APP_PROPERTY_ORIG_ADAPTER
        The name of the AMQP 1.0 message application property containing the name of the protocol adapter over which an uploaded message has originally been received.
        See Also:
        Constant Field Values

      • APP_PROPERTY_REGISTRATION_ASSERTION

        public static final String APP_PROPERTY_REGISTRATION_ASSERTION
        The name of the AMQP 1.0 message application property containing a JWT token asserting a device's registration status.
        See Also:
        Constant Field Values

      • APP_PROPERTY_RESOURCE

        public static final String APP_PROPERTY_RESOURCE
        The name of the AMQP 1.0 message application property containing the resource a message is addressed at.
        See Also:
        Constant Field Values

      • APP_PROPERTY_STATUS

        public static final String APP_PROPERTY_STATUS
        The name of the AMQP 1.0 message application property containing the status code indicating the outcome of processing a request.
        See Also:
        Constant Field Values

      • APP_PROPERTY_TENANT_ID

        public static final String APP_PROPERTY_TENANT_ID
        The name of the AMQP 1.0 message application property containing the id of the tenant the device that has reported the data belongs to.
        See Also:
        Constant Field Values

      • SYS_PROPERTY_ABSOLUTE_EXPIRY_TIME

        public static final String SYS_PROPERTY_ABSOLUTE_EXPIRY_TIME
        The AMQP 1.0 absolute-expiry-time message property.
        See Also:
        Constant Field Values

      • SYS_PROPERTY_CONTENT_ENCODING

        public static final String SYS_PROPERTY_CONTENT_ENCODING
        The AMQP 1.0 content-encoding message property.
        See Also:
        Constant Field Values

      • SYS_PROPERTY_CONTENT_TYPE

        public static final String SYS_PROPERTY_CONTENT_TYPE
        The AMQP 1.0 content-type message property.
        See Also:
        Constant Field Values

      • SYS_PROPERTY_CORRELATION_ID

        public static final String SYS_PROPERTY_CORRELATION_ID
        The AMQP 1.0 correlation-id message property.
        See Also:
        Constant Field Values

      • SYS_PROPERTY_CREATION_TIME

        public static final String SYS_PROPERTY_CREATION_TIME
        The AMQP 1.0 creation-time message property.
        See Also:
        Constant Field Values

      • SYS_PROPERTY_GROUP_ID

        public static final String SYS_PROPERTY_GROUP_ID
        The AMQP 1.0 group-id message property.
        See Also:
        Constant Field Values

      • SYS_PROPERTY_GROUP_SEQUENCE

        public static final String SYS_PROPERTY_GROUP_SEQUENCE
        The AMQP 1.0 group-sequence message property.
        See Also:
        Constant Field Values

      • SYS_PROPERTY_MESSAGE_ID

        public static final String SYS_PROPERTY_MESSAGE_ID
        The AMQP 1.0 message-id message property.
        See Also:
        Constant Field Values

      • SYS_PROPERTY_REPLY_TO

        public static final String SYS_PROPERTY_REPLY_TO
        The AMQP 1.0 reply-to message property.
        See Also:
        Constant Field Values

      • SYS_PROPERTY_REPLY_TO_GROUP_ID

        public static final String SYS_PROPERTY_REPLY_TO_GROUP_ID
        The AMQP 1.0 reply-to-group-id message property.
        See Also:
        Constant Field Values

      • SYS_PROPERTY_SUBJECT

        public static final String SYS_PROPERTY_SUBJECT
        The AMQP 1.0 subject message property.
        See Also:
        Constant Field Values

      • SYS_PROPERTY_USER_ID

        public static final String SYS_PROPERTY_USER_ID
        The AMQP 1.0 user-id message property.
        See Also:
        Constant Field Values

      • TTD_VALUE_UNLIMITED

        public static final int TTD_VALUE_UNLIMITED
        The time-til-disconnect value to use for indicating that a device will remain connected until further notice.
        See Also:
        Constant Field Values

      • JMS_VENDOR_PROPERTY_CONTENT_ENCODING

        public static final String JMS_VENDOR_PROPERTY_CONTENT_ENCODING
        The JMS_AMQP_CONTENT_ENCODING vendor property name.
        See Also:
        Constant Field Values

      • JMS_VENDOR_PROPERTY_CONTENT_TYPE

        public static final String JMS_VENDOR_PROPERTY_CONTENT_TYPE
        The JMS_AMQP_CONTENT_TYPE vendor property name.
        See Also:
        Constant Field Values

      • CONTENT_TYPE_APPLICATION_JSON

        public static final String CONTENT_TYPE_APPLICATION_JSON
        The MIME type representing the String representation of a JSON Object.
        See Also:
        Constant Field Values

    • Method Detail

      • getDeviceId

        public static String getDeviceId​(org.apache.qpid.proton.message.Message msg)
        Gets the value of a message's APP_PROPERTY_DEVICE_ID application property.
        Parameters:
        msg - The message.
        Returns:
        The property value or null if not set.

      • getTenantId

        public static String getTenantId​(org.apache.qpid.proton.message.Message msg)
        Gets the value of a message's APP_PROPERTY_TENANT_ID application property.
        Parameters:
        msg - The message.
        Returns:
        The property value or null if not set.

      • getRegistrationAssertion

        public static String getRegistrationAssertion​(org.apache.qpid.proton.message.Message msg)
        Gets the registration assertion conveyed in an AMQP 1.0 message.

        The assertion is expected to be contained in the messages's application-properties under key APP_PROPERTY_REGISTRATION_ASSERTION.

        Parameters:
        msg - The message.
        Returns:
        The assertion or null if the message does not contain an assertion (at the expected location).

      • getAndRemoveRegistrationAssertion

        public static String getAndRemoveRegistrationAssertion​(org.apache.qpid.proton.message.Message msg)
        Gets and removes the registration assertion conveyed in an AMQP 1.0 message.

        The assertion is expected to be contained in the messages's application-properties under key APP_PROPERTY_REGISTRATION_ASSERTION.

        Parameters:
        msg - The message.
        Returns:
        The assertion or null if the message does not contain an assertion (at the expected location).

      • getDeviceIdAnnotation

        public static String getDeviceIdAnnotation​(org.apache.qpid.proton.message.Message msg)
        Gets the value of a message's APP_PROPERTY_DEVICE_ID annotation.
        Parameters:
        msg - The message.
        Returns:
        The annotation value or null if not set.

      • getTenantIdAnnotation

        public static String getTenantIdAnnotation​(org.apache.qpid.proton.message.Message msg)
        Gets the value of a message's APP_PROPERTY_TENANT_ID annotation.
        Parameters:
        msg - The message.
        Returns:
        The annotation value or null if not set.

      • getXOptAppCorrelationId

        public static boolean getXOptAppCorrelationId​(org.apache.qpid.proton.message.Message msg)
        Gets the value of the x-opt-appl-correlation-id annotation from a message.
        Parameters:
        msg - the message to get the annotation from.
        Returns:
        the value of the annotation (if present) or false if the message does not contain the annotation.

      • getApplicationProperty

        public static <T> T getApplicationProperty​(org.apache.qpid.proton.amqp.messaging.ApplicationProperties props,
                                           String name,
                                           Class<T> type)
        Gets the value of a specific application property.
        Type Parameters:
        T - The expected type of the property to retrieve the value of.
        Parameters:
        props - The application properties to retrieve the value from.
        name - The property name.
        type - The expected value type.
        Returns:
        The value or null if the properties do not contain a value of the expected type for the given name.

      • getJsonPayload

        public static io.vertx.core.json.JsonObject getJsonPayload​(org.apache.qpid.proton.message.Message msg)
        Parses a message's body into a JSON object.
        Parameters:
        msg - The AMQP 1.0 message to parse the body of.
        Returns:
        The message body parsed into a JSON object or null if the message does not have a Data nor an AmqpValue section.
        Throws:
        NullPointerException - if the message is null.
        io.vertx.core.json.DecodeException - if the payload cannot be parsed into a JSON object.

      • getPayload

        public static io.vertx.core.buffer.Buffer getPayload​(org.apache.qpid.proton.message.Message msg)
        Gets a message's body as Buffer object.
        Parameters:
        msg - The AMQP 1.0 message to parse the body of.
        Returns:
        The message body as a Buffer or null if the message does not have a Data nor an AmqpValue section.
        Throws:
        NullPointerException - if the message is null.

      • getPayloadAsString

        public static String getPayloadAsString​(org.apache.qpid.proton.message.Message message)
        Gets a message's body as String.
        Parameters:
        message - The AMQP 1.0 message to parse the body of.
        Returns:
        The message body as a String or null if the message does not have a Data nor an AmqpValue section.
        Throws:
        NullPointerException - if the message is null.

      • addTenantId

        public static void addTenantId​(org.apache.qpid.proton.message.Message msg,
                               String tenantId)
        Adds a tenant ID to a message's application properties.

        The name of the application property is APP_PROPERTY_TENANT_ID.

        Parameters:
        msg - The message.
        tenantId - The tenant identifier to add.
        Throws:
        NullPointerException - if any of the parameters are null.

      • addDeviceId

        public static void addDeviceId​(org.apache.qpid.proton.message.Message msg,
                               String deviceId)
        Adds a device ID to a message's application properties.

        The name of the application property is APP_PROPERTY_DEVICE_ID.

        Parameters:
        msg - The message.
        deviceId - The device identifier to add.
        Throws:
        NullPointerException - if any of the parameters are null.

      • addRegistrationAssertion

        public static void addRegistrationAssertion​(org.apache.qpid.proton.message.Message msg,
                                            String token)
        Adds a registration assertion to an AMQP 1.0 message.

        The assertion is put to the message's application-properties under key APP_PROPERTY_REGISTRATION_ASSERTION.

        Parameters:
        msg - The message.
        token - The assertion to add.
        Throws:
        NullPointerException - if any of the parameters are null.

      • addCacheDirective

        public static void addCacheDirective​(org.apache.qpid.proton.message.Message msg,
                                     CacheDirective cacheDirective)
        Adds a caching directive to an AMQP 1.0 message.

        The directive is put to the message's application-properties under key APP_PROPERTY_CACHE_CONTROL.

        Parameters:
        msg - The message to add the directive to.
        cacheDirective - The cache directive.
        Throws:
        NullPointerException - if any of the parameters are null.

      • getCacheDirective

        public static String getCacheDirective​(org.apache.qpid.proton.message.Message msg)
        Gets the value of a message's APP_PROPERTY_CACHE_CONTROL application property.
        Parameters:
        msg - The message to get the property from.
        Returns:
        The property value or null if not set.

      • addTimeUntilDisconnect

        public static void addTimeUntilDisconnect​(org.apache.qpid.proton.message.Message msg,
                                          int timeUntilDisconnect)
        Adds a property indicating a device's time until disconnect property to an AMQP 1.0 message.

        The value is put to the message's application-properties under key APP_PROPERTY_DEVICE_TTD.

        Parameters:
        msg - The message to add the property to.
        timeUntilDisconnect - The value of the property (number of seconds).

      • getTimeUntilDisconnect

        public static Integer getTimeUntilDisconnect​(org.apache.qpid.proton.message.Message msg)
        Gets the value of a message's APP_PROPERTY_DEVICE_TTD application property.
        Parameters:
        msg - The message to get the property from.
        Returns:
        The property value or null if not set.

      • addProperty

        public static void addProperty​(org.apache.qpid.proton.message.Message msg,
                               String key,
                               Object value)
        Adds a property to an AMQP 1.0 message.

        The property is added to the message's application-properties.

        Parameters:
        msg - The message.
        key - The property key.
        value - The property value.
        Throws:
        NullPointerException - if any of th parameters are null.

      • rejected

        public static void rejected​(io.vertx.proton.ProtonDelivery delivery,
                            org.apache.qpid.proton.amqp.transport.ErrorCondition error)
        Rejects and settles an AMQP 1.0 message.
        Parameters:
        delivery - The message's delivery handle.
        error - The error condition to set as the reason for rejecting the message (may be null.
        Throws:
        NullPointerException - if delivery is null.

      • annotate

        public static void annotate​(org.apache.qpid.proton.message.Message msg,
                            ResourceIdentifier resourceIdentifier)
        Adds several AMQP 1.0 message annotations to the given message that are used to process/route the message.

        In particular, the following annotations are added:

        Parameters:
        msg - the message to add the message annotations to.
        resourceIdentifier - the resource identifier that will be added as annotation.

      • addJmsVendorProperties

        public static void addJmsVendorProperties​(org.apache.qpid.proton.message.Message msg)
        Adds JMS vendor properties defined by AMQP JMS Mapping 1.0 as AMQP 1.0 application properties to a given message.

        The following vendor properties are added (if the message has a corresponding non-null value set):

        Parameters:
        msg - the message to add the vendor properties to.

      • addAnnotation

        public static void addAnnotation​(org.apache.qpid.proton.message.Message msg,
                                 String key,
                                 Object value)
        Adds a value for a symbol to an AMQP 1.0 message's annotations.
        Parameters:
        msg - the message to add the symbol to.
        key - the name of the symbol to add a value for.
        value - the value to add.

      • getAnnotation

        public static <T> T getAnnotation​(org.apache.qpid.proton.message.Message msg,
                                  String key,
                                  Class<T> type)
        Returns the value to which the specified key is mapped in the message annotations, or null if the message annotations contain no mapping for the key.
        Type Parameters:
        T - the expected type of the property to read.
        Parameters:
        msg - the message that contains the annotations.
        key - the name of the symbol to return a value for.
        type - the expected type of the value.
        Returns:
        the annotation's value or null if no such annotation exists or its value is not of the expected type.

      • setCreationTime

        public static void setCreationTime​(org.apache.qpid.proton.message.Message msg)
        Sets the #SYS_PROPERTY_CREATION_TIME of the AMQP 1.0 message to the current timestamp.
        Parameters:
        msg - the message for that the creation-time property is set.

      • isDeviceCurrentlyConnected

        public static Boolean isDeviceCurrentlyConnected​(org.apache.qpid.proton.message.Message msg)
        Verify if a device is currently connected to a protocol adapter. This is evaluated at the point in time this method is invoked.

        This could be used as a trigger condition for an attempt to send a command upstream to the device.

        Parameters:
        msg - Message that is evaluated.
        Returns:
        Boolean true if the message signals that the device now should be ready to receive a command, false otherwise.
        Throws:
        NullPointerException - If msg is null.

      • setPayload

        public static void setPayload​(org.apache.qpid.proton.message.Message message,
                              String contentType,
                              byte[] payload)
        Set the payload of the message using a Data section.

        If the payload is null, then neither the payload, nor content type will be set.

        Parameters:
        message - The message to update.
        contentType - An optional content type.
        payload - The optional message payload.
        Throws:
        NullPointerException - If the parameter message was null.

      • setPayload

        public static void setPayload​(org.apache.qpid.proton.message.Message message,
                              String contentType,
                              io.vertx.core.buffer.Buffer payload)
        Set the payload of the message using a Data section.

        If the payload is null, then neither the payload, nor content type will be set.

        Parameters:
        message - The message to update.
        contentType - An optional content type.
        payload - The optional message payload.
        Throws:
        NullPointerException - If the parameter message was null.

      • setJsonPayload

        public static void setJsonPayload​(org.apache.qpid.proton.message.Message message,
                                  io.vertx.core.json.JsonObject payload)
        Set the JSON payload of the message using a Data section.

        If the payload is null, then neither the payload, nor content type will be set.

        Parameters:
        message - The message to update.
        payload - The optional message payload.
        Throws:
        NullPointerException - If the parameter message was null.

      • setJsonPayload

        public static void setJsonPayload​(org.apache.qpid.proton.message.Message message,
                                  String payload)
        Set the JSON payload of the message using a Data section.

        If the payload is null, then neither the payload, nor content type will be set.

        Note: No formal check is done if the payload actually is a JSON string.

        Parameters:
        message - The message to update.
        payload - The optional message payload.
        Throws:
        NullPointerException - If the parameter message was null.

      • hasDataBody

        public static boolean hasDataBody​(org.apache.qpid.proton.message.Message message,
                                  boolean allowAmqpValue)
        Test if the message has a Data section set as the body.
        Parameters:
        message - The message to test.
        allowAmqpValue - Whether or now to allow AmqpValue of type String or byte[] to pass as well.
        Returns:
        true if the body was not null and an instance of Data, false otherwise. If the parameter allowAmqpValue was true, then the method would also return true if the body contains an AmqpValue of type String or byte[].
        Throws:
        NullPointerException - If the parameter message was null.