Permalink
Browse files

Updating the documentation.

  • Loading branch information...
1 parent cb4e742 commit f1148ef1d32c7b51298acd57a26347a04d77f319 Jon Brisbin committed Mar 6, 2013
Showing with 170 additions and 11 deletions.
  1. +137 −0 src/reference/docbook/events.xml
  2. +1 −0 src/reference/docbook/index.xml
  3. +32 −11 src/reference/docbook/validation.xml
@@ -0,0 +1,137 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter xml:id="events-chapter"
+ xmlns="http://docbook.org/ns/docbook"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://docbook.org/ns/docbook http://www.oasis-open.org/docbook/xml/5.0/xsd/docbook.xsd">
+
+ <title>Events</title>
+
+ <para>There are six different events that the REST exporter emits throughout the process of working with an entity.
+ Those are:
+
+ <itemizedlist>
+ <listitem>
+ <para>BeforeCreateEvent</para>
+ </listitem>
+ <listitem>
+ <para>AfterCreateEvent</para>
+ </listitem>
+ <listitem>
+ <para>BeforeSaveEvent</para>
+ </listitem>
+ <listitem>
+ <para>AfterSaveEvent</para>
+ </listitem>
+ <listitem>
+ <para>BeforeLinkSaveEvent</para>
+ </listitem>
+ <listitem>
+ <para>AfterLinkSaveEvent</para>
+ </listitem>
+ <listitem>
+ <para>BeforeDeleteEvent</para>
+ </listitem>
+ <listitem>
+ <para>AfterDeleteEvent</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <section>
+ <title>Writing an
+ <classname>ApplicationListener</classname>
+ </title>
+
+ <para>There is an abstract class you can subclass which listens for these kinds of events and calls
+ the appropriate method based on the event type. You just override the methods for
+ the events you're interested in.
+
+ <programlisting language="java"><![CDATA[
+public class BeforeSaveEventListener extends AbstractRepositoryEventListener {
+
+ @Override public void onBeforeSave(Object entity) {
+ ... logic to handle inspecting the entity before the Repository saves it
+ }
+
+ @Override public void onAfterDelete(Object entity) {
+ ... send a message that this entity has been deleted
+ }
+
+}]]></programlisting>
+ </para>
+
+ <para>One thing to note with this approach, however, is that it makes no distinction based on
+ the type of the entity. You'll have to inspect that yourself.
+ </para>
+
+ </section>
+
+ <section>
+ <title>Writing an annotated handler</title>
+
+ <para>Another approach is to use an annotated handler, which does filter events based on domain type.</para>
+
+ <para>To declare a handler, create a POJO and put the
+ <classname>@RepositoryEventHandler</classname>
+ annotation on it. This tells the
+ <classname>BeanPostProcessor</classname>
+ that this class needs to be inspected for handler methods.
+ </para>
+
+ <para>Once it finds a bean with this annotation, it iterates over the exposed methods and looks for
+ annotations that correspond to the event you're interested in. For example, to handle BeforeSaveEvents
+ in an annotated POJO for different kinds of domain types, you'd define your class like this:
+
+ <programlisting language="java"><![CDATA[
+@RepositoryEventHandler
+public class PersonEventHandler {
+
+ @HandleBeforeSave(Person.class) public void handlePersonSave(Person p) {
+ ... you can now deal with Person in a type-safe way
+ }
+
+ @HandleBeforeSave(Profile.class) public void handleProfileSave(Profile p) {
+ ... you can now deal with Profile in a type-safe way
+ }
+
+}]]></programlisting>
+ </para>
+
+ <para>You can also declare the domain type at the class level:
+
+ <programlisting language="java"><![CDATA[
+@RepositoryEventHandler(Person.class)
+public class PersonEventHandler {
+
+ @HandleBeforeSave public void handleBeforeSave(Person p) {
+ ...
+ }
+
+ @HandleAfterDelete public void handleAfterDelete(Person p) {
+ ...
+ }
+
+}]]></programlisting>
+ </para>
+
+ <para>Just declare an instance of your annotated bean in your
+ <classname>ApplicationContext</classname>
+ and the
+ <classname>BeanPostProcessor</classname>
+ that is by default created in
+ <classname>RepositoryRestMvcConfiguration</classname>
+ will inspect the bean for handlers and wire them to the correct events.
+
+ <programlisting language="java"><![CDATA[
+@Configuration
+public class RepositoryConfiguration {
+
+ @Bean PersonEventHandler personEventHandler() {
+ return new PersonEventHandler();
+ }
+
+}]]></programlisting>
+ </para>
+ </section>
+
+</chapter>
@@ -47,6 +47,7 @@
<xi:include href="representations.xml"/>
<xi:include href="paging.xml"/>
<xi:include href="validation.xml"/>
+ <xi:include href="events.xml"/>
<xi:include href="rest-shell.xml"/>
</book>
@@ -6,23 +6,44 @@
<title>Validation</title>
- <para>Integrating validation into Spring Data REST is as easy as registering your
+ <para>There are two ways to register a
<classname>Validator</classname>
- implementation with the
- <classname>ValidatingRepositoryEventListener</classname>, whose job it is to trigger
- validators whenever certain events happen inside Spring Data REST.
+ instance in Spring Data REST: wire it by bean name or register the validator manually. For the majority of cases,
+ the simple bean name prefix style will be sufficient.
</para>
- <para>To add your validators, override the
- <code>configureValidatingRepositoryEventListener</code>
- method and call the
- <code>addValidator</code>
- method:
+ <para>In order to tell Spring Data REST you want a particular
+ <classname>Validator</classname>
+ assigned to a particular event, you simply prefix the bean name with the event you're interested in. For example, to
+ validate instances of the
+ <classname>Person</classname>
+ class before new ones are saved into the repository, you would declare an instance of a
+ <classname>Validator&lt;Person&gt;</classname>
+ in your
+ <classname>ApplicationContext</classname>
+ with the bean name "beforeCreatePersonValidator". Since the prefix "beforeCreate" matches a known Spring Data REST
+ event, that validator will be wired to the correct event.
+ </para>
+
+ <section>
+ <title>Assigning Validators manually</title>
- <programlisting language="java"><![CDATA[
+ <para>If you would rather not use the bean name prefix approach, then you simply need to register an instance of
+ your validator with the bean who's job it is to invoke validators after the correct event. In your configuration
+ that subclasses Spring Data REST's
+ <classname>RepositoryRestMvcConfiguration</classname>, override the
+ <code>configureValidatingRepositoryEventListener</code>
+ method and call the
+ <code>addValidator</code>
+ method on the
+ <classname>ValidatingRepositoryEventListener</classname>, passing the event you want this validator
+ to be triggered on, and an instance of the validator.
+
+ <programlisting language="java"><![CDATA[
@Override protected void configureValidatingRepositoryEventListener(ValidatingRepositoryEventListener v) {
v.addValidator("beforeSave", new BeforeSaveValidator());
}]]></programlisting>
- </para>
+ </para>
+ </section>
</chapter>

0 comments on commit f1148ef

Please sign in to comment.