Message Transmission API

Creating and Managing Messaging Contexts

This section provides information about creating and managing messaging contexts in Oracle Messaging Cloud Service.

Topics:

Create a Messaging Context

A messaging context is a container of ephemeral objects like connections, sessions, producers, consumers, temporary destinations, and queue browsers.

Creation of a messaging context is an implicit operation. It is created by the first access to the Oracle Messaging Cloud Service that passes authentication. At least one messaging context must be created by a client in order to access Oracle Messaging Cloud Service. When a new messaging context is created, the HTTP response includes the header X-OC-NEW-MESSAGING-CONTEXT: true. Existing messaging contexts are identified in HTTP requests by JSESSIONID cookies. If an HTTP request does not include a JSESSIONID cookie, or if the HTTP request includes a JSESSIONID cookie for an expired messaging context, then a new messaging context is created. For more information about messaging contexts, see Messaging Context and HTTP Cookies.

Each messaging context created by the REST API has a maximum inactive interval (MII) associated with it. A messaging context expires if it is not accessed for a period of time longer than the associated MII.

Get Maximum Inactive Interval (MII)

This section provides information about getting the maximum MII allowed to be set by the service or service instance.

Method: GET

Path: /maxInactiveInterval

Scope: Messaging Context

Authorization: Messaging Administrator or Messaging Worker

Result: Returns the information of the current MII and the maximum allowed MII.

Response Headers:

X-OC-MII: positive integer number of seconds

Indicates the current value of the MII.
X-OC-MAX-MII: positive integer number of seconds

Indicates the maximum MII allowed to be set by the service or service instance.

Error Response:

Error Message	Description
`operationFailed`	A low-level exception occurred in attempting to obtain the client ID.

Set Maximum Inactive Interval (MII)

This section provides information about setting the Maximum Inactive Interval (MII).

Method: POST

Path: /maxInactiveInterval

Scope: Messaging Context

Authorization: Messaging Administrator or Messaging Worker

Request Parameter:

Parameter	Description
`mii`	The value must be a non-negative integer, interpreted as the number of seconds to which the client would like to set the MII.

Result: If the value of mii in the request is positive, then the MII is set to that value (or 900 if the value is greater than 900). If it is 0, the messaging context expires immediately, and is deleted.

Note:

A value of 0 does not indicate infinity. Clients may not set messaging contexts to never expire.

Response Headers:

X-OC-MII: positive integer number of seconds

If the requested MII was positive, this is the new value of the maximum inactive interval, which may be less than the value submitted. The maximum is 900 seconds.
X-OC-MAX-MII: positive integer number of seconds

Indicates the maximum MII allowed to be set by the service or service instance. The maximum MII allowed is 900 seconds.

Error Responses:

Error Message	Description
`badParameter`	The value of the `mii` parameter did not parse as an integer or was negative.
`operationFailed`	A low-level exception occurred.

Creating and Managing Connections

A client can associate a client ID with a connection. The client ID is a string that, along with a subscription name, identifies a durable subscription to a topic. When creating a durable consumer on a topic, the client ID set on the connection is used with the subscription name supplied in the consumer creation method to identify the durable subscription.

An attempt to set the client ID on a connection that generates an error with InvalidClientIDException as its exceptionClass causes the connection to become unusable. Any connection on which such an error response is received should be closed.

Topics:

Create a Connection

This topic provides information about creating a connection.

Method: PUT

Path: /connections/connectionName

Scope: Messaging Context

Authorization: Messaging Administrator or Messaging Worker

Request Parameters:

Parameter	Description
`clientId`	Optional. The value is the client ID that the client would like to set on the connection.
`action`	Optional. To start a connection, value of the `action` parameter must be `start`.

Result: Creates a connection with the name connectionName. A connection is stopped when it is created (unless the start action is specified in the PUT request to create the connection).

Response Body:

The response body in XML for creating a connection is as follows:

<connection>
    <metadata>
        <JMSXPropertyNames>
            <items>JMSXDeliveryCount</items>
            <items>JMSXGroupID</items>
            <items>JMSXGroupSeq</items>
        </JMSXPropertyNames>
    </metadata>
  <canonicalLink>relative path to newly created connection</canonicalLink>
</connection>

Each supported JMSX property name is listed in an <items> element.

The response body in JSON for creating a connection is as follows:

{ 
   "metadata": 
      { 
        "JMSXPropertyNames": 
            [
              "JMSXDeliveryCount",
              "JMSXGroupID",
              "JMSXGroupSeq"
            ] 
      }
  "canonicalLink": "relative path to newly created connection" 
}

For more information, refer to the following links:

Error Responses:

