Permalink
Browse files

First stab at the plugin documentation

  • Loading branch information...
1 parent db2c814 commit 0d7bd987f79319825eb11e66b1408b0858be847f @kimble kimble committed Feb 14, 2011
@@ -32,7 +32,7 @@ class HawkEventingGrailsPlugin {
def title = "Hawk Eventing"
def documentation = "http://grails.org/plugin/eventing"
- def description = 'Event plugin similar to the Falcone-Util plugin, but without the Hibernate integration.'
+ def description = "Very simple in-vm event publish / subscribe system."
def doWithSpring = {
View
113 README.md
@@ -4,115 +4,4 @@ Hawk Eventing
This is a plugin very similar to the [Falcone-Util plugin](http://grails.org/plugin/falcone-util), but without the Hibernate integration.
The main goal of the plugin is to provide a very simple, non intrusive message broker.
-Warning
---------
-
-Expect the API to break.
-
-Subscribing to events
----------------------
-
-### Manually, using the eventBroker bean
-
- class BookService implements InitializingBean {
- def eventBroker // Injected by Spring
-
- void afterPropertiesSet() {
-
- eventBroker.subscribe("hibernate.book") { Event event ->
- // Do something with book (event.payload)
- }
-
- }
-
- }
-
-
-### In applications, creating grails-app/conf/events.groovy
-
- consumers = {
-
- hibernate.book.created { Event event ->
- // Do something with book (event.payload)
- }
-
- }
-
-### In plugins, adding a doWithEvents closure to the plugin description file (...GrailsPlugin.groovy)
-
- def doWithEvents = { ApplicationContext ctx ->
-
- hibernate.book.created { Event event ->
- // Do something with event.payload
- }
-
- }
-
-### Implementing EventConsumer + registering it with the eventBroker
-
- class MyConsumer implements EventConsumer, InitializingBean {
-
- EventBroker eventBroker;
-
- void consume(Event event) {
- // ...
- }
-
- void afterPropertiesSet() {
- eventBroker.subscribe("hibernate.saveOrUpdate.author", this);
- }
-
- }
-
-### Using annotations
-
-**Important:** This only works on Spring beans.
-
-**Important:** This feature is experimental
-
- @HawkEventConsumer
- class BookService {
-
- @Consuming("hibernate.save.book")
- void onNewBook(Event newBookEvent) {
- // ...
- }
-
- }
-
-Event bubbling
---------------
-
-Events published to `hibernate.book.created` will also be published to `hibernate.book` and `hibernate`.
-
-
-Changelog
-----------
-
-### v0.5 - Valentines day 2010
-
- * Removed the async experiment
- * Cleaned up code formatting
- * Added some JavaDoc and started working on the plugin documentation
-
-### v0.4 - November the 28th. 2010
-
- * Started working (not completed) on support for async event publishing if the [Grails Executor](http://grails.org/plugin/executor) plugin is installed (no compile time dependency).
- * Breaking: Refactored package structure to reflect the new name
-
-### v0.3 - November the 6th. 2010
-
-* Feature: Support for declaring methods as event consumers using a @Consuming annotation.
-* Refactoring: Moved configuration methods out from the plugin descriptor.
-* Refactoring: Rewritten a lot of the classes in Java + more unit testing.
-* Breaking: Introduced the Event interface.
-Objects that's not an instance of Event will be wrapped in the BaseEvent class.
-* Breaking: The EventBroker is not published together with the Event.
-This way events has the option to be serialized.
-Consumers in need of the broker should have it injected by Spring.
-
-
-Roadmap
---------
-
-The plugin is pretty much feature ready, but more tests, examples and documentation would be nice.
+The documentation is hosted at [GitHub Pages](http://multi-tenant.github.com/grails-hawk-eventing/)
@@ -30,3 +30,8 @@ coverage {
// The following properties have been added by the Upgrade process...
grails.views.default.codec="none" // none, html, base64
grails.views.gsp.encoding="UTF-8"
+
+grails.doc.authors="Kim A. Betti"
+grails.doc.license="Apache 2.0"
+grails.doc.copyright=""
+grails.doc.footer="Have a nice day!"
@@ -0,0 +1 @@
+Hawk Eventing provides a very simple in-vm event publish / subscribe system.
@@ -0,0 +1,2 @@
+* Keep it simple!
+* Be compatible with Falcone Util where possible.
@@ -0,0 +1,10 @@
+The plugin is based on [Falcone Util|http://grails.org/plugin/falcone-util].
+
+h3. Why another plugin?
+
+Falcone Util is not actively maintained and contains a lot of code from another project.
+
+h3. Why not update Falcone Util instead of creating yet another plugin?
+
+People still use and depend on the code in Falcone Util.
+
@@ -0,0 +1 @@
+Event subscriptions can be configured in many different ways.
@@ -0,0 +1,21 @@
+You can configure subscriptions by adding annotations to your beans.
+
+{note}
+Important! This will only work for Spring beans!
+{note}
+
+{warning}
+This support is experimental and subject to change.
+{warning}
+
+{code:java}
+@HawkEventConsumer
+class BookService {
+
+ @Consuming("hibernate.save.book")
+ void onNewBook(Event event) {
+ // do something with event.payload
+ }
+
+}
+{code}
@@ -0,0 +1,11 @@
+This was implemented to increase compatibility with Falcone Util. You can register events using a simple dsl in @grails-app/conf/events.groovy@.
+
+{code:java}
+consumers = {
+
+ hibernate.book.created { Event event ->
+ // Do something with book (event.payload)
+ }
+
+}
+{code}
@@ -0,0 +1,11 @@
+You can register events in the plugin descriptor. By adding a doWithEvents closure. The DSL is the same as the one used in events.groovy.
+
+{code:java}
+def doWithEvents = { ApplicationContext ctx ->
+
+ hibernate.book.created { Event event ->
+ // Do something with event.payload
+ }
+
+}
+{code}
@@ -0,0 +1,35 @@
+You can add your subscriptions during bean initialization.
+
+h3. Simple event consumer using a closure
+
+{code:java}
+class BookService implements InitializingBean {
+
+ def eventBroker // Injected by Spring
+
+ void afterPropertiesSet() {
+ eventBroker.subscribe("hibernate.book") { Event event ->
+ // Do something with book (event.payload)
+ }
+ }
+
+}
+{code}
+
+h3. Implement the EventConsumer interface
+
+{code:java}
+class MyConsumer implements EventConsumer, InitializingBean {
+
+ EventBroker eventBroker;
+
+ void consume(Event event) {
+ // do something with the event
+ }
+
+ void afterPropertiesSet() {
+ eventBroker.subscribe("hibernate.saveOrUpdate.author", this);
+ }
+
+}
+{code}
@@ -0,0 +1,19 @@
+The first thing you have to do is to inject the @eventBroker@ bean where you need it. Grails artifacts are autowired by name so simply adding @def eventBroker@ will suffice.
+
+You can choose whether you want to publish your own custom @Event@ implementation or just any object. If you choose to publish a non-event object it will be wrapped in a @BaseEvent@ before published to any consumers.
+
+{code:java}
+class UserService {
+
+ def eventBroker
+
+ User registerUser(String username, ...) {
+ // ...
+
+ if (success) {
+ eventBroker.publish("user.created", userInstance);
+ }
+ }
+
+}
+{code}
@@ -0,0 +1 @@
+Events published to @hibernate.book.created@ will also be published to @hibernate@ and @hibernate@.
@@ -0,0 +1,20 @@
+Have a look at [GitHub|http://github.com/multi-tenant/grails-hawk-eventing] for a detailed changelog.
+
+h3. v0.5 - Valentines day 2010
+
+ * Removed the async experiment
+ * Cleaned up code formatting
+ * Added some JavaDoc and started working on the plugin documentation
+
+h3. v0.4 - November the 28th. 2010
+
+ * Started working (not completed) on support for async event publishing if the [Grails Executor](http://grails.org/plugin/executor) plugin is installed (no compile time dependency).
+ * Breaking: Refactored package structure to reflect the new name
+
+h3. v0.3 - November the 6th. 2010
+
+* Feature: Support for declaring methods as event consumers using a @Consuming annotation.
+* Refactoring: Moved configuration methods out from the plugin descriptor.
+* Refactoring: Rewritten a lot of the classes in Java + more unit testing.
+* Breaking: Introduced the Event interface. Objects that's not an instance of Event will be wrapped in the BaseEvent class.
+* Breaking: The EventBroker is not published together with the Event. This way events has the option to be serialized. Consumers in need of the broker should have it injected by Spring.
@@ -0,0 +1 @@
+No roadmap yet, just keep it simple and working with newer versions of Grails.

0 comments on commit 0d7bd98

Please sign in to comment.