[GitHub] qpid-dispatch pull request #218: DISPATCH-875 - Doc new "pattern" attribute
Github user asfgit closed the pull request at: https://github.com/apache/qpid-dispatch/pull/218 --- - To unsubscribe, e-mail: dev-unsubscr...@qpid.apache.org For additional commands, e-mail: dev-h...@qpid.apache.org
[GitHub] qpid-dispatch pull request #218: DISPATCH-875 - Doc new "pattern" attribute ...
Github user kgiusti commented on a diff in the pull request: https://github.com/apache/qpid-dispatch/pull/218#discussion_r151715642 --- Diff: doc/new-book/routing.adoc --- @@ -213,15 +213,17 @@ address { } -`prefix` | `pattern`:: The address or group of addresses to which the address settings should be applied. You can specify a prefix to match an exact address or segment of an address. Alternatively, you can specify a pattern to match an address using wildcards. +`prefix` | `pattern`:: The address or group of addresses to which the address settings should be applied. You can specify a prefix to match an exact address or beginning segment of an address. Alternatively, you can specify a pattern to match an address using wildcards. + //tag::prefix-matching[] -A _prefix_ matches either an exact address or a segment within an address that is delimited by either a `.` or `/` character. For example, the prefix `my_address` would match the address `my_address` as well as `my_address.1` and `my_address/1`. However, it would not match `my_address1`. +A _prefix_ matches either an exact address or the beginning segment within an address that is delimited by either a `.` or `/` character. For example, the prefix `my_address` would match the address `my_address` as well as `my_address.1` and `my_address/1`. However, it would not match `my_address1`. //end::prefix-matching[] + //tag::pattern-matching[] A _pattern_ matches an address that corresponds to a pattern. A pattern is a sequence of words delimited by either a `.` or `/` character. You can use wildcard characters to represent a word. The `*` character matches exactly one word, and the `#` character matches any sequence of zero or more words. + +The pattern configuration and the address(es) that match the pattern should use the same delimiter character. For example, if you configure the pattern to be `my.+`, then the addresses that match the pattern should also use a `.` as a delimiter (instead of a `/`). --- End diff -- Yes I agree on that change - but there's a typo in that last paragraph: / is not a wildcard, # is. --- - To unsubscribe, e-mail: dev-unsubscr...@qpid.apache.org For additional commands, e-mail: dev-h...@qpid.apache.org
[GitHub] qpid-dispatch pull request #218: DISPATCH-875 - Doc new "pattern" attribute ...
Github user bhardesty commented on a diff in the pull request: https://github.com/apache/qpid-dispatch/pull/218#discussion_r151542358 --- Diff: doc/new-book/routing.adoc --- @@ -213,15 +213,17 @@ address { } -`prefix` | `pattern`:: The address or group of addresses to which the address settings should be applied. You can specify a prefix to match an exact address or segment of an address. Alternatively, you can specify a pattern to match an address using wildcards. +`prefix` | `pattern`:: The address or group of addresses to which the address settings should be applied. You can specify a prefix to match an exact address or beginning segment of an address. Alternatively, you can specify a pattern to match an address using wildcards. + //tag::prefix-matching[] -A _prefix_ matches either an exact address or a segment within an address that is delimited by either a `.` or `/` character. For example, the prefix `my_address` would match the address `my_address` as well as `my_address.1` and `my_address/1`. However, it would not match `my_address1`. +A _prefix_ matches either an exact address or the beginning segment within an address that is delimited by either a `.` or `/` character. For example, the prefix `my_address` would match the address `my_address` as well as `my_address.1` and `my_address/1`. However, it would not match `my_address1`. //end::prefix-matching[] + //tag::pattern-matching[] A _pattern_ matches an address that corresponds to a pattern. A pattern is a sequence of words delimited by either a `.` or `/` character. You can use wildcard characters to represent a word. The `*` character matches exactly one word, and the `#` character matches any sequence of zero or more words. + +The pattern configuration and the address(es) that match the pattern should use the same delimiter character. For example, if you configure the pattern to be `my.+`, then the addresses that match the pattern should also use a `.` as a delimiter (instead of a `/`). --- End diff -- It sounds like I can just remove line 225 then. While it makes sense to just use a single delimiter character (i.e. either "." or "/" but not both), it sounds like Dispatch will still route messages correctly if the address and configured pattern use a mixture of both types of delimiters. Instead of line 225, I think we need a different statement about not using reserved characters in message addresses. What do you think about this (including the previous para for context): > A pattern matches an address that corresponds to a pattern. A pattern is a sequence of words delimited by either a `.` or `/` character. You can use wildcard characters to represent a word. The `*` character matches exactly one word, and the `#` character matches any sequence of zero or more words. > The `*` and `/` characters are reserved as wildcards. Therefore, you should not use them in the message address. --- - To unsubscribe, e-mail: dev-unsubscr...@qpid.apache.org For additional commands, e-mail: dev-h...@qpid.apache.org
[GitHub] qpid-dispatch pull request #218: DISPATCH-875 - Doc new "pattern" attribute ...
Github user kgiusti commented on a diff in the pull request: https://github.com/apache/qpid-dispatch/pull/218#discussion_r151509115 --- Diff: doc/new-book/routing.adoc --- @@ -213,15 +213,17 @@ address { } -`prefix` | `pattern`:: The address or group of addresses to which the address settings should be applied. You can specify a prefix to match an exact address or segment of an address. Alternatively, you can specify a pattern to match an address using wildcards. +`prefix` | `pattern`:: The address or group of addresses to which the address settings should be applied. You can specify a prefix to match an exact address or beginning segment of an address. Alternatively, you can specify a pattern to match an address using wildcards. + //tag::prefix-matching[] -A _prefix_ matches either an exact address or a segment within an address that is delimited by either a `.` or `/` character. For example, the prefix `my_address` would match the address `my_address` as well as `my_address.1` and `my_address/1`. However, it would not match `my_address1`. +A _prefix_ matches either an exact address or the beginning segment within an address that is delimited by either a `.` or `/` character. For example, the prefix `my_address` would match the address `my_address` as well as `my_address.1` and `my_address/1`. However, it would not match `my_address1`. //end::prefix-matching[] + //tag::pattern-matching[] A _pattern_ matches an address that corresponds to a pattern. A pattern is a sequence of words delimited by either a `.` or `/` character. You can use wildcard characters to represent a word. The `*` character matches exactly one word, and the `#` character matches any sequence of zero or more words. + +The pattern configuration and the address(es) that match the pattern should use the same delimiter character. For example, if you configure the pattern to be `my.+`, then the addresses that match the pattern should also use a `.` as a delimiter (instead of a `/`). --- End diff -- Yeah that seems likely. However on re-reading line 225 I'm not sure what it describes is actually correct. There really isn't a standard for the format of addresses. A proposal was made to define the '/' character as a separator for hierarchical addresses, but that never reached consensus. In the meantime, dispatch tended to use "." as a separator when comparing address prefixes. Later when the proposal surfaced dispatch was changed to allow either '.' or '/' as separators, preserving backward compatibility and anticipating future uses. The new pattern matching feature follows the same behavior: either '.' or '/' as a separator. But that complicates things a bit, since the code can't be sure of the intent when both '.' and '/' appear in a message's address. Should '.' designate a token boundary, or should '/'? In the end the router treats them both as separators *but* does not compare the separators themselves when pattern matching the address. As an example, let's assume the following pattern is configured: a.b/c.d Dispatch's token parser is going to split this up into the following token sequence: a, b, c, d effectively stripping away the separators before the comparison is done. So the above a.b/c.d pattern would match the following message addresses: a.b.c/d a/b/c/d a.b.c.d So for the purpose of documentation: 1 both '.' and '/' are considered separators when determining words (tokens) both in the configured pattern and in incoming message addresses. 2 all '.' and '/' are ignored when comparing a message's address to a configured pattern. This means a message with address 'a.b.c' will match the pattern 'a/b/*' 3 asterisk and hash are reserved characters and must not appear in a message's address (note: _address_, not _pattern_). Therefore a message with a to: address of 'a.#.b' may not be routed properly. --- - To unsubscribe, e-mail: dev-unsubscr...@qpid.apache.org For additional commands, e-mail: dev-h...@qpid.apache.org
[GitHub] qpid-dispatch pull request #218: DISPATCH-875 - Doc new "pattern" attribute ...
Github user bhardesty commented on a diff in the pull request: https://github.com/apache/qpid-dispatch/pull/218#discussion_r151506496 --- Diff: doc/new-book/routing.adoc --- @@ -213,15 +213,17 @@ address { } -`prefix` | `pattern`:: The address or group of addresses to which the address settings should be applied. You can specify a prefix to match an exact address or segment of an address. Alternatively, you can specify a pattern to match an address using wildcards. +`prefix` | `pattern`:: The address or group of addresses to which the address settings should be applied. You can specify a prefix to match an exact address or beginning segment of an address. Alternatively, you can specify a pattern to match an address using wildcards. + //tag::prefix-matching[] -A _prefix_ matches either an exact address or a segment within an address that is delimited by either a `.` or `/` character. For example, the prefix `my_address` would match the address `my_address` as well as `my_address.1` and `my_address/1`. However, it would not match `my_address1`. +A _prefix_ matches either an exact address or the beginning segment within an address that is delimited by either a `.` or `/` character. For example, the prefix `my_address` would match the address `my_address` as well as `my_address.1` and `my_address/1`. However, it would not match `my_address1`. //end::prefix-matching[] + //tag::pattern-matching[] A _pattern_ matches an address that corresponds to a pattern. A pattern is a sequence of words delimited by either a `.` or `/` character. You can use wildcard characters to represent a word. The `*` character matches exactly one word, and the `#` character matches any sequence of zero or more words. + +The pattern configuration and the address(es) that match the pattern should use the same delimiter character. For example, if you configure the pattern to be `my.+`, then the addresses that match the pattern should also use a `.` as a delimiter (instead of a `/`). --- End diff -- That's correct - it's a typo. I fixed it ("my.+" is now "my.*"). --- - To unsubscribe, e-mail: dev-unsubscr...@qpid.apache.org For additional commands, e-mail: dev-h...@qpid.apache.org
[GitHub] qpid-dispatch pull request #218: DISPATCH-875 - Doc new "pattern" attribute ...
Github user jdanekrh commented on a diff in the pull request: https://github.com/apache/qpid-dispatch/pull/218#discussion_r151467622 --- Diff: doc/new-book/routing.adoc --- @@ -213,15 +213,17 @@ address { } -`prefix` | `pattern`:: The address or group of addresses to which the address settings should be applied. You can specify a prefix to match an exact address or segment of an address. Alternatively, you can specify a pattern to match an address using wildcards. +`prefix` | `pattern`:: The address or group of addresses to which the address settings should be applied. You can specify a prefix to match an exact address or beginning segment of an address. Alternatively, you can specify a pattern to match an address using wildcards. + //tag::prefix-matching[] -A _prefix_ matches either an exact address or a segment within an address that is delimited by either a `.` or `/` character. For example, the prefix `my_address` would match the address `my_address` as well as `my_address.1` and `my_address/1`. However, it would not match `my_address1`. +A _prefix_ matches either an exact address or the beginning segment within an address that is delimited by either a `.` or `/` character. For example, the prefix `my_address` would match the address `my_address` as well as `my_address.1` and `my_address/1`. However, it would not match `my_address1`. //end::prefix-matching[] + //tag::pattern-matching[] A _pattern_ matches an address that corresponds to a pattern. A pattern is a sequence of words delimited by either a `.` or `/` character. You can use wildcard characters to represent a word. The `*` character matches exactly one word, and the `#` character matches any sequence of zero or more words. + +The pattern configuration and the address(es) that match the pattern should use the same delimiter character. For example, if you configure the pattern to be `my.+`, then the addresses that match the pattern should also use a `.` as a delimiter (instead of a `/`). --- End diff -- I think the '+' is a typo and '*' was intended. --- - To unsubscribe, e-mail: dev-unsubscr...@qpid.apache.org For additional commands, e-mail: dev-h...@qpid.apache.org
[GitHub] qpid-dispatch pull request #218: DISPATCH-875 - Doc new "pattern" attribute ...
Github user kgiusti commented on a diff in the pull request: https://github.com/apache/qpid-dispatch/pull/218#discussion_r151441999 --- Diff: doc/new-book/routing.adoc --- @@ -213,15 +213,17 @@ address { } -`prefix` | `pattern`:: The address or group of addresses to which the address settings should be applied. You can specify a prefix to match an exact address or segment of an address. Alternatively, you can specify a pattern to match an address using wildcards. +`prefix` | `pattern`:: The address or group of addresses to which the address settings should be applied. You can specify a prefix to match an exact address or beginning segment of an address. Alternatively, you can specify a pattern to match an address using wildcards. + //tag::prefix-matching[] -A _prefix_ matches either an exact address or a segment within an address that is delimited by either a `.` or `/` character. For example, the prefix `my_address` would match the address `my_address` as well as `my_address.1` and `my_address/1`. However, it would not match `my_address1`. +A _prefix_ matches either an exact address or the beginning segment within an address that is delimited by either a `.` or `/` character. For example, the prefix `my_address` would match the address `my_address` as well as `my_address.1` and `my_address/1`. However, it would not match `my_address1`. //end::prefix-matching[] + //tag::pattern-matching[] A _pattern_ matches an address that corresponds to a pattern. A pattern is a sequence of words delimited by either a `.` or `/` character. You can use wildcard characters to represent a word. The `*` character matches exactly one word, and the `#` character matches any sequence of zero or more words. + +The pattern configuration and the address(es) that match the pattern should use the same delimiter character. For example, if you configure the pattern to be `my.+`, then the addresses that match the pattern should also use a `.` as a delimiter (instead of a `/`). --- End diff -- "my.+" - did you intend to use '+' as a token? I'd avoid using '+' as an example since in the future we may want to support MQTT compatible wildcards, which use '+' as a wildcard value. --- - To unsubscribe, e-mail: dev-unsubscr...@qpid.apache.org For additional commands, e-mail: dev-h...@qpid.apache.org
[GitHub] qpid-dispatch pull request #218: DISPATCH-875 - Doc new "pattern" attribute ...
Github user kgiusti commented on a diff in the pull request: https://github.com/apache/qpid-dispatch/pull/218#discussion_r151167247 --- Diff: doc/new-book/routing.adoc --- @@ -288,11 +307,13 @@ address { } -`prefix`:: The address prefix that matches the broker queue to which you want to route messages. +`prefix` | `pattern`:: The address prefix that matches the broker queue to which you want to route messages. + -//tag::prefix-matching[] -The prefix can match either an exact address or a segment within an address that is delimited by either a `.` or `/` character. For example, the prefix `my_address` would match the address `my_address` as well as `my_address.1` and `my_address/1`. However, it would not match `my_address1`. -//end::prefix-matching[] +The address prefix or pattern that matches the broker queue to which you want to send messages. You can specify a prefix to match an exact address or segment of an address. Alternatively, you can specify a pattern to match an address using wildcards. --- End diff -- Line 312 essentially duplicates 310, or at least that was my impression on the read through. Perhaps replace the description on 310 with the one in 312? --- - To unsubscribe, e-mail: dev-unsubscr...@qpid.apache.org For additional commands, e-mail: dev-h...@qpid.apache.org
[GitHub] qpid-dispatch pull request #218: DISPATCH-875 - Doc new "pattern" attribute ...
Github user kgiusti commented on a diff in the pull request: https://github.com/apache/qpid-dispatch/pull/218#discussion_r151166644 --- Diff: doc/new-book/routing.adoc --- @@ -213,11 +213,30 @@ address { } -`prefix`:: The address prefix. All messages that match this prefix will be distributed according to the distribution pattern you specify. +`prefix` | `pattern`:: The address or group of addresses to which the address settings should be applied. You can specify a prefix to match an exact address or segment of an address. Alternatively, you can specify a pattern to match an address using wildcards. + //tag::prefix-matching[] -The prefix can match either an exact address or a segment within an address that is delimited by either a `.` or `/` character. For example, the prefix `my_address` would match the address `my_address` as well as `my_address.1` and `my_address/1`. However, it would not match `my_address1`. +A _prefix_ matches either an exact address or a segment within an address that is delimited by either a `.` or `/` character. For example, the prefix `my_address` would match the address `my_address` as well as `my_address.1` and `my_address/1`. However, it would not match `my_address1`. //end::prefix-matching[] ++ +//tag::pattern-matching[] +A _pattern_ matches an address that corresponds to a pattern. A pattern is a sequence of words delimited by either a `.` or `/` character. You can use wildcard characters to represent a word. The `*` character matches exactly one word, and the `#` character matches any sequence of zero or more words. ++ +The following table shows some examples of address patterns: ++ +[cols="25,75"] +|=== +| This pattern... | Matches... +| `news` | `news` +| `news/*/sports` | `news/europe/sports` and `news/usa/sports`, but not `news` or `news/europe/fr/sports` +| `news/#`| `news`, `news/europe`, `news/usa`, `news/usa/sports` +|=== ++ +[NOTE] + +You can convert a `prefix` value to a `pattern` by appending `/\#` to it. For example, the prefix `a/b/c` is equivalent to the pattern `a/b/c/#`. + +//end::pattern-matching[] --- End diff -- Would it be possible to add an additional note to urge users to consistently use either '.' or '/' as the word separator and not mix both? IOW if using '/' don't use '.' in the address and vice versa? --- - To unsubscribe, e-mail: dev-unsubscr...@qpid.apache.org For additional commands, e-mail: dev-h...@qpid.apache.org
[GitHub] qpid-dispatch pull request #218: DISPATCH-875 - Doc new "pattern" attribute ...
Github user kgiusti commented on a diff in the pull request: https://github.com/apache/qpid-dispatch/pull/218#discussion_r151165869 --- Diff: doc/new-book/routing.adoc --- @@ -213,11 +213,30 @@ address { } -`prefix`:: The address prefix. All messages that match this prefix will be distributed according to the distribution pattern you specify. +`prefix` | `pattern`:: The address or group of addresses to which the address settings should be applied. You can specify a prefix to match an exact address or segment of an address. Alternatively, you can specify a pattern to match an address using wildcards. --- End diff -- When describing the 'prefix' match I would avoid using the unqualified term 'segment' in favor of something like 'beginning segment'. In other words: 'match an exact address or **beginning segment** of an address' I'd apply that to all the other prefix descriptions throughout the doc. --- - To unsubscribe, e-mail: dev-unsubscr...@qpid.apache.org For additional commands, e-mail: dev-h...@qpid.apache.org
[GitHub] qpid-dispatch pull request #218: DISPATCH-875 - Doc new "pattern" attribute ...
GitHub user bhardesty opened a pull request: https://github.com/apache/qpid-dispatch/pull/218 DISPATCH-875 - Doc new "pattern" attribute (WIP) **Note:** This doc update is under review. Please do not merge. Added some doc describing the new pattern attribute. I updated the following procedures: - Routing Messages Between Clients - Routing Messages Through a Broker Queue - Creating a Link Route It's worth noting that I opted to use "word" instead of "token" to refer to the characters that appear between delimiters. This is less precise technically, but it seems to be the most common usage (i.e. most users would use addresses consisting of words). You can merge this pull request into a Git repository by running: $ git pull https://github.com/bhardesty/qpid-dispatch dispatch-875-address-wildcards-doc Alternatively you can review and apply these changes as the patch at: https://github.com/apache/qpid-dispatch/pull/218.patch To close this pull request, make a commit to your master/trunk branch with (at least) the following in the commit message: This closes #218 commit 51673d1fa2eb37729b568d3172e89fce86bd227d Author: Ben Hardesty Date: 2017-11-13T22:29:05Z Add doc for new 'pattern' attribute. --- - To unsubscribe, e-mail: dev-unsubscr...@qpid.apache.org For additional commands, e-mail: dev-h...@qpid.apache.org