Error Message	Description
`clientIdFailure`	The value that is provided for the connection's client ID is rejected by the JMS provider.
`connectionAlreadyExists`	A connection with the specified name already exists.
`maxConnectionCountUnavailable`	An internal error has occurred in determining the number of connections that a service instance is allowed.
`maxLocalConnectionsReached`	The service instance has exceeded the number of connections it can create on a single virtual machine in the cloud. This usually means that the service instance has reached, or even gone beyond, the maximum number of allowed connections.
`operationFailed`	A low-level exception occurred in attempting to obtain the client ID.

Update Connection Properties

This section provides information about updating connection properties.

Method: POST

Path: /connections/connectionName

Scope: Messaging Context

Authorization: Messaging Administrator or Messaging Worker

Request Parameters:

Parameter	Description
`clientId`	Optional. The value is the client ID that the client would like to set on the connection.
`action`	Optional. To start a connection, value of the `action` parameter must be `start`. To stop a connection, the value of the action parameter must be `stop`.

Result: If the clientId parameter is present, the client ID of the connection is set to the specified value, provided that none of the following blocking conditions are true:

The client ID has already been set to a value for the connection.
The connection was started when it was created.
The connection has been used for any operation.
The client ID is in use by some other application.

If any of the blocking conditions is true, a 400 error response is generated.

Note:

If a REST API client sets a client ID on a connection, as long as that connection exists, no other connection will be able to have the same client ID set on it. As a consequence, no other connection will be able to create, delete, or consume from any durable subscription with that client ID. For example, consider the following situations:

A client fails, or otherwise loses the value of the JSESSIONID HTTP cookie that identifies the messaging context that contains a connection with a client ID.
A client exits without either deleting a connection with a client ID or expiring the messaging context containing it by setting the messaging context's MII to 0.

In either of these cases, no client will be able to create a new connection with the given client ID until the messaging context expires. To avoid these situations, a REST API client that sets a client ID on a connection should do the following:

Set the MII of any messaging context containing a connection with a client ID to the smallest feasible value, so that, if the client fails or loses the value of the JSESSIONID HTTP cookie, the time before the client ID can be used again is minimal.
Delete connections with client IDs before exiting, either by explicitly performing a DELETE on the connection resource or by setting the MII of the messaging context containing such connections to 0, which will close all connections in the context.

Error Responses:

Error Message	Description
`clientIdFailure`	The value that is provided for the connection's client ID is rejected by the JMS provider. The value of the clientId may be in use by another application, including message push listeners.
`connectionNotFound`	The requested connection does not exist.
`clientIdUnsettable`	An attempt was made to set the client ID on a connection on which it cannot be set, either because it has already been set or because an operation has been performed (for example, starting the connection, or creating a session) after which the client ID can no longer be set.
`operationFailed`	A low-level exception occurred in attempting to obtain the client ID, or its value has been rejected.

Delete a Connection

This topic provides information about deleting a connection.

Method: DELETE

Path: /connections/connectionName

Scope: Messaging Context

Authorization: Messaging Administrator or Messaging Worker

Result: Closes and deletes the connection. This also closes and deletes all sessions, producers, consumers, temporary destinations, and queue browsers created with the connection.

Error Response:

Error Message	Description
`connectionNotFound`	The requested connection does not exist.

Creating and Managing Sessions

Before messages can be sent or received through the Message Transmission API, a connection and a session must be created. A session provides a behavioral context that defines what it means for messages to be sent and received between clients and Oracle Messaging Cloud Service.

Topics:

Create a Session

This topic provides information about creating a session.

Method: PUT

Path: /sessions/sessionName

Scope: Messaging Context

Authorization: Messaging Administrator or Messaging Worker

Request Parameters:

Parameter	Description
`connection`	Specify the name of the connection used to create the session.
`transacted`	Optional. If present, must have value `true` or `false`; default is `false`. Determines whether the session is transacted.
`ackMode`	Optional. If present, must have value `auto`, `client`, or `dups_ok`; default is `auto`. Determines how messages received through the session are acknowledged. This parameter is irrelevant if the `transacted` parameter is `true`. The `auto` value means that received messages are automatically acknowledged as they are received. The `client` value means that messages must be explicitly acknowledged by the client. The `dups_ok` value means that messages are automatically acknowledged, but "lazily", so their acknowledgement may be delayed.

Result: Creates a session.

Error Responses:

Error Message	Description
`missingParameter`	The `connection` parameter was not supplied.
`badParameter`	The value of the `transacted` parameter had a value other than `true` or `false`, or the value of the `ackMode` parameter had a value other than the allowed ones.
`sessionAlreadyExists`	A session with the given name already exists.
`connectionParameterNotFound`	No connection exists with name which is specified for the `connection` parameter.
`operationFailed`	A low-level exception was thrown in creating the session.

Acknowledge, Commit, Rollback, or Recover a Session

This topic provides information about acknowledging, committing, doing a rollback, or recovering a session.

Method: POST

