javadoc for new event system

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

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

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<T>
 {
 
   /**
-   * 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();
 }

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;
 }

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.:
+ * 
+ * <pre><code>
+ *   @Extension
+ *   @Subscriber
+ *   @EagerSingleton
+ *   public class MyListener {
+ * 
+ *     @Subscribe
+ *     public void receiveEvent(Event event){
+ *       // do something with the event
+ *     }
+ * 
+ *   }
+ * </code></pre>
  *
  * @author Sebastian Sdorra
  * @since 1.23
+ * 
+ * @apiviz.landmark
  */
 @Documented
 @Target({ ElementType.TYPE })

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;