1. Using Oracle Messaging Cloud Service
  2. Accessing Oracle Messaging Cloud Service Using REST API
  3. Resource Management API

Resource Management API

The Resource Management API provides functionality to create and manage destinations, and message push listeners.

Topics:

Creating and Managing Destinations

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

Topics:

Create a Destination

This section provides information about creating a destination.

Names of queues or topics must always consist solely of letters of the Roman alphabet (a through z or A through Z), decimal digits (0 through 9), and underscores ('_'). No other characters are allowed.

Method: PUT

Path:

  • To create a queue, the path is /queues/queueName

  • To create a topic, the path is /topics/topicName

Scope: Service Instance

Authorization: Messaging Administrator

Result: Create a queue or topic with the supplied name.

Error Responses:

Error Message Description

destinationAlreadyExists

A destination of the specified type with the specified name already exists.

maxQueuesReached

A request was made to create a queue, but the number of queues is already at the maximum for the service.

maxTopicsReached

A request was made to create a topic, but the number of topics is already at the maximum for the service.

See Create a Queue and Create a Topic for example HTTP requests which create destinations.

List Destinations

This section provides information about listing destinations.

Method: GET

Path:

  • To list queues, the path is /queues

  • To list topics, the path is /topics

Scope: Service Instance

Authorization: Messaging Administrator

Result: Returns a listing of all queues or topics in the service instance.

Response Body: XML or JSON. The XML format has one element for each destination of the appropriate type.

For queues, the format in JSON is as follows:

{
    "items": [
        {
            "name": "name",
            "status": "status",
            "canonicalLink": "relative path to queue"
        },
        ...
    ],
    "canonicalLink": "relative path to queue list"
}

The format for queues in XML is as follows:

<queues>
    <items>
        <name>name</name>
        <status>status</status>
        <canonicalLink>relative path to queue</canonicalLink>
    </items>
    ...
    <canonicalLink>relative path to list of queues</canonicalLink>
</queues>

For topics, the format in JSON is as follows:

{
    "items": [
        {
            "name": "name",
            "status": "status",
            "canonicalLink": "relative path to topic"
        },
        ...
    ],
    "canonicalLink": "relative path to topic list"
}

The JSON format for listing topics is the same as that for listing queues except that the canonicalLink properties are different.

The format for topics in XML is as follows:

<topics>
    <items>
        <name>name</name>
        <status>status</status>
        <canonicalLink>relative path to topic</canonicalLink>
    </items>
    ...
    <canonicalLink>relative path to list of topics</canonicalLink>
</topics>

In all cases, name is the name of the destination of the given type and status is MARK_FOR_DELETION if the destination still exists in the JMS broker but has been marked for deletion (and thus is in the process of being deleted), and is PROVISIONED otherwise. If a destination has been marked for deletion, then it cannot be used, but it is also not possible to create a destination of a given type with the marked destination's name until the marked destination has been deleted (and thus does not appear in the output of this method).

Retrieve Destination Properties

This section provides information about retrieving destination properties.

Method: GET

Path:

  • To get the properties of a queue, the path is /queues/queueName

  • To get the properties of a topic, the path is /topics/topicName

Authorization: Messaging Administrator

Scope: Service Instance

Request Parameter:

Parameter Description

backlog

The value must be true or false. The default value is false.

A destination’s backlog size is the number of messages currently stored for the destination.

Every destination in Oracle Messaging Cloud Service has a maximum backlog size of 100,000 messages. Attempts to send messages to a destination with a backlog of 100,000 messages will fail. The value reported for a queue's backlog size may be up to 30 seconds old.

Note that the backlog feature is currently available only for queues.

Result: Returns the properties of the destination with the specified name. When retrieving a queue’s properties, if backlog is set to true, the HTTP response body includes a backlogStats element for XML and JSON response types, respectively.

Response Body: For queues, the format in JSON is as follows: 

