Changeset 34043 in osm for applications/editors


Ignore:
Timestamp:
2018-02-05T20:59:52+01:00 (7 years ago)
Author:
donvip
Message:

fix javadoc errors and warnings

Location:
applications/editors/josm/plugins/eventbus/src/org/openstreetmap/josm
Files:
5 edited

Legend:

Unmodified
Added
Removed

  • applications/editors/josm/plugins/eventbus/src/org/openstreetmap/josm/eventbus/Dispatcher.java

    r34000 r34043  
    4242   * thread. That is, all subscribers to a single event A will be called before any subscribers to
    4343   * any events B and C that are posted to the event bus by the subscribers to A.
     44   * @return dispatcher
    4445   */
    4546  static Dispatcher perThreadDispatchQueue() {
    … …  
    5253   * For async dispatch, an {@linkplain #immediate() immediate} dispatcher should generally be
    5354   * preferable.
     55   * @return dispatcher
    5456   */
    5557  static Dispatcher legacyAsync() {
    … …  
    6163   * without using an intermediate queue to change the dispatch order. This is effectively a
    6264   * depth-first dispatch order, vs. breadth-first when using a queue.
     65   * @return dispatcher
    6366   */
    6467  static Dispatcher immediate() {
    … …  
    6669  }
    6770
    68   /** Dispatches the given {@code event} to the given {@code subscribers}. */
     71  /**
     72   * Dispatches the given {@code event} to the given {@code subscribers}.
     73   * @param event event to dispatch
     74   * @param subscribers subscribers to notify
     75   */
    6976  abstract void dispatch(Object event, Iterator<Subscriber> subscribers);
    7077

  • applications/editors/josm/plugins/eventbus/src/org/openstreetmap/josm/eventbus/EventBus.java

    r34000 r34043  
    100100  private final Dispatcher dispatcher;
    101101
     102  /**
     103   * Simple executor singleton that runs commands in the same thread.
     104   */
    102105  enum DirectExecutor implements Executor {
     106    /** unique instance */
    103107    INSTANCE;
    104108
    … …  
    142146  }
    143147
     148  /**
     149   * Constructs a new {@code EventBus}.
     150   * @param identifier the identifier for this event bus. Must not be null
     151   * @param executor the default executor to use for dispatching events to subscribers. Must not be null
     152   * @param dispatcher the event dispatcher. Must not be null
     153   * @param exceptionHandler handles the exceptions thrown by a subscriber. Must not be null
     154   */
    144155  EventBus(
    145156      String identifier,
    … …  
    163174  }
    164175
    165   /** Returns the default executor this event bus uses for dispatching events to subscribers. */
     176  /**
     177   * Returns the default executor this event bus uses for dispatching events to subscribers.
     178   * @return the default executor this event bus uses for dispatching events to subscribers
     179   */
    166180  final Executor executor() {
    167181    return executor;
    168182  }
    169183
    170   /** Handles the given exception thrown by a subscriber with the given context. */
     184  /**
     185   * Handles the given exception thrown by a subscriber with the given context.
     186   * @param e exception thrown by a subscriber
     187   * @param context subscriber context
     188   */
    171189  void handleSubscriberException(Throwable e, SubscriberExceptionContext context) {
    172190    Objects.requireNonNull(e);
    … …  
    229247  /** Simple logging handler for subscriber exceptions. */
    230248  static final class LoggingHandler implements SubscriberExceptionHandler {
     249    /** unique instance */
    231250    static final LoggingHandler INSTANCE = new LoggingHandler();
    232251

  • applications/editors/josm/plugins/eventbus/src/org/openstreetmap/josm/eventbus/Subscriber.java

    r34000 r34043  
    3131class Subscriber {
    3232
    33   /** Creates a {@code Subscriber} for {@code method} on {@code listener}. */
     33  /**
     34   * Creates a {@code Subscriber} for {@code method} on {@code listener}.
     35   * @param bus event bus
     36   * @param listener listener
     37   * @param method method
     38   * @return subscriber
     39   */
    3440  static Subscriber create(EventBus bus, Object listener, Method method) {
    3541    return isDeclaredThreadSafe(method)
    … …  
    5965  }
    6066
    61   /** Dispatches {@code event} to this subscriber using the proper executor. */
     67  /**
     68   * Dispatches {@code event} to this subscriber using the proper executor.
     69   * @param event event to dispatch
     70   */
    6271  final void dispatchEvent(final Object event) {
    6372    executor.execute(
    64         new Runnable() {
    65           @Override
    66           public void run() {
     73        () -> {
    6774            try {
    6875              invokeSubscriberMethod(event);
    … …  
    7077              bus.handleSubscriberException(e.getCause(), context(event));
    7178            }
    72           }
    73         });
     79          });
    7480  }
    7581
    … …  
    7783   * Invokes the subscriber method. This method can be overridden to make the invocation
    7884   * synchronized.
     85   * @param event event to dispatch
     86   * @throws InvocationTargetException if the invocation fails
    7987   */
    8088  void invokeSubscriberMethod(Object event) throws InvocationTargetException {
    … …  
    93101  }
    94102
    95   /** Gets the context for the given event. */
     103  /**
     104   * Gets the context for the given event.
     105   * @param event event
     106   * @return context for the given event
     107   */
    96108  private SubscriberExceptionContext context(Object event) {
    97109    return new SubscriberExceptionContext(bus, event, target, method);
    … …  
    118130   * Checks whether {@code method} is thread-safe, as indicated by the presence of the {@link
    119131   * AllowConcurrentEvents} annotation.
     132   * @param method method to check
     133   * @return {@code true} if {@code method} is thread-safe
    120134   */
    121135  private static boolean isDeclaredThreadSafe(Method method) {

  • applications/editors/josm/plugins/eventbus/src/org/openstreetmap/josm/eventbus/SubscriberRegistry.java

    r34000 r34043  
    5454  private final EventBus bus;
    5555
     56  /**
     57   * Constructs a new {@code SubscriberRegistry}.
     58   * @param bus event bus
     59   */
    5660  SubscriberRegistry(EventBus bus) {
    5761    this.bus = Objects.requireNonNull(bus);
    5862  }
    5963
    60   /** Registers all subscriber methods on the given listener object. */
     64  /**
     65   * Registers all subscriber methods on the given listener object.
     66   * @param listener listener
     67   */
    6168  void register(Object listener) {
    6269    MultiMap<Class<?>, Subscriber> listenerMethods = findAllSubscribers(listener);
    … …  
    7885  }
    7986
    80   /** Unregisters all subscribers on the given listener object. */
     87  /** Unregisters all subscribers on the given listener object.
     88   * @param listener listener
     89   */
    8190  void unregister(Object listener) {
    8291    MultiMap<Class<?>, Subscriber> listenerMethods = findAllSubscribers(listener);
    … …  
    101110  }
    102111
     112  /**
     113   * Returns subscribers for given {@code eventType}. Only used for unit tests.
     114   * @param eventType event type
     115   * @return subscribers for given {@code eventType}. Can be empty, but never null
     116   */
    103117  Set<Subscriber> getSubscribersForTesting(Class<?> eventType) {
    104118    return firstNonNull(subscribers.get(eventType), new HashSet<Subscriber>());
    … …  
    108122   * Gets an iterator representing an immutable snapshot of all subscribers to the given event at
    109123   * the time this method is called.
     124   * @param event event
     125   * @return subscribers iterator
    110126   */
    111127  Iterator<Subscriber> getSubscribers(Object event) {
    … …  
    127143  /**
    128144   * Returns all subscribers for the given listener grouped by the type of event they subscribe to.
     145   * @param listener listener
     146   * @return all subscribers for the given listener
    129147   */
    130148  private MultiMap<Class<?>, Subscriber> findAllSubscribers(Object listener) {
    … …  
    175193   * Flattens a class's type hierarchy into a set of {@code Class} objects including all
    176194   * superclasses (transitively) and all interfaces implemented by these superclasses.
     195   * @param concreteClass concrete class
     196   * @return set of {@code Class} objects including all superclasses and interfaces
    177197   */
    178198  static Set<Class<?>> flattenHierarchy(Class<?> concreteClass) {
    … …  
    205225    }
    206226  }
    207  
     227
    208228  /**
    209229   * Returns the first of two given parameters that is not {@code null}, if either is, or otherwise
    … …  
    214234   * Predicates.notNull())}, static importing as necessary.
    215235   *
    216    * <p><b>Note:</b> if {@code first} is represented as an {@link Optional}, this can be
    217    * accomplished with {@link Optional#or(Object) first.or(second)}. That approach also allows for
    218    * lazy evaluation of the fallback instance, using {@link Optional#or(Supplier)
    219    * first.or(supplier)}.
     236   * @param <T> object type
     237   * @param first first object
     238   * @param second second object
    220239   *
    221240   * @return {@code first} if it is non-null; otherwise {@code second} if it is non-null
    … …  
    232251    throw new NullPointerException("Both parameters are null");
    233252  }
    234  
     253
    235254  private static Set<Class<?>> getClassesAndInterfaces(Class<?> clazz) {
    236255      Set<Class<?>> result = new HashSet<>();

  • applications/editors/josm/plugins/eventbus/src/org/openstreetmap/josm/plugins/eventbus/EventBusPlugin.java

    r34034 r34043  
    379379    }
    380380
     381    /**
     382     * Registers all JOSM listeners.
     383     */
    381384    void registerAllJosmListeners() {
    382385        Main.addProjectionChangeListener(projectionChangeListener);
    … …  
    399402    }
    400403
     404    /**
     405     * Unregisters all JOSM listeners.
     406     */
    401407    void unregisterAllJosmListeners() {
    402408        Main.removeProjectionChangeListener(projectionChangeListener);
Note: See TracChangeset for help on using the changeset viewer.