Finish Javadocs for public classes in core.execution

Also finish all outstanding TODO's
Still needs to be done:
- Documentation of executing objects for maintenance reasons.
- Building a test suite for Metric definition.

Author: Kiskae

src/main/java/nl/rug/jbi/jsm/core/calculator/MetricState.java

@@ -52,8 +52,8 @@ public Exception getExecutionException() {
 
     /**
      * Invalidate this state with the given exception, once invalidated this state will cease evaluating and either
-     * return an {@link nl.rug.jbi.jsm.core.execution.InvalidResult} if the metric is isolated or accumulate the
-     * 'invalidMembers' count for shared metrics or producers.
+     * return an error result if the metric is isolated or accumulate the 'invalidMembers' count for shared metrics or
+     * producers.
      *
      * @param ex Exception that has caused invalidation.
      * @throws java.lang.NullPointerException if ex is NULL

src/main/java/nl/rug/jbi/jsm/core/execution/CalculationStageTask.java

@@ -7,13 +7,15 @@
 import nl.rug.jbi.jsm.core.calculator.MetricResult;
 import nl.rug.jbi.jsm.core.calculator.MetricState;
 import nl.rug.jbi.jsm.core.event.EventBus;
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.Logger;
 
 import java.util.List;
 import java.util.Map;
 import java.util.concurrent.CountDownLatch;
 
 class CalculationStageTask implements Runnable {
-
+    private final static Logger logger = LogManager.getLogger(CalculationStageTask.class);
     private final CountDownLatch latch;
     private final Runnable modifier;
     private final EventBus dataStore;
@@ -57,7 +59,7 @@ public Class apply(final IsolatedMetric isolatedMetric) {
                 if (state.isValid()) {
                     results.add(m.getResult(this.dataStore.getIdentifier(), state));
                 } else {
-                    //TODO: properly log this
+                    logger.warn("Failed to calculate '{}' for '{}'", m.getClass().getName(), state.getIdentifier());
                     results.add(new InvalidResult(this.dataStore.getIdentifier(), m, "Error during calculation"));
                 }
             }

src/main/java/nl/rug/jbi/jsm/core/execution/ClassVisitorFactory.java

@@ -3,7 +3,24 @@
 import nl.rug.jbi.jsm.core.event.EventBus;
 import org.apache.bcel.classfile.JavaClass;
 
+/**
+ * Factory for the ClassVisitor runnable, given the {@link org.apache.bcel.classfile.JavaClass} and the associated
+ * EventBus, a class visitor needs to be created which extracts data from the JavaClass and publishes it through the
+ * EventBus.
+ * The default ClassVisitor is {@link nl.rug.jbi.jsm.bcel.ClassVisitor}.
+ *
+ * @author David van Leusen
+ * @since 2014-06-02
+ */
 public interface ClassVisitorFactory {
 
+    /**
+     * Create a class visitor for the given class and event bus, the produced object should be a Runnable and  this
+     * visitor should be start when {@link Runnable#run()} is called.
+     *
+     * @param targetClass Class to evaluate
+     * @param eventBus    EventBus associated with the given class.
+     * @return Runnable that will execute the class visitor.
+     */
     public Runnable createClassVisitor(final JavaClass targetClass, final EventBus eventBus);
 }

src/main/java/nl/rug/jbi/jsm/core/execution/ControllerThread.java

@@ -14,6 +14,7 @@
 import org.apache.bcel.util.Repository;
 import org.apache.logging.log4j.LogManager;
 import org.apache.logging.log4j.Logger;
+import org.apache.logging.log4j.message.ParameterizedMessage;
 
 import java.util.*;
 import java.util.concurrent.*;
@@ -32,18 +33,23 @@ public Class apply(Object metric) {
             return metric.getClass();
         }
     };