{
    "name": "name",
    "status": "status",
    "canonicalLink": "relative path to queue"
    "backlogStats" : {
    "current" : "size of the destination's backlog"
    }
}

The format in XML is as follows:

<queue>
    <name>name</name>
    <status>status</status>
    <canonicalLink>relative path to queue</canonicalLink>
    <backlogStats>
      <current>size of the destination's backlog</current>
    </backlogStats>
</queue>

For topics, the JSON format is the same, but with the appropriate value of the canonicalLink property. The format in XML is as follows: 

<topic>
    <name>name</name>
    <status>status</status>
    <canonicalLink>relative path to topic</canonicalLink>
</topic>

The value and interpretation of status are as in the List Destinations method.

Error Response:

Error Message Description

destinationNotFound

The destination whose properties are requested does not exist.

Remove a Destination

This section provides information about removing destinations.

Deleting a destination is a non-blocking operation. For more information, refer to About Destination Deletion.

Method: DELETE

Path:

  • To delete a queue, the path is /queues/queueName

  • To delete a topic, the path is /topics/topicName

Scope: Service Instance

Authorization: Messaging Administrator

Result: Deletes the destination with the given name.

Error Response:

Error Message Description

destinationNotFound

The destination whose deletion is requested does not exist.

Creating and Managing Message Push Listeners

This section provides information about creating and managing message push listeners in Oracle Messaging Cloud Service.

Topics:

Create a Listener

This topic provides information about creating a listener. The name of a listener must always consist solely of letters of the Roman alphabet (a through z or A through Z), decimal digits (0 through 9), and underscores ('_'). No other characters are allowed.

Method: PUT

Path: /listeners/listenerName

Scope: Service Instance

Authorization: Messaging Administrator or Messaging Worker

Request Parameter:

Parameter Description

verificationToken

A token used in message push listener verification. The value of the verificationToken parameter is a string which is passed along with the message push listener verification request as the X-OC-MPL-VERIFICATION header.

Note: The X-OC-MPL-VERIFICATION header is a header that the service sends to the endpoint.

Request Body: An XML document that specifies the following:

  • The URI to which to push messages, with any associated parameters to the push.

  • The selector, if any, the listener should apply to filter the messages it receives.

  • The existing durable subscription, if any, on which the listener should listen for messages.

  • The policy the listener should follow if an attempt to push a message fails.

Note:

The XML document should not contain a DOCTYPE declaration. If a DOCTYPE declaration is included in the XML document, a 500 operationFailed response is returned. This is done to prevent certain security and Denial of Service (DoS) attacks.

See Create a Message Push Listener for an example HTTP request which creates a message push listener.

The root of the document is <listener>. The root must contain a single <version> whose content is the version of the listener XML. For the current release, the version must be 1.0. The root must also contain exactly one <name> element whose content is listener name. The root may also contain a single <source> element whose content specifies the queue or topic on which the listener listens for messages. If present, its content must be one each of the following elements:

  • <type>

    The content must be either queue or topic.

  • <name>

    The name of the queue or topic.

If the <source> element is not present, the <listener> element must contain a <subscription> element. Note that the <source> element implicitly specifies a non-temporary queue or topic. Message push listeners may not listen on temporary queues or topics.

The root must contain exactly one <target> element, 0 or 1 <selector> elements, 0 or 1 <subscription> elements, and 0 or 1 <failurePolicy> elements; order of all child elements is irrelevant. If a <subscription> element is present, there can be neither a <source> nor a <selector> element, as both the destination and selector, if any, is determined by the subscription.

