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

Create a Consumer

put

/consumers/{consumerName}

Create a consumer with the name consumerName.  If the destination parameter is present and it specifies a queue, then the consumer will consume from the queue.  If the destination parameter is present and it specifies a topic, then the consumer will consume from the topic.

If the subscriptionName parameter is present, the session in which the consumer is being created must have been created from a connection with a client ID set on it, or an error will be returned.

The exact result when there is a subscriptionName depends on whether the destination parameter is present or not.  If the destination parameter is present, a consumer is created with characteristics given by the other parameters, as follows:

  • If no durable subscription with the connection's client ID and name exists, one is created on the specified topic with the specified selector.
  • If a durable subscription for the client ID and name already exists, and the topic and selector are the same as in the method that created the durable subscription, the existing durable subscription is used (and, thus, any messages sent to the topic since the subscription was created that have not already been consumed are available to be received).
  • If a durable subscription for the client ID and name already exists, but either the topic or the selector (or lack thereof) specified in this method are different from the topic and selector (or lack thereof) specified in the method that created the existing subscription, the existing subscription is deleted, and messages saved by it discarded, and a new durable subscription with the specified client ID, name, and selector on the specified topic is created.

If the destination parameter is not present, the subscriptionName parameter must be present, the selector parameter must not be present, and there must be an existing durable subscription with the given client ID and subscription name.  (The semantics of localMode are unchanged.) In this case, the consumer created is a consumer on the topic for the existing subscription, with the selector (or lack thereof) of the existing subscription, that uses the existing subscription.  In this case, the method will not create or delete a subscription.

Request

Path Parameters
Query Parameters
  • Optional.  Specifies the queue or topic from which the consumer consumes messages.  If present, the value must have one of the following forms:
    • /queues/queueName
  • /topics/topicName
  • /temporaryQueues/queueName
  • /temporaryTopics/topicName

If the destination parameter is present, a consumer is created with characteristics given by the other parameters, as described later.  If the destination parameter is not present, the consumer being created should be a consumer of a topic through an already created durable subscription.

  • Optional.  Specification of whether a consumer on a topic will receive messages sent via the consumer's connection.  If present, its value must be GET_LOCAL or NO_LOCAL.  A value of GET_LOCAL means that messages sent via the connection are received, and a value of NO_LOCAL means that such messages will not be received.  The default is GET_LOCAL.
  • Optional.  Specification of a subset of messages the consumer will receive.  The value of the parameter must be a well-formed JMS selector.  For the syntax of selectors, see the Message Selectors section of the Java API reference for the javax.jms.Messageclass.
  • Required.  The name of the session in which to create the consumer.
  • Optional.  Specifies the name of the durable subscription.  If present, the consumer created will be a durable topic subscriber (and so the destination parameter, if present, must specify a topic, not a queue).
    • Back to Top

    Response

    201 Response

    Consumer created.  The response to creating a consumer on an existing durable subscription contains certain headers that provide the properties of the subscriber.
    Headers

    400 Response

    Error Codes

    • missingParameter: The session parameter was not supplied.
    • badParameter: One of the following occurred:
      • The destination parameter value did not parse as a specification of a queue or topic.
      • The selector parameter value was ill-formed.
      • The localMode parameter value is not one of the allowed values.
      • The method did not supply a destinationparameter, but the existing durable subscription from which it was meant to consume had a bad selector.
    • noDestinationForConsumer: Neither a destination nor a subscription name were supplied.
    • localModeNonTopic: The localMode and destination parameters were supplied, but the destination parameter does not specify a topic.
    • subscriptionNonTopic: The subscription name and destination parameters were supplied, but the destination parameter does not specify a topic.
    • sessionParameterNotFound: The session by which to create the producer does not exist.
    • destinationParameterNotFound: The destination from which the consumer should get messages is nonexistent.
    • subscriptionNotFoundNoInfo: The method did not supply a destination parameter, but the existing durable subscription from which it was meant to consume was not found.
    • maxDurableSubscriptionsReached: The consumer whose creation was attempted was on a durable subscription that does not currently exist, and this method invocation would create the subscription if it does not exist, and the service instance is at its maximum number of durable subscriptions.

    409 Response

    Error Codes

    • consumerAlreadyExists:A consumer with the specified name already exists.

    500 Response

    Error Codes

    • operationFailed:A low-level exception occurred in attempting to create the consumer.
    Back to Top

    Examples

    cURL Commands

    Create a consumer on a queue. 

    cookie=/tmp/messaging-cookie
curl -s -u $USER:$PASS -c $cookie -b $cookie \
     -H "X-OC-ID-TOKEN-STATUS: disabled" \
     -X PUT "https://messaging.us2.oraclecloud.com/myService-myTenant/api/v1/consumers/myFirstConsumer?session=myFirstSession&destination=/queues/myFirstQueue"

    There is no request body to submit with the HTTP request and there is no response body.

    Create a consumer on a topic. 

    cookie=/tmp/messaging-cookie
curl -s -u $USER:$PASS -c $cookie -b $cookie \
     -H "X-OC-ID-TOKEN-STATUS: disabled" \
     -X PUT "https://messaging.us2.oraclecloud.com/myService-myTenant/api/v1/consumers/myFirstConsumer?session=myFirstSession&destination=/topics/myFirstTopic"

    There is no request body to submit with the HTTP request and there is no response body.

    Create a durable subscription - a special consumer on a topic which persists messages even after the consumer is deleted. To delete a durable subscription see the section on Sessions > Delete a Durable Subscription. 

    cookie=/tmp/messaging-cookie
curl -s -u $USER:$PASS -c $cookie -b $cookie \
     -H "X-OC-ID-TOKEN-STATUS: disabled" \
     -X PUT "https://messaging.us2.oraclecloud.com/myService-myTenant/api/v1/consumers/myFirstConsumer?session=myFirstSession&destination=/topics/myFirstTopic&subscriptionName=myFirstSubscription"

    There is no request body to submit with the HTTP request and there is no response body.

    Back to Top