Added CacheEntryListenerException and updated Javadoc with behaviour …

…as discussed with YC and BFF.

src/main/java/javax/cache/event/CacheEntryCreatedListener.java

@@ -26,13 +26,15 @@ public interface CacheEntryCreatedListener<K, V> extends CacheEntryListener<K, V
      *
      * @param event The entry just added.
      * @see #entriesCreated(Iterable)
+     * @throws CacheEntryListenerException if there is problem executing the listener
      */
-    void entryCreated(CacheEntryEvent<? extends K, ? extends V> event);
+    void entryCreated(CacheEntryEvent<? extends K, ? extends V> event) throws CacheEntryListenerException;
 
     /**
      * Called after the entries have been created (put into the cache where no previous mapping existed).
      *
      * @param events The entries just added.
+     * @throws CacheEntryListenerException if there is problem executing the listener
      */
-    void entriesCreated(Iterable<CacheEntryEvent<? extends K, ? extends V>> events);
+    void entriesCreated(Iterable<CacheEntryEvent<? extends K, ? extends V>> events) throws CacheEntryListenerException;
 }

src/main/java/javax/cache/event/CacheEntryExpiredListener.java

@@ -23,6 +23,7 @@ public interface CacheEntryExpiredListener<K, V> extends CacheEntryListener<K, V
      * This is distinguished from the {@link CacheEntryRemovedListener} where an explicit remove call was made.
      *
      * @param entry The entry that has expired.
+     * @throws CacheEntryListenerException if there is problem executing the listener
      */
-    void entryExpired(CacheEntryEvent<? extends K, ? extends V> entry);
+    void entryExpired(CacheEntryEvent<? extends K, ? extends V> entry) throws CacheEntryListenerException;
 }

src/main/java/javax/cache/event/CacheEntryListener.java

@@ -33,7 +33,6 @@
  *
  * todo simplify back to one
  * todo Java SE wants one method per listener. Yannis to find email
- * todo remove Notification Scope
  * todo say something about exceptions
  * todo say the key cannot be mutated?
  *

src/main/java/javax/cache/event/CacheEntryListenerException.java

@@ -0,0 +1,77 @@
+/**
+ *  Copyright (c) 2011 Terracotta, Inc.
+ *  Copyright (c) 2011 Oracle and/or its affiliates.
+ *
+ *  All rights reserved. Use is subject to license terms.
+ */
+
+package javax.cache.event;
+
+import javax.cache.CacheException;
+
+/**
+ * An exception to indicate a problem has occurred with a listener.
+ * As listeners are only called after the cache has been updated, the update
+ * to the cache is not affected.
+ *
+ * @author Greg Luck
+ * @since 1.0
+ *
+ */
+public class CacheEntryListenerException extends CacheException {
+
+    private static final long serialVersionUID = 1L;
+
+
+    /**
+     * Constructs a new InvalidConfigurationException.
+     */
+    public CacheEntryListenerException() {
+        super();
+    }
+
+    /**
+     * Constructs a new CacheEntryListenerException with a message string.
+     *
+     * @param message the detail message. The detail message is saved for
+     *                later retrieval by the {@link #getMessage()} method.
+     */
+    public CacheEntryListenerException(String message) {
+        super(message);
+    }
+
+    /**
+     * Constructs a CacheEntryListenerException with a message string, and
+     * a base exception
+     *
+     * @param message   the detail message. The detail message is saved for
+     *                  later retrieval by the {@link #getMessage()} method.
+     * @param  cause the cause (which is saved for later retrieval by the
+     *         {@link #getCause()} method).  (A <tt>null</tt> value is
+     *         permitted, and indicates that the cause is nonexistent or
+     *         unknown.)
+     * @since  1.0
+     */
+    public CacheEntryListenerException(String message, Throwable cause) {
+        super(message, cause);
+    }
+
+
+    /**
+     * Constructs a new CacheEntryListenerException with the specified cause and a
+     * detail message of <tt>(cause==null ? null : cause.toString())</tt>
+     * (which typically contains the class and detail message of
+     * <tt>cause</tt>).  This constructor is useful for runtime exceptions
+     * that are little more than wrappers for other throwables.
+     *
+     * @param  cause the cause (which is saved for later retrieval by the
+     *         {@link #getCause()} method).  (A <tt>null</tt> value is
+     *         permitted, and indicates that the cause is nonexistent or
+     *         unknown.)
+     * @since  1.0
+     */
+    public CacheEntryListenerException(Throwable cause) {
+        super(cause);
+    }
+
+}

src/main/java/javax/cache/event/CacheEntryReadListener.java