The <target> element specifies the URI to which the listener pushes messages; it must contain at most one of each of the following elements:

  • <uri>

    There must be exactly one such element. The content is the URI to which to push, which must be one of the following types:

    • An HTTP or HTTPS URL

    • A URN of the form urn:oracle:cloud:messaging:queues:queueName or urn:oracle:cloud:messaging:topics:topicName.

    A URI of the first type indicates that the listener should push to an HTTP or HTTPS endpoint. A URI of the second type indicates that the listener should send the message to a queue or topic; the fifth colon-separated component specifies whether the destination is a queue or topic, and the last colon-separated component specifies the name of the queue or topic. It is expected that targets of the latter form will usually occur as targets to which to push a message after an HTTP or HTTPS push has failed, but this is not required.

    Message push listeners will not follow HTTP redirects. An HTTP redirect response from a user-specified URL will be treated as an error as described in the explanation of the <failurePolicy> element below.

  • <method>

    The content is the HTTP method to use for the push if the <uri> contains an HTTP or HTTPS URI. Only the POST and PUT methods will work; the default is POST. This element is optional, and must be omitted if the URI is not an HTTP or HTTPS URI.

  • <user>

    The user to use for HTTP authentication if <uri> contains an HTTP or HTTP URI. This element is optional, and must be omitted if the URI is not an HTTP or HTTPS URI. There is no default value.

  • <password>

    The password to use for HTTP authentication if <uri> contains an HTTP or HTTP URI. This element must be present if and only if the <user> element is present. There is no default value.

The <target> element may contain an arbitrary number (including 0) of <header> elements; these elements are ignored if the target is not an HTTP or HTTPS target. Each <header> element must contain exactly one <name> and <value> element. The content specifies a value for the header with name given by the content of the <name> element and value given by the content of the <value> element. Multiple <header> elements with the same <name> content are allowed; those after the first with a given name add headers rather than overwriting the earlier headers. The <name> element's content may not begin with "X-OC-" (case-insensitive). The <name> element's content must be a legal HTTP header name and the <value> element's content must be a legal HTTP header value. If the <name> element contains Content-Type (case-insensitive), the value is ignored, unless the message being pushed has type HTTP and does not specify a Content-Type. Otherwise, the Content-Type header of a message push request is determined by the message. If the <name> element contains Content-Language (case-insensitive), the value assigned by the listener is overridden if the message being pushed has type HTTP and specifies the Content-Language.

The content of the <selector> element is used as the JMS selector for the listener. For the syntax of selectors, see the Message Selectors section of the Java API reference for the javax.jms.Message class.

The <subscription> element must contain one of each of the following elements:

  • <clientId>

    The content is the client ID of the durable subscription to use.

  • <name>

    The content is the name of the subscription.

If present, this element specifies an existing durable subscription whose messages the listener should receive and push.

Note:

If there is a listener listening on a durable subscription, no other client or listener is able to use the same client ID, even with a different subscription name. Thus, any client ID used with a listener should be dedicated to that listener, and only one durable subscription can be used for that client ID.

The <failurePolicy> element, if present, specifies what the listener does if its attempt to push a message to a URI fails. If no <failurePolicy> element is present, a message whose push fails is discarded. If present, <failurePolicy> must contain 0 or more <failure> elements. Each <failure> element specifies the kind of push failures to which it applies, and what to do in case of the given failure. If a push fails, the <failure> element that is first in document order that applies to the failure is used to determine what action is taken. If no <failure> element applies (in particular, if the <failurePolicy> element contains no <failure> elements), the message is discarded.

A <failure> element must contain exactly one <cond>. Its content must be one of the following:

  • connection: this value indicates that the <failure> element applies if the target URI was an HTTP or HTTPS URL and the listener was unable to establish a connection to the specified endpoint, or the host and port specified by the URL was not an HTTP endpoint.

  • responseCode:n-m, in which n and m are positive integers: a value of this form indicates that the <failure> element applies if the target URI was an HTTP or HTTPS URL, a connection was successfully made to the specified HTTP endpoint, and the response code is greater than or equal to n and less than or equal to m. Note that, regardless of the values of n and m, the <failure> element will only apply if the response status is 300 or greater. HTTP requests to push messages will not follow redirects, and will generate a responseCode error.

  • responseCode: n: this is equivalent to responseCode:n-n.

  • send: this value indicates that the <failure> element applies if the target URI was a URN specifying a queue or topic, and the attempt to send failed.

  • maxHops: this value indicates that the <failure> element applies if the target URI was a URN specifying a queue or topic, and the message had already been pushed by a listener to a queue or topic the maximum number of times allowed (currently 8).

  • any: this value indicates that the <failure> element applies to any of the above failure types.

