From 31fe7bc7f8f619c8b26b149e9eac503a7a68d3d1 Mon Sep 17 00:00:00 2001
From: Andrea Burattin <andrea.burattin@gmail.com>
Date: Sat, 26 Mar 2022 20:06:26 +0100
Subject: [PATCH] Some work on the documentation

---
 .../java/beamline/events/package-info.java    |  4 ++++
 .../beamline/exceptions/EventException.java   | 10 ++++++++++
 .../beamline/exceptions/SourceException.java  | 10 ++++++++++
 .../beamline/exceptions/package-info.java     |  4 ++++
 .../InfiniteSizeDirectlyFollowsMapper.java    |  4 +---
 .../algorithms/StreamMiningAlgorithm.java     | 18 +++++++++++++----
 .../beamline/models/responses/Response.java   | 17 +++++++++++++++-
 .../models/responses/StringResponse.java      | 20 +++++++++++++++++++
 8 files changed, 79 insertions(+), 8 deletions(-)
 create mode 100644 src/main/java/beamline/events/package-info.java
 create mode 100644 src/main/java/beamline/exceptions/package-info.java

diff --git a/src/main/java/beamline/events/package-info.java b/src/main/java/beamline/events/package-info.java
new file mode 100644
index 0000000..408806d
--- /dev/null
+++ b/src/main/java/beamline/events/package-info.java
@@ -0,0 +1,4 @@
+/**
+ * This package contains the description of events in Beamline.
+ */
+package beamline.events;
\ No newline at end of file
diff --git a/src/main/java/beamline/exceptions/EventException.java b/src/main/java/beamline/exceptions/EventException.java
index f8f71fa..ad19166 100644
--- a/src/main/java/beamline/exceptions/EventException.java
+++ b/src/main/java/beamline/exceptions/EventException.java
@@ -1,9 +1,19 @@
 package beamline.exceptions;
 
