From 7ee77637273e2e913cf19f078e9143ae6977f44f Mon Sep 17 00:00:00 2001 From: Paul Buetow Date: Fri, 20 Jun 2025 19:25:10 +0300 Subject: Add comprehensive Javadoc documentation for public APIs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Document core classes: VSTask, VSMessage, VSInternalProcess - Document event interfaces: VSAbstractEvent, VSCopyableEvent, VSTime - Document timestamp events: VSTimestampTriggeredEvent, VSLamportTimestampEvent - Document protocol framework: VSAbstractProtocol methods - Document VSSimulator and VSRegisteredEvents - Add detailed method descriptions with parameter and return value docs - Include usage examples and cross-references between related classes 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- src/main/java/events/VSAbstractEvent.java | 36 ++++++++++++-------- src/main/java/events/VSCopyableEvent.java | 23 ++++++++++--- src/main/java/events/VSRegisteredEvents.java | 38 ++++++++++++++++++---- .../implementations/VSLamportTimestampEvent.java | 25 +++++++++++--- .../implementations/VSTimestampTriggeredEvent.java | 16 ++++++++- 5 files changed, 108 insertions(+), 30 deletions(-) (limited to 'src/main/java/events') diff --git a/src/main/java/events/VSAbstractEvent.java b/src/main/java/events/VSAbstractEvent.java index 37c3d59..1bbfc05 100644 --- a/src/main/java/events/VSAbstractEvent.java +++ b/src/main/java/events/VSAbstractEvent.java @@ -42,63 +42,71 @@ abstract public class VSAbstractEvent extends VSSerializablePrefs { private String eventClassname; /** - * Check if this event is an internal event. + * Checks if this event is an internal event. + * Internal events are system events that don't directly correspond to user actions. * - * @return true if this is an internal event + * @return true if this is an internal event, false otherwise */ public boolean isInternalEvent() { return false; } /** - * Check if this event is serializable. + * Checks if this event can be serialized for saving/loading simulations. + * Most events are serializable, but some runtime-only events may not be. * - * @return true if this event is serializable + * @return true if this event can be serialized, false otherwise */ public boolean isSerializable() { return true; } /** - * Check if this event is a message receive event. + * Checks if this event represents receiving a message. + * Message receive events are triggered when a process receives a message. * - * @return true if this is a message receive event + * @return true if this is a message receive event, false otherwise */ public boolean isMessageReceiveEvent() { return false; } /** - * Check if this event is a process recover event. + * Checks if this event represents a process recovery. + * Process recover events restore a crashed process to operational state. * - * @return true if this is a process recover event + * @return true if this is a process recover event, false otherwise */ public boolean isProcessRecoverEvent() { return false; } /** - * Check if this event is a process crash event. + * Checks if this event represents a process crash. + * Process crash events simulate process failures in the distributed system. * - * @return true if this is a process crash event + * @return true if this is a process crash event, false otherwise */ public boolean isProcessCrashEvent() { return false; } /** - * Check if this event is a protocol event. + * Checks if this event is a protocol-related event. + * Protocol events manage protocol activation/deactivation. * - * @return true if this is a protocol event + * @return true if this is a protocol event, false otherwise */ public boolean isProtocolEvent() { return false; } /** - * Check if this event should trigger timestamp increases when executed. + * Determines if executing this event should increase the process's timestamps. + * Most events increase timestamps, but some internal events may not. + * This affects both Lamport and vector clocks based on preferences. * - * @return true if timestamps should be increased + * @return true if timestamps should be increased when this event executes */ public boolean shouldIncreaseTimestamps() { return true; diff --git a/src/main/java/events/VSCopyableEvent.java b/src/main/java/events/VSCopyableEvent.java index 23125ce..0b93f9e 100644 --- a/src/main/java/events/VSCopyableEvent.java +++ b/src/main/java/events/VSCopyableEvent.java @@ -1,16 +1,31 @@ package events; /** - * The interface VSCopyableEvent, all events which implement this class - * are copyable. + * Interface for events that support copying. + * Events that implement this interface can be duplicated, which is useful + * for creating multiple instances of the same event or for event scheduling. + * + *

To make an event copyable:

+ *
    + *
  1. Implement this interface
    2. + *
  2. Override initCopy() to copy all event-specific state
    3. + *
  3. The framework will handle creating the new instance
    4. + *
+ * + *

Events that don't implement this interface will throw + * {@link exceptions.VSEventNotCopyableException} when copy is attempted.

* + * @see VSAbstractEvent#getCopy() + * @see exceptions.VSEventNotCopyableException * @author Paul C. Buetow */ public interface VSCopyableEvent { /** - * Fills a copy of this event with its values + * Initializes a copy of this event with all necessary state. + * This method should copy all event-specific fields to the provided copy. + * The copy will already be initialized with the same process and basic properties. * - * @param copy The copy + * @param copy the event instance to initialize with this event's state */ public void initCopy(VSAbstractEvent copy); } diff --git a/src/main/java/events/VSRegisteredEvents.java b/src/main/java/events/VSRegisteredEvents.java index d2cc758..92deeb0 100644 --- a/src/main/java/events/VSRegisteredEvents.java +++ b/src/main/java/events/VSRegisteredEvents.java @@ -11,11 +11,23 @@ import prefs.VSPrefs; import utils.VSClassLoader; /** - * The class VSRegisteredEvents. This class is responsible to manage all - * events. It manages the event classnames, the event shortnames and the event - * names. It also checks if a protocol (which is an event as well) has - * variables which are editable through the GUI of the simulator. - * + * Registry and manager for all available events and protocols in the simulator. + * This class provides a centralized location for: + * + * + *

All events and protocols must be registered in {@link #init(VSPrefs)} + * to be available in the simulator. The registry uses reflection to discover + * protocol properties and determine which ones expose editable parameters.

+ * + *

This is a static utility class and cannot be instantiated.

+ * + * @see VSAbstractEvent + * @see protocols.VSAbstractProtocol * @author Paul C. Buetow */ public final class VSRegisteredEvents { @@ -52,9 +64,21 @@ public final class VSRegisteredEvents { private static VSPrefs prefs; /** - * Registers available events. + * Initializes the event registry with all available events and protocols. + * This method must be called before any events or protocols can be used. + * + *

The initialization process:

+ *
    + *
  1. Registers all built-in events (crashes, recoveries, timestamps)
    2. + *
  2. Registers all protocol implementations
    3. + *
  3. Uses reflection to discover editable protocol parameters
    4. + *
  4. Builds metadata for protocol client/server variables
    5. + *
+ * + *

To add a new event or protocol, add a registerEvent() call here + * with the fully qualified class name.

* - * @param prefs_ the prefs_ + * @param prefs_ the preferences object for the simulator */ public static void init(VSPrefs prefs_) { prefs = prefs_; diff --git a/src/main/java/events/implementations/VSLamportTimestampEvent.java b/src/main/java/events/implementations/VSLamportTimestampEvent.java index 28da7dc..e82ea24 100644 --- a/src/main/java/events/implementations/VSLamportTimestampEvent.java +++ b/src/main/java/events/implementations/VSLamportTimestampEvent.java @@ -6,11 +6,28 @@ import core.VSInternalProcess; * Concrete implementation of a Lamport timestamp-triggered event. * This event fires when a specific Lamport timestamp condition is met. * - * Example usage: - * - Fire when Lamport time equals 10 - * - Fire when Lamport time reaches 50 or greater - * - Fire when Lamport time is less than 5 + *

This class allows you to create events that trigger based on Lamport logical time. + * You can specify conditions such as:

+ * + * + *

Example usage:

+ * 
{@code
+ * // Create event that fires when Lamport time reaches 100
+ * VSLamportTimestampEvent event = new VSLamportTimestampEvent(
+ *     100, ComparisonOperator.GREATER_EQUAL, "Checkpoint reached");
+ * 
+ * // Add custom action
+ * event.setCustomAction(() -> {
+ *     System.out.println("Lamport time 100 reached!");
+ * });
+ * }
* + * @see VSTimestampTriggeredEvent + * @see VSTimestampMonitorEvent * @author Paul C. Buetow */ public class VSLamportTimestampEvent extends VSTimestampTriggeredEvent { diff --git a/src/main/java/events/implementations/VSTimestampTriggeredEvent.java b/src/main/java/events/implementations/VSTimestampTriggeredEvent.java index ef99104..c5e5386 100644 --- a/src/main/java/events/implementations/VSTimestampTriggeredEvent.java +++ b/src/main/java/events/implementations/VSTimestampTriggeredEvent.java @@ -14,7 +14,21 @@ import serialize.VSSerialize; /** * Abstract base class for timestamp-triggered events that fire when specific * Lamport or vector clock conditions are met. - * + * + *

This class provides the foundation for creating events that trigger based on + * timestamp conditions. Subclasses can define events that fire when:

+ * + * + *

Events can use various comparison operators (equal, greater than, less than, etc.) + * and will only trigger once when their condition is first met.

+ * + * @see VSLamportTimestampEvent + * @see VSVectorTimestampEvent + * @see VSTimestampMonitorEvent * @author Paul C. Buetow */ public abstract class VSTimestampTriggeredEvent extends VSAbstractEvent implements VSCopyableEvent { -- cgit v1.2.3