Path: /sessions/sessionName/state

Scope: Messaging Context

Authorization: Messaging Administrator or Messaging Worker

Request Parameter:

Parameter	Description
`action`	Required. Must have value `acknowledge`, `commit`, `rollback`, or `recover`. Value determines whether the operation is to acknowledge any unacknowledged messages received through the session, commit any uncommitted sends and receives, roll back any uncommitted sends and receives, or recover any unacknowledged messages.

Result: Performs the specified operation. If the action is acknowledge or recover, and the session is set to acknowledge messages automatically (either with acknowledgement mode auto or dups_ok), this is a no-op. If the action is commit or rollback, and the session is not transacted, this is a no-op. If the action is recover and the session is transacted, a 500 error response is generated.

See Process Messages using a Transaction for an example HTTP request/response sequence.

Error Responses:

Error Message	Description
`missingParameter`	The `action` parameter was not supplied.
`badParameter`	The value of the action parameter was not `acknowledge`, `commit`, `rollback`, or `recover`.
`sessionNotFound`	There is no session with the specified name.
`operationFailed`	A low-level exception was thrown while attempting to carry out the specified action on the specified session.

Delete a Durable Subscription

This topic provides information about deleting a durable subscription.

Method: DELETE

Path: /sessions/sessionName/subscriptions/subscriptionName

Scope: Messaging Context

Authorization: Messaging Administrator or Messaging Worker

Result: Deletes the subscription whose client ID is that set on the connection and whose name is that given on the path.

Error Responses:

Error Message	Description
`sessionNotFound`	Session specified on the path does not exist.
`subscriptionInUse`	The subscription has a consumer on it.
`subscriptionNotFound`	Subscription specified on the path does not exist.
`operationFailed`	A low-level exception was thrown while attempting to delete the subscription.

Close and Delete a Session

This topic provides information about closing and deleting a session.

Method: DELETE

Path: /sessions/sessionName

Scope: Messaging Context

Authorization: Messaging Administrator or Messaging Worker

Result: Session with name sessionName is closed and deleted. All producers, consumers, and queue browsers associated with the session are implicitly closed and deleted.

Error Responses:

Error Message	Description
`sessionNotFound`	There is no session with the specified name.
`operationFailed`	A low-level exception was thrown while attempting to close and delete the specified session.

Sending Messages

This section provides information about sending messages using the REST API.

Topics:

See Send a Message to a Topic for example HTTP requests which send a message to a destination.

Create a Producer

This topic provides information about creating a producer.

Method: PUT

Path: /producers/producerName

Scope: Messaging Context

Authorization: Messaging Administrator or Messaging Worker

Request Parameters:

Parameter	Description
`session`	Required. The value is the name of the session in which to create the producer.
`destination`	Optional. If present, the value must have one of the following forms: `/queues/queueName` `/topics/topicName` `/temporaryQueues/queueName` `/temporaryTopics/topicName` Specifies the default destination of messages sent via the producer. If this parameter is omitted, then the destination to which a message is sent must be specified as a parameter in each send operation performed via this producer.
`messageIdEnabled`	Optional. If present, the value must be `true` or `false`; default is `true`. Determines whether the producer generates IDs for messages sent through it. Note: The value of this parameter is a hint to the service, which may disregard the value.
`deliveryMode`	Optional. If present, the value must be `persistent` or `non_persistent`; default is `persistent`. Determines whether messages produced are persistent.
`ttl`	Optional. If present, the value must be a strictly positive long integer or the value `maximum`; default is `maximum`. 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.

Result: Creates a producer.

Error Responses:

Error Message	Description
`missingParameter`	The `session` parameter value 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 `messageIdEnabled` parameter had a value other than `true` or `false`. 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.
`sessionParameterNotFound`	Session by which to create the producer does not exist.
`destinationParameterNotFound`	The default destination specified for the producer does not exist.
`producerAlreadyExists`	There is already a producer with the specified name.
`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).
`operationFailed`	A low-level exception was thrown while attempting to create the producer.

Set Properties of a Producer

This section provides information about setting properties of a producer.

Method: POST

Path: /producers/producerName

Scope: Messaging Context

Authorization: Messaging Administrator or Messaging Worker

Request Parameters:

Parameter Description

Parameter	Description
`messageIdEnabled`	Optional. If present, the value must be `true` or `false`. Determines whether the producer generates IDs for messages sent through it. Note: The value of this parameter is a hint to the service, which may disregard the value.
`deliveryMode`	Optional. If present, the value must be `persistent` or `non_persistent`. Determines whether messages produced are persistent.
`ttl`	Optional. If present, the value must be a strictly positive long integer or the value `maximum`. 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.

messageIdEnabled

Optional. If present, the value must be true or false. Determines whether the producer generates IDs for messages sent through it.

Note: The value of this parameter is a hint to the service, which may disregard the value.

deliveryMode

Optional. If present, the value must be persistent or non_persistent. Determines whether messages produced are persistent.

ttl

Optional. If present, the value must be a strictly positive long integer or the value maximum. 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.

Result: Sets the property associated with the parameter to the specified value for all parameters present.

Error Responses:

Error Message	Description
`badParameter`	One of the following occurred: The `messageIdEnabled` parameter had a value other than `true` or `false`. 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.
`producerNotFound`	The specified producer to modify does not exist.
`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).
`operationFailed`	A low-level exception was thrown while attempting to modify the producer.

