refactor and add docs to monitor

.github/workflows/ci.yaml

@@ -191,4 +191,4 @@ jobs:
             `;
             
             console.log(summary);
-            await core.summary.addRaw(summary).write();
+            await core.summary.addRaw(summary).write();

src/main/java/Main.java

@@ -1,7 +1,6 @@
 import java.util.Arrays;
 
 public class Main {
-  // static boolean condicion = true;
 
   public static void main(String[] args) {
 
@@ -26,7 +25,7 @@ public static void main(String[] args) {
     Monitor monitor = Monitor.getMonitor(petriNet);
 
     // Create and start threads
-    Arrays.setAll(threads, i -> new Thread(new Segments(rdPConf.getSequence(i), monitor)));
+    Arrays.setAll(threads, i -> new Thread(new Segments(rdPConf.getTransitionSequence(i), monitor)));
     Arrays.stream(threads).forEach(Thread::start);
   }
 }

src/main/java/Monitor.java

@@ -1,32 +1,48 @@
 import java.util.concurrent.Semaphore;
-import java.util.concurrent.atomic.AtomicBoolean;
 
+/**
+ * Monitor class for managing synchronized interactions with a Petri Net.
+ * Ensures only one instance of Monitor is created using the Singleton pattern.
+ */
 class Monitor implements MonitorInterface {
+
+  // Singleton instance of the Monitor
   private static Monitor monitor = null;
   boolean isFireSuccessful = false;
-  // Policy policyQueue;
-  // Policy policy;
-  PetriNet petriNet;
+  PetriNet petriNet; // The associated Petri Net instance
 
-  private final Semaphore mutex;
+  private final Semaphore mutex; // Mutex to ensure thread safety
 
-  AtomicBoolean isRunning = new AtomicBoolean(true);
+  /**
+   * Private constructor to enforce Singleton pattern.
+   *
+   * @param petriNet the PetriNet instance to control.
+   */
+  private Monitor(PetriNet petriNet) {
+    this.mutex = new Semaphore(1, true);
+    this.petriNet = petriNet;
+  }
 
-  // Using Singleton pattern to ensure that only one instance of Monitor is created
+  /**
+   * Returns the singleton instance of the Monitor.
+   *
+   * @param petriNet the PetriNet instance to associate with the Monitor.
+   * @return the Monitor instance.
+   */
   public static Monitor getMonitor(PetriNet petriNet) {
     if (monitor == null) {
       monitor = new Monitor(petriNet);
     }
     return monitor;
   }
 
-  private Monitor(PetriNet petriNet) {
-    this.mutex = new Semaphore(1, true);
-    // this.policyQueue = policyQueue;
-    // this.policy = policy;
-    this.petriNet = petriNet;
-  }
 
+  /**
+   * Attempts to fire a transition in the associated Petri Net.
+   *
+   * @param transitionIndex the index of the transition to fire.
+   * @return true if the transition was successfully fired at least once, false otherwise.
+   */
   @Override
   public boolean fireTransition(int transitionIndex) {
     try {
@@ -36,21 +52,29 @@ public boolean fireTransition(int transitionIndex) {
     }
     isFireSuccessful = true;
     while (isFireSuccessful) {
-      isFireSuccessful = petriNet.fireTransition(transitionIndex);
+      isFireSuccessful = petriNet.tryFireTransition(transitionIndex);
       if (isFireSuccessful) {
         System.out.println(
-            "Transition fired: " + transitionIndex + " Marking: " + petriNet.printMarking());
+            "Transition fired: " + transitionIndex + " Marking: " + petriNet.getStringMarking());
       }
     }
     mutex.release();
     return false;
   }
 
+  /**
+   * Checks if the Petri Net has achieved its invariants target.
+   *
+   * @return true if the invariants target is achieved, false otherwise.
+   */
   public boolean petriNetIsShutdown() {
     return petriNet.invariantsTargetAchieved();
   }
 }
 
+/**
+ * Interface for Monitor functionality.
+ */
 interface MonitorInterface {
   boolean fireTransition(int transition);
 }

src/main/java/PetriNet.java

@@ -53,7 +53,7 @@ public PetriNet(
    *
    * @param transitionIndex The index of the transition to fire in the input incidence matrix
    */
-  public boolean fireTransition(int transitionIndex) {
+  public boolean tryFireTransition(int transitionIndex) {
     Transition transitionFromIndex = transitions.get(transitionIndex);
 
     // If not enabled, return false
@@ -106,14 +106,12 @@ public boolean fireTransition(int transitionIndex) {
   }
 
   /** Prints the current marking of the Petri net. */
-  public String printMarking() {
+  public String getStringMarking() {
     String markingString =
         IntStream.range(0, marking.length)
             .mapToObj(placeIndex -> String.valueOf("P" + placeIndex + ": " + marking[placeIndex]))
             .collect(Collectors.joining(" "));
 
-    // Print marking string to the console
-    // System.out.println(markingString);
     return markingString;
   }
 
@@ -163,7 +161,6 @@ public List<Transition> getEnabledTransitions() {
   }
 
   public boolean invariantsTargetAchieved() {
-    return invariantsTargetAchieved; // TODO: protect this because many threads can access
-    // lectura
+    return invariantsTargetAchieved; 
   }
 }

src/main/java/PetriNetConf.java

@@ -63,8 +63,6 @@ public class PetriNetConf {
    * The sequence is defined by the index of the transitions in the transitions list
    * For example, the sequence for thread 0 is {T0, T1}
    */
-  // TODO: no convendria hacer que este array sea una lista de listas? List<List<Transition>>?
-  // Simplificaria la funcion getSequence
   private static final int[][] TRANSITIONS_THREADS = {
     {0, 1}, // Thread 0
     {2, 5}, // Thread 1
@@ -109,7 +107,7 @@ public List<Transition> getTransitions() {
     return transitions;
   }
 
-  public List<Transition> getSequence(int sequenceNumber) {
+  public List<Transition> getTransitionSequence(int sequenceNumber) {
     if (sequenceNumber < 0 || sequenceNumber >= TRANSITIONS_THREADS.length) {
       throw new IllegalArgumentException("Index for TRANSITIONS_THREADS invalid");
     }

src/main/java/Transition.java

@@ -14,7 +14,6 @@ public Transition(int number, int delayTime, int maxTime) {
     this.isImmediate = delayTime == 0;
   }
 
-  // TODO: remove (unused?)
   public void setTime(int delayTime) {
     if (delayTime < 0) {
       throw new IllegalArgumentException("Time cannot be negative");

src/test/java/PetriNetConfTest.java

@@ -59,19 +59,19 @@ void testTransitionsInitialization() {
 
   @Test
   void testGetSequenceValidIndex() {
-    List<Transition> sequence = petriNetConf.getSequence(0);
+    List<Transition> sequence = petriNetConf.getTransitionSequence(0);
     assertThat(sequence).hasSize(2);
     assertThat(sequence.get(0).getNumber()).isEqualTo(0); // T0
     assertThat(sequence.get(1).getNumber()).isEqualTo(1); // T1
   }
 
   @Test
   void testGetSequenceInvalidIndex() {
-    assertThatThrownBy(() -> petriNetConf.getSequence(-1))
+    assertThatThrownBy(() -> petriNetConf.getTransitionSequence(-1))
         .isInstanceOf(IllegalArgumentException.class)
         .hasMessage("Index for TRANSITIONS_THREADS invalid");
 
-    assertThatThrownBy(() -> petriNetConf.getSequence(6))
+    assertThatThrownBy(() -> petriNetConf.getTransitionSequence(6))
         .isInstanceOf(IllegalArgumentException.class)
         .hasMessage("Index for TRANSITIONS_THREADS invalid");
   }

src/test/java/PetriNetTest.java

@@ -1,6 +1,5 @@
 import static org.junit.jupiter.api.Assertions.assertArrayEquals;
 import static org.junit.jupiter.api.Assertions.assertEquals;
-
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 
@@ -37,19 +36,19 @@ public void testEnabledTransitions() {
   @Test
   public void testFailFireTransitions() {
     int[] actualMarking = petriNet.getMarking();
-    petriNet.fireTransition(10);
+    petriNet.tryFireTransition(10);
     assertArrayEquals(actualMarking, petriNet.getMarking());
   }
 
   @Test
   public void testFireTransitions() {
-    petriNet.fireTransition(0);
+    petriNet.tryFireTransition(0);
     int[] newMarking = {4, 0, 1, 0, 4, 0, 1, 1, 0, 0, 1, 0, 0, 0, 0};
     assertArrayEquals(newMarking, petriNet.getMarking());
     newMarking[1] = 1;
     newMarking[2] = 0;
     newMarking[3] = 1;
-    petriNet.fireTransition(1);
+    petriNet.tryFireTransition(1);
     assertArrayEquals(newMarking, petriNet.getMarking());
   }
 }