EventHandler: add optional key attribute

This attribute is a unique subscription key. If multiple EventHandler
annotations exist with the same key, only the first to be subscribed
will be respected; the others will be silently ignored. If no key is
specified, the event handler is always subscribed.

This feature exists to enable better extensibility of event handling:
if code exists that handles an event in an undesirable way, that logic
can be completely intercepted and overridden by writing more code that
handles the event in a better way, specifying the same key as the
original.

Author: ctrueden

src/main/java/org/scijava/event/DefaultEventService.java

@@ -35,6 +35,7 @@
 import java.lang.reflect.Method;
 import java.util.ArrayList;
 import java.util.Collection;
+import java.util.HashSet;
 import java.util.List;
 import java.util.WeakHashMap;
 
@@ -79,6 +80,12 @@ public class DefaultEventService extends AbstractService implements
 
 	private DefaultEventBus eventBus;
 
+	/**
+	 * Set of claimed {@link EventHandler#key()}s. Additional event handlers
+	 * specifying the same key will be ignored rather than subscribed.
+	 */
+	private final HashSet<String> keys = new HashSet<String>();
+
 	// -- EventService methods --
 
 	@Override
@@ -100,11 +107,23 @@ public List<EventSubscriber<?>> subscribe(final Object o) {
 		final List<Method> eventHandlers =
 			ClassUtils.getAnnotatedMethods(o.getClass(), EventHandler.class);
 		for (final Method m : eventHandlers) {
+			// verify that the event handler method is valid
 			final Class<? extends SciJavaEvent> eventClass = getEventClass(m);
 			if (eventClass == null) {
 				log.warn("Invalid EventHandler method: " + m);
 				continue;
 			}
+
+			// verify that the event handler key isn't already claimed
+			final String key = m.getAnnotation(EventHandler.class).key();
+			if (!key.isEmpty()) {
+				synchronized (keys) {
+					if (keys.contains(key)) continue;
+					keys.add(key);
+				}
+			}
+
+			// subscribe the event handler
 			subscribers.add(subscribe(eventClass, o, m));
 		}
 		return subscribers;

src/main/java/org/scijava/event/EventHandler.java

@@ -59,5 +59,19 @@
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.METHOD)
 public @interface EventHandler {
-	// no attributes
+
+	/**
+	 * Unique subscription key. If multiple {@code @EventHandler} annotations
+	 * exist with the same key, only the first to be subscribed will be respected;
+	 * the others will be silently ignored. If no key is specified, the event
+	 * handler is always subscribed.
+	 * <p>
+	 * This feature exists to enable better extensibility of event handling: if
+	 * code exists that handles an event in an undesirable way, that logic can be
+	 * completely intercepted and overridden by writing more code that handles the
+	 * event in a better way, specifying the same key as the original.
+	 * </p>
+	 */
+	String key() default "";
+
 }