A <failure> element may contain 0 or 1 <wait> elements.

The <wait> element must contain exactly one <time> element. The content of the <time> element must be a non-negative integer, and is interpreted as a number of milliseconds to wait before attempts to push the message again. The allowed content of a <wait> element, other than <time>, is the same as that of <listener>, except that <target> is not required. If there is no <target> element, it is equivalent to the <target> element being the same as that of the nearest enclosing <listener> or <wait> element. After waiting the specified wait time, the listener then behaves as if it were a listener whose content is that of the <wait>; it attempts to push the message to the URI specified by its <target>, and, if that fails, applies the failure policy specified by its <failurePolicy> child, if any. Note that the <failurePolicy> of the parent is not inherited; successive push attempts use the <failurePolicy> at the appropriate level. Thus, a listener will never retry forever; if all push attempts for a given message fail, the message will eventually be discarded.

If a message received by a listener is pushed to a queue or topic, the type and content of the message is preserved. All properties will also be preserved, with the following exceptions:

  • The X_OC_PushCount property will either be set to 1, if it is not present, is not an integer, or is a negative integer; otherwise, it will be incremented by 1. This property is used by listeners to track how many times the message has been re-sent to a queue or topic by a listener. If the incoming message's X_OC_PushCount is 8 or greater, and the listener is directed to push it to a queue or topic, it will instead cause a failure that can be handled by a <failure> element containing a <cond>maxHops</cond> element.

  • The ID of the received message is set as the X_OC_PastJMSMessageIDN property of the outgoing message, where N is 1 less than the value of the X_OC_PushCount property on the outgoing message.

  • The destination header of the received message, expressed as a String of the form /queues/queueName or /topics/topicName, is set as the X_OC_PastJMSDestinationN property of the outgoing message (N as above).

  • The value of the timestamp header of the received message is set as the X_OC_PastJMSTimestampN property of the outgoing message (N as above).

  • The value of the "redelivered" header of the received message is set as the X_OC_PastJMSRedeliveredN property of the outgoing message (N as above).

The correlation ID, reply-to, and delivery mode of the received message is set as the corresponding headers of the outgoing message. The message is sent with a time-to-live that will make it expire at roughly the same time as the received message.

For example:

<listener>
    <version>1.0</version>
    <name>myListener</name>
    <source>
        <type>queue</type>
        <name>myQueue</name>
    </source>
    <target>
        <uri>http://myHost/receiver</uri>
        <method>PUT</method>
        <user>u</user>
        <password>guest</password>
        <header>
            <name>X-PIN</name>
            <value>123456</value>
        </header>
    </target>
    <selector>(urgency = 'high') AND (count &lt; 5)</selector>
    <failurePolicy>
        <failure>
            <cond>connection</cond>
            <wait>
                <time>5000</time>
                <failurePolicy>
                    <failure>
                        <cond>any</cond>
                        <wait>
                            <time>0</time>
                            <target>
                                <uri>http://myBackupHost/deadLetter</uri>
                            </target>
                        </wait>
                    </failure>
                </failurePolicy>
            </wait>
        </failure>
        <failure>
            <cond>responseCode:500-599</cond>
            <wait>
                <time>0</time>
                <target>
                    <uri>http://myBackupHost/deadLetter</uri>
                </target>
            </wait>
        </failure>
        <failure>
            <cond>responseCode:401-499</cond>
            <wait>
                <time>0</time>
                <target>
                    <uri>urn:oracle:cloud:messaging:queues:unpushed</uri>
                </target>
                <failurePolicy>
                    <failure>
                        <cond>send</cond>
                        <wait>
                            <time>0</time>
                            <target>
                                <uri>urn:oracle:cloud:messaging:topics:backup</uri>
                            </target>
                        </wait>
                    </failure>
                </failurePolicy>
            </wait>
        </failure>
    </failurePolicy>
