From 7dfe81b03bb1a78268cc27567e1ec65f78cce4a9 Mon Sep 17 00:00:00 2001 From: Sebastian Sdorra Date: Sat, 8 Dec 2012 14:32:46 +0100 Subject: [PATCH] javadoc for new event system --- .../common/eventbus/ThrowingEventBus.java | 3 +- .../sonia/scm/event/EventBusException.java | 4 +++ .../sonia/scm/event/HandlerEventBase.java | 9 ++--- .../java/sonia/scm/event/ScmEventBus.java | 34 +++++++++++-------- .../main/java/sonia/scm/event/Subscriber.java | 29 ++++++++++++++++ .../java/sonia/scm/event/package-info.java | 33 ++++++++++++++++++ 6 files changed, 93 insertions(+), 19 deletions(-) create mode 100644 scm-core/src/main/java/sonia/scm/event/package-info.java diff --git a/scm-core/src/main/java/com/google/common/eventbus/ThrowingEventBus.java b/scm-core/src/main/java/com/google/common/eventbus/ThrowingEventBus.java index 81794590e7..29db56f5b1 100644 --- a/scm-core/src/main/java/com/google/common/eventbus/ThrowingEventBus.java +++ b/scm-core/src/main/java/com/google/common/eventbus/ThrowingEventBus.java @@ -40,6 +40,7 @@ import sonia.scm.event.EventBusException; import java.lang.reflect.InvocationTargetException; /** + * {@link EventBus} which is able to throw {@link EventBusException}. * * @author Sebastian Sdorra * @since 1.23 @@ -48,7 +49,7 @@ public class ThrowingEventBus extends EventBus { /** - * Method description + * {@inheritDoc} * * * @param event diff --git a/scm-core/src/main/java/sonia/scm/event/EventBusException.java b/scm-core/src/main/java/sonia/scm/event/EventBusException.java index 6ae22bb43e..432c843bf0 100644 --- a/scm-core/src/main/java/sonia/scm/event/EventBusException.java +++ b/scm-core/src/main/java/sonia/scm/event/EventBusException.java @@ -31,7 +31,11 @@ package sonia.scm.event; +import com.google.common.eventbus.ThrowingEventBus; + /** + * Exception is thrown if from the {@link ThrowingEventBus} an error occurs + * during a synchronous event post operation. * * @author Sebastian Sdorra * @since 1.23 diff --git a/scm-core/src/main/java/sonia/scm/event/HandlerEventBase.java b/scm-core/src/main/java/sonia/scm/event/HandlerEventBase.java index 573267f015..fc6e13b361 100644 --- a/scm-core/src/main/java/sonia/scm/event/HandlerEventBase.java +++ b/scm-core/src/main/java/sonia/scm/event/HandlerEventBase.java @@ -36,6 +36,7 @@ package sonia.scm.event; import sonia.scm.HandlerEvent; /** + * Base class for hadler events. * * TODO for 2.0 rename to HandlerEvent * @@ -48,18 +49,18 @@ public interface HandlerEventBase { /** - * Method description + * Returns the type of the event, * * - * @return + * @return event type */ public HandlerEvent getEventType(); /** - * Method description + * Returns the item which has changed. * * - * @return + * @return changed item */ public T getItem(); } diff --git a/scm-core/src/main/java/sonia/scm/event/ScmEventBus.java b/scm-core/src/main/java/sonia/scm/event/ScmEventBus.java index 55b7b4a6b6..4dab7d835c 100644 --- a/scm-core/src/main/java/sonia/scm/event/ScmEventBus.java +++ b/scm-core/src/main/java/sonia/scm/event/ScmEventBus.java @@ -47,9 +47,14 @@ import org.slf4j.LoggerFactory; import java.util.concurrent.Executors; /** + * Dispatches events to listeners, and provides ways for listeners to register + * themselves. * + * @see {@link EventBus} * @author Sebastian Sdorra * @since 1.23 + * + * @apiviz.landmark */ public class ScmEventBus extends EventBus { @@ -66,7 +71,7 @@ public class ScmEventBus extends EventBus //~--- constructors --------------------------------------------------------- /** - * Constructs ... + * Constructs a new ScmEventBus * */ private ScmEventBus() @@ -79,10 +84,10 @@ public class ScmEventBus extends EventBus //~--- get methods ---------------------------------------------------------- /** - * Method description + * Returns the singleton instance of the ScmEventBus * * - * @return + * @return singleton instance */ public static ScmEventBus getInstance() { @@ -92,7 +97,7 @@ public class ScmEventBus extends EventBus //~--- methods -------------------------------------------------------------- /** - * Method description + * {@inheritDoc} * * * @param event @@ -106,7 +111,7 @@ public class ScmEventBus extends EventBus } /** - * Method description + * {@inheritDoc} * * * @param object @@ -118,11 +123,12 @@ public class ScmEventBus extends EventBus } /** - * Method description + * Registers a object to the eventbus. * + * @param object object to register + * @param async handle event asynchronously * - * @param object - * @param async + * @see {@link #register(java.lang.Object)} */ public void register(Object object, boolean async) { @@ -139,7 +145,7 @@ public class ScmEventBus extends EventBus } /** - * Method description + * {@inheritDoc} * * * @param object @@ -153,11 +159,11 @@ public class ScmEventBus extends EventBus } /** - * Method description + * Unregisters the object from eventbus. * * - * @param bus - * @param object + * @param bus event bus + * @param object object to unregister */ private void unregister(EventBus bus, Object object) { @@ -173,9 +179,9 @@ public class ScmEventBus extends EventBus //~--- fields --------------------------------------------------------------- - /** Field description */ + /** asynchronous event bus */ private AsyncEventBus asyncEventBus; - /** Field description */ + /** synchronous event bus */ private EventBus eventBus; } diff --git a/scm-core/src/main/java/sonia/scm/event/Subscriber.java b/scm-core/src/main/java/sonia/scm/event/Subscriber.java index d695cf2495..4df678427e 100644 --- a/scm-core/src/main/java/sonia/scm/event/Subscriber.java +++ b/scm-core/src/main/java/sonia/scm/event/Subscriber.java @@ -33,16 +33,45 @@ package sonia.scm.event; //~--- JDK imports ------------------------------------------------------------ +import com.google.common.eventbus.EventBus; +import com.google.common.eventbus.Subscribe; import java.lang.annotation.Documented; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; +import sonia.scm.EagerSingleton; /** + * The subscriber annotation could be use to register listener classes to the + * {@link ScmEventBus}. A registered listener object can use the + * {@link Subscribe} annotation for methods to receive events, + * for more informations have a look at {@link EventBus}. The annotated object + * is only bind to the {@link ScmEventBus}, if the the object is loaded from the + * injection system of SCM-Manager. If your object is not loaded by the + * injection system you have to register your object by yourself with the + * {@link ScmEventBus#register(Object, boolean)} method. If you would like to + * register object which is a "listener only" object you have to use the + * {@link EagerSingleton} scope for your object. E.g.: + * + * 

+ *   @Extension
+ *   @Subscriber
+ *   @EagerSingleton
+ *   public class MyListener {
+ * 
+ *     @Subscribe
+ *     public void receiveEvent(Event event){
+ *       // do something with the event
+ *     }
+ * 
+ *   }
+ *
* * @author Sebastian Sdorra * @since 1.23 + * + * @apiviz.landmark */ @Documented @Target({ ElementType.TYPE }) diff --git a/scm-core/src/main/java/sonia/scm/event/package-info.java b/scm-core/src/main/java/sonia/scm/event/package-info.java new file mode 100644 index 0000000000..eb2ebdd882 --- /dev/null +++ b/scm-core/src/main/java/sonia/scm/event/package-info.java @@ -0,0 +1,33 @@ +/** + * Copyright (c) 2010, Sebastian Sdorra All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. 2. Redistributions in + * binary form must reproduce the above copyright notice, this list of + * conditions and the following disclaimer in the documentation and/or other + * materials provided with the distribution. 3. Neither the name of SCM-Manager; + * nor the names of its contributors may be used to endorse or promote products + * derived from this software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR + * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL + * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER + * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, + * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + * + * http://bitbucket.org/sdorra/scm-manager + * + */ + +/** + * Event system of SCM-Manager + */ +package sonia.scm.event; \ No newline at end of file