From 628b83e82a5356acdbe70a72474a594fa45c2f1c Mon Sep 17 00:00:00 2001 From: gregrluck Date: Thu, 19 Jan 2012 18:28:37 +1000 Subject: [PATCH] Added CacheEntryListenerException and updated Javadoc with behaviour as discussed with YC and BFF. --- .../event/CacheEntryCreatedListener.java | 6 +- .../event/CacheEntryExpiredListener.java | 3 +- .../javax/cache/event/CacheEntryListener.java | 1 - .../event/CacheEntryListenerException.java | 77 +++++++++++++++++++ .../cache/event/CacheEntryReadListener.java | 6 +- .../event/CacheEntryRemovedListener.java | 6 +- .../event/CacheEntryUpdatedListener.java | 6 +- src/main/java/javax/cache/event/Filter.java | 11 ++- .../java/javax/cache/event/package-info.java | 17 +++- 9 files changed, 118 insertions(+), 15 deletions(-) create mode 100644 src/main/java/javax/cache/event/CacheEntryListenerException.java diff --git a/src/main/java/javax/cache/event/CacheEntryCreatedListener.java b/src/main/java/javax/cache/event/CacheEntryCreatedListener.java index 68c0816..a420a88 100644 --- a/src/main/java/javax/cache/event/CacheEntryCreatedListener.java +++ b/src/main/java/javax/cache/event/CacheEntryCreatedListener.java @@ -26,13 +26,15 @@ public interface CacheEntryCreatedListener extends CacheEntryListener event); + void entryCreated(CacheEntryEvent 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> events); + void entriesCreated(Iterable> events) throws CacheEntryListenerException; } diff --git a/src/main/java/javax/cache/event/CacheEntryExpiredListener.java b/src/main/java/javax/cache/event/CacheEntryExpiredListener.java index 9623a73..3f53a58 100644 --- a/src/main/java/javax/cache/event/CacheEntryExpiredListener.java +++ b/src/main/java/javax/cache/event/CacheEntryExpiredListener.java @@ -23,6 +23,7 @@ public interface CacheEntryExpiredListener extends CacheEntryListener entry); + void entryExpired(CacheEntryEvent entry) throws CacheEntryListenerException; } diff --git a/src/main/java/javax/cache/event/CacheEntryListener.java b/src/main/java/javax/cache/event/CacheEntryListener.java index d6a908d..e53c7f2 100644 --- a/src/main/java/javax/cache/event/CacheEntryListener.java +++ b/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? * diff --git a/src/main/java/javax/cache/event/CacheEntryListenerException.java b/src/main/java/javax/cache/event/CacheEntryListenerException.java new file mode 100644 index 0000000..6a200a3 --- /dev/null +++ b/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 null 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 (cause==null ? null : cause.toString()) + * (which typically contains the class and detail message of + * cause). 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 null value is + * permitted, and indicates that the cause is nonexistent or + * unknown.) + * @since 1.0 + */ + public CacheEntryListenerException(Throwable cause) { + super(cause); + } + +} diff --git a/src/main/java/javax/cache/event/CacheEntryReadListener.java b/src/main/java/javax/cache/event/CacheEntryReadListener.java index 4aa28d5..bc0266a 100644 --- a/src/main/java/javax/cache/event/CacheEntryReadListener.java +++ b/src/main/java/javax/cache/event/CacheEntryReadListener.java @@ -24,13 +24,15 @@ public interface CacheEntryReadListener extends CacheEntryListener { * * @param event The event just read. * @see #entriesRead(Iterable) + * @throws CacheEntryListenerException if there is problem executing the listener */ - void entryRead(CacheEntryEvent event); + void entryRead(CacheEntryEvent 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> events); + void entriesRead(Iterable> events) throws CacheEntryListenerException; } diff --git a/src/main/java/javax/cache/event/CacheEntryRemovedListener.java b/src/main/java/javax/cache/event/CacheEntryRemovedListener.java index e149cbd..d8014f5 100644 --- a/src/main/java/javax/cache/event/CacheEntryRemovedListener.java +++ b/src/main/java/javax/cache/event/CacheEntryRemovedListener.java @@ -25,13 +25,15 @@ public interface CacheEntryRemovedListener extends CacheEntryListener event); + void entryRemoved(CacheEntryEvent 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> events); + void entriesRemoved(Iterable> events) throws CacheEntryListenerException; } diff --git a/src/main/java/javax/cache/event/CacheEntryUpdatedListener.java b/src/main/java/javax/cache/event/CacheEntryUpdatedListener.java index 75d2b7b..e911434 100644 --- a/src/main/java/javax/cache/event/CacheEntryUpdatedListener.java +++ b/src/main/java/javax/cache/event/CacheEntryUpdatedListener.java @@ -26,13 +26,15 @@ public interface CacheEntryUpdatedListener extends CacheEntryListener event); + void entryUpdated(CacheEntryEvent 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> events); + void entriesUpdated(Iterable> events) throws CacheEntryListenerException; } diff --git a/src/main/java/javax/cache/event/Filter.java b/src/main/java/javax/cache/event/Filter.java index de74c3c..a5e9871 100644 --- a/src/main/java/javax/cache/event/Filter.java +++ b/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); } diff --git a/src/main/java/javax/cache/event/package-info.java b/src/main/java/javax/cache/event/package-info.java index b095109..3b1941d 100644 --- a/src/main/java/javax/cache/event/package-info.java +++ b/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. +

+ Events may be filtered by any {@link Filter} registered with the event listener. +

+ 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}. +

+ Listeners are invoked after 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 before listeners are called. If an exception is thrown by a listener this does not + affect the transaction as the transaction has already completed. +

@author Greg Luck @author Yannis Cosmadopoulos @since 1.0