</listener>

This listener listens for messages sent to the queue myQueue whose urgency property has the value high and whose count property has value less than 5. (The urgency and count properties of a message sent via the REST API, if present, would be set to the value of the X-OC-type-PROPERTY-urgency and X-OC-type-PROPERTY-count headers, respectively, of the HTTP request that created it, if present. The type parts of the two property headers might be, for example, STRING for urgency and INT for count.) The listener attempts to push messages it receives to http://myHost/receiver with method PUT, user and password u and guest respectively, and header X-PIN: 123456. If it cannot connect, it waits for 5 seconds and tries again. If that fails in any way, it immediately attempts to push to http://myBackupHost/deadLetter, with method POST, no HTTP authentication credentials, and no special headers. If the second push fails in any way, the message is discarded. If the initial push fails with response status code in the range 500-599, the listener will immediately attempt a push to http://myBackupHost/deadLetter as above. If that fails, the message is discarded. If the initial push fails with response status code in the range 401-499, the listener will immediately attempt a push to a queue with name unpushed. If that fails, the listener will attempt to push the message to a topic called backup, discarding the message if that fails. If the initial push failed for any other reason (for example, response code of exactly 400), the message is discarded.

The following is an example with a durable subscription:

<listener>
    <version>1.0</version>
    <name>myListener</name>
    <target>
        <uri>http://myHost/receiver</uri>
        <method>PUT</method>
        <user>u</user>
        <password>guest</password>
        <header>
            <name>X-PIN</name>
            <value>123456</value>
        </header>
    </target>
    <subscription>
        <clientId>myListenerID</clientId>
        <name>sub</name>
    </subscription>
    <failurePolicy>
        <failure>
            <cond>connection</cond>
            <wait>
                <time>5000</time>
                <failurePolicy>
                    <failure>
                        <cond>any</cond>
                        <wait>
                            <time>0</time>
                            <target>
                                <uri>http://myBackupHost/deadLetter</uri>
                            </target>
                        </wait>
                    </failure>
                </failurePolicy>
            </wait>
        </failure>
        <failure>
            <cond>responseCode:500-599</cond>
            <wait>
                <time>0</time>
                <target>
                    <uri>http://myBackupHost/deadLetter</uri>
                </target>
            </wait>
        </failure>
        <failure>
            <cond>responseCode:401-499</cond>
            <wait>
                <time>0</time>
                <target>
                    <uri>urn:oracle:cloud:messaging:queues:unpushed</uri>
                </target>
                <failurePolicy>
                    <failure>
                        <cond>send</cond>
                        <wait>
                            <time>0</time>
                            <target>
                                <uri>urn:oracle:cloud:messaging:topics:backup</uri>
                            </target>
                        </wait>
                    </failure>
                </failurePolicy>
            </wait>
        </failure>
    </failurePolicy>
</listener>

This listener is the same as the previous one, except that the topic it listens on and the selector, if any, are taken from an existing durable subscription with client ID myListenerID and name sub.

Result: Creates a listener with name listenerName.

Error Responses:

Error Message Description

nonexistentNamespace

The specified namespace does not exist.

nonexistentNamespaceComponents

The namespace specified for the request does not exist.

nonexistentNamespaceUnknown

The namespace specified in the request URL does not exist.

malformedListener

One of the following occurred:

  • Neither a source nor a durable subscription was specified in the XML.

  • The listener XML did not conform to the syntax described in Create a Listener.

destinationParameterNotFound

