OpenAjax Hub 1.1 Specification Publish Subscribe Best Practices
From MemberWiki
NOTE: This wiki page holds part of the early draft specification for OpenAjax Hub 1.1. It contains all of the finalized and approved content from the OpenAjax Hub 1.0 Specification, plus draft text for the new features in OpenAjax Hub 1.1. Text repeated from the Hub 1.0 spec isidentified by the string [HUB10]. The draft text for the features that are new to Hub 1.1 is identified by the string [HUB11]. At this point, the new features are very early in development and have received little or no review by the Interoperability Working Group. All of the new features should be treated by the community as a work in progress that is not yet ready for use by the community.
8 Publish Subscribe Best Practices
NOTE: So far, the chapter is simply a repeat of text found in the [HUB10] spec.
NOTE: Need an intro section.
NOTE: At this point, this chapter simply holds the same set of best practices that were listed in the Hub 1.0 spec.
Event names
Event names may use any (Unicode) character permitted by the JavaScript language, but there are various factors that developers need to take into account:
- The OpenAjax Hub uses the period character (".") as a token separator character (see discussion above about tokenization)
- Each token within an event name MUST consist of at least one character. For example, the event name "
a..b" is invalid because the middle token has no characters. - The OpenAjax Hub uses the asterisk character ("*") to indicate wildcards (see discussion above about wildcards).
- Wildcard specifications MUST appear within a token only as a single "*" or a double "**". For example, the event names
org.example.*,org.*.foo, andorg.example.**are valid, but the event nameaaa.bb*ccMUST 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 event name. For example,
org.example.**is valid butorg.**.fooMUST NOT be treated as a valid wildcard specification. - While any Unicode character permitted by the JavaScript language is valid in an event name, it is recommended that developers SHOULD avoid event names that might lead to human error (e.g., spaces at beginning or end of topic might lead to confusion); prove problematic to 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). It is therefore recommended that event names avoid the use of control characters (e.g., 0x01), quote characters (single or double quotes), whitespace characters (leading space, trailing space, tabs or newlines), or punctuation characters (e.g., parentheses, less-than, greater-than).
- To avoid potential event name conflicts with other components, it is recommended that event names begin with a registered internet domain expressed in reverse order, such as
org.openajax.registerLibrary. - It is recommended that event names are tokenized to maximize usefulness in wildcarding scenarios, while taking into account that there is likely a slight performance impact for names with many tokens (e.g.,
a.b.c.d.e.f.g.h.i.jmight require the Hub invokes 10 levels of recursive function calls) - The latest releases of browsers have good support for Unicode, but there are known bugs with Unicode support beyond the ASCII range in previous browser releases. Therefore, if event names include characters outside the ASCII range, be sure to test across all target browsers. (This problem should go away over the course of time.)
Undetermined order, asynchronous execution of callback functions
While Hub implementations SHOULD normally deliver messages in a simple time-ordered manner, developers MUST NOT depend on any particular invocation order as a number of different operational factors can impact the order in which messages are delivered.
While Hub implementations SHOULD normally invoke subscriber callback functions as soon as possible, which in some cases translates into immediate execution, developers SHOULD NOT depend on immediate execution of subscriber callback functions as there are various scenarios where subscriber callback functions might execute asynchronously.
Do not communicate via exceptions
Publishers and subscribers SHOULD NOT use exceptions as part of the protocol by which they communicate with each other and share information. Hub implementations are not required to transmit exceptions from subscribers to a given publisher.
As a result, applications that rely on exceptions to communicate responses back to the publisher will not be portable and publishers SHOULD NOT design their events such that subscribers are instructed to throw particular exceptions in particular cases.
Subscriber callback function guidelines
Subscriber callbacks often execute within the single-threaded browser JavaScript context and therefore SHOULD execute and return quickly to prevent the Web page from becoming unresponsive.
Implementations of the OpenAjax Hub are not required to include code to manage exceptions raised by callback functions. If callback functions throw uncaught exceptions, serious side effects might occur, including suspension of execution of JavaScript logic on that page. Therefore, callback functions SHOULD NOT throw uncaught exceptions.
Subscriber callbacks functions MAY invoke other OpenAjax Hub services as part of their processing. For example, they may publish events, even on the same topic name (but beware of infinite recursion). They may also subscribe to topic names, including the same topic name. And they may unsubscribe, including the same subscription or other subscriptions to the same topic name.
Note that all of the same guidelines that ordinarily apply to published events (e.g., general guideline about publisher/subscriber independence) also apply to events published by subscriber callback functions.
General guideline: publisher/subscriber independence
As a general rule, publishers and subscribers SHOULD be designed to operate independently and SHOULD NOT assume that publishers and subscribers share the same JavaScript environment. Publishers SHOULD NOT pass references to JavaScript objects within publisherData and instead pass the values of those objects.
General guideline: read-only publisherData
Developers need to be aware that the contents of parameter publisherData that is passed to a subscriber callback function SHOULD be passed by value (see general guidelines above). However, in some scenario's (see next section) some of the publisher data might be references to objects which might be live data fields that are critical to other JavaScript logic used within the given Web page. Because of this, callback functions SHOULD treat publisherData as read-only and therefore, as a general rule, not change its contents.
Scenario when it is appropriate to have read/write sections in publisherData
In certain workflows where the developer has full control of the execution context, it can be appropriate to loosen the two general rules above (i.e., publisher/subscriber independence and read-only publisherData). One scenario is when the developer knows that the publisher logic and subscriber logic share the same JavaScript environment, such as operating within the same browser frame, and that subscriber callbacks are invoked and return synchronously (i.e., immediate execution). In this case, subscriber callback functions MAY modify particular areas within publisherData that have been documented to be read-write. For example, perhaps there is a boolean flag in publisherData that is initialized to false and but which callbacks are instructed to set to true in particular situations.