-    private final PipelineExecutor executionPlan;
+    private final int executionId = UNIQUE_EXECUTION_ID.incrementAndGet();
     private final ExecutorService executorPool = Executors.newFixedThreadPool(
             Runtime.getRuntime().availableProcessors(),
             new ThreadFactory() {
                 private final AtomicInteger executionId = new AtomicInteger(0);
 
                 @Override
                 public Thread newThread(Runnable r) {
-                    return new Thread(r, String.format("JSM Execution Thread #%d", executionId.getAndIncrement()));
+                    return new Thread(r, String.format(
+                            "JSM Execution Thread #%d/%d",
+                            ControllerThread.this.executionId,
+                            executionId.getAndIncrement()
+                    ));
                 }
             }
     );
+    private final PipelineExecutor executionPlan;
     private final Map<String, EventBus> stateContainers = Maps.newHashMap();
     private final Table<MetricScope, String, List<Object>> dataForFutureScope = Tables.newCustomTable(
             Maps.<MetricScope, Map<String, List<Object>>>newEnumMap(MetricScope.class),
@@ -63,7 +69,9 @@ public boolean apply(List<MetricResult> metricResults) {
     };
 
     public ControllerThread(final PipelineExecutor executionPlan, final Set<String> classNames) {
-        super(String.format("JSM Controller Thread #%d", ControllerThread.UNIQUE_EXECUTION_ID.getAndIncrement()));
+        super();
+        this.setName(String.format("JSM Controller Thread #%d", this.executionId));
+
         this.executionPlan = executionPlan;
 
         final HandlerMap classHandlerMap = this.executionPlan.getHandlerMap(MetricScope.CLASS);
@@ -107,8 +115,7 @@ public void run() {
                         cvFactory.createClassVisitor(jc, entry.getValue())
                 ));
             } catch (ClassNotFoundException e) {
-                //TODO: proper handling
-                logger.debug(e);
+                logger.error("Failed to load '{}', it will not be evaluated.", e);
             }
         }
 
@@ -125,8 +132,7 @@ public void run() {
             try {
                 performCalculationStage(taskQueue, currentFrame.getIsolatedMetrics());
             } catch (InterruptedException e) {
-                //TODO: handle interruption correctly.
-                logger.debug(e);
+                logger.warn("Execution interrupted, stopping evaluation.", e);
                 break;
             }
 
@@ -145,8 +151,7 @@ public void run() {
                     performCollectionStage(dataMap, currentFrame, produceList);
                 }
             } catch (InterruptedException e) {
-                //TODO: handle interruption correctly.
-                logger.debug(e);
+                logger.warn("Execution interrupted, stopping evaluation.", e);
                 break;
             }
 
@@ -182,7 +187,11 @@ public void run() {
                 logger.debug("State containers and tasks added for next scope.");
             }
 
-            prepareCalculatorsForNextFrame(taskQueue, nextFrameExecutionData);
+            prepareCalculatorsForNextFrame(
+                    taskQueue,
+                    nextFrameExecutionData,
+                    this.executionPlan.getHandlerMap(currentScope)
+            );
 
             logger.debug("Tasks for next frame prepared.");
         }
