DATACMNS-1467 - Polishing.

Tweak docs.

Original Pull Request: #332

src/main/java/org/springframework/data/mapping/callback/EntityCallback.java

@@ -16,34 +16,47 @@
 package org.springframework.data.mapping.callback;
 
 /**
- * Marker interface for entity callbacks to be implemented in specific callback subtypes intended for internal usage
- * within store specific implementations. <br />
+ * Marker interface for entity callbacks to be implemented in specific callback subtypes. Intended for internal usage
+ * within store specific implementations.
+ * <h3>Ordering {@link EntityCallback}</h3>
+ * <p/>
+ * Multiple entity callbacks are invoked sequentially with the result of the previous callback. Callbacks are unordered
+ * by default. It is possible to define the order in which listeners for a certain domain type are to be invoked. To do
+ * so, add Spring's common {@link org.springframework.core.annotation.Order @Order} annotation or implement
+ * {@link org.springframework.core.Ordered}.
+ * <h3>Exception Handling</h3>
  * <p />
- * Multiple entity callbacks are invoked sequentially with the result of the previous callback. Those callbacks do by
- * default not follow an explicit order of invocation. It is strongly recommended to enforce ordering for callbacks of
- * the same by implementing {@link org.springframework.core.Ordered} or following the annotation driven approach using
- * {@link org.springframework.core.annotation.Order}.
+ * While it is possible for a {@link EntityCallback} to declare that it throws arbitrary exception types, any checked
+ * exceptions thrown from a {@link EntityCallback} are wrapped in an
+ * {@link java.lang.reflect.UndeclaredThrowableException UndeclaredThrowableException} since the callback mechanism can
+ * only handle runtime exceptions. Entity callback processing is stopped on the {@link EntityCallback} that raised an
+ * exception and the caused exception is propagated to the caller.
+ * <h3>Domain Type Binding</h3>
  * <p />
- * Entity callbacks are invoked after publishing {@link org.springframework.context.ApplicationEvent events}.
+ * An {@link EntityCallback} can generically declare the domain type that it is able to process by specifying the
+ * generic type parameter {@code <T>}. When registered with a Spring
+ * {@link org.springframework.context.ApplicationContext}, callbacks are filtered accordingly, with the callback getting
+ * invoked for assignable domain objects only.
+ * <p/>
+ * Typically, entity callbacks are invoked after publishing {@link org.springframework.context.ApplicationEvent events}.
+ * <p/>
+ * <h3>Defining {@link EntityCallback} Interfaces</h3>
  * <p />
- * A store specific {@link EntityCallback} needs to define a callback method accepting an object of the parameterized
- * type as its first argument followed by additional <i>optional</i> arguments.
- * 
- * <pre>
- * <code>
+ * A {@link EntityCallback} interface needs to define a callback method accepting an object of the parameterized type as
+ * its first argument followed by additional <i>optional</i> arguments.
+ *
+ * <pre class="code">
  *
  * public interface BeforeSaveCallback&lt;T&gt; extends EntityCallback&lt;T&gt; {
  *
- *     T onBeforeSave(T entity, String collection);
+ * 	T onBeforeSave(T entity, String collection);
  * }
- * </code>
  * </pre>
  *
- * The
- *
  * @author Mark Paluch
  * @author Christoph Strobl
- * @param <T> Entity type. Used to detect {@link EntityCallback callbacks} to invoke via their generic type signature.
+ * @param <T> Entity type used to detect {@link EntityCallback callbacks} to invoke via their generic type signature.
+ * @since 2.2
  * @see org.springframework.core.Ordered
  * @see org.springframework.core.annotation.Order
  */

src/main/java/org/springframework/data/mapping/callback/EntityCallbacks.java

@@ -19,8 +19,12 @@ import org.springframework.beans.factory.BeanFactory;
 import org.springframework.util.Assert;
 
 /**
+ * Interface to be implemented by objects that can manage a number of {@link EntityCallback} objects and invoke these
+ * with a specific entity.
+ *
  * @author Christoph Strobl
  * @since 2.2
+ * @see EntityCallback
  */
 public interface EntityCallbacks {
 
@@ -39,7 +43,7 @@ public interface EntityCallbacks {
 	 * @param callbackType must not be {@literal null}.
 	 * @param entity must not be {@literal null}.
 	 * @param args optional arguments.
-	 * @param <T>
+	 * @param <T> Entity type.
 	 * @return never {@literal null}.
 	 * @throws IllegalArgumentException if a required argument is {@literal null}.
 	 */

src/main/java/org/springframework/data/mapping/callback/ReactiveEntityCallbacks.java

@@ -21,8 +21,12 @@ import org.springframework.beans.factory.BeanFactory;
 import org.springframework.util.Assert;
 
 /**
+ * Interface to be implemented by objects that can manage a number of {@link EntityCallback} objects and invoke these
+ * with a specific entity.
+ *
  * @author Christoph Strobl
  * @since 2.2
+ * @see EntityCallback
  */
 public interface ReactiveEntityCallbacks {
 
@@ -42,7 +46,7 @@ public interface ReactiveEntityCallbacks {
 	 * @param callbackType must not be {@literal null}.
 	 * @param entity must not be {@literal null}.
 	 * @param args optional arguments.
-	 * @param <T>
+	 * @param <T> Entity type.
 	 * @return a {@link Mono} emitting the result after invoking the callbacks.
 	 * @throws IllegalArgumentException if a required argument is {@literal null}.
 	 */