Close and Delete a Producer

This topic provides information about closing and deleting a producer.

Method: DELETE

Path: /producers/producerName

Scope: Messaging Context

Authorization: Messaging Administrator or Messaging Worker

Result: Closes and deletes the producer with name producerName.

Error Responses:

Error Message	Description
`producerNotFound`	The specified producer to close and delete does not exist.
`operationFailed`	A low-level exception was thrown while attempting to close and delete the producer.

Send a Message via a Producer

This section provides information about sending a message via a producer.

Method: POST

Path: /producers/producerName/messages

Scope: Messaging Context

Authorization: Messaging Administrator or Messaging Worker

Result: Sends the message specified by the HTTP headers and request body to the destination specified as described below.

Request parameters, headers, and the request body are as described in Properties of HTTP Requests to Send Messages from REST Clients, with the following differences in the request parameters:

Parameter	Description
`deliveryMode`	The default value of this header is defined by the producer.
`ttl`	The default value of this header is defined by the producer.
`destination`	Required if the producer was not created with a destination, in which case the message is sent to the specified destination. If present, must have one of the following forms: `/queues/queueName` `/topics/topicName` `/temporaryQueues/queueName` `/temporaryTopics`/`topicName` Forbidden if the producer was created with a destination, in which case the message is sent to the destination with which the producer was created.
`groupId`	Optional. This parameter is used to set the `JMSXGroupID` property on the message being sent. This is the name of the message group of which this message is a part, if any. Note: If the `JMSXGroupID` property is set as an HTTP request header, it must be set to an escaped value String or a `badParameter` error response will be generated. For more information on escaped value Strings, see About Escaped Value Strings. If the `JMSXGroupID` property is set as a query string parameter, the usual conventions for escaping query string parameters hold. This parameter is optional, but should be set if, and only if, `groupSeq` is set.
`groupSeq`	Optional. This parameter is used to set 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. Note that this parameter is optional, but should be set if, and only if, `groupId` is set.

Response Headers:

Header	Description
`X-OC-DESTINATION`	One of the following values is set for this header: `/queues/name of the queue to which the message was sent` `/topics/name of the topic to which the message was sent` `/temporaryQueues/name of the temporary queue to which the message was sent` `/temporaryTopics/name of the temporary topic to which the message was sent`
`X-OC-MESSAGE-ID`	`message's ID`, if present
`X-OC-DELIVERY-MODE`	`persistent` or `non_persistent`. For more information, see About Persistent and Non-Persistent Messages.
`X-OC-TIMESTAMP`	`time at which message was handed off to the JMS broker`, if present. This is a long integer interpreted as Unix time.
`X-OC-EXPIRATION`	`message expiration time.` This is a long integer interpreted as Unix time.
`X-OC-PRIORITY`	This is always the default value, `4`.

Error Responses:

Error Message	Description
`badParameter`	One of the following occurred: The request specified a value for the `destination` 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`. See Error Keys, Status Codes and Error Messages for further information.
`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.
`producerNotFound`	The specified producer by which to send 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. For more information, see Hard and Soft Quotas.
`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.

Receiving Messages

This section provides information about receiving messages using REST API.

Topics:

Create a Consumer

This topic provides information about creating a consumer.

Method: PUT

Path: /consumers/consumerName

Scope: Messaging Context

Authorization: Messaging Administrator or Messaging Worker

Request Parameters:

Parameter	Description
`session`	Required. The value is the name of the session in which to create the consumer.
`destination`	Optional. If present, the value must have one of the following forms: `/queues/queueName` `/topics/topicName` `/temporaryQueues/queueName` `/temporaryTopics/topicName` Specifies the destination from which the consumer consumes messages. 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.
`selector`	Optional. Specifies the subset of messages the consumer will receive. The value of the parameter must be a selector. For the syntax of selectors, see the Message Selectors section of the Java API reference for the `javax.jms.Message` class.
`localMode`	Optional. If present, value must be `GET_LOCAL` or `NO_LOCAL`. Specifies whether the consumer on a topic will receive messages sent via the connection that contains the consumer. 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`.
`subscriptionName`	Optional. Specifies the name of the durable subscription. If present, the consumer created will be a durable topic subscriber (and so the `destination` parameter must specify a topic). See Create a Durable Subscription for an example HTTP request/response sequence.

