diff options
Diffstat (limited to 'src/main/java/events')
5 files changed, 108 insertions, 30 deletions
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. + * + * <p>To make an event copyable:</p> + * <ol> + * <li>Implement this interface</li> + * <li>Override initCopy() to copy all event-specific state</li> + * <li>The framework will handle creating the new instance</li> + * </ol> + * + * <p>Events that don't implement this interface will throw + * {@link exceptions.VSEventNotCopyableException} when copy is attempted.</p> * + * @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: + * <ul> + * <li>Registering event and protocol implementations</li> + * <li>Mapping between class names, short names, and display names</li> + * <li>Identifying which protocols have editable parameters</li> + * <li>Managing client/server variable metadata for protocols</li> + * </ul> + * + * <p>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.</p> + * + * <p>This is a static utility class and cannot be instantiated.</p> + * + * @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. + * + * <p>The initialization process:</p> + * <ol> + * <li>Registers all built-in events (crashes, recoveries, timestamps)</li> + * <li>Registers all protocol implementations</li> + * <li>Uses reflection to discover editable protocol parameters</li> + * <li>Builds metadata for protocol client/server variables</li> + * </ol> + * + * <p>To add a new event or protocol, add a registerEvent() call here + * with the fully qualified class name.</p> * - * @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 + * <p>This class allows you to create events that trigger based on Lamport logical time. + * You can specify conditions such as:</p> + * <ul> + * <li>Fire when Lamport time equals 10</li> + * <li>Fire when Lamport time reaches 50 or greater</li> + * <li>Fire when Lamport time is less than 5</li> + * </ul> + * + * <p>Example usage:</p> + * <pre>{@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!"); + * }); + * }</pre> * + * @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. - * + * + * <p>This class provides the foundation for creating events that trigger based on + * timestamp conditions. Subclasses can define events that fire when:</p> + * <ul> + * <li>Lamport time reaches a specific value</li> + * <li>Vector clock matches certain conditions</li> + * <li>Custom timestamp comparisons are satisfied</li> + * </ul> + * + * <p>Events can use various comparison operators (equal, greater than, less than, etc.) + * and will only trigger once when their condition is first met.</p> + * + * @see VSLamportTimestampEvent + * @see VSVectorTimestampEvent + * @see VSTimestampMonitorEvent * @author Paul C. Buetow */ public abstract class VSTimestampTriggeredEvent extends VSAbstractEvent implements VSCopyableEvent { |