Permalink
Browse files

Added CacheEntryListenerException and updated Javadoc with behaviour …

…as discussed with YC and BFF.
  • Loading branch information...
gregrluck committed Jan 19, 2012
1 parent 1e31574 commit 628b83e82a5356acdbe70a72474a594fa45c2f1c
@@ -26,13 +26,15 @@
*
* @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;
}
@@ -23,6 +23,7 @@
* 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;
}
@@ -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?
*
@@ -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);
+ }
+
+}
@@ -24,13 +24,15 @@
*
* @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;
}
@@ -25,13 +25,15 @@
*
* @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;
}
@@ -26,13 +26,15 @@
*
* @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;
}
@@ -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);
}
@@ -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

0 comments on commit 628b83e

Please sign in to comment.