From 849b83972f540ad237f39433e0ed53b677829b2a Mon Sep 17 00:00:00 2001 From: Justin Bertram Date: Fri, 10 Mar 2017 15:23:40 -0600 Subject: [PATCH] NO-JIRA STOMP doc updates --- .../en/protocols-interoperability.md | 121 +++++++++++------- 1 file changed, 78 insertions(+), 43 deletions(-) diff --git a/docs/user-manual/en/protocols-interoperability.md b/docs/user-manual/en/protocols-interoperability.md index 5d7aa3e339..b4d57c30cb 100644 --- a/docs/user-manual/en/protocols-interoperability.md +++ b/docs/user-manual/en/protocols-interoperability.md @@ -280,18 +280,53 @@ set). Apache ActiveMQ Artemis currently doesn't support virtual hosting, which means the 'host' header in CONNECT fram will be ignored. -### Mapping Stomp destinations to Apache ActiveMQ Artemis addresses and queues +### Mapping Stomp destinations to addresses and queues Stomp clients deals with *destinations* when sending messages and subscribing. Destination names are simply strings which are mapped to some form of destination on the server - how the server translates these is left to the server implementation. -In Apache ActiveMQ Artemis, these destinations are mapped to *addresses* and *queues*. -When a Stomp client sends a message (using a `SEND` frame), the -specified destination is mapped to an address. When a Stomp client -subscribes (or unsubscribes) for a destination (using a `SUBSCRIBE` or -`UNSUBSCRIBE` frame), the destination is mapped to an Apache ActiveMQ Artemis queue. +In Apache ActiveMQ Artemis, these destinations are mapped to *addresses* and *queues* +depending on the operation being done and the desired semantics (e.g. anycast or +multicast). + +#### Sending + +When a Stomp client sends a message (using a `SEND` frame), the protocol manager looks +at the message to determine where to route it and potentially how to create the address +and/or queue to which it is being sent. The protocol manager uses either of the following +bits of information from the frame to determine the routing type: + +1. The value of the `destination-type` header. Valid values are `ANYCAST` and +`MULTICAST` (case sensitive). + +2. The "prefix" on the `destination` header. See [additional info](address-model.md) on +prefixes. + +If no indication of routing type is supplied then anycast semantics are used. + +The `destination` header maps to an address of the same name. If the `destination` header +used a prefix then the prefix is stripped. + +#### Subscribing + +When a Stomp client subscribes to a destination (using a `SUBSCRIBE` frame), the protocol +manager looks at the frame to determine what subscription semantics to use and potentially how +to create the address and/or queue for the subscription. The protocol manager uses either of +the following bits of information from the frame to determine the routing type: + +1. The value of the `subscription-type` header. Valid values are `ANYCAST` and +`MULTICAST` (case sensitive). + +2. The "prefix" on the `destination` header. See [additional info](address-model.md) on +prefixes. + +If no indication of routing type is supplied then anycast semantics are used. + +The `destination` header maps to an address of the same name if multicast is used or to a queue +of the same name if anycast is used. If the `destination` header used a prefix then the prefix +is stripped. ### STOMP heart-beating and connection-ttl @@ -393,40 +428,6 @@ The same logic applies when mapping a JMS message or a Core message to Stomp. A Stomp 1.0 client can check the presence of the `content-length` header to determine the type of the message body (String or bytes). -#### Durable Subscriptions - -The `SUBSCRIBE` and `UNSUBSCRIBE` frames can be augmented with special headers to create -and destroy durable subscriptions respectively. - -To create a durable subscription the `client-id` header must be set on the `CONNECT` frame -and the `durable-subscription-name` must be set on the `SUBSCRIBE` frame. The combination -of these two headers will form the identity of the durable subscription. - -To delete a durable subscription the `client-id` header must be set on the `CONNECT` frame -and the `durable-subscription-name` must be set on the `UNSUBSCRIBE` frame. The values for -these headers should match what was set on the `SUBSCRIBE` frame to delete the corresponding -durable subscription. - -It is possible to pre-configure durable subscriptions since the Stomp implementation creates -the queue used for the durable subscription in a deterministic way (i.e. using the format of -`client-id`.`subscription-name`). For example, if you wanted to configure a durable -subscription on the JMS topic `myTopic` with a client-id of `myclientid` and a subscription -name of `mysubscriptionname` then configure the durable subscription: - -~~~ - - ... - -
- - - -
- - ... - -~~~ - #### Message IDs for Stomp messages When receiving Stomp messages via a JMS consumer or a QueueBrowser, the @@ -449,9 +450,43 @@ long type internal message id prefixed with "`STOMP`", like: If `stomp-enable-message-id` is not specified in the configuration, default is `false`. -#### Handling of Large Messages with Stomp +### Durable Subscriptions -Stomp clients may send very large bodys of frames which can exceed the +The `SUBSCRIBE` and `UNSUBSCRIBE` frames can be augmented with special headers to create +and destroy durable subscriptions respectively. + +To create a durable subscription the `client-id` header must be set on the `CONNECT` frame +and the `durable-subscription-name` must be set on the `SUBSCRIBE` frame. The combination +of these two headers will form the identity of the durable subscription. + +To delete a durable subscription the `client-id` header must be set on the `CONNECT` frame +and the `durable-subscription-name` must be set on the `UNSUBSCRIBE` frame. The values for +these headers should match what was set on the `SUBSCRIBE` frame to delete the corresponding +durable subscription. + +It is possible to pre-configure durable subscriptions since the Stomp implementation creates +the queue used for the durable subscription in a deterministic way (i.e. using the format of +`client-id`.`subscription-name`). For example, if you wanted to configure a durable +subscription on the address `myAddress` with a client-id of `myclientid` and a subscription +name of `mysubscription` then configure the durable subscription: + +~~~ + + ... + +
+ + + +
+ + ... + +~~~ + +### Handling of Large Messages with Stomp + +Stomp clients may send very large frame bodies which can exceed the size of Apache ActiveMQ Artemis server's internal buffer, causing unexpected errors. To prevent this situation from happening, Apache ActiveMQ Artemis provides a stomp configuration attribute `stompMinLargeMessageSize`. This attribute @@ -465,7 +500,7 @@ Stomp frame arrived from connections established with this acceptor. If the size of the body is equal or greater than the value of `stompMinLargeMessageSize`, the message will be persisted as a large message. When a large message is delievered to a stomp consumer, the -HorentQ server will automatically handle the conversion from a large +broker will automatically handle the conversion from a large message to a normal message, before sending it to the client. If a large message is compressed, the server will uncompressed it before