Result: Creates a consumer. 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.

Note:

If the subscriptionName parameter is present, then the exact result depends significantly 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 the destination specifies a topic, the client ID has been set for the connection and subscriptionName is present, then the consumer will consume messages via a durable subscription to the topic specified by the client ID and the subscription name.
If no durable subscription with the given client ID and name exists, one is created on the specified topic with the specified selector.
If a durable subscription for the 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 been consumed through the subscription is available to be consumed).
If a durable subscription for the 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 ID, name and selector on the specified topic is created.

If the destination parameter is not present, the client ID must have been set on the connection, 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.

Response Headers:

Response to creating a consumer on an existing durable subscription contains the following headers that provide the properties of the subscriber:

X-OC-DESTINATION

Indicates the topic of the subscription.
X-OC-SELECTOR

Indicates the selector of the subscription, if any.

Error Responses:

Error Message	Description
`missingParameter`	The `session` parameter value 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, or contained a disallowed identifier. The `localMode` parameter value is not one of the allowed values. The method did not supply a `destination` parameter, 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.
`subscriptionInUse`	An attempt was made to create a consumer on a durable subscription when that durable subscription already has a consumer on it.
`subscriptionNonTopic`	Subscription name and destination parameters were supplied, but the `destination` parameter does not specify a topic.
`sessionParameterNotFound`	Session by which to create the producer does not exist.
`destinationParameterNotFound`	The destination from which the consumer should get messages is nonexistent.
`consumerAlreadyExists`	There is already a consumer with the given name.
`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.
`operationFailed`	The method did not supply a `destination` parameter, but the existing durable subscription from which it was meant to consume had a bad destination, or a low-level exception was thrown while creating the consumer.

Close and Delete a Consumer

This topic provides information about closing and deleting a consumer.

Method: DELETE

Path: /consumers/consumerName

Scope: Messaging Context

Authorization: Messaging Administrator or Messaging Worker

Result: Closes and deletes the consumer.

Error Responses:

Error Message	Description
`consumerNotFound`	The specified consumer to close does not exist.
`operationFailed`	A low-level exception was thrown while closing and deleting the specified consumer.

Receive a Message via a Consumer

This section provides information about receiving a message via a consumer.

Method: POST

Path: /consumers/consumerName/messages

Scope: Messaging Context

Authorization: Messaging Administrator or Messaging Worker

Request Parameter:

Parameter	Description
`timeout`	Required. The number of milliseconds in the value must be a strictly positive long integer that is no more than the maximum receive timeout of 5 minutes. Specifies the amount of time in milliseconds to wait for a message to become available from the consumer before returning a null message.

See Receive a Message from a Queue with a Selector and Receive a Message from a Durable Subscription for examples of HTTP request/response sequences.

Result:

If there is a message on the consumer's queue that satisfies the selector (if it was set on the consumer), or if one enters the queue within the number of milliseconds in timeout, it is returned in the HTTP response. Otherwise, a null response is returned.
If receiving from a topic, if messages have been published to the topic since the consumer was created, or if messages are published to the topic within the number of milliseconds in timeout, one of those messages will be return in the HTTP response. Otherwise, a null response is returned.
If the consumer is consuming from a durable subscription, and if there is a message currently stored in the durable subscription, or if one enters the durable subscription within the number of milliseconds in timeout, it is returned in the HTTP response. Otherwise, a null response is returned.

Note:

If the session by which the consumer was created is transacted, or is not transacted but has client acknowledgement set, only one message may be received via that consumer before committing (if the session is transacted) or acknowledging (if the session is not transacted but has client acknowledgement set) the session. Until the appropriate commit or acknowledgement action is taken, receives from that consumer will return a null response, even if there are other messages that could otherwise be received from the consumer's destination.

Response Headers: If a message is returned, the headers will include those determined by the message described in Properties of HTTP Requests and Responses that Deliver Messages. Otherwise, a response with no content with the header X-OC-NULL: true is returned.

Error Responses:

Error Message	Description
`missingParameter`	The request had no `timeout` parameter specified.
`badParameter`	The value of the `timeout` parameter did not parse as a long integer value, or the value of the `timeout` parameter was 0 or a negative number.
`consumerNotFound`	The specified consumer from which to receive does not exist.
`timeoutTooLarge`	The value of the `timeout` parameter was larger than the maximum allowed value (5 minutes).
`operationFailed`	A low-level exception was thrown while receiving, or an exception was thrown while attempting to extract information from the received message.

Creating and Managing Durable Subscriptions

This section provides information about creating and managing durable subscriptions in Oracle Messaging Cloud Service.

Topics:

Create a Durable Subscription

Durable subscriptions are implicitly created by creating a special type of consumer.

To create a durable subscription, see the Create a Consumer section, specifically the notes about subscriptionName and clientId.

List Durable Subscriptions

This section provides information about listing durable subscriptions.

Method: GET

Path: /subscriptions

Scope: Messaging Context

Authorization: Messaging Administrator or Messaging Worker

Request Parameters:

Parameter	Description
`subscriptionName`	The name of the subscription.
`topicName`	The name of a topic. Note that the value of this parameter is not of the form `/topics/name`, but is only the `name` part of that form, since durable subscriptions only apply to topics.
`clientId`	A client ID associated with the subscription.

None of these parameters are mandatory, but only certain combinations are allowed, as described below.

Result: Returns information about one or more durable subscriptions depending on the request parameters supplied:

clientId and subscriptionName

Returns an XML or a JSON document specifying the unique durable subscription for the given name and client ID, if one exists, for the namespace specified in the request.

The XML format is as follows:
```
<subscription>
    <clientId>client ID<clientId>
    <name>subscription name</name>
    <topic>topic name</topic>
    <selector>selector</selector>
    <canonicalLink>relative path to the subscription</canonicalLink>