@@ -24,13 +24,15 @@ public interface CacheEntryReadListener<K, V> extends CacheEntryListener<K, V> {
      *
      * @param event The event just read.
      * @see #entriesRead(Iterable)
+     * @throws CacheEntryListenerException if there is problem executing the listener
      */
-    void entryRead(CacheEntryEvent<? extends K, ? extends V> event);
+    void entryRead(CacheEntryEvent<? extends K, ? extends V> event) throws CacheEntryListenerException;
 
     /**
      * Called after the entries have been read. Only entries which existed in the cache are passed in.
      *
      * @param events The events just read.
+     * @throws CacheEntryListenerException if there is problem executing the listener
      */
-    void entriesRead(Iterable<CacheEntryEvent<? extends K, ? extends V>> events);
+    void entriesRead(Iterable<CacheEntryEvent<? extends K, ? extends V>> events) throws CacheEntryListenerException;
 }

src/main/java/javax/cache/event/CacheEntryRemovedListener.java

@@ -25,13 +25,15 @@ public interface CacheEntryRemovedListener<K, V> extends CacheEntryListener<K, V
      *
      * @param event The entry just removed.
      * @see #entryRemoved(CacheEntryEvent)
+     * @throws CacheEntryListenerException if there is problem executing the listener
      */
-    void entryRemoved(CacheEntryEvent<? extends K, ? extends V> event);
+    void entryRemoved(CacheEntryEvent<? extends K, ? extends V> event) throws CacheEntryListenerException;
 
     /**
      * Called after the entries have been removed by a batch operation.
      *
      * @param events The entry just removed.
+     * @throws CacheEntryListenerException if there is problem executing the listener
      */
-    void entriesRemoved(Iterable<CacheEntryEvent<? extends K, ? extends V>> events);
+    void entriesRemoved(Iterable<CacheEntryEvent<? extends K, ? extends V>> events) throws CacheEntryListenerException;
 }

src/main/java/javax/cache/event/CacheEntryUpdatedListener.java

@@ -26,13 +26,15 @@ public interface CacheEntryUpdatedListener<K, V> extends CacheEntryListener<K, V
      *
      * @param event The event just updated.
      * @see #entriesUpdated(Iterable)
+     * @throws CacheEntryListenerException if there is problem executing the listener
      */
-    void entryUpdated(CacheEntryEvent<? extends K, ? extends V> event);
+    void entryUpdated(CacheEntryEvent<? extends K, ? extends V> event) throws CacheEntryListenerException;
 
     /**
      * Called after the entries have been updated (put into the cache where a previous mapping existed).
      *
      * @param events The entries just updated.
+     * @throws CacheEntryListenerException if there is problem executing the listener
      */
-    void entriesUpdated(Iterable<CacheEntryEvent<? extends K, ? extends V>> events);
+    void entriesUpdated(Iterable<CacheEntryEvent<? extends K, ? extends V>> events) throws CacheEntryListenerException;
 }

src/main/java/javax/cache/event/Filter.java

@@ -7,15 +7,18 @@
 package javax.cache.event;
 
 /**
- * Run a test for a condition. Allows for pluggable filtering behavior.
+ * Evaluates a {@link CacheEntryEvent} as to whether a listener should be invoked.
+ * This allows for pluggable filtering behavior.
  * @author Yannis Cosmadopoulos
+ * @author Greg Luck
  * @since 1.0
  */
 public interface Filter {
+
     /**
      * Apply the test to the object
-     * @param o an object
-     * @return true if the test passes, false otherwise.
+     * @param cacheEntryEvent the event to evaluate for inclusion
+     * @return true if the listener should be invoked, false otherwise.
      */
-    boolean evaluate(Object o);
+    boolean evaluate(CacheEntryEvent cacheEntryEvent);
 }

src/main/java/javax/cache/event/package-info.java

@@ -6,8 +6,23 @@
  */
 
 /**
- This package contains event listeners.
+ This package contains event listener interfaces.
 
+ These may be registered for callback notification of the cache events.
+ The specific interface should be implemented for each event type a callback
+ is desired on.
+ <p/>
+ Events may be filtered by any {@link Filter} registered with the event listener.
+ <p/>
+ Event notifications occur synchronously in the line of execution of the calling thread.
+ The calling thread blocks until the listener has completed execution or thrown a {@link CacheEntryListenerException}.
+ <p/>
+ Listeners are invoked <strong>after</strong> the cache is updated. If the listener throws
+ an {@link CacheEntryListenerException} this will propagate back to the caller but it does not affect the cache update
+ as it already completed before the listener was called. If the cache is transactional, transactions
+ must commit <strong>before</strong> listeners are called. If an exception is thrown by a listener this does not
+ affect the transaction as the transaction has already completed.
+ <p/>
  @author Greg Luck
  @author Yannis Cosmadopoulos
  @since 1.0