OpenAjax Hub 2.0 Specification Topic Names

From MemberWiki

Jump to: navigation, search

NOTE: This wiki page holds part of the OpenAjax Hub 2.0 Specification.


<--previous       contents--^       next-->


Contents

8 Topic Names

This chapter defines the rules and guidelines for the topic names that are passed as parameters to various publish() and subscribe() methods defined by this specification.

Topic names are expressed as tokens separated by the "." character (period character - 0x2E). For example, the event name "org.openajax.hub.registerLibrary" has four tokens. Topic names must contain at least one token. Each token MUST consist of at least one character. For example, the topic name "a..b" is invalid because the middle token has no characters.

Wildcard Tokens

Two types of wildcards can appear in a topic name:

  • "*" wildcard (asterisk character - 0x2A) tokens may appear anywhere in a topic name. It matches exactly one token with any value.
  • A "**" wildcard (two asterisk characters) may ONLY be used as the last token in a topic name. "**" matches one or more tokens with any value.

Wildcard Tokens

Each "*" wildcard token matches a single token. For example, a subscription to "org.example.module1.*" receives all published events whose topics have exactly four tokens and whose first three tokens match "org.example.module1".

Multiple "*" wildcard tokens are supported within a single topic name.

"*" wildcard tokens can appear in the middle of a topic; for example, "org.example.*.log" will subscribe to all events that have four tokens where the first two tokens match "org.example" and the fourth token matches "log". Therefore, this wildcard pattern would match either "org.example.type1.log" and "org.example.type99.log".

Trailing ** Wildcard Token

A single trailing "**" wildcard token matches one or more tokens at the end of a topic name. "**" allows you to subscribe to all topic names that share the same root. For example, a subscription to the topic name "org.example.**" will receive all published events that have at least 3 tokens, where the first two tokens match "org.example". Thus, "org.example.**" matches "org.example.m" and "org.example.abcdef.ghijkl.mnopqr".

Wildcard characters MUST NOT be mixed with other characters within a token. They MUST appear either as a "*" token or as a trailing "**" token in the topic. For example, the following topic names are valid:

  • org.example.*
  • org.*.foo
  • org.example.**

but the topic name

  • aaa.bb*cc    (Note: invalid topic name)

MUST NOT be treated as a valid wildcard specification because the "*" is mixed with other characters.

A double asterisk wildcard value ("**") MUST NOT appear except as the final token in the topic name. For example, org.example.** is valid but org.**.foo MUST be rejected.

Characters in Topic Names

Topic names may use any (Unicode) character permitted by the JavaScript language, but there are various factors that developers SHOULD take into account.

The period character (".") and the asterisk character ("*") MUST only be used as described in this chapter.

Characters that Cause Problems

In addition, while any Unicode character permitted by the JavaScript language is valid in a topic name, developers SHOULD avoid topic names that might lead to human error (e.g., spaces at beginning or end of topic might lead to confusion), cause problems during automated processing (e.g., quotes, less-than or greater-than symbols are special characters for HTML and XML) or prove problematic for transmission through emails or via system copy/paste facilities (e.g., newline characters).

Thus, developers SHOULD NOT use the following characters in topic names:

  • control characters (e.g., 0x01)
  • quote characters (single or double quotes)
  • whitespace characters (leading space, trailing space, tabs or newlines)
  • punctuation characters (e.g., parentheses, less-than, greater-than).

Unicode

Although the latest releases of browsers have good support for Unicode, previous browser releases contain known bugs with Unicode support beyond the ASCII range. Therefore, if topic names include characters outside the ASCII range, be careful to test across all target browsers.

Reverse DNS Topic Names

To avoid potential topic name conflicts with other components, we STRONGLY RECOMMEND that all topic names begin with a registered internet domain expressed in reverse order, such as org.openajax.registerLibrary.

Tokenizing to maximize usefulness in wildcarding scenarios

We recommend that topic names be tokenized to maximize usefulness in wildcarding scenarios. While there may be a very small performance impact when names contain many tokens (e.g., a.b.c.d.e.f.g.h.i.j might require that the Hub invokes 10 levels of recursive function calls), performance tests on the reference implementation show that adding a few tokens does not impact the performance of non-trivial applications.

Wildcards allowed for subscribe(), disallowed for publish()

The subscribe() methods defined in this specification MUST accept topic names that contain wildcards. The publish() methods defined in this specification MUST NOT accept topic names that contain wildcards.

Examples

Here are examples of valid topic names:

org.openajax.example.token.one5 tokens "org", "openajax", "example", "token", "one".
ABCSingle token "ABC"
zSingle token "z"
ABC.d.Efg.11.$.X_Y_Z6 tokens: "ABC", "d", "Efg", "11", "$", "X_Y_Z"
*One token (the "*" wildcard). Matches all topic names that contain exactly one token.
**One token (the "**" wildcard). Matches all topic names.
AA.BB.*3 tokens "AA", "BB", and "*". Matches all topic names that have exactly 3 tokens and have "AA" and "BB" as first two tokens.
AA.BB.**3 tokens "AA", "BB", and "**". Matches all topic names that have at least 3 tokens and have "AA" and "BB" as first two tokens.
AA.BB.*.DD4 tokens "AA", "BB", "*", and "DD". Matches all topic names that have exactly 4 tokens and have "AA" and "BB" as first two tokens and "DD" as the fourth token.
AA.*.CC.*.EE5 tokens "AA", "*", "CC", "*", and "EE". Matches all topic names that have exactly 5 tokens and where the first token is "AA", the third token is "CC", and the fifth token is "EE".
AA.*.CC.**4 tokens "AA", "*", "CC", and "**". Matches all topic names that have at least 4 tokens and where the first token is "AA" and the third token is "CC".



<--previous       contents--^       next-->
Personal tools