REST API for Oracle Messaging Cloud Service

Create a Listener

put

/listeners/{listenerName}

Create a listener with the supplied name.

Request

Supported Media Types

application/xml

Path Parameters

listenerName: string

The name of the listener

Query Parameters

verificationToken: string

Required. A token used to verify that a URL is willing to accept messages pushed from a listener. The token is a string which is passed along with the message push listener verification request as the X-OC-MPL-VERIFICATION header. See the About Verification of Message Push Listeners for details on message push listener verification.

The XML definition of the listener to be created. See the 'Examples' tab for a description of the XML for listeners.

Root Schema : schema

Type: string

XML definition of the listener to be created. See 'Examples' for details

Response

201 Response

Listener was created.

400 Response

The listener was not created for one of the following reasons:

The destination parameter value did not parse as a specification of a queue or topic.
The message push listener specification did not have the proper syntax or the source specified on which the listener should listen does not exist.
The request body specified a subscription from which to receive, but the subscription does not exist.
The client ID submitted is invalid or is already in use, either by a listener, another client, or by the current client.
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.
Oracle Messaging Cloud Service was unable to connect to an HTTP or HTTPS endpoint to send a verification request.
An HTTP or HTTPS endpoint responded to a verification request with a status code other than 200.
An exception occurred in attempting to read the response to a verification request, or the listener XML specifies at least one HTTP or HTTPS URL to which to push messages, but no verificationToken was supplied.

409 Response

The listener was not created because a listener with the same name already exists.

500 Response

The listener was not created for one of the following reasons:

A failed attempt was made to disable HTTP redirects for the message push listener verification request.
A low-level exception was thrown while checking for a pre-existing listener, or while creating the listener.

Examples

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 below 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.

Create a Message Push Listener

The example shows an HTTP request and response for a message push listener named l being created.

Request to create a listener named l.

PUT /MCSService03-MCSOracle3/api/v1/listeners/l HTTP/1.1
X-OC-ID-TOKEN-STATUS: disabled
Authorization: Basic YXd1c2VyOldlbGNvbWVfMQ==
Content-Type: application/xml
Accept: application/json, application/xml;q=0.8, */*;q=0.5
Content-Length: 286

<?xml version="1.0" encoding="UTF-8"?>
<listener>
    <version>1.0</version>
    <name>l</name>
    <source>
        <type>topic</type>
        <name>Incoming</name>
    </source>
    <target>
        <uri>urn:oracle:cloud:messaging:queues:Preprocessing</uri>
    </target>
</listener>

Note:

The X-OC-ID-TOKEN-STATUS header indicates that the anti-CSRF token is disabled.
The Authorization header indicates that the authentication type is Basic.
The Accept header accepts JSON (most preferable), or XML (second preference), or anything else (least preferable).
The Content-Type header indicates that body of the request is in XML.
The XML body of the request indicates the properties of the listener. The listener receives messages from the topic Incoming and sends them to the queue Preprocessing.

Note:

Successful response.

HTTP/1.1 201 Created
Cache-Control: no-cache;no-store;must-revalidate;max-age=0
Content-Length: 0
X-OC-NEW-MESSAGING-CONTEXT: true
Set-Cookie: JSESSIONID=MLyKTrjTh62Hb1PGkwCFGrrLc5p2sVdl8vv1WD5CzdNXTtppJJCZ!-1133198190; path=/; HttpOnly

Note:

A listener named l is created by the request.
The Cache-Control header indicates that the response should not be cached.
The X-OC-NEW-MESSAGING-CONTEXT header indicates that the request created a new messaging context.
The Set-Cookie header provides the JSESSIONID cookie that must be sent in future requests in order to use the same connection.