NO-JIRA STOMP doc updates
Project: http://git-wip-us.apache.org/repos/asf/activemq-artemis/repo Commit: http://git-wip-us.apache.org/repos/asf/activemq-artemis/commit/849b8397 Tree: http://git-wip-us.apache.org/repos/asf/activemq-artemis/tree/849b8397 Diff: http://git-wip-us.apache.org/repos/asf/activemq-artemis/diff/849b8397 Branch: refs/heads/master Commit: 849b83972f540ad237f39433e0ed53b677829b2a Parents: 75a4162 Author: Justin Bertram <[email protected]> Authored: Fri Mar 10 15:23:40 2017 -0600 Committer: Clebert Suconic <[email protected]> Committed: Tue Mar 14 17:09:52 2017 -0400 ---------------------------------------------------------------------- .../en/protocols-interoperability.md | 111 ++++++++++++------- 1 file changed, 73 insertions(+), 38 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/849b8397/docs/user-manual/en/protocols-interoperability.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/protocols-interoperability.md b/docs/user-manual/en/protocols-interoperability.md index 5d7aa3e..b4d57c3 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,7 +428,29 @@ 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 +#### Message IDs for Stomp messages + +When receiving Stomp messages via a JMS consumer or a QueueBrowser, the +messages have no properties like JMSMessageID by default. However this +may bring some inconvenience to clients who wants an ID for their +purpose. Apache ActiveMQ Artemis Stomp provides a parameter to enable message ID on +each incoming Stomp message. If you want each Stomp message to have a +unique ID, just set the `stompEnableMessageId` to true. For example: + + <acceptor name="stomp-acceptor">tcp://localhost:61613?protocols=STOMP;stompEnableMessageId=true</acceptor> + +When the server starts with the above setting, each stomp message sent +through this acceptor will have an extra property added. The property +key is ` + amq-message-id` and the value is a String representation of a +long type internal message id prefixed with "`STOMP`", like: + + amq-message-id : STOMP12345 + +If `stomp-enable-message-id` is not specified in the configuration, +default is `false`. + +### Durable Subscriptions The `SUBSCRIBE` and `UNSUBSCRIBE` frames can be augmented with special headers to create and destroy durable subscriptions respectively. @@ -408,16 +465,16 @@ these headers should match what was set on the `SUBSCRIBE` frame to delete the c 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: +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: ~~~ <core xmlns="urn:activemq:core"> ... - <addresses> - <address name="myTopic"> + <addresses> + <address name="myAddress"> <multicast> <queue name="myclientid.mysubscription"/> </multicast> @@ -427,31 +484,9 @@ name of `mysubscriptionname` then configure the durable subscription: </core> ~~~ -#### Message IDs for Stomp messages - -When receiving Stomp messages via a JMS consumer or a QueueBrowser, the -messages have no properties like JMSMessageID by default. However this -may bring some inconvenience to clients who wants an ID for their -purpose. Apache ActiveMQ Artemis Stomp provides a parameter to enable message ID on -each incoming Stomp message. If you want each Stomp message to have a -unique ID, just set the `stompEnableMessageId` to true. For example: - - <acceptor name="stomp-acceptor">tcp://localhost:61613?protocols=STOMP;stompEnableMessageId=true</acceptor> - -When the server starts with the above setting, each stomp message sent -through this acceptor will have an extra property added. The property -key is ` - amq-message-id` and the value is a String representation of a -long type internal message id prefixed with "`STOMP`", like: - - amq-message-id : STOMP12345 - -If `stomp-enable-message-id` is not specified in the configuration, -default is `false`. - -#### Handling of Large Messages with Stomp +### Handling of Large Messages with Stomp -Stomp clients may send very large bodys of frames which can exceed the +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
