Added documentation to code

.gitignore

 /target/
+/doc/

src/main/java/beamline/filters/ExcludeActivitiesFilter.java

@@ -4,8 +4,20 @@ import org.deckfour.xes.extension.std.XConceptExtension;
 import org.deckfour.xes.model.XAttributeLiteral;
 import org.deckfour.xes.model.impl.XAttributeLiteralImpl;
 
+/**
+ * A specific instance of the {@link ExcludeOnEventAttributeEqualityFilter} that
+ * considers the name of the activity as attribute to filter.
+ * 
+ * @author Andrea Burattin
+ *
+ */
 public class ExcludeActivitiesFilter extends ExcludeOnEventAttributeEqualityFilter<XAttributeLiteral> {
 
+	/**
+	 * Constructors
+	 * 
+	 * @param activities the sequence of activity names to exclude
+	 */
 	public ExcludeActivitiesFilter(String ...activities) {
 		super(XConceptExtension.KEY_NAME);
 		

src/main/java/beamline/filters/ExcludeOnCaseAttributeEqualityFilter.java

@@ -10,17 +10,38 @@ import org.deckfour.xes.model.XTrace;
 import io.reactivex.rxjava3.annotations.NonNull;
 import io.reactivex.rxjava3.functions.Predicate;
 
+/**
+ * This filter excludes events based on the equality of a certain trace
+ * attribute to a given set of values. Values are considered in disjunction
+ * (i.e., it is enough that the attribute is equal to one of the values to
+ * discard the event).
+ * 
+ * @author Andrea Burattin
+ *
+ * @param <T> the type of the attribute
+ */
 public class ExcludeOnCaseAttributeEqualityFilter<T extends XAttribute> implements Predicate<XTrace> {
 
 	private String attributeName;
 	private Set<T> attributeValues;
 	
+	/**
+	 * Constructor
+	 * 
+	 * @param attributeName the name of the trace attribute
+	 * @param values the sequence of values to consider
+	 */
 	@SafeVarargs
 	public ExcludeOnCaseAttributeEqualityFilter(String attributeName, T ...values) {
 		this.attributeName = attributeName;
 		this.attributeValues = new HashSet<T>(Arrays.asList(values));
 	}
 	
+	/**
+	 * Adds the value to the list of values to be considered for removal
+	 * 
+	 * @param value
+	 */
 	public void addValue(T value) {
 		this.attributeValues.add(value);
 	}

src/main/java/beamline/filters/ExcludeOnEventAttributeEqualityFilter.java

@@ -10,17 +10,38 @@ import org.deckfour.xes.model.XTrace;
 import io.reactivex.rxjava3.annotations.NonNull;
 import io.reactivex.rxjava3.functions.Predicate;
 
+/**
+ * This filter excludes events based on the equality of a certain event
+ * attribute to a given set of values. Values are considered in disjunction
+ * (i.e., it is enough that the attribute is equal to one of the values to
+ * discard the event).
+ * 
+ * @author Andrea Burattin
+ *
+ * @param <T> the type of the attribute
+ */
 public class ExcludeOnEventAttributeEqualityFilter<T extends XAttribute> implements Predicate<XTrace> {
 
 	private String attributeName;
 	private Set<T> attributeValues;
 	
+	/**
+	 * Constructor
+	 * 
+	 * @param attributeName the name of the event attribute
+	 * @param values the sequence of values to consider
+	 */
 	@SafeVarargs
 	public ExcludeOnEventAttributeEqualityFilter(String attributeName, T ...values) {
 		this.attributeName = attributeName;
 		this.attributeValues = new HashSet<T>(Arrays.asList(values));
 	}
 	
+	/**
+	 * Adds the value to the list of values to be considered for removal
+	 * 
+	 * @param value
+	 */
 	public void addValue(T value) {
 		this.attributeValues.add(value);
 	}

src/main/java/beamline/filters/RetainActivitiesFilter.java

@@ -4,8 +4,20 @@ import org.deckfour.xes.extension.std.XConceptExtension;
 import org.deckfour.xes.model.XAttributeLiteral;
 import org.deckfour.xes.model.impl.XAttributeLiteralImpl;
 
+/**
+ * A specific instance of the {@link RetainOnEventAttributeEqualityFilter} that
+ * considers the name of the activity as attribute to filter.
+ * 
+ * @author Andrea Burattin
+ *
+ */
 public class RetainActivitiesFilter extends RetainOnEventAttributeEqualityFilter<XAttributeLiteral> {
 
+	/**
+	 * Constructors
+	 * 
+	 * @param activities the sequence of activity names to retain
+	 */
 	public RetainActivitiesFilter(String ...activities) {
 		super(XConceptExtension.KEY_NAME);
 		

src/main/java/beamline/filters/RetainOnCaseAttributeEqualityFilter.java

@@ -10,17 +10,38 @@ import org.deckfour.xes.model.XTrace;
 import io.reactivex.rxjava3.annotations.NonNull;
 import io.reactivex.rxjava3.functions.Predicate;
 
+/**
+ * This filter retains events based on the equality of a certain trace
+ * attribute to a given set of values. Values are considered in disjunction
+ * (i.e., it is enough that the attribute is equal to one of the values to
+ * retain the event).
+ * 
+ * @author Andrea Burattin
+ *
+ * @param <T> the type of the attribute
+ */
 public class RetainOnCaseAttributeEqualityFilter<T extends XAttribute> implements Predicate<XTrace> {
 
 	private String attributeName;
 	private Set<T> attributeValues;
 	
+	/**
+	 * Constructor
+	 * 
+	 * @param attributeName the name of the trace attribute
+	 * @param values the sequence of values to consider
+	 */
 	@SafeVarargs
 	public RetainOnCaseAttributeEqualityFilter(String attributeName, T ...values) {
 		this.attributeName = attributeName;
 		this.attributeValues = new HashSet<T>(Arrays.asList(values));
 	}
 	
+	/**
+	 * Adds the value to the list of values to be considered for retention
+	 * 
+	 * @param value
+	 */
 	public void addValue(T value) {
 		this.attributeValues.add(value);
 	}

src/main/java/beamline/filters/RetainOnEventAttributeEqualityFilter.java

@@ -10,17 +10,38 @@ import org.deckfour.xes.model.XTrace;
 import io.reactivex.rxjava3.annotations.NonNull;
 import io.reactivex.rxjava3.functions.Predicate;
 
+/**
+ * This filter retains events based on the equality of a certain event
+ * attribute to a given set of values. Values are considered in disjunction
+ * (i.e., it is enough that the attribute is equal to one of the values to
+ * retain the event).
+ * 
+ * @author Andrea Burattin
+ *
+ * @param <T> the type of the attribute
+ */
 public class RetainOnEventAttributeEqualityFilter<T extends XAttribute> implements Predicate<XTrace> {
 
 	private String attributeName;
 	private Set<T> attributeValues;
 	
+	/**
+	 * Constructor
+	 * 
+	 * @param attributeName the name of the event attribute
+	 * @param values the sequence of values to consider
+	 */
 	@SafeVarargs
 	public RetainOnEventAttributeEqualityFilter(String attributeName, T ...values) {
 		this.attributeName = attributeName;
 		this.attributeValues = new HashSet<T>(Arrays.asList(values));
 	}
 	
+	/**
+	 * Adds the value to the list of values to be considered for retention
+	 * 
+	 * @param value
+	 */
 	public void addValue(T value) {
 		this.attributeValues.add(value);
 	}

src/main/java/beamline/filters/package-info.java

+/**
+ * This package contains some filters that are available by default in the
+ * framework.
+ */
+package beamline.filters;
\ No newline at end of file

src/main/java/beamline/mappers/DirectlyFollowsRelation.java

@@ -2,26 +2,54 @@ package beamline.mappers;
 
 import org.deckfour.xes.model.XEvent;
 
+/**
+ * This class represents a directly follows relation as produced by
+ * {@link InfiniteSizeDirectlyFollowsMapper}.
+ * 
+ * @author Andrea Burattin
+ */
 public class DirectlyFollowsRelation {
 
 	private String caseId;
 	public XEvent first;
 	public XEvent second;
 	
+	/**
+	 * Constructor
+	 * 
+	 * @param caseId
+	 * @param first
+	 * @param second
+	 */
 	public DirectlyFollowsRelation(String caseId, XEvent first, XEvent second) {
 		this.caseId = caseId;
 		this.first = first;
 		this.second = second;
 	}
 	
+	/**
+	 * Returns the case id this directly follows relation belongs to
+	 * 
+	 * @return
+	 */
 	public String getCaseId() {
 		return caseId;
 	}
 
+	/**
+	 * Returns the first event
+	 * 
+	 * @return
+	 */
 	public XEvent getFirst() {
 		return first;
 	}
 
+	/**
+	 * Returns the second event
+	 * 
+	 * @return
+	 */
 	public XEvent getSecond() {
 		return second;
 	}

src/main/java/beamline/mappers/InfiniteSizeDirectlyFollowsMapper.java

@@ -12,6 +12,18 @@ import io.reactivex.rxjava3.core.Observable;
 import io.reactivex.rxjava3.core.ObservableSource;
 import io.reactivex.rxjava3.functions.Function;
 
+/**
+ * This mapper transforms a stream of {@link XTrace}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}).
+ * 
+ * <p>
+ * This mapper is called infinite because it's memory footprint will grow as the
+ * number of case ids grows as well.
+ * 
+ * @author Andrea Burattin
+ */
 public class InfiniteSizeDirectlyFollowsMapper implements Function<XTrace, ObservableSource<DirectlyFollowsRelation>> {
 
 	private Map<String, XEvent> map = new HashMap<String, XEvent>();

src/main/java/beamline/mappers/package-info.java

+/**
+ * This package contains some mappers that are available by default in the
+ * framework.
+ */
+package beamline.mappers;
\ No newline at end of file

src/main/java/beamline/models/algorithms/HookEventProcessing.java

 package beamline.models.algorithms;
 
+/**
+ * This interface defines the structure of the callback function that a
+ * {@link StreamMiningAlgorithm} can execute (cf.,
+ * {@link StreamMiningAlgorithm#setOnBeforeEvent(HookEventProcessing)} and
+ * {@link StreamMiningAlgorithm#setOnAfterEvent(HookEventProcessing)}).
+ * 
+ * @author Andrea Burattin
+ */
 public interface HookEventProcessing {
 
+	/**
+	 * The actual function to trigger
+	 */
 	public void trigger();
 }

src/main/java/beamline/models/algorithms/StreamMiningAlgorithm.java

@@ -3,6 +3,16 @@ package beamline.models.algorithms;
 import io.reactivex.rxjava3.annotations.NonNull;
 import io.reactivex.rxjava3.functions.Consumer;
 
+/**
+ * This abstract class defines the root of the mining algorithms hierarchy. It
+ * is a {@link Consumer} of elements with type <tt>T</tt> that is capable of
+ * producing responses of a certain type <tt>K</tt>.
+ * 
+ * @author Andrea Burattin
+ *
+ * @param <T> the type of the consumed events
+ * @param <K> the type of the responses produced by the mining algorithm
+ */
 public abstract class StreamMiningAlgorithm<T, K> implements Consumer<T> {
 
 	private int processedEvents = 0;
@@ -10,29 +20,59 @@ public abstract class StreamMiningAlgorithm<T, K> implements Consumer<T> {
 	private HookEventProcessing onBeforeEvent = null;
 	private HookEventProcessing onAfterEvent = null;
 	
+	/**
+	 * This abstract method is what each derive class is expected to implement.
+	 * The argument of the method is the new observation and the returned value
+	 * is the result of the mining.
+	 * 
+	 * @param event the new event being observed
+	 * @return the result of the mining of the event
+	 */
 	public abstract K ingest(T event);
 	
-	public void process(T event) {
-		this.processedEvents++;
-		latestResponse = ingest(event);
-	}
-	
+	/**
+	 * Returns the total number of events processed so far
+	 * 
+	 * @return
+	 */
 	public int getProcessedEvents() {
 		return processedEvents;
 	}
 	
+	/**
+	 * Returns the latest result of the mining
+	 * 
+	 * @return
+	 */
 	public K getLatestResponse() {
 		return latestResponse;
 	}
 	
+	/**
+	 * This method can be used to set a hook to a callback function to be
+	 * executed before an event is processed
+	 * 
+	 * @param onBeforeEvent the callback function
+	 */
 	public void setOnBeforeEvent(HookEventProcessing onBeforeEvent) {
 		this.onBeforeEvent = onBeforeEvent;
 	}
 	
+	/**
+	 * This method can be used to set a hook to a callback function to be
+	 * executed after an event is processed
+	 * 
+	 * @param onAfterEvent the callback function
+	 */
 	public void setOnAfterEvent(HookEventProcessing onAfterEvent) {
 		this.onAfterEvent = onAfterEvent;
 	}
 	
+	protected void process(T event) {
+		this.processedEvents++;
+		latestResponse = ingest(event);
+	}
+	
 	protected K setLatestResponse(K latestResponse) {
 		this.latestResponse = latestResponse;
 		return latestResponse;

src/main/java/beamline/models/algorithms/package-info.java

+/**
+ * This package contains all classes of the framework necessary to have mining
+ * algorithms functioning.
+ */
+package beamline.models.algorithms;
\ No newline at end of file

src/main/java/beamline/models/responses/GraphvizResponse.java

@@ -2,7 +2,18 @@ package beamline.models.responses;
 
 import beamline.graphviz.Dot;
 
+/**
+ * A refined {@link Response} that can be rendered in Graphviz using the Dot
+ * language.
+ * 
+ * @author Andrea Burattin
+ */
 public interface GraphvizResponse extends Response {
 
+	/**
+	 * Returns the Dot representation of the response
+	 * 
+	 * @return
+	 */
 	public abstract Dot generateDot();
 }

src/main/java/beamline/models/responses/Response.java

 package beamline.models.responses;
 
+/**
+ * Marker interface used to define the type of the responses
+ * 
+ * @author Andrea Burattin
+ */
 public interface Response {
 
 }

src/main/java/beamline/models/responses/package-info.java

+/**
+ * This package contains all classes of the framework necessary to handle the
+ * responses of mining algorithms.
+ */
+package beamline.models.responses;
\ No newline at end of file

src/main/java/beamline/sources/CSVLogSource.java

@@ -20,6 +20,12 @@ import io.reactivex.rxjava3.core.Observable;
 import io.reactivex.rxjava3.core.ObservableEmitter;
 import io.reactivex.rxjava3.core.ObservableOnSubscribe;
 
+/**
+ * This implementation of a {@link XesSource} produces events according to the
+ * events contained in a CSV file. This source produces a cold observable.
+ * 
+ * @author Andrea Burattin
+ */
 public class CSVLogSource implements XesSource {
 
 	private static XFactory xesFactory = new XFactoryNaiveImpl();
@@ -29,6 +35,26 @@ public class CSVLogSource implements XesSource {
 	private int activityNameColumn;
 	private CSVParser parser;
 	
+	/**
+	 * Constructs the source by providing a CSV parser.
+	 * 
+	 * <p>
+	 * A parser can be produced, for example with the following code:
+	 * <pre>
+	 * CSVParser parser = new CSVParserBuilder()
+	 *     .withSeparator(',')
+	 *     .withIgnoreQuotations(true)
+	 *     .build();
+	 * </pre>
+	 * 
+	 * @param filename the absolute path of the CSV file
+	 * @param caseIdColumn the id of the column containing the case id (counting
+	 * starts from 0)
+	 * @param activityNameColumn the id of the column containing the activity
+	 * name (counting starts from 0)
+	 * @param parser the parser to be used for parsing the CSV file
+	 * @throws IOException
+	 */
 	public CSVLogSource(String filename, int caseIdColumn, int activityNameColumn, CSVParser parser) throws IOException {
 		this.filename = filename;
 		this.caseIdColumn = caseIdColumn;
@@ -36,6 +62,16 @@ public class CSVLogSource implements XesSource {
 		this.parser = parser;
 	}
 	
+	/**
+	 * Constructs the source
+	 * 
+	 * @param filename the absolute path of the CSV file
+	 * @param caseIdColumn the id of the column containing the case id (counting
+	 * starts from 0)
+	 * @param activityNameColumn the id of the column containing the activity
+	 * name (counting starts from 0)
+	 * @throws IOException
+	 */
 	public CSVLogSource(String filename, int caseIdColumn, int activityNameColumn) throws IOException {
 		this(filename, caseIdColumn, activityNameColumn, null);
 	}

src/main/java/beamline/sources/MQTTXesSource.java

@@ -19,6 +19,20 @@ import org.eclipse.paho.client.mqttv3.MqttMessage;
 import io.reactivex.rxjava3.core.Observable;
 import io.reactivex.rxjava3.subjects.PublishSubject;
 
+/**
+ * This implementation of a {@link XesSource} produces events as they are
+ * observed in an MQTT-XES broker. This source produces a hot observable.
+ * 
+ * <p>
+ * Example of usage:
+ * <pre>
+ * XesSource source = new MQTTXesSource("tcp://broker.hivemq.com:1883", "topicBase", "processName");
+ * source.prepare();
+ * </pre>
+ * 
+ * @see {@link http://www.beamline.cloud/mqtt-xes/}
+ * @author Andrea Burattin
+ */
 public class MQTTXesSource implements XesSource {
 
 	private static XFactory xesFactory = new XFactoryNaiveImpl();
@@ -27,6 +41,13 @@ public class MQTTXesSource implements XesSource {
 	private String topicBase;
 	private PublishSubject<XTrace> ps;
 	
+	/**
+	 * Constructs the source
+	 * 
+	 * @param brokerHost the URL of the broker host
+	 * @param topicBase the base of the topic for the
+	 * @param processName the name of the process
+	 */
 	public MQTTXesSource(String brokerHost, String topicBase, String processName) {
 		this.brokerHost = brokerHost;
 		this.topicBase = topicBase;

src/main/java/beamline/sources/Source.java

@@ -2,9 +2,32 @@ package beamline.sources;
 
 import io.reactivex.rxjava3.core.Observable;
 
+/**
+ * This interface is the base type that should be extended by all sources to be
+ * used in the framework. When using a source implementing this type, the method
+ * {@link #prepare()} should be called <strong>before</strong>
+ * {@link #getObservable()}.
+ * 
+ * @author Andrea Burattin
+ *
+ * @param <T> the type of observable objects this interface will produce.
+ */
 public interface Source<T> {
 
+	/**
+	 * This method returns the observable created by the source. Before calling
+	 * this method, it is important to prepare the source by calling the
+	 * {@link #prepare()} method.
+	 * 
+	 * @return
+	 */
 	public Observable<T> getObservable();
 	
+	/**
+	 * This method is supposed to be called before the {@link #getObservable()}
+	 * one: it is in charge of preparing the source to be processed.
+	 * 
+	 * @throws Exception 
+	 */
 	public void prepare() throws Exception;
 }