+/**
+ * Exception thrown during events creation
+ * 
+ * @author Andrea Burattin
+ */
 public class EventException extends Exception {
 
 	private static final long serialVersionUID = 5835305478001040595L;
 	
+	/**
+	 * Constructs a new exception
+	 * 
+	 * @param message the message
+	 */
 	public EventException(String message) {
 		super(message);
 	}
diff --git a/src/main/java/beamline/exceptions/SourceException.java b/src/main/java/beamline/exceptions/SourceException.java
index 8c48cd1..131e3fc 100644
--- a/src/main/java/beamline/exceptions/SourceException.java
+++ b/src/main/java/beamline/exceptions/SourceException.java
@@ -1,9 +1,19 @@
 package beamline.exceptions;
 
+/**
+ * Exception thrown during source processing
+ * 
+ * @author Andrea Burattin
+ */
 public class SourceException extends Exception {
 
 	private static final long serialVersionUID = -3387719059778550013L;
 
+	/**
+	 * Constructs a new exception
+	 * 
+	 * @param message the message
+	 */
 	public SourceException(String message) {
 		super(message);
 	}
diff --git a/src/main/java/beamline/exceptions/package-info.java b/src/main/java/beamline/exceptions/package-info.java
new file mode 100644
index 0000000..470a405
--- /dev/null
+++ b/src/main/java/beamline/exceptions/package-info.java
@@ -0,0 +1,4 @@
+/**
+ * This package contains the specific exceptions that Beamline can throw.
+ */
+package beamline.exceptions;
\ No newline at end of file
diff --git a/src/main/java/beamline/models/algorithms/InfiniteSizeDirectlyFollowsMapper.java b/src/main/java/beamline/models/algorithms/InfiniteSizeDirectlyFollowsMapper.java
index 0df27ff..e7fbeaf 100644
--- a/src/main/java/beamline/models/algorithms/InfiniteSizeDirectlyFollowsMapper.java
+++ b/src/main/java/beamline/models/algorithms/InfiniteSizeDirectlyFollowsMapper.java
@@ -3,13 +3,11 @@ package beamline.models.algorithms;
 import java.util.HashMap;
 import java.util.Map;
 
-import org.deckfour.xes.model.XTrace;
-
 import beamline.events.BEvent;
 import beamline.models.responses.DirectlyFollowsRelation;
 
 /**
- * This mapper transforms a stream of {@link XTrace}s into a stream of
+ * This mapper transforms a stream of {@link BEvent}s into a stream of
  * {@link DirectlyFollowsRelation}s. It transforms each pair of consequent
  * events appearing in the same case as a directly follows operator (generating
  * an object with type {@link DirectlyFollowsRelation}).
diff --git a/src/main/java/beamline/models/algorithms/StreamMiningAlgorithm.java b/src/main/java/beamline/models/algorithms/StreamMiningAlgorithm.java
index e901def..7c9cd6d 100644
--- a/src/main/java/beamline/models/algorithms/StreamMiningAlgorithm.java
+++ b/src/main/java/beamline/models/algorithms/StreamMiningAlgorithm.java
@@ -2,7 +2,6 @@ package beamline.models.algorithms;
 
 import java.io.IOException;
 
-import org.apache.flink.api.common.functions.MapFunction;
 import org.apache.flink.api.common.functions.RichFlatMapFunction;
 import org.apache.flink.api.common.state.ValueState;
 import org.apache.flink.api.common.state.ValueStateDescriptor;
@@ -14,8 +13,14 @@ import beamline.models.responses.Response;
 
 /**
  * This abstract class defines the root of the mining algorithms hierarchy. It
- * is a {@link MapFunction} of elements with type {@link BEvent} that is capable
- * of producing responses of type {@link Response}.
+ * is a {@link RichFlatMapFunction} of elements with type {@link BEvent} that is
+ * capable of producing responses of type {@link Response}.
+ * 
+ * <p>
+ * Since this map is actually "rich" this means that classes that extends this
+ * one can have access to the state of the operator and use it in a distributed
+ * fashion. Additionally, being this map a "flat" it might return 0 or 1 results
+ * for each event being consumed.
  * 
  * @author Andrea Burattin
  */
@@ -42,8 +47,13 @@ public abstract class StreamMiningAlgorithm<T extends Response> extends RichFlat
 	 * The argument of the method is the new observation and the returned value
 	 * is the result of the mining.
 	 * 
+	 * <p>
+	 * If this method returns value <tt>null</tt>, then the value is not moved
+	 * forward into the pipeline.
+	 * 
 	 * @param event the new event being observed
-	 * @return the result of the mining of the event
+	 * @return the result of the mining of the event, or <tt>null</tt> if
+	 * nothing should go through the rest of the pipeline
 	 */
 	public abstract T ingest(BEvent event);
 	
diff --git a/src/main/java/beamline/models/responses/Response.java b/src/main/java/beamline/models/responses/Response.java
index 256972c..2cfebf1 100644
--- a/src/main/java/beamline/models/responses/Response.java
+++ b/src/main/java/beamline/models/responses/Response.java
@@ -2,8 +2,12 @@ package beamline.models.responses;
 
 import java.io.Serializable;
 
+import beamline.models.algorithms.StreamMiningAlgorithm;
+
 /**
- * Marker interface used to define the type of the responses
+ * General class describing what a {@link StreamMiningAlgorithm} is supposed to
+ * return. This class can be extended with additional information. The class by
+ * itself carries only information regarding the number of events processed.
  * 
  * @author Andrea Burattin
  */
@@ -12,10 +16,21 @@ public class Response implements Serializable {
 	private static final long serialVersionUID = 3104314256198741100L;
 	private Long processedEvents;
 
+	/**
+	 * Gets the number of events processed when the response was produced
+	 * 
+	 * @return number of events processed when the response was produced
+	 */
 	public Long getProcessedEvents() {
 		return processedEvents;
 	}
 
+	/**
+	 * Sets the number of events processed when the response was produced
+	 * 
+	 * @param processedEvents the number of events processed when the response
+	 * was produced
+	 */
 	public void setProcessedEvents(Long processedEvents) {
 		this.processedEvents = processedEvents;
 	}
diff --git a/src/main/java/beamline/models/responses/StringResponse.java b/src/main/java/beamline/models/responses/StringResponse.java
index 1f27d85..dd7b61f 100644
--- a/src/main/java/beamline/models/responses/StringResponse.java
+++ b/src/main/java/beamline/models/responses/StringResponse.java
@@ -1,18 +1,38 @@
 package beamline.models.responses;
 
+/**
+ * A simple {@link Response} containing just a string
+ * 
+ * @author Andrea Burattin
+ */
 public class StringResponse extends Response {
 
 	private static final long serialVersionUID = 7863665787098981704L;
 	private String str;
 	
+	/**
+	 * Constructor
+	 * 
+	 * @param str the value of this response
+	 */
 	public StringResponse(String str) {
 		set(str);
 	}
 	
+	/**
+	 * Gets the string of this response
+	 * 
+	 * @return the string of this response
+	 */
 	public String get() {
 		return str;
 	}
 	
+	/**
+	 * Sets the string of this response
+	 * 
+	 * @param str the string of this response
+	 */
 	public void set(String str) {
 		this.str = str;
 	}
-- 
GitLab