Index: applications/editors/josm/plugins/eventbus/src/org/openstreetmap/josm/eventbus/Dispatcher.java =================================================================== --- applications/editors/josm/plugins/eventbus/src/org/openstreetmap/josm/eventbus/Dispatcher.java (revision 34042) +++ applications/editors/josm/plugins/eventbus/src/org/openstreetmap/josm/eventbus/Dispatcher.java (revision 34043) @@ -42,4 +42,5 @@ * thread. That is, all subscribers to a single event A will be called before any subscribers to * any events B and C that are posted to the event bus by the subscribers to A. + * @return dispatcher */ static Dispatcher perThreadDispatchQueue() { @@ -52,4 +53,5 @@ * For async dispatch, an {@linkplain #immediate() immediate} dispatcher should generally be * preferable. + * @return dispatcher */ static Dispatcher legacyAsync() { @@ -61,4 +63,5 @@ * without using an intermediate queue to change the dispatch order. This is effectively a * depth-first dispatch order, vs. breadth-first when using a queue. + * @return dispatcher */ static Dispatcher immediate() { @@ -66,5 +69,9 @@ } - /** Dispatches the given {@code event} to the given {@code subscribers}. */ + /** + * Dispatches the given {@code event} to the given {@code subscribers}. + * @param event event to dispatch + * @param subscribers subscribers to notify + */ abstract void dispatch(Object event, Iterator subscribers); Index: applications/editors/josm/plugins/eventbus/src/org/openstreetmap/josm/eventbus/EventBus.java =================================================================== --- applications/editors/josm/plugins/eventbus/src/org/openstreetmap/josm/eventbus/EventBus.java (revision 34042) +++ applications/editors/josm/plugins/eventbus/src/org/openstreetmap/josm/eventbus/EventBus.java (revision 34043) @@ -100,5 +100,9 @@ private final Dispatcher dispatcher; + /** + * Simple executor singleton that runs commands in the same thread. + */ enum DirectExecutor implements Executor { + /** unique instance */ INSTANCE; @@ -142,4 +146,11 @@ } + /** + * Constructs a new {@code EventBus}. + * @param identifier the identifier for this event bus. Must not be null + * @param executor the default executor to use for dispatching events to subscribers. Must not be null + * @param dispatcher the event dispatcher. Must not be null + * @param exceptionHandler handles the exceptions thrown by a subscriber. Must not be null + */ EventBus( String identifier, @@ -163,10 +174,17 @@ } - /** Returns the default executor this event bus uses for dispatching events to subscribers. */ + /** + * Returns the default executor this event bus uses for dispatching events to subscribers. + * @return the default executor this event bus uses for dispatching events to subscribers + */ final Executor executor() { return executor; } - /** Handles the given exception thrown by a subscriber with the given context. */ + /** + * Handles the given exception thrown by a subscriber with the given context. + * @param e exception thrown by a subscriber + * @param context subscriber context + */ void handleSubscriberException(Throwable e, SubscriberExceptionContext context) { Objects.requireNonNull(e); @@ -229,4 +247,5 @@ /** Simple logging handler for subscriber exceptions. */ static final class LoggingHandler implements SubscriberExceptionHandler { + /** unique instance */ static final LoggingHandler INSTANCE = new LoggingHandler(); Index: applications/editors/josm/plugins/eventbus/src/org/openstreetmap/josm/eventbus/Subscriber.java =================================================================== --- applications/editors/josm/plugins/eventbus/src/org/openstreetmap/josm/eventbus/Subscriber.java (revision 34042) +++ applications/editors/josm/plugins/eventbus/src/org/openstreetmap/josm/eventbus/Subscriber.java (revision 34043) @@ -31,5 +31,11 @@ class Subscriber { - /** Creates a {@code Subscriber} for {@code method} on {@code listener}. */ + /** + * Creates a {@code Subscriber} for {@code method} on {@code listener}. + * @param bus event bus + * @param listener listener + * @param method method + * @return subscriber + */ static Subscriber create(EventBus bus, Object listener, Method method) { return isDeclaredThreadSafe(method) @@ -59,10 +65,11 @@ } - /** Dispatches {@code event} to this subscriber using the proper executor. */ + /** + * Dispatches {@code event} to this subscriber using the proper executor. + * @param event event to dispatch + */ final void dispatchEvent(final Object event) { executor.execute( - new Runnable() { - @Override - public void run() { + () -> { try { invokeSubscriberMethod(event); @@ -70,6 +77,5 @@ bus.handleSubscriberException(e.getCause(), context(event)); } - } - }); + }); } @@ -77,4 +83,6 @@ * Invokes the subscriber method. This method can be overridden to make the invocation * synchronized. + * @param event event to dispatch + * @throws InvocationTargetException if the invocation fails */ void invokeSubscriberMethod(Object event) throws InvocationTargetException { @@ -93,5 +101,9 @@ } - /** Gets the context for the given event. */ + /** + * Gets the context for the given event. + * @param event event + * @return context for the given event + */ private SubscriberExceptionContext context(Object event) { return new SubscriberExceptionContext(bus, event, target, method); @@ -118,4 +130,6 @@ * Checks whether {@code method} is thread-safe, as indicated by the presence of the {@link * AllowConcurrentEvents} annotation. + * @param method method to check + * @return {@code true} if {@code method} is thread-safe */ private static boolean isDeclaredThreadSafe(Method method) { Index: applications/editors/josm/plugins/eventbus/src/org/openstreetmap/josm/eventbus/SubscriberRegistry.java =================================================================== --- applications/editors/josm/plugins/eventbus/src/org/openstreetmap/josm/eventbus/SubscriberRegistry.java (revision 34042) +++ applications/editors/josm/plugins/eventbus/src/org/openstreetmap/josm/eventbus/SubscriberRegistry.java (revision 34043) @@ -54,9 +54,16 @@ private final EventBus bus; + /** + * Constructs a new {@code SubscriberRegistry}. + * @param bus event bus + */ SubscriberRegistry(EventBus bus) { this.bus = Objects.requireNonNull(bus); } - /** Registers all subscriber methods on the given listener object. */ + /** + * Registers all subscriber methods on the given listener object. + * @param listener listener + */ void register(Object listener) { MultiMap, Subscriber> listenerMethods = findAllSubscribers(listener); @@ -78,5 +85,7 @@ } - /** Unregisters all subscribers on the given listener object. */ + /** Unregisters all subscribers on the given listener object. + * @param listener listener + */ void unregister(Object listener) { MultiMap, Subscriber> listenerMethods = findAllSubscribers(listener); @@ -101,4 +110,9 @@ } + /** + * Returns subscribers for given {@code eventType}. Only used for unit tests. + * @param eventType event type + * @return subscribers for given {@code eventType}. Can be empty, but never null + */ Set getSubscribersForTesting(Class eventType) { return firstNonNull(subscribers.get(eventType), new HashSet()); @@ -108,4 +122,6 @@ * Gets an iterator representing an immutable snapshot of all subscribers to the given event at * the time this method is called. + * @param event event + * @return subscribers iterator */ Iterator getSubscribers(Object event) { @@ -127,4 +143,6 @@ /** * Returns all subscribers for the given listener grouped by the type of event they subscribe to. + * @param listener listener + * @return all subscribers for the given listener */ private MultiMap, Subscriber> findAllSubscribers(Object listener) { @@ -175,4 +193,6 @@ * Flattens a class's type hierarchy into a set of {@code Class} objects including all * superclasses (transitively) and all interfaces implemented by these superclasses. + * @param concreteClass concrete class + * @return set of {@code Class} objects including all superclasses and interfaces */ static Set> flattenHierarchy(Class concreteClass) { @@ -205,5 +225,5 @@ } } - + /** * Returns the first of two given parameters that is not {@code null}, if either is, or otherwise @@ -214,8 +234,7 @@ * Predicates.notNull())}, static importing as necessary. * - *

Note: if {@code first} is represented as an {@link Optional}, this can be - * accomplished with {@link Optional#or(Object) first.or(second)}. That approach also allows for - * lazy evaluation of the fallback instance, using {@link Optional#or(Supplier) - * first.or(supplier)}. + * @param object type + * @param first first object + * @param second second object * * @return {@code first} if it is non-null; otherwise {@code second} if it is non-null @@ -232,5 +251,5 @@ throw new NullPointerException("Both parameters are null"); } - + private static Set> getClassesAndInterfaces(Class clazz) { Set> result = new HashSet<>(); Index: applications/editors/josm/plugins/eventbus/src/org/openstreetmap/josm/plugins/eventbus/EventBusPlugin.java =================================================================== --- applications/editors/josm/plugins/eventbus/src/org/openstreetmap/josm/plugins/eventbus/EventBusPlugin.java (revision 34042) +++ applications/editors/josm/plugins/eventbus/src/org/openstreetmap/josm/plugins/eventbus/EventBusPlugin.java (revision 34043) @@ -379,4 +379,7 @@ } + /** + * Registers all JOSM listeners. + */ void registerAllJosmListeners() { Main.addProjectionChangeListener(projectionChangeListener); @@ -399,4 +402,7 @@ } + /** + * Unregisters all JOSM listeners. + */ void unregisterAllJosmListeners() { Main.removeProjectionChangeListener(projectionChangeListener);