1. REST API for Oracle Messaging Cloud Service
  2. Tasks
  3. Sending Messages

Send a Message

post

/producers/{producerName}/messages

Send the message specified by the HTTP headers and request body to the destination specified.

Oracle Messaging Cloud Service only allows messages with at most 3K (3072) characters of messaging-relevant HTTP request headers and at most 512K (524,288) bytes or characters of HTTP request body.  An attempt to send a message that exceeds these limits will generate an error response, and no message will be sent.

Request

Path Parameters
Query Parameters
  • Optional.  The JMS correlation ID header for the message.  This parameter is used to match up different messages.
  • Optional.  Whether messages are required to be stored in persistent storage.  If present, the value must be persistent or non_persistent; default is persistent.  If the value is persistent, the message must be stored in persistent storage; otherwise, it may or may not be stored in persistent storage.  Messages in persistent storage can persist through outages or failover of the service.
  • Required if the producer was not created with a destination; otherwise, it is forbidden.  The value is the destination to which the message will be sent.  If present, must have one of the following forms:
    • /queues/queueName
    • /topics/topicName
    • /temporaryQueues/queueName
    • /temporaryTopics/topicName
  • Optional.  The value of the JMSXGroupID property on the message being sent.  This parameter is optional, but should be set if, and only if, groupSeq is set.
  • Optional.  The value of the JMSXGroupSeq property on the message being sent.  This is the sequence number of the message within the message group specified by the groupId parameter.  The groupSeq parameter must be set to an integer or a badParameter error response will be generated.  This parameter is optional, but should be set if, and only if, groupId is set.

  • Optional; The type of JMS message sent, or HTTP.  If omitted, the default is HTTP.  Depending on the value, there may be restrictions on the HTTP request body, and/or special interpretation of that body and/or some of the standard HTTP request parameters.
  • Optional.  The JMS reply-to header for the message.  If present, it must have one of the following forms:
    • /queues/queueName
    • /temporaryQueues/queueName
    • /topics/topicName
    • /temporaryTopics/topicName

    The value is a destination to which replies should be sent.

  • Optional.  The amount of time for which the message will be kept in the service if not received.  If present, the value must be a strictly positive long integer or the value maximum; default is maximum.  The value determines the time in milliseconds between when a message is dispatched and when the JMS broker may delete it if not yet delivered.  The value maximum indicates that the maximum time-to-live allowed by the service (the number of milliseconds in 2 weeks) should be used.
Back to Top

Response

200 Response

Message successfully sent.
Headers
  • persistent or non_persistent
  • One of the following values is set for this header:
    • /queues/queue to which the message was sent
    • /topics/topic to which the message was sent
    • /temporaryQueues/temporary queue to which the message was sent
    • /temporaryTopics/temporary topic to which the message was sent
    • Time at which the message will expire, and be removed from the service.  This is a long integer interpreted as Unix time.
    • The message's unique ID, if present
    • This is always the default value, 4.
    • The time at which message was handed off to the JMS broker, if present.  This is a long integer interpreted as Unix time.

    400 Response

    Error Codes

    • badParameter: One of the following occurred:
      • The request specified a value for thedestination parameter that did not parse as a specification of a queue or topic.
      • The value of the deliveryMode parameter did not parse as a delivery mode.
      • The value of the ttl parameter was not a valid time-to-live.
      • The value of the replyTo parameter did not parse as a queue or topic specification.
      • The value of the messageType parameter was not one of the allowed values for this parameter.
    • badProperty: An X-OC-type-PROPERTY-name header had a value that did not fit the format of properties with the given type.
    • forbiddenContentType: The Content-Type header of the HTTP request had value application/x-www-form-urlencoded
    • multipleDestinations: Either the producer has no default destination and no destination was specified by the request, or the producer has a default destination and a destination was specified by the request.
    • destinationParameterNotFound: The destination specified for the message does not exist.
    • messageHeadersTooLarge: The request's message-relevant headers exceeded the maximum size.
    • messageBodyTooLarge: The request's body exceeded the maximum size.
    • timeToLiveTooLarge: The ttl parameter was supplied, but was an integer that is larger than that permitted by the service (the number of milliseconds in 2 weeks).
    • maxMessagesOnTargetDestinationReached: The service instance already has the maximum number of messages on the specified destination of the message.
    • maxMessageBytesOnTargetDestinationReached: The message could not be sent because the targeted destination reached the hard quota on the number of bytes of messages on it, and has not yet fallen below its soft quota.

    404 Response

    Error Codes

    • producerNotFound: The requested producer does not exist.

    500 Response

    Error Codes

    • operationFailed: The server was unable to obtain the input stream containing the message body, or a low-level exception was thrown by the JMS broker in trying to send the message.
    Back to Top

    Examples

    cURL Command

    Send using a "wildcard" producer where the destination to be sent the message must be specified. 

    cookie=/tmp/messaging-cookie
curl -s -u $USER:$PASS -c $cookie -b $cookie \
     -H "X-OC-ID-TOKEN-STATUS: disabled" \
     -d "My First Message" \
     -X POST "https://messaging.us2.oraclecloud.com/myService-myTenant/api/v1/producers/myFirstProducer/messages?destination=/queues/myFirstQueue"

    The request body is the content of the message to be sent and there is no response body.

    Send using a producer which had the destination specified during creation. 

    cookie=/tmp/messaging-cookie
curl -s -u $USER:$PASS -c $cookie -b $cookie \
     -H "X-OC-ID-TOKEN-STATUS: disabled" \
     -d "My First Message" \
     -X PUT "https://messaging.us2.oraclecloud.com/myService-myTenant/api/v1/producers/myFirstProducer/messages"

    The request body is the content of the message to be sent and there is no response body.

    Back to Top