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