From 591e107f4e379dba9117505eccba1a0aa3efb339 Mon Sep 17 00:00:00 2001
From: benni <benjamin.diedrichsen@friendsurance.de>
Date: Sun, 28 Oct 2012 09:11:45 +0100
Subject: [PATCH] added sampe code in documentation

---
 README.md                                     | 46 +++++++++++++++++++
 .../java/org/mbassy/filter/MessageFilter.java |  9 ++++
 src/test/java/org/mbassy/MBassadorTest.java   | 13 +++++-
 3 files changed, 67 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 981fabd..50d98da 100644
--- a/README.md
+++ b/README.md
@@ -24,6 +24,52 @@ a single message handler
 mark and configure your message handlers with @Listener annotations and finally register the listeners at any Mbassador instance. Start
 sending messages to your listeners using one of Mbassador's publication methods (sync or async). Done!
 
+
+---------------------------------------
+
+Usage:
+
+Listener Definition (in any Bean):
+
+        // every event of type TestEvent or any subtype will be delivered
+        // to this handler
+        @Listener
+		public void handleTestEvent(TestEvent event) {
+			// do something
+		}
+
+        // this handler will be invoked asynchronously
+		@Listener(mode = Listener.Dispatch.Asynchronous)
+		public void handleSubTestEvent(SubTestEvent event) {
+            // do something more expensive here
+		}
+
+		// this handler will receive events of type SubTestEvent
+        // or any subtabe and that passes the given filter(s)
+        @Listener({@Filter(value = SpecialEventsOnly.class),@Filter(value = SpecialEventsOnly.class)})
+        public void handleFiltered(SubTestEvent event) {
+           //do something special here
+        }
+
+Creation of message bus and registration of listeners:
+
+        // create as many instances as necessary
+        // bind it to any upper bound
+        MBassador<TestEvent> bus = new MBassador<TestEvent();
+        ListeningBean listener = new ListeningBean();
+        bus.subscribe(listener)
+
+Message puclication:
+
+        TestEvent event = new TestEvent();
+        TestEvent subEvent = new SubTestEvent();
+
+        bus.publishAsync(event); //returns immediately, publication will continue asynchronously
+        bus.publish(subEvent);   // will return after each handler has been invoked
+
+---------------------------------------
+
+
 Planned features:
 
 + Maven dependency: Add Mbassador to your project using maven. Coming soon!
diff --git a/src/main/java/org/mbassy/filter/MessageFilter.java b/src/main/java/org/mbassy/filter/MessageFilter.java
index 0169ccf..8cc1e8d 100644
--- a/src/main/java/org/mbassy/filter/MessageFilter.java
+++ b/src/main/java/org/mbassy/filter/MessageFilter.java
@@ -28,4 +28,13 @@ public interface MessageFilter {
 		}
 	}
 
+    public static final class None implements MessageFilter {
+
+        @Override
+        public boolean accepts(Object event, Object listener) {
+            return false;
+        }
+    }
+
+
 }
diff --git a/src/test/java/org/mbassy/MBassadorTest.java b/src/test/java/org/mbassy/MBassadorTest.java
index 6103e41..8cd6fb6 100644
--- a/src/test/java/org/mbassy/MBassadorTest.java
+++ b/src/test/java/org/mbassy/MBassadorTest.java
@@ -2,6 +2,8 @@ package org.mbassy;
 
 import org.junit.Assert;
 import org.junit.Test;
+import org.mbassy.filter.Filter;
+import org.mbassy.filter.MessageFilter;
 
 import java.util.ArrayList;
 import java.util.List;
@@ -149,17 +151,26 @@ public class MBassadorTest {
 
 	public class EventingTestBean {
 
-
+        // every event of type TestEvent or any subtype will be delivered
+        // to this listener
 		@Listener
 		public void handleTestEvent(TestEvent event) {
 			event.counter.incrementAndGet();
 		}
 
+        // this handler will be invoked asynchronously
 		@Listener(mode = Listener.Dispatch.Asynchronous)
 		public void handleSubTestEvent(SubTestEvent event) {
             event.counter.incrementAndGet();
 		}
 
+        // this handler will receive events of type SubTestEvent
+        // or any subtabe and that passes the given filter
+        @Listener({@Filter(MessageFilter.None.class),@Filter(MessageFilter.All.class)})
+        public void handleFiltered(SubTestEvent event) {
+            event.counter.incrementAndGet();
+        }
+
 
 	}