From 585a96860d10ecfd1901d51b306f1a6339cdc970 Mon Sep 17 00:00:00 2001 From: smjonas Date: Wed, 19 Apr 2023 12:20:41 +0200 Subject: [PATCH] Add more Javadoc --- .../HandcraftedScxmlTokenGenerator.java | 10 ++- .../parser/SimpleScxmlTokenGenerator.java | 3 +- .../model/executable_content/Action.java | 15 +++++ .../model/executable_content/Cancel.java | 4 ++ .../executable_content/ExecutableContent.java | 23 ++++++- .../model/executable_content/ForEach.java | 6 ++ .../parser/model/executable_content/If.java | 23 ++++++- .../de/jplag/scxml/parser/util/NodeUtil.java | 9 ++- .../jplag/scxml/sorting/SortingStrategy.java | 1 + .../scxml/util/AbstractScxmlVisitor.java | 62 ++++++++++++++++++- 10 files changed, 144 insertions(+), 12 deletions(-) diff --git a/languages/scxml/src/main/java/de/jplag/scxml/parser/HandcraftedScxmlTokenGenerator.java b/languages/scxml/src/main/java/de/jplag/scxml/parser/HandcraftedScxmlTokenGenerator.java index 8460a045e..0f0b0b197 100644 --- a/languages/scxml/src/main/java/de/jplag/scxml/parser/HandcraftedScxmlTokenGenerator.java +++ b/languages/scxml/src/main/java/de/jplag/scxml/parser/HandcraftedScxmlTokenGenerator.java @@ -14,13 +14,19 @@ public class HandcraftedScxmlTokenGenerator extends SimpleScxmlTokenGenerator { /** - * Creates the visitor. - * @param adapter is the parser adapter which receives the generated tokens. + * Creates the token generator. + * @param adapter the parser adapter which receives the generated tokens */ public HandcraftedScxmlTokenGenerator(ScxmlParserAdapter adapter) { super(adapter); } + /** + * Visits a state and extracts tokens based on whether its {@code initial} + * and {@code parallel} attributes are set to {@code true}. + * + * @param state the state to visit + */ protected void visitStateAttributes(State state) { if (state.initial()) { adapter.addToken(INITIAL_STATE, state); diff --git a/languages/scxml/src/main/java/de/jplag/scxml/parser/SimpleScxmlTokenGenerator.java b/languages/scxml/src/main/java/de/jplag/scxml/parser/SimpleScxmlTokenGenerator.java index 30b921600..d8c8fb78e 100644 --- a/languages/scxml/src/main/java/de/jplag/scxml/parser/SimpleScxmlTokenGenerator.java +++ b/languages/scxml/src/main/java/de/jplag/scxml/parser/SimpleScxmlTokenGenerator.java @@ -20,7 +20,7 @@ public class SimpleScxmlTokenGenerator extends AbstractScxmlVisitor { /** - * Creates the visitor. + * Creates the token generator. * @param adapter the parser adapter which receives the generated tokens */ public SimpleScxmlTokenGenerator(ScxmlParserAdapter adapter) { @@ -135,6 +135,7 @@ public void visitExecutableContent(ExecutableContent content) { return; } + // TODO: use entries Map, ScxmlTokenType> tokenTypeMap = Map.of(Send.class, SEND, Cancel.class, CANCEL); ScxmlTokenType type = tokenTypeMap.get(content.getClass()); adapter.addToken(type, content); diff --git a/languages/scxml/src/main/java/de/jplag/scxml/parser/model/executable_content/Action.java b/languages/scxml/src/main/java/de/jplag/scxml/parser/model/executable_content/Action.java index d0195e0a0..9e058afda 100644 --- a/languages/scxml/src/main/java/de/jplag/scxml/parser/model/executable_content/Action.java +++ b/languages/scxml/src/main/java/de/jplag/scxml/parser/model/executable_content/Action.java @@ -3,6 +3,12 @@ import java.util.List; import java.util.Objects; +/** + * Represents and SCXML elements which contain + * executable content to be executed when a state is entered / exited. + * @param type the type of the action ({@link Type#ON_ENTRY} or {@link Type#ON_EXIT}) + * @param contents the list of executable contents within the action + */ public record Action(Type type, List contents) implements ExecutableContent { @Override @@ -15,8 +21,17 @@ public String toString() { return String.format("Action (type=%s) {", type == Type.ON_ENTRY ? "OnEntry" : "OnExit"); } + /** + * The type of the action. + */ public enum Type { + /** + * Represents an SCXML element. + */ ON_ENTRY, + /** + * Represents an SCXML element. + */ ON_EXIT, } } diff --git a/languages/scxml/src/main/java/de/jplag/scxml/parser/model/executable_content/Cancel.java b/languages/scxml/src/main/java/de/jplag/scxml/parser/model/executable_content/Cancel.java index b6852236c..2f12923cf 100644 --- a/languages/scxml/src/main/java/de/jplag/scxml/parser/model/executable_content/Cancel.java +++ b/languages/scxml/src/main/java/de/jplag/scxml/parser/model/executable_content/Cancel.java @@ -1,5 +1,9 @@ package de.jplag.scxml.parser.model.executable_content; +/** + * Represents a SCXML element. + * @param sendid represents the sendid attribute of the SCXML element which is the ID of the event to be cancelled + */ public record Cancel(String sendid) implements ExecutableContent { @Override diff --git a/languages/scxml/src/main/java/de/jplag/scxml/parser/model/executable_content/ExecutableContent.java b/languages/scxml/src/main/java/de/jplag/scxml/parser/model/executable_content/ExecutableContent.java index 07c027a3f..d0ab01328 100644 --- a/languages/scxml/src/main/java/de/jplag/scxml/parser/model/executable_content/ExecutableContent.java +++ b/languages/scxml/src/main/java/de/jplag/scxml/parser/model/executable_content/ExecutableContent.java @@ -9,17 +9,36 @@ import de.jplag.scxml.parser.model.StatechartElement; import de.jplag.scxml.parser.util.NodeUtil; +/** + * Represents executable content in an SCXML statechart, which are elements that can be executed + * during state transitions, state entry, state exit or in conditional statements. + */ public interface ExecutableContent extends StatechartElement { /** - * Defines the set of allowed XML element names that are considered valid executable content. and - * elements are not allowed as they may only present as children of an element. + * Defines the set of allowed XML element names that are considered valid executable content. {@literal } and + * {@literal } elements are not allowed as they may only present as children of an {@literal } element. */ Set ALLOWED_XML_ELEMENTS = Set.of("raise", "if", "foreach", "log", "assign", "script", "send", "cancel"); + /** + * String constant for the element. + */ String ELSE_ELEMENT = "else"; + + /** + * String constant for the "event" attribute. + */ String EVENT_ATTRIBUTE = "event"; + + /** + * String constant for the "sendid" attribute. + */ String SEND_ID_ATTRIBUTE = "sendid"; + + /** + * String constant for the "delay" attribute. + */ String DELAY_ATTRIBUTE = "delay"; /** diff --git a/languages/scxml/src/main/java/de/jplag/scxml/parser/model/executable_content/ForEach.java b/languages/scxml/src/main/java/de/jplag/scxml/parser/model/executable_content/ForEach.java index 9db18cc2c..70be409fa 100644 --- a/languages/scxml/src/main/java/de/jplag/scxml/parser/model/executable_content/ForEach.java +++ b/languages/scxml/src/main/java/de/jplag/scxml/parser/model/executable_content/ForEach.java @@ -2,6 +2,12 @@ import java.util.List; +/** + * Represents a {@code } SCXML element, which is executable content + * that executes its contents for each item in a given data set. + * + * @param contents the list of executable contents within the {@code } element + */ public record ForEach(List contents) implements ExecutableContent { @Override diff --git a/languages/scxml/src/main/java/de/jplag/scxml/parser/model/executable_content/If.java b/languages/scxml/src/main/java/de/jplag/scxml/parser/model/executable_content/If.java index 2e7817b3b..1ca55135d 100644 --- a/languages/scxml/src/main/java/de/jplag/scxml/parser/model/executable_content/If.java +++ b/languages/scxml/src/main/java/de/jplag/scxml/parser/model/executable_content/If.java @@ -9,6 +9,16 @@ import de.jplag.scxml.parser.util.NodeUtil; +/** + * Represents an {@literal } SCXML element, which is an executable content element used for conditional execution. + * The {@literal } element can contain {@literal } and {@literal } branches for handling multiple conditions. + * + * @param cond the cond attribute of the {@literal } element which is the condition expression + * for the contained executable contents to be executed + * @param contents the list of executable contents to be executed when the condition is met + * @param elseIfs represents the list of {@literal } branches in the {@literal } element + * @param else_ the {@literal } branch corresponding to the {@literal } element, or {@code null} if not present + */ public record If(String cond, List contents, List elseIfs, Else else_) implements ExecutableContent { private static final Set ALLOWED_CONTENTS = Set.of("raise", "if", "foreach", "log", "assign", "script", "send", "cancel"); @@ -17,6 +27,15 @@ public record If(String cond, List contents, List els private static final String ELSEIF_ELEMENT = "elseif"; private static final String COND_ATTRIBUTE = "cond"; + + /** + * Constructs an If instance with the specified condition and a list of executable contents. + * The {@code elseIf} attribute is set to an empty list and the {@code else} is set to null. + * + * @param cond the cond attribute of the {@literal } element which is the condition expression + * for the contained executable contents to be executed + * @param contents the list of executable contents to be executed when the condition is met + */ public If(String cond, ExecutableContent... contents) { this(cond, new ArrayList<>(List.of(contents)), new ArrayList<>(), null); } @@ -32,8 +51,7 @@ private static void addBranch(String branch, List contents, L /** * Constructs an If statechart element from a given node with optional ElseIf or Else branches. The W3C SCXML * specification defines a valid {@literal } element as follows: - *

- * + * * 

      * {@code
      * 
@@ -52,6 +70,7 @@ private static void addBranch(String branch, List contents, L
      * on the same level.
      * @param node the node to create the If object from. Must contain at least one {@literal } element and optionally
      * {@literal } or {@literal } tags.
+     * @return an instance of If created from the node
      * @throws IllegalArgumentException when more than one {@literal } statement is present
      */
     public static If fromNode(Node node) throws IllegalArgumentException {
diff --git a/languages/scxml/src/main/java/de/jplag/scxml/parser/util/NodeUtil.java b/languages/scxml/src/main/java/de/jplag/scxml/parser/util/NodeUtil.java
index 3a530cac2..003d71304 100644
--- a/languages/scxml/src/main/java/de/jplag/scxml/parser/util/NodeUtil.java
+++ b/languages/scxml/src/main/java/de/jplag/scxml/parser/util/NodeUtil.java
@@ -76,8 +76,13 @@ public static List getNodesRecursive(Node root, String childName) {
     }
 
     /**
-     * @return the value of the attribute specified by name of the given node or null if the node does not contain an
-     * attribute with this name
+     * Retrieves the value of an attribute with the specified name from the given node. If the attribute is not present,
+     * {@code null} is returned.
+     *
+     * @param node the node containing the attribute
+     * @param name the name of the attribute to retrieve
+     * @return the value of the attribute, or {@code null} if the node does not contain an
+     * attribute with the given name
      */
     public static String getAttribute(Node node, String name) {
         Node attribute = node.getAttributes().getNamedItem(name);
diff --git a/languages/scxml/src/main/java/de/jplag/scxml/sorting/SortingStrategy.java b/languages/scxml/src/main/java/de/jplag/scxml/sorting/SortingStrategy.java
index ea0f66491..095ecffcb 100644
--- a/languages/scxml/src/main/java/de/jplag/scxml/sorting/SortingStrategy.java
+++ b/languages/scxml/src/main/java/de/jplag/scxml/sorting/SortingStrategy.java
@@ -13,5 +13,6 @@ public interface SortingStrategy {
      * Sorts a list of statechart elements.
      * @param statechartElements the list of statechart elements to sort
      */
+    // TODO: try without type parameter
      List sort(List statechartElements);
 }
diff --git a/languages/scxml/src/main/java/de/jplag/scxml/util/AbstractScxmlVisitor.java b/languages/scxml/src/main/java/de/jplag/scxml/util/AbstractScxmlVisitor.java
index 7f0a5eed1..31ba4c5bb 100644
--- a/languages/scxml/src/main/java/de/jplag/scxml/util/AbstractScxmlVisitor.java
+++ b/languages/scxml/src/main/java/de/jplag/scxml/util/AbstractScxmlVisitor.java
@@ -19,8 +19,19 @@
  */
 public abstract class AbstractScxmlVisitor {
 
+    /**
+     * The current parser adapter that is called to add new tokens.
+     */
     protected ScxmlParserAdapter adapter;
+
+    /**
+     * The sorting strategy to use for visiting nested statechart elements.
+     */
     protected SortingStrategy sorter;
+
+    /**
+     * The current depth in the statechart.
+     */
     protected int depth;
 
     public AbstractScxmlVisitor(ScxmlParserAdapter adapter) {
@@ -40,6 +51,7 @@ public void setSorter(SortingStrategy sorter) {
      * Visits a statechart element without effecting the main token stream by temporarily swapping out the current parser
      * adapter. Returns a list of collected token type ordinals.
      * @param element the statechart element to visit
+     * @return a list of visited token type ordinals
      */
     public List peekTokens(StatechartElement element) {
         ScxmlParserAdapter prevAdapter = this.adapter;
@@ -76,22 +88,66 @@ public final void visit(StatechartElement element) throws IllegalArgumentExcepti
         visitorMap.get(element.getClass()).accept(element);
     }
 
+    /**
+     * Recursively visits a statechart.
+     *
+     * @param statechart the statechart to visit
+     */
     protected abstract void visitStatechart(Statechart statechart);
 
+    /**
+     * Recursively visits a state.
+     *
+     * @param state the state to visit
+     */
     protected abstract void visitState(State state);
 
+    /**
+     * Recursively visits a transition.
+     *
+     * @param transition the transition to visit
+     */
+    protected abstract void visitTransition(Transition transition);
+
+    /**
+     * Recursively visits a list of actions.
+     *
+     * @param actions the list of actions to visit
+     */
     protected abstract void visitActions(List actions);
 
+    /**
+     * Recursively visits an if statechart element.
+     *
+     * @param if_ the if element to visit
+     */
     protected abstract void visitIf(If if_);
 
+    /**
+     * Recursively visits an elseIf statechart element.
+     *
+     * @param elseIf the elseIf element to visit
+     */
     protected abstract void visitElseIf(ElseIf elseIf);
 
+    /**
+     * Recursively visits an else statechart element.
+     *
+     * @param else_ the else element to visit
+     */
     protected abstract void visitElse(Else else_);
 
+    /**
+     * Recursively visits executable content.
+     *
+     * @param content the executable content to visit
+     */
     protected abstract void visitExecutableContent(ExecutableContent content);
 
+    /**
+     * Visits simple executable content.
+     *
+     * @param content the simple executable content to visit
+     */
     protected abstract void visitSimpleExecutableContent(SimpleExecutableContent content);
-
-    protected abstract void visitTransition(Transition transition);
-
 }