The source specified on which the listener should listen does not exist.

subscriptionParameterNotFound

The request body specified a subscription from which to receive, and the subscription does not exist.

subscriptionNotFoundNoInfo

The request body specified a subscription from which to receive, and the subscription does not exist.

listenerAlreadyExists

A listener with the given name already exists.

clientIdFailure

The listener XML specifies a listener on a durable subscription whose client ID is invalid or in use by some client or other listener.

messagePushListenerVerificationBadResponse

An HTTP or HTTPS endpoint responded to a verification request with a response body that did not match the challenge token sent by Oracle Messaging Cloud Service.

messagePushListenerVerificationConnectionFailed

Oracle Messaging Cloud Service was unable to connect to an HTTP or HTTPS endpoint to send a verification request.

messagePushListenerVerificationErrorResponse

An HTTP or HTTPS endpoint responded to a verification request with a status code other than 200.

messagePushListenerVerificationException

An exception occurred in attempting to read the response to a verification request.

messagePushListenerVerificationNoToken

The listener XML specifies at least one HTTP or HTTPS URL to which to push messages, but no verificationToken was supplied.

messagePushListenerVerificationRedirectionDisableFailed

A failed attempt was made to disable HTTP redirects for the message push listener verification request.

operationFailed

A low-level exception was thrown while checking for a pre-existing listener, or while creating the listener.

Delete a Listener

This topic provides information about deleting a listener.

Method: DELETE

Path: /listeners/listenerName

Scope: Service Instance

Authorization: Messaging Administrator or Messaging Worker

Result: Deletes listener with name listenerName

Error Responses:

Error Message Description

nonexistentNamespace

The specified namespace does not exist.

nonexistentNamespaceComponents

The namespace specified for the request does not exist.

nonexistentNamespaceUnknown

The namespace specified in the request URL does not exist.

listenerNotFound

The listener to delete did not exist.

operationFailed

A low-level exception was thrown while deleting the listener.

List Listeners

This section provides information about listing listeners.

Method: GET

Path: /listeners

Scope: Service Instance

Authorization: Messaging Administrator or Messaging Worker

Request Parameter:

Parameter Description

destination

Optional. If present, value must be /queues/queueName or /topics/topicName. Specifies a destination whose listeners should be listed.

Result: Returns a list of all listeners created for the namespace if there is no destination parameter, and a list of all listeners on the destination specified by destination otherwise.

Response Body: XML format with one <items> element for each listener and a <canonicalLink> element. 

<listeners>
    <items>
        <name>listener name</name>
        <canonicalLink>relative path to access /listeners/listener name</canonicalLink>
    </items>
    ....
    <canonicalLink>relative path to access /listeners</canonicalLink>
</listeners>

Error Responses:

Error Message Description

malformedDestination

The destination parameter value did not parse as a specification of a queue or topic.

nonexistentNamespace

The specified namespace does not exist.

nonexistentNamespaceComponents

The namespace specified for the request does not exist.

nonexistentNamespaceUnknown

The namespace specified in the request URL does not exist.

destinationParameterNotFound

The destination parameter specified a destination that does not exist.

operationFailed

An exception was thrown while getting the list of listeners or outputting the XML representation of the listeners.

Retrieve Listener Properties

This section provides information about retrieving listener properties.

Method: GET

Path: /listeners/listenerName

Scope: Service Instance

Authorization: Messaging Administrator or Messaging Worker

Result: Returns properties of the listener with name listenerName.

Response Body: An XML document in the format used in the request body to create the listener, describing the listener with name listenerName.

Error Responses:

Error Message Description

nonexistentNamespace

The specified namespace does not exist.

nonexistentNamespaceComponents

The namespace specified for the request does not exist.

nonexistentNamespaceUnknown

The namespace specified in the request URL does not exist.

listenerNotFound

The specified listener does not exist.

operationFailed

A low-level exception was thrown while retrieving the listener properties.