Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

First stab at the plugin documentation

  • Loading branch information...
commit 0d7bd987f79319825eb11e66b1408b0858be847f 1 parent db2c814
@kimble kimble authored
View
2  HawkEventingGrailsPlugin.groovy
@@ -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/)
View
5 grails-app/conf/Config.groovy
@@ -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!"
View
1  src/docs/guide/1. Overview.gdoc
@@ -0,0 +1 @@
+Hawk Eventing provides a very simple in-vm event publish / subscribe system.
View
2  src/docs/guide/1.1 Design goals.gdoc
@@ -0,0 +1,2 @@
+* Keep it simple!
+* Be compatible with Falcone Util where possible.
View
10 src/docs/guide/1.2 Falcone util.gdoc
@@ -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.
+
View
1  src/docs/guide/2. Subscribing to events.gdoc
@@ -0,0 +1 @@
+Event subscriptions can be configured in many different ways.
View
21 src/docs/guide/2.1 Annotations.gdoc
@@ -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}
View
11 src/docs/guide/2.2 Event configuration file.gdoc
@@ -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}
View
11 src/docs/guide/2.3 Plugin descriptor.gdoc
@@ -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}
View
35 src/docs/guide/2.4 Programmatically.gdoc
@@ -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}
View
19 src/docs/guide/3. Publishing events.gdoc
@@ -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}
View
1  src/docs/guide/3.1 Bubbling.gdoc
@@ -0,0 +1 @@
+Events published to @hibernate.book.created@ will also be published to @hibernate@ and @hibernate@.
View
20 src/docs/guide/4. Changelog.gdoc
@@ -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.
View
1  src/docs/guide/5. Roadmap.gdoc
@@ -0,0 +1 @@
+No roadmap yet, just keep it simple and working with newer versions of Grails.
Please sign in to comment.
Something went wrong with that request. Please try again.