Editing for core.pipeline

- Add javadocs
- Tighten access where appropiate
- Add check for non-public metric methods in the Pipeline

Author: Kiskae

src/main/java/nl/rug/jbi/jsm/core/pipeline/HandlerExecutor.java

@@ -1,7 +1,6 @@
 package nl.rug.jbi.jsm.core.pipeline;
 
 import com.google.common.base.Objects;
-import com.google.common.base.Preconditions;
 import nl.rug.jbi.jsm.core.calculator.BaseMetric;
 import nl.rug.jbi.jsm.core.calculator.MetricScope;
 import nl.rug.jbi.jsm.core.calculator.MetricState;
@@ -10,23 +9,46 @@
 import java.lang.reflect.InvocationTargetException;
 import java.lang.reflect.Method;
 
+import static com.google.common.base.Preconditions.checkNotNull;
+
+/**
+ * This class encapsulates a object-method pair accepting a certain data-type, derived from a metric.
+ * As data becomes available it gets sent through this object together with the associated MetricState to mutate that
+ * state using the method.
+ *
+ * @author David van Leusen
+ * @since 2014-06-02
+ */
 public class HandlerExecutor {
     private final Method eventMethod;
     private final BaseMetric metricCalculator;
 
-    public HandlerExecutor(final Method eventMethod, final BaseMetric metricCalculator) {
-        this.eventMethod = Preconditions.checkNotNull(eventMethod);
-        this.metricCalculator = Preconditions.checkNotNull(metricCalculator);
+    HandlerExecutor(final Method eventMethod, final BaseMetric metricCalculator) {
+        this.eventMethod = checkNotNull(eventMethod);
+        this.metricCalculator = checkNotNull(metricCalculator);
     }
 
+    /**
+     * @return The metric class this handler is built from.
+     */
     public Class getMetricClass() {
         return this.metricCalculator.getClass();
     }
 
+    /**
+     * @return The scope in which this handler gets executed.
+     */
     public MetricScope getScope() {
         return this.metricCalculator.getScope();
     }
 
+    /**
+     * Applies the internal method to the given data and state, mutating the state to progress to the result.
+     *
+     * @param obj   Data to publish
+     * @param state External state associated with the data-source.
+     * @throws MetricExecutionException If an exception occurs whilst executing the method.
+     */
     public void emitEvent(final Object obj, final MetricState state) throws MetricExecutionException {
         try {
             this.eventMethod.invoke(this.metricCalculator, state, obj);

src/main/java/nl/rug/jbi/jsm/core/pipeline/HandlerMap.java

@@ -8,10 +8,23 @@
 import java.util.List;
 import java.util.Map;
 
+/**
+ * Container for a set of handlers, associating data-types to a list of {@link nl.rug.jbi.jsm.core.pipeline.HandlerExecutor}.
+ *
+ * @author David van Leusen
+ * @since 2014-06-02
+ */
 public class HandlerMap {
     private final static List<HandlerExecutor> EMPTY_LIST = ImmutableList.of();
     private final Map<Class, List<HandlerExecutor>> handlers = Maps.newIdentityHashMap();
 
+    /**
+     * Get the list of handlers for the given data-type.
+     * Will always return a list even if there are no handlers for the given data-type.
+     *
+     * @param dataType data-type to retrieve the handlers for.
+     * @return List of handlers for the given data-type, never returns NULL.
+     */
     public List<HandlerExecutor> getHandlers(final Class dataType) {
         final List<HandlerExecutor> ret = this.handlers.get(dataType);
         return ret != null ? ret : EMPTY_LIST;

src/main/java/nl/rug/jbi/jsm/core/pipeline/MetricPreparationException.java

@@ -1,5 +1,12 @@
 package nl.rug.jbi.jsm.core.pipeline;
 
+/**
+ * Exception thrown is there is an issue with the definition or registration of a metric.
+ * The error message will always contain the reason for the exception.
+ *
+ * @author David van Leusen
+ * @since 2014-06-02
+ */
 public class MetricPreparationException extends Exception {
     public MetricPreparationException(final String msg) {
         super(msg);

src/main/java/nl/rug/jbi/jsm/core/pipeline/Pipeline.java

@@ -14,13 +14,19 @@
 
 import java.lang.reflect.InvocationTargetException;
 import java.lang.reflect.Method;
+import java.lang.reflect.Modifier;
 import java.util.*;
 
 import static com.google.common.base.Preconditions.checkArgument;
 import static com.google.common.base.Preconditions.checkNotNull;
 
 /**
+ * The pipeline encapsulates the planned execution order of metrics, when data is available and what metrics to finalize
+ * when. It does this by creating chains of {@link nl.rug.jbi.jsm.core.pipeline.PipelineFrame} for each scope, with each
+ * frame building upon the data produced by the last frame.
  *
+ * @author David van Leusen
+ * @since 2014-06-02
  */
 public class Pipeline {
     private final static Logger logger = LogManager.getLogger(Pipeline.class);
@@ -59,6 +65,13 @@ public Pipeline() {
         this.frameMap.put(MetricScope.COLLECTION, new PipelineFrame(MetricScope.COLLECTION));
     }
 
+    /**
+     * To be used in conjunction with {@link nl.rug.jbi.jsm.core.execution.PipelineExecutor#setClassVisitorFactory(nl.rug.jbi.jsm.core.execution.ClassVisitorFactory)}
+     * to set up a custom ClassLoader with custom initial data. This method needs to be called any instances of this
+     * class are created to prevent exceptions related to unknown data-types.
+     *
+     * @param dataType The data-type to register within the initial CLASS frame.
+     */
     public static void registerNewBaseData(final Class dataType) {
         Pipeline.BASE_DATA_CLASSES.add(dataType);
     }
@@ -75,6 +88,14 @@ private Pair<Class, HandlerExecutor> processMethod(final Method listener, final
             ));
         }
 
+        //Method has to be set to public.
+        if ((listener.getModifiers() & Modifier.PUBLIC) == 0) {
+            throw new MetricPreparationException(String.format(
+                    "'%s' isn't set to public",
+                    listener
+            ));
+        }
+
         //The first parameter is always of type MetricState
         if (!MetricState.class.equals(params[0])) {
             throw new MetricPreparationException(String.format(
@@ -160,6 +181,15 @@ public Class apply(Pair<Class, HandlerExecutor> classHandlerExecutorPair) {
         }
     }
 
+    /**
+     * Registers a metric to be evaluated within this pipeline, it will be validated and then placed within a frame
+     * where all the data required by the metric is available. Metrics registered need to subclass
+     * {@link nl.rug.jbi.jsm.core.calculator.IsolatedMetric} or {@link nl.rug.jbi.jsm.core.calculator.SharedMetric}.ø
+     *
+     * @param metric Metric to registered to this pipeline.
+     * @throws MetricPreparationException If there is an issue with the metric definition or its requirements, see the
+     *                                    associated error for more information.
+     */
     public void registerMetric(final BaseMetric metric) throws MetricPreparationException {
         if (!(metric instanceof IsolatedMetric || metric instanceof SharedMetric)) {
             throw new MetricPreparationException("A metric needs to be a subclass of IsolatedMetric or SharedMetric");
@@ -168,10 +198,16 @@ public void registerMetric(final BaseMetric metric) throws MetricPreparationExce
         }
     }
 
+    /**
+     * @return An unmodifiable map containing all scopes and the listeners for those scopes.
+     */
     public Map<MetricScope, HandlerMap> getHandlerMaps() {
         return Collections.unmodifiableMap(this.handlerMaps);
     }
 
+    /**
+     * @return An unmodifiable map containing all scopes and the execution frames for those scopes.
+     */
     public Map<MetricScope, PipelineFrame> getPipelineFrames() {
         return Collections.unmodifiableMap(this.frameMap);
     }

src/main/java/nl/rug/jbi/jsm/core/pipeline/PipelineFrame.java

@@ -11,6 +11,14 @@
 
 import static com.google.common.base.Preconditions.checkNotNull;
 
+/**
+ * A frame of execution, it describes a set of data that is available within this frame and contains lists of metrics
+ * that are ready for finalization within this frame. Each frame represents a frame of execution in
+ * {@link nl.rug.jbi.jsm.core.execution.PipelineExecutor}.
+ *
+ * @author David van Leusen
+ * @since 2014-06-02
+ */
 public class PipelineFrame {
     private final MetricScope scope;
     private final Set<Class> availableData = Sets.newHashSet();
@@ -19,38 +27,56 @@ public class PipelineFrame {
     private final List<ProducerMetric> producerMetrics = Lists.newLinkedList();
     private PipelineFrame nextFrame = null;
 
-    public PipelineFrame(final MetricScope scope) {
+    PipelineFrame(final MetricScope scope) {
         this.scope = checkNotNull(scope);
     }
 
-    public PipelineFrame(final MetricScope scope, final Set<Class> initData) {
+    PipelineFrame(final MetricScope scope, final Set<Class> initData) {
         this(scope);
         this.availableData.addAll(
                 checkNotNull(initData)
         );
     }
 
-    public PipelineFrame(final PipelineFrame previousFrame) {
-        this(checkNotNull(previousFrame).getScope());
-        this.availableData.addAll(previousFrame.availableData);
+    PipelineFrame(final PipelineFrame previousFrame) {
+        this(checkNotNull(previousFrame).getScope(), previousFrame.availableData);
         previousFrame.setNextFrame(this);
     }
 
+    /**
+     * Adds a type of data that will be available in this frame AND all subsequent frames.
+     *
+     * @param dataClass Data to register
+     */
     public void addDataClass(final Class dataClass) {
         this.availableData.add(dataClass);
         if (this.nextFrame != null) {
             this.nextFrame.addDataClass(dataClass);
         }
     }
 
+    /**
+     * @return The scope in which this frame will be evaluated.
+     */
     public MetricScope getScope() {
         return this.scope;
     }
 
+    /**
+     * Checks whether this frame has all the given data available. The set of data available in this frame is determined
+     * by the base set of data in {@link nl.rug.jbi.jsm.core.pipeline.Pipeline} and the results of any producers in
+     * previous frames.
+     *
+     * @param requiredData The set of data that needs to be available.
+     * @return Whether said data is available.
+     */
     public boolean checkAvailableData(final Set<Class> requiredData) {
         return this.availableData.containsAll(requiredData);
     }
 
+    /**
+     * @return The next frame of execution, can be NULL.
+     */
     public PipelineFrame getNextFrame() {
         return this.nextFrame;
     }
@@ -59,19 +85,28 @@ private void setNextFrame(final PipelineFrame nextFrame) {
         this.nextFrame = nextFrame;
     }
 
+    /**
+     * @return Unmodifiable list of all isolated metrics that are finished in this frame.
+     */
     public List<IsolatedMetric> getIsolatedMetrics() {
         return Collections.unmodifiableList(this.isolatedMetrics);
     }
 
+    /**
+     * @return Unmodifiable list of all shared metrics that are finished in this frame.
+     */
     public List<SharedMetric> getSharedMetrics() {
         return Collections.unmodifiableList(this.sharedMetrics);
     }
 
+    /**
+     * @return Unmodifiable list of all producers that are finished in this frame.
+     */
     public List<ProducerMetric> getProducerMetrics() {
         return Collections.unmodifiableList(this.producerMetrics);
     }
 
-    public void registerMetric(final BaseMetric metric) throws MetricPreparationException {
+    void registerMetric(final BaseMetric metric) throws MetricPreparationException {
         if (metric instanceof IsolatedMetric) {
             this.isolatedMetrics.add((IsolatedMetric) metric);
         } else if (metric instanceof SharedMetric) {