</subscription>
```
The JSON format is as follows:
```
{ 
    "clientId": "client ID", 
    "name": "subscription name", 
    "topic": "topic name", 
    "selector": "selector", 
    "canonicalLink": "relative path to the subscription" 
}
```
All child elements will be present except selector, which is present if the subscription is associated with a selector. The clientId and name elements always have the same values as the corresponding parameters.

clientId

Returns an XML or a JSON document specifying all of the durable subscriptions for the given client ID for the namespace specified in the request.

The XML format is as follows:

<subscriptions>
    <items>
        <clientId>client ID<clientId>
        <name>name</name>
        <topic>topic name</topic>
        <selector>selector</selector>
        <canonicalLink>relative path to the subscription</canonicalLink>
    </items>
    ...
    <canonicalLink>relative path to the subscription list</canonicalLink>
</subscriptions>

The JSON format is as follows:

{ 
   "subscriptions": 
      { 
        "clientId": "client ID",
        "name": "subscription name"
        "topic": "topic name", 
        "selector": "selector", 
        "canonicalLink": "relative path to the subscription" 
      } 
    "canonicalLink": "relative path to the subscription list" 
}

This element may be empty if the client ID has no subscriptions. Each child specifies a unique durable subscription. The client ID of all subscription elements is the same as the value of the corresponding request parameter; each value of name will appear only once, as a durable subscription is specified by the client ID and subscription name.

topicName

Returns an XML or a JSON document specifying all of the durable subscriptions for the topic with the given name for the namespace specified in the request. Note that the value of this parameter is not of the form /topics/name, but is only the name part of that form, since durable subscriptions only apply to topics. The format of the XML document in the response is the same as the XML format described earlier for clientId. This element may be empty if the topic has no subscriptions. Each child specifies a unique durable subscription. The topic> content of all subscription elements is the same as the value of the corresponding request parameter; each pair of values for client ID and name will appear only once, as a durable subscription is specified by the client ID and subscription name.
None of the parameters are supplied

Returns an XML or a JSON document specifying all of the durable subscriptions for the namespace specified in the request. The format is the same as described earlier for clientId and subscriptionName, clientId, and topicName. This element may be empty if the namespace has no durable subscriptions. Each child specifies a unique durable subscription. The topic values of all subscription elements is the same as the value of the corresponding request parameter; each pair of values for client ID and name will appear only once, as a durable subscription is specified by the client ID and subscription name.

Error Responses:

Error Message	Description
`disallowedSubscriptionLookup`	A combination of the `subscriptionName`, `clientId`, and `topicName` parameters has been supplied that is not one of those listed earlier.
`destinationParameterNotFound`	The `topicName` parameter was specified, but there is no topic by that name in the namespace.
`subscriptionNotFoundFull`	A client ID and subscription name were specified in the request, but no such subscription exists.
`operationFailed`	A low-level exception occurred.

Delete a Durable Subscription

Durable subscriptions are implicitly created by creating a special type of consumer. A durable subscription stores all messages sent to a topic until each message is received.

For information about deleting durable subscriptions through sessions, see Delete a Durable Subscription.

Creating and Managing Temporary Destinations

This section provides information about creating and managing temporary destinations in Oracle Messaging Cloud Service.

Topics:

Create a Temporary Destination

You can create the following kinds of temporary destinations:

Temporary Queue: A TemporaryQueue is a unique Queue object created for the duration of a connection. Messages may only be consumed from a temporary queue through the connection with which it was created.
Temporary Topic: A TemporaryTopic is a unique Topic object created for the duration of a connection. Messages may only be consumed from a temporary topic through the connection with which it was created.

Method: POST

Path:

To create a temporary queue, the path is /temporaryQueues
To create a temporary topic, the path is /temporaryTopics

Scope: Messaging Context

Authorization: Messaging Administrator or Messaging Worker

Request Parameter:

Parameter	Description
`session`	Specify the session name. This parameter is mandatory.

Result: Creates a temporary queue or temporary topic.

Response Header:

Location

Contains the URL for the newly created temporary queue or temporary topic.

Response Body:

Destination Type	XML Format	JSON Format
Temporary queue	<temporaryQueue> <name>queue name</name> <connection>name of the connection with which the queue is associated</connection> <canonicalLink>relative path to temporary queue</canonicalLink> </temporaryQueue>	{ "type": "temporaryQueue", "name" "queue name", "connection": "name of the connection with which the queue is associated", "canonicalLink": "relative path to temporary queue" }
Temporary topic	<temporaryTopic> <name>topic name</name> <connection>name of the connection with which the topic is associated</connection> <canonicalLink>relative path to temporary topic</canonicalLink> </temporaryTopic>	{ "type": "temporaryTopic", "name" "topic name", "connection": "name of the connection with which the topic is associated", "canonicalLink": "relative path to temporary topic" }
Temporary queues	<temporaryQueues> <name>queue name</name> <connection>name of the connection with which the queue is associated</connection> <canonicalLink>relative path to temporary queue</canonicalLink> ... <canonicalLink>relative path to list of temporary queues</canonicalLink> </temporaryQueues>	{ "temporaryQueues": [ { "name": "queue name", "connection": "name of the connection with which the queue is associated", "canonicalLink": "relative path to temporary queue" } ... ], "canonicalLink": "relative path to list of temporary queues" }
Temporary topics	<temporaryTopics> <name>topic name</name> <connection>name of the connection with which the topic is associated</connection> <canonicalLink>relative path to temporary topic</canonicalLink> ... <canonicalLink>relative path to list of temporary topics</canonicalLink> </temporaryTopics>	{ "temporaryTopics": [ { "name": "topic name", "connection": "name of the connection with which the topic is associated", "canonicalLink": "relative path to temporary topic" } ... ], "canonicalLink": "relative path to list of temporary topics" }

The content of the name field is a pseudorandom name generated by the service for the newly created temporary queue or topic.

The connection field is omitted if the destination was not created from a connection in the messaging context.

Error Response:

Error Message	Description
`sessionNotFound`	A session with the specified name does not exists.

List Temporary Destinations

This section provides information about listing temporary destinations.

List Temporary Queues or Temporary Topics

Method: GET

Path:

To list all temporary queues in the messaging context, the path is /temporaryQueues
To list all temporary topics in the messaging context, the path is /temporaryTopics

Scope: Messaging Context

Authorization: Messaging Administrator or Messaging Worker

Request Parameter:

Parameter	Description
`connection`	Optional. Specify the `connection` parameter to list all temporary queues or topics associated with the connection with the name `connection-name`.

Result: Returns a listing of all temporary queues or temporary topics in the messaging context.

Response Body:

In XML, the format for listing all temporary queues associated with an HTTP cookie is as follows:

<temporaryQueues>
    <items>
        <name>queue name</name>
        <connection>name of the connection with which the queue is associated</connection>
        <canonicalLink>relative path to temporary queue</canonicalLink>
    </items>
    ...
    <canonicalLink>relative path to list of temporary queues</canonicalLink>
</temporaryQueues>

In XML, the format for listing all temporary topics associated with an HTTP cookie is as follows:

<temporaryTopics>
    <items>
        <name>topic name</name>
        <connection>name of the connection with which the topic is associated</connection>
        <canonicalLink>relative path to temporary topic</canonicalLink>
    </items>
    ...
    <canonicalLink>relative path to list of temporary topics</canonicalLink>
</temporaryTopics>

The content of the <name> element is the queueName or topicName.The <connection> element is present only if the temporary queue or topic was created from a connection associated with the client's messaging context.

If the temporary queue or topic was created elsewhere and received as, for example, in the Reply-To header of a message, then the <connection> element will not be present.

Error Response:

Error Message	Description
`connectionParameterNotFound`	A REST API client invoked the method to list all temporary destinations created through a certain named connection, but no connection with that name exists in the messaging context.

Retrieve Properties of a Single Temporary Queue or a Single Temporary Topic

Method: GET

Path:

To retrieve the properties of a single temporary queue, the path is /temporaryQueues/queueName
To retrieve the properties a single temporary topic, the path is /temporaryTopics/topicName

Scope: Messaging Context

Authorization: Messaging Administrator or Messaging Worker

Result: Returns the properties of a temporary queue or a temporary topic with the given name.

Response Body:

The format for listing a single temporary queue is as follows:

<temporaryQueue>
    <name>queue name</name>
    <connection>name of the connection with which the queue is associated</connection>
    <canonicalLink>relative path to temporary queue</canonicalLink>
</temporaryQueue>

The format for listing a single temporary topic is as follows:

<temporaryTopic>
    <name>topic name</name>
    <connection>name of the connection with which the topic is associated</connection>
    <canonicalLink>relative path to temporary topic</canonicalLink>
</temporaryTopic>

The content of the <name> element is the queueName or topicName.The <connection> element is present only if the temporary queue or topic was created from a connection associated with the client's messaging context.

If the temporary queue or topic was created elsewhere and received as, for example, in the Reply-To header of a message, then the <connection> element will not be present.

Error Response:

Error Message	Description
`destinationNotFound`	The temporary destination that is requested does not exist.

Remove a Temporary Destination

This section provides information about removing temporary destinations.

Method: DELETE

Path:

To delete a temporary queue, the path is /temporaryQueues/queueName
To delete a temporary topic, the path is /temporaryTopics/topicName

Scope: Messaging Context

Authorization: Messaging Administrator or Messaging Worker

Result: Deletes the temporary destination with the given name.

Note:

If the temporary destination that is being deleted was created from a connection in the same messaging context, the temporary destination will be deleted from the back-end. Else, it will be deleted only from the messaging context, and not from the back-end.

After being deleted from the back-end, the temporary destination will not be available for use to other clients.

Error Response:

Error Message	Description
`destinationNotFound`	The temporary destination whose deletion is requested does not exist.

Creating and Managing Queue Browsers

This section provides information about creating and managing queue browsers in Oracle Messaging Cloud Service.

Topics:

Create a Queue Browser

A client uses a queue browser to look at messages on a queue without removing them. A queue browser is created from a Session.

A queue browser may be used to look at all the messages in a queue, or only those that match a message selector. Note that if messages are sent to a queue after a browser on that queue is created, those messages may not be visible via the queue browser.

Method: PUT

Path: /queueBrowsers/browserName

Scope: Messaging Context

Authorization: Messaging Administrator or Messaging Worker

Request Parameters:

Parameter	Description
`session`	The value is the name of the session in which the queue browser needs to be created.
`destination`	Specify the destination name. The value must have the form `/queues/queueName`.
`selector`	Message selector, which is optional.

Result: Creates a queue browser on the destination parameter.

Error Responses:

Error Message	Description
`sessionNotFound`	There is no session with the specified name.
`destinationNotFound`	The destination that is requested does not exist.
`queueBrowserAlreadyExists`	A queue browser with the specified name already exists.
`badParameter`	One of the following occurred: The `destination` parameter value did not parse as a specification of a queue. The `selector` parameter value was ill-formed, or contained a disallowed identifier.

Retrieve Queue Browser Properties

This section provides information about retrieving queue browser properties.

Method: GET

Path: /queueBrowsers/browserName

Scope: Messaging Context

Authorization: Messaging Administrator or Messaging Worker

Result: Returns properties of the queue browser with the name browserName.

Response Body:

In XML, the format for the properties of a queue browser is as follows:

<queueBrowser>
    <name>client-assigned name of the browser</name>
    <queue>path specifying the persistent or temporary queue browsed</queue>
    <selector>selector expression<selector>
    <canonicalLink>relative path to queue browser</canonicalLink>
</queueBrowser>

In JSON, the format for the properties of a queue browser is as follows:

{ 
    "name": "client-assigned name of the browser", 
    "queue": "path specifying the persistent or temporary queue browsed", 
    "selector": "selector expression", 
    "canonicalLink": "relative path to queue browser" 
}

The content of the queue element has the form /queue/queueName if the browser browses a persistent queue named queueName; it has the form /temporaryQueue/queueName if the browser browses a temporary queue named queueName.

The selector element is present only if the queue browser is associated with a selector.

Error Response:

Error Message	Description
`queueBrowserNotFound`	The queue browser that is requested does not exist.

Browse Messages

This topic provides information about browsing messages in a queue browser.

Method: POST

Path: /queueBrowsers/browserName

Scope: Messaging Context

Authorization: Messaging Administrator or Messaging Worker

Result: If there is a message in the browser, it is returned in the HTTP response. Otherwise, a null response is returned.

Response Header:

If there is an X-OC-NULL header with value true, then it indicates that there are no more messages in the browser.

Error Response:

Error Message	Description
`queueBrowserNotFound`	The queue browser that is requested does not exist.

Remove a Queue Browser

This section provides information about removing a queue browser.

Method: DELETE

Scope: Messaging Context

Path: /queueBrowsers/browserName

Authorization: Messaging Administrator or Messaging Worker

Result: Closes and deletes the queue browser.

Error Response:

Error Message	Description
`queueBrowserNotFound`	The queue browser that is requested does not exist.