@@ -194,11 +203,23 @@ public void run() {
 
     private void prepareCalculatorsForNextFrame(
             final Queue<Pair<EventBus, Runnable>> taskQueue,
-            final Map<String, List<Object>> executionData
+            final Map<String, List<Object>> executionData,
+            final HandlerMap hMap
     ) {
         for (final Map.Entry<String, List<Object>> entry : executionData.entrySet()) {
-            final EventBus eBus = this.stateContainers.get(entry.getKey());
-            //TODO: if eBus == null, try to fix it....
+            final EventBus eBus;
+            if (this.stateContainers.containsKey(entry.getKey())) {
+                eBus = this.stateContainers.get(entry.getKey());
+            } else {
+                logger.warn(
+                        "Request for undefined identifier, might indicate that " +
+                                "a producer is returning wrong data: '{}'",
+                        entry.getKey()
+                );
+
+                eBus = new EventBus(entry.getKey(), hMap);
+                this.stateContainers.put(entry.getKey(), eBus);
+            }
             taskQueue.add(new Pair<EventBus, Runnable>(eBus, new DataListDispatcher(eBus, entry.getValue())));
         }
     }
@@ -238,36 +259,44 @@ private void performCollectionStage(
 
         final CountDownLatch latch = createCountdownLatch(sharedMetrics.size() + producerMetrics.size());
 
-        //TODO: use Pair to link Futures to the metrics, for logging purposes
-        final List<Future<List<MetricResult>>> futureResults = Lists.newLinkedList();
-        final List<Future<List<ProducerMetric.Produce>>> futureProduce = Lists.newLinkedList();
+        final List<Pair<SharedMetric, Future<List<MetricResult>>>> futureResults = Lists.newLinkedList();
+        final List<Pair<ProducerMetric, Future<List<ProducerMetric.Produce>>>> futureProduce = Lists.newLinkedList();
 
         for (final SharedMetric metric : sharedMetrics) {
             final Map<String, MetricState> data = dataMap.get(metric.getClass());
-            futureResults.add(this.executorPool.submit(CollectionStageTask.forSharedMetric(metric, data, latch)));
+            futureResults.add(new Pair<SharedMetric, Future<List<MetricResult>>>(
+                    metric,
+                    this.executorPool.submit(CollectionStageTask.forSharedMetric(metric, data, latch))
+            ));
         }
 
         for (final ProducerMetric metric : producerMetrics) {
             final Map<String, MetricState> data = dataMap.get(metric.getClass());
-            futureProduce.add(this.executorPool.submit(CollectionStageTask.forProducer(metric, data, latch)));
+            futureProduce.add(new Pair<ProducerMetric, Future<List<ProducerMetric.Produce>>>(
+                            metric,
+                            this.executorPool.submit(CollectionStageTask.forProducer(metric, data, latch)))
+            );
         }
 
         //Await completion of async collection.
         latch.await();
 
         //Collection Results
         final List<MetricResult> results = Lists.newLinkedList();
-        for (final Future<List<MetricResult>> fResult : futureResults) {
+        for (final Pair<SharedMetric, Future<List<MetricResult>>> fResult : futureResults) {
             try {
-                final List<MetricResult> resList = fResult.get();
+                final List<MetricResult> resList = fResult.second.get();
                 if (resList != null) {
                     results.addAll(resList);
                 } else {
-                    //TODO: log invalid metric
+                    logger.warn("'{}' returned null as a list of results.", fResult.first.getClass().getName());
                 }
             } catch (ExecutionException e) {
-                //TODO: how to handle errors here (do they even happen?)
-                logger.warn("Exception getting results", e);
+                logger.warn(new ParameterizedMessage(
+                        "Exception occurred whilst calculating results for '{}': {}",
+                        fResult.first.getClass().getName(),
+                        e.getCause().getMessage()
+                ), e);
             }
         }
 
@@ -276,17 +305,20 @@ private void performCollectionStage(
             this.resultsCallback.apply(results);
 
         //Collect and return produce.
-        for (final Future<List<ProducerMetric.Produce>> fProduce : futureProduce) {
+        for (final Pair<ProducerMetric, Future<List<ProducerMetric.Produce>>> fProduce : futureProduce) {
             try {
-                final List<ProducerMetric.Produce> prodList = fProduce.get();
+                final List<ProducerMetric.Produce> prodList = fProduce.second.get();
                 if (prodList != null) {
                     produceOutput.addAll(prodList);
                 } else {
-                    //TODO: log invalid metric
+                    logger.warn("'{}' returned null as a list of produce.", fProduce.first.getClass().getName());
                 }
             } catch (ExecutionException e) {
-                //TODO: how to handle errors here (do they even happen?)
-                logger.warn("Exception getting results", e);
+                logger.warn(new ParameterizedMessage(
+                        "Exception occurred whilst calculating produce for '{}': {}",
+                        fProduce.first.getClass().getName(),
+                        e.getCause().getMessage()
+                ), e);
             }
         }
     }

src/main/java/nl/rug/jbi/jsm/core/execution/InvalidResult.java

@@ -3,7 +3,7 @@
 import nl.rug.jbi.jsm.core.calculator.BaseMetric;
 import nl.rug.jbi.jsm.core.calculator.MetricResult;
 
-public class InvalidResult extends MetricResult {
+class InvalidResult extends MetricResult {
     public InvalidResult(String identifier, BaseMetric m, String msg) {
         super(identifier, m.getClass(), m.getResultScopes().iterator().next(), msg);
     }

src/main/java/nl/rug/jbi/jsm/core/execution/PipelineExecutor.java

@@ -10,12 +10,22 @@
 import nl.rug.jbi.jsm.frontend.Frontend;
 import org.apache.bcel.util.ClassLoaderRepository;
 import org.apache.bcel.util.Repository;
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.Logger;
 
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
 
+/**
+ * Executor for a previously constructed {@link nl.rug.jbi.jsm.core.pipeline.Pipeline}. Execution happens completely
+ * asynchronously and will call {@link nl.rug.jbi.jsm.frontend.Frontend#signalDone()}.
+ *
+ * @author David van Leusen
+ * @since 2014-06-02
+ */
 public class PipelineExecutor {
+    private final static Logger logger = LogManager.getLogger(PipelineExecutor.class);
     private final Frontend frontend;
     private final CompositeBCELClassLoader dataSource;
     private final Repository repo;
@@ -28,41 +38,69 @@ public class PipelineExecutor {
     private Runnable finishCallback = null;
     private ClassVisitorFactory cvFactory = JSMClassVisitorFactory.INSTANCE;
 
+    /**
+     * Construct an executor for the given data and target
+     *
+     * @param frontend      Frontend callback for results.
+     * @param executionPlan Pipeline describing the handlers and execution-frames.
+     * @param dataSource    ClassLoader to build the {@link org.apache.bcel.util.ClassLoaderRepository} from.
+     * @param classNames    Set of classes that need to be evaluated.
+     */
     public PipelineExecutor(
             final Frontend frontend,
-            final Pipeline pipe,
+            final Pipeline executionPlan,
             final CompositeBCELClassLoader dataSource,
             final Set<String> classNames
     ) {
         this.frontend = frontend;
         this.dataSource = dataSource;
         this.repo = new ClassLoaderRepository(dataSource);
-        this.handlerMap = pipe.getHandlerMaps();
-        this.frameMap = pipe.getPipelineFrames();
+        this.handlerMap = executionPlan.getHandlerMaps();
+        this.frameMap = executionPlan.getPipelineFrames();
         this.controllerThread = new ControllerThread(this, classNames);
     }
 
-    public HandlerMap getHandlerMap(final MetricScope scope) {
+    HandlerMap getHandlerMap(final MetricScope scope) {
         return this.handlerMap.get(Preconditions.checkNotNull(scope));
     }
 
-    public PipelineFrame getPipelineFrame(final MetricScope scope) {
+    PipelineFrame getPipelineFrame(final MetricScope scope) {
         return this.frameMap.get(Preconditions.checkNotNull(scope));
     }
 
+    /**
+     * Sets a callback that is to be executed once processing has been finished.
+     *
+     * @param finishCallback the callback to be executed.
+     */
     public void setFinishCallback(final Runnable finishCallback) {
         this.finishCallback = finishCallback;
     }
 
+    /**
+     * Begin the asynchronous execution of this executor, this call will not block.
+     */
     public void beginExecution() {
-        //TODO: custom exception handler
+        this.controllerThread.setUncaughtExceptionHandler(new Thread.UncaughtExceptionHandler() {
+            @Override
+            public void uncaughtException(Thread t, Throwable e) {
+                logger.error("Uncaught exception has caused execution to fail", e);
+                PipelineExecutor.this.onFinish(); //Ensure the system doesn't get stuck.
+            }
+        });
         this.controllerThread.start();
     }
 
     ClassVisitorFactory getClassVisitorFactory() {
         return this.cvFactory;
     }
 
+    /**
+     * Sets the ClassVisitor factory for this executor, this needs to be set to use custom ClassVisitors.
+     * It will default to a factory that creates {@link nl.rug.jbi.jsm.bcel.ClassVisitor}.
+     *
+     * @param cvFactory ClassVisitor factory
+     */
     public void setClassVisitorFactory(final ClassVisitorFactory cvFactory) {
         this.cvFactory = Preconditions.checkNotNull(cvFactory);
     }