As seen in the last example, events are a nice mechanism for attaching to certain actions without changing any of the existing code. In the last recipe the RegistrationPlugin was attached to the event of storing to create an entity. This is only one of many use-cases. This mechanism is quite seldom used in Play. There are some pros and cons about using events. It is always worth to think about whether using events is the right approach.
The source code of the example is available at examples/chapter5/events.
Triggering events yourself is absolutely easy. You can put the following anywhere in your code:
PlayPlugin.postEvent("foo.bar", "called it");The first argument is an arbitrary string and should by convention consist of two words split by a dot. The first part should resemble some generic identifier. In order to correlate it easily this part is ideally the source of where it is coming from. The second part should be a unique identifier representing the reason for this event to be triggered. The last argument of the method can be any object. You have to take care of correct conversion and usage in the plugin yourself.
Receiving events is just as simple. Just write a plugin and implement the onEvent method:
public void onEvent(String event, Object context) {
if (event.startsWith("foo.")) {
Logger.info("Some event: %s with content %s", event, context);
}
}There are actually surprisingly few events predefined in the framework. Only the JPA plugin emits three different events:
JPASupport.objectDeletedis posted when any object is deleted. You could possibly implement some sort of audit history this way. However, this is better done with hibernate in this case.JPASupport.objectPersistedis posted when a new object is created.JPASupport.objectUpdatedis posted whenever an existing object is updated.
Currently, the event mechanism is not used that much. At the time of this writing, only the Ebean plugin made use of it.
If you take a look at the PlayPlugin class' postEvent() method, you will see the following snippet:
public static void postEvent(String message, Object context) {
Play.pluginCollection.onEvent(message, context);
}So, for each emitted event, the framework loops through all plugins and executes the onEvent() method. This means that all this is done synchronously. Therefore, you should never put heavy weight operations into this method, as this might block the currently running request.
Possibly, you could also make the business logic inside your onEvent() methods run asynchronously in order to speed things up and return to the caller method faster.
Events are a nice and handy feature, but you should not use them overly, as they might make your code less readable. Furthermore, you should not mix this mechanism up with real event messaging solutions.
Events only get emitted inside the JVM. If you want a reliable way to collect and process your events in a multi-node environment, you cannot use the built-in event mechanism of the Play framework. You might be better off with a real messaging solution, which is in the Integrating with messaging queues recipe in the next chapter.