You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@zookeeper.apache.org by iv...@apache.org on 2012/11/30 16:28:44 UTC
svn commit: r1415691 - in /zookeeper/bookkeeper/trunk: CHANGES.txt
doc/hedwigMessageFilter.textile doc/index.textile
Author: ivank
Date: Fri Nov 30 15:28:43 2012
New Revision: 1415691
URL: http://svn.apache.org/viewvc?rev=1415691&view=rev
Log:
BOOKKEEPER-389: add documentation for message filter. (sijie via ivank)
Added:
zookeeper/bookkeeper/trunk/doc/hedwigMessageFilter.textile
Modified:
zookeeper/bookkeeper/trunk/CHANGES.txt
zookeeper/bookkeeper/trunk/doc/index.textile
Modified: zookeeper/bookkeeper/trunk/CHANGES.txt
URL: http://svn.apache.org/viewvc/zookeeper/bookkeeper/trunk/CHANGES.txt?rev=1415691&r1=1415690&r2=1415691&view=diff
==============================================================================
--- zookeeper/bookkeeper/trunk/CHANGES.txt (original)
+++ zookeeper/bookkeeper/trunk/CHANGES.txt Fri Nov 30 15:28:43 2012
@@ -238,6 +238,8 @@ Trunk (unreleased changes)
BOOKKEEPER-487: Add existed hub server settings to configuration template file (sijie via ivank)
+ BOOKKEEPER-389: add documentation for message filter. (sijie via ivank)
+
hedwig-client:
BOOKKEEPER-306: Change C++ client to use gtest for testing (ivank via sijie)
Added: zookeeper/bookkeeper/trunk/doc/hedwigMessageFilter.textile
URL: http://svn.apache.org/viewvc/zookeeper/bookkeeper/trunk/doc/hedwigMessageFilter.textile?rev=1415691&view=auto
==============================================================================
--- zookeeper/bookkeeper/trunk/doc/hedwigMessageFilter.textile (added)
+++ zookeeper/bookkeeper/trunk/doc/hedwigMessageFilter.textile Fri Nov 30 15:28:43 2012
@@ -0,0 +1,76 @@
+Title: Hedwig Message Filter
+Notice: Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License. You may
+ obtain a copy of the License at "http://www.apache.org/licenses/LICENSE-2.0":http://www.apache.org/licenses/LICENSE-2.0.
+ .
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an "AS IS"
+ BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied. See the License for the specific language governing permissions
+ and limitations under the License.
+ .
+ .
+
+h1. Message Filter
+
+Apache Hedwig provides an efficient mechanism for supporting application-defined __message filtering__.
+
+h2. Message
+
+Most message-oriented middleware (MOM) products treat messages as lightweight entities that consist of a header and a payload. The header contains fields used for message routing and identification; the payload contains the application data being sent.
+
+Hedwig messages follow a similar template, being composed of following parts:
+
+* @Header@ - All messages support both system defined fields and application defined property values. Properties provide an efficient mechanism for supporting application-defined message filtering.
+* @Body@ - Hedwig considers the message body as a opaque binary blob.
+* @SrcRegion@ - Indicates where the message comes from.
+* @MessageSeqId@ - The unique message sequence id assigned by Hedwig.
+
+h3. Message Header Properties
+
+A __Message__ object contains a built-in facility for supporting application-defined property values. In effect, this provides a mechanism for adding application-specific header fields to a message.
+
+By using properties and __message filters__, an application can have Hedwig select, or filter, messages on its behalf using application-specific criteria.
+
+Property names must be a __String__ and must not be null, while property values are binary blobs. The flexibility of binary blobs allows applications to define their own serialize/deserialize functions, allowing structured data to be stored in the message header.
+
+h2. Message Filter
+
+A __Message Filter__ allows an application to specify, via header properties, the messages it is interested in. Only messages which pass validation of a __Message Filter__, specified by a subscriber, are be delivered to the subscriber.
+
+A message filter could be run either on the __server side__ or on the __client side__. For both __server side__ and __client side__, a __Message Filter__ implementation needs to implement the following two interfaces:
+
+* @setSubscriptionPreferences(topic, subscriberId, preferences)@: The __subscription preferences__ of the subscriber will be passed to message filter when it was attached to its subscription either on the server-side or on the client-side.
+* @testMessage(message)@: Used to test whether a particular message passes the filter or not.
+
+The __subscription preferences__ are used to specify the messages that the user is interested in. The __message filter__ uses the __subscription preferences__ to decide which messages are passed to the user.
+
+Take a book store(using topic __BookStore__) as an example:
+
+# User A may only care about History books. He subscribes to __BookStore__ with his custom preferences : type="History".
+# User B may only care about Romance books. He subscribes to __BookStore__ with his custom preferences : type="Romance".
+# A new book arrives at the book store; a message is sent to __BookStore__ with type="History" in its header
+# The message is then delivered to __BookStore__'s subscribers.
+# Subscriber A filters the message by checking messages' header to accept those messages whose type is "History".
+# Subscriber B filters out the message, as the type does not match its preferences.
+
+h3. Client Message Filter.
+
+A __ClientMessageFilter__ runs on the client side. Each subscriber can write its own filter and pass it as a parameter when starting delivery ( __startDelivery(topic, subscriberId, messageHandler, messageFilter)__ ).
+
+h3. Server Message Filter.
+
+A __ServerMessageFilter__ runs on the server side (a hub server). A hub server instantiates a server message filter, by means of reflection, using the message filter class specified in the subscription preferences which are provided by the subscriber. Since __ServerMessageFilter__s run on the hub server, all filtered-out messages are never delivered to client, reducing unnecessary network traffic. Hedwig uses a implementation of __ServerMessageFilter__ to filter unnecessary message deliveries between regions.
+
+Since hub servers use reflection to instantiate a __ServerMessageFilter__, an implementation of __ServerMessageFilter__ needs to implement two additional methods:
+
+* @initialize(conf)@: Initialize the message filter before filtering messages.
+* @uninitialize()@: Uninitialize the message filter to release resources used by the message filter.
+
+For the hub server to load the message filter, the implementation class must be in the server's classpath at startup.
+
+h3. Which message filter should be used?
+
+It depends on application requirements. Using a __ServerMessageFilter__ will reduce network traffic by filtering unnecessary messages, but it would compete for resources on the hub server(CPU, memory, etc). Conversely, __ClientMessageFilter__s have the advantage of inducing no extra load on the hub server, but at the price of higher network utilization. A filter can be installed both at the server side and on the client; Hedwig does not restrict this.
+
Modified: zookeeper/bookkeeper/trunk/doc/index.textile
URL: http://svn.apache.org/viewvc/zookeeper/bookkeeper/trunk/doc/index.textile?rev=1415691&r1=1415690&r2=1415691&view=diff
==============================================================================
--- zookeeper/bookkeeper/trunk/doc/index.textile (original)
+++ zookeeper/bookkeeper/trunk/doc/index.textile Fri Nov 30 15:28:43 2012
@@ -37,6 +37,7 @@ h1. Apache Hedwig documentation
* "Building Hedwig, or how to set up Hedwig":./hedwigBuild.html
* "User's Guide, or how to program against the Hedwig API and how to run it":./hedwigUser.html
* "Developer's Guide, or Hedwig internals and hacking details":./hedwigDesign.html
+* "Message Filtering":./hedwigMessageFilter.html
h2. Hedwig Admin & Ops