diff options
66 files changed, 257 insertions, 14475 deletions
diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..ef967f8 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,92 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Build and Development Commands + +**Essential Commands:** +```bash +# Full build (recommended) +mvn clean package + +# Run the application +java -jar target/ds-sim-1.0.1-SNAPSHOT.jar + +# Quick build and run +mvn clean package && java -jar target/ds-sim-1.0.1-SNAPSHOT.jar + +# Clean build artifacts +mvn clean +``` + +**Development Commands:** +```bash +# Fast compilation for development +mvn compile + +# Run directly with Maven +mvn exec:java + +# Build without tests (faster development) +mvn package -DskipTests + +# Run tests +mvn test + +# Generate Javadoc +mvn javadoc:javadoc +``` + +**Code Quality Scripts:** +```bash +# Format code before commit +./scripts/formatthecode.sh + +# Run pre-commit checks +./scripts/beforecommit.sh +``` + +## Architecture Overview + +This is a distributed systems simulator built on an **event-driven architecture** with clear layered separation: + +### Core Components + +- **Simulator Engine**: `VSSimulator` drives the main simulation loop with `VSTaskManager` executing time-ordered tasks +- **Process Framework**: `VSAbstractProcess` provides base functionality; `VSInternalProcess` extends for simulation features +- **Event System**: All actions are `VSTask` objects containing events, executed in temporal order via priority queues +- **Protocol Framework**: `VSAbstractProtocol` base class for implementing distributed algorithms with server/client modes +- **Time Management**: Supports global time, local logical clocks, Lamport timestamps, and vector clocks +- **Message System**: `VSMessage` objects with automatic timestamp updates and configurable network simulation + +### Key Patterns + +- **Maven Standard Layout**: Source code in `src/main/java/` with standard Maven directory structure +- **Template Method**: Abstract protocol classes define structure, concrete implementations provide specifics +- **Event-Driven**: Tasks trigger events which generate new tasks/messages in the simulation loop +- **Pluggable Protocols**: Register new protocols in `VSRegisteredEvents.init()` + +### Implementation Guidelines + +**Adding New Protocols:** +1. Extend `VSAbstractProtocol` +2. Implement `onServerInit()`, `onClientInit()`, `onServerRecv()`, `onClientRecv()` methods +3. Register protocol class name in `VSRegisteredEvents.init()` + +**Adding New Events:** +1. Extend `VSAbstractEvent` +2. Implement `onInit()` and `onStart()` methods +3. Register event class name in `VSRegisteredEvents` + +**Understanding Simulation Flow:** +- `VSSimulatorVisualization.run()` drives main loop +- `VSTaskManager.runTasks()` executes pending tasks each time step +- Tasks are either local-timed (process clock) or global-timed (simulation clock) +- Messages include network delay simulation and visual representation + +## Entry Points + +- **Main Class**: `simulator.VSMain` +- **Simulator Core**: `simulator.VSSimulator` +- **Protocol Implementations**: `protocols.implementations.*` +- **Event Registration**: `events.VSRegisteredEvents.init()`
\ No newline at end of file @@ -14,46 +14,184 @@ DS-Sim is a modern, open-source simulator for distributed systems, written in Ja ## Requirements -- Java 17 or higher +- Java 11 or higher - Maven 3.8 or higher -## Building +### Setting up JAVA_HOME on Fedora Linux + +If you encounter "JAVA_HOME environment variable is not defined correctly" errors: + +#### Method 1: Automatic Setup (Recommended) +```bash +# Find and set JAVA_HOME automatically +export JAVA_HOME=$(dirname $(dirname $(readlink -f $(which java)))) +echo $JAVA_HOME # Should show something like /usr/lib/jvm/java-21-openjdk +``` + +#### Method 2: Manual Setup +```bash +# Check available Java versions +alternatives --display java + +# Set JAVA_HOME to the current Java installation +export JAVA_HOME=/usr/lib/jvm/java-21-openjdk + +# Or for Java 11 if you have it installed +export JAVA_HOME=/usr/lib/jvm/java-11-openjdk +``` + +#### Method 3: Permanent Setup +To make JAVA_HOME persistent across sessions, add it to your shell profile: + +```bash +# Add to ~/.bashrc or ~/.zshrc +echo 'export JAVA_HOME=/usr/lib/jvm/java-21-openjdk' >> ~/.bashrc +source ~/.bashrc + +# Verify it's set correctly +echo $JAVA_HOME +java -version +``` + +#### Install Java Development Kit (if needed) +```bash +# Install OpenJDK 21 (recommended) +sudo dnf install java-21-openjdk-devel + +# Or install OpenJDK 11 (minimum requirement) +sudo dnf install java-11-openjdk-devel + +# Install Maven +sudo dnf install maven +``` + +## Quick Start ```bash # Clone the repository git clone https://github.com/yourusername/ds-sim.git cd ds-sim -# Build the project +# Set JAVA_HOME if needed (Fedora Linux) +export JAVA_HOME=$(dirname $(dirname $(readlink -f $(which java)))) + +# Build and run in one step +mvn clean package && java -jar target/ds-sim-1.0.1-SNAPSHOT.jar +``` + +## Building the Project + +### Full Build +```bash +# Clean and build everything (recommended) mvn clean package +``` -# Run the simulator -java -jar target/ds-sim-1.0-SNAPSHOT.jar +### Development Build +```bash +# Fast compilation only +mvn compile + +# Build without running tests (faster) +mvn package -DskipTests +``` + +### Build Output +After building, you'll find: +- `target/ds-sim-1.0.1-SNAPSHOT.jar` - Executable JAR with all dependencies +- `target/classes/` - Compiled class files +- `target/original-ds-sim-1.0.1-SNAPSHOT.jar` - JAR without dependencies + +## Running the Application + +### Method 1: Using JAR File (Recommended) +```bash +# After building, run the executable JAR +java -jar target/ds-sim-1.0.1-SNAPSHOT.jar +``` + +### Method 2: Direct Maven Execution +```bash +# Run without building JAR first +mvn exec:java +``` + +### Method 3: Build and Run Combined +```bash +# Build and run in one command +mvn clean package && java -jar target/ds-sim-1.0.1-SNAPSHOT.jar ``` -## Development +## Cleaning the Project +### Remove All Build Artifacts ```bash -# Run tests +# Clean everything Maven generated +mvn clean +``` + +### What Gets Cleaned +The `mvn clean` command removes: +- `target/` directory and all contents +- Compiled `.class` files +- Generated JAR files +- Test reports +- Dependency cache + +### Force Clean (if needed) +```bash +# Remove target directory manually if Maven clean fails +rm -rf target/ +mvn clean +``` + +## Development Workflow + +```bash +# 1. Make code changes +# 2. Quick compile to check for errors +mvn compile + +# 3. Run tests (if any exist) mvn test -# Generate documentation -mvn javadoc:javadoc +# 4. Build and test the application +mvn package && java -jar target/ds-sim-1.0.1-SNAPSHOT.jar + +# 5. Clean up when done +mvn clean ``` +## Maven Command Reference + +| Command | Purpose | When to Use | +|---------|---------|-------------| +| `mvn compile` | Compile source code only | Quick syntax checking | +| `mvn test` | Run unit tests | Before committing code | +| `mvn package` | Create JAR files | Ready to distribute | +| `mvn clean package` | Full clean build | First build or after major changes | +| `mvn exec:java` | Run application directly | Quick testing without JAR | +| `mvn javadoc:javadoc` | Generate documentation | Creating API docs | +| `mvn clean` | Remove build artifacts | Clean workspace | +| `mvn package -DskipTests` | Fast build without tests | Development iterations | + ## Project Structure ``` ds-sim/ ├── src/ -│ ├── main/ -│ │ ├── java/ # Source code -│ │ └── resources/ # Configuration files -│ └── test/ -│ ├── java/ # Test code -│ └── resources/ # Test resources -├── docs/ # Documentation -└── pom.xml # Project configuration +│ └── main/ +│ ├── java/ # Source code +│ │ ├── core/ # Process and message handling +│ │ ├── events/ # Event system +│ │ ├── protocols/ # Distributed algorithms +│ │ ├── simulator/ # Main simulation engine +│ │ └── utils/ # Utilities and helpers +│ └── resources/ # Configuration files +├── docs/ # Documentation +├── saved-simulations/ # Example simulation files +├── scripts/ # Development scripts +└── pom.xml # Maven configuration ``` ## Contributing diff --git a/build.xml b/build.xml deleted file mode 100644 index 6487c16..0000000 --- a/build.xml +++ /dev/null @@ -1,65 +0,0 @@ -<project name="Verteilte Systeme" default="dist" basedir="."> - <description>This is the distributed systems simulation/learning environment!</description> - - <!-- set global properties for this build --> - <property name="sources" location="sources" /> - <property name="dist" location="dist" /> - <property name="classes" location="classes" /> - - <target name="init"> - <tstamp /> - <mkdir dir="${classes}" /> - </target> - - <target name="compile" depends="init" description="compile the source" > - <javac srcdir="${sources}" destdir="${classes}"> - <compilerarg value="-Xlint:deprecation,unchecked" /> - </javac> - <copy todir="${classes}/icons"> - <fileset dir="icons" /> - </copy> - </target> - - <target name="dist" depends="compile" description="generate the distribution" > - <delete file="MANIFEST.MF" /> - - <manifest file="MANIFEST.MF"> - <attribute name="Built-By" value="Paul C. Buetow" /> - <attribute name="Main-Class" value="simulator/VSMain" /> - </manifest> - - <mkdir dir="${dist}/lib" /> - <jar jarfile="${dist}/lib/VS-Sim-${DSTAMP}.jar" basedir="${classes}" manifest="MANIFEST.MF" /> - <copy file="${dist}/lib/VS-Sim-${DSTAMP}.jar" tofile="${dist}/lib/VS-Sim-Latest.jar" /> - </target> - - <target name="clean" description="clean up" > - <delete dir="${basedir}/javadoc/" /> - <delete dir="${classes}" /> - <delete dir="${dist}" /> - <delete file="MANIFEST.MF" /> - </target> - - <target name="rundist" depends="dist"> - <java jar="${dist}/lib/VS-Sim-Latest.jar" fork="true" /> - </target> - - <target name="run" depends="compile"> - <java dir="${classes}" classname="simulator.VSMain" fork="true" /> - </target> - - <target name="testdist" depends="dist,rundist" /> - - <target name="test" depends="compile"> - <java dir="${classes}" classname="simulator.VSMain" fork="true"> - <!-- <arg value="-debug" /> --> - </java> - </target> - - <target name="javadoc" description="Generate Javadocs"> - <mkdir dir="${basedir}/javadoc/"/> - <javadoc destdir="${basedir}/javadoc/"> - <fileset dir="${basedir}/" includes="**/*.java" /> - </javadoc> - </target> -</project> @@ -7,7 +7,7 @@ <groupId>org.ds-sim</groupId> <artifactId>ds-sim</artifactId> - <version>1.0-SNAPSHOT</version> + <version>1.0.1-SNAPSHOT</version> <name>DS-Sim</name> <description>Distributed Systems Simulator - A modern Java-based simulator for distributed systems</description> @@ -92,6 +92,15 @@ </execution> </executions> </plugin> + + <plugin> + <groupId>org.codehaus.mojo</groupId> + <artifactId>exec-maven-plugin</artifactId> + <version>3.1.0</version> + <configuration> + <mainClass>simulator.VSMain</mainClass> + </configuration> + </plugin> </plugins> </build> diff --git a/sources/core/VSAbstractProcess.java b/sources/core/VSAbstractProcess.java deleted file mode 100644 index 78e7844..0000000 --- a/sources/core/VSAbstractProcess.java +++ /dev/null @@ -1,738 +0,0 @@ -package core; - -import java.awt.Color; -import java.io.IOException; -import java.io.ObjectInputStream; -import java.io.ObjectOutputStream; -import java.util.ArrayList; - -import core.time.VSLamportTime; -import core.time.VSTime; -import core.time.VSVectorTime; -import prefs.VSPrefs; -import prefs.VSSerializablePrefs; -import protocols.VSAbstractProtocol; -import serialize.VSSerialize; -import simulator.VSLogging; -import simulator.VSSimulatorVisualization; -import utils.VSPriorityQueue; -import utils.VSRandom; -import utils.VSTools; - -/** - * The class VSAbstractProcess, an object of this class represents a process - * of a simulator. - * - * @author Paul C. Buetow - */ -public abstract class VSAbstractProcess extends VSSerializablePrefs { - /** The data serialization id. */ - protected static final long serialVersionUID = 1L; - - /** The protocols to reset if the simulator is over or the reset - * button has been pressed. - */ - protected ArrayList<VSAbstractProtocol> protocolsToReset; - - /** The crash history. represents all crashes of the process using the - * global simulator time. - */ - protected ArrayList<Long> crashHistory; - - /** The lamport time history. */ - protected ArrayList<VSLamportTime> lamportTimeHistory; - - /** The vector time history. */ - protected ArrayList<VSVectorTime> vectorTimeHistory; - - /** The color used if the process has crashed. */ - protected Color crashedColor;; - - /** The process' current color. */ - protected Color currentColor; - - /** A temp. color. For internal usage. */ - protected Color tmpColor; - - /** The loging object. */ - protected VSLogging loging; - - /** The simulator's default prefs. */ - protected VSPrefs prefs; - - /** The random generator of the process. */ - protected VSRandom random; - - /** The simulator canvas. */ - protected VSSimulatorVisualization simulatorVisualization; - - /** The random crash task. May be null if there is no such random task. */ - protected VSTask randomCrashTask; - - /** The vector time. */ - protected VSVectorTime vectorTime; - - /** The tasks of the process. DO ONLY MANIPULATE THIS OBJECT WITHIN THE - * VSTaskManager CLASS! OTHERWISE THE SYNCHRONIZATION IS WRONG! Use the - * VSAbstractProcess.getTasks() method to get a reference to this object - * within the VSTaskManager! */ - protected VSPriorityQueue<VSTask> tasks; - - /** The process has crashed. But may be working again. */ - protected boolean hasCrashed; - - /** The process has started. But may be paused or crashed.. */ - protected boolean hasStarted; - - /** The process is crashed. */ - protected boolean isCrashed; - - /** The process is highlighted. */ - protected boolean isHighlighted; - - /** The process is paused. */ - protected boolean isPaused; - - /** The time has been modified in a task. Needed by the task manager to - * calculate correct offsets. - */ - protected boolean timeModified; - - /** The clock offset. Used by the task manager and also by the process' - * clock variance. - */ - protected double clockOffset; - - /** The clock variance. */ - protected float clockVariance; - - /** The process id. */ - protected int processID; - - /** The process num. It is different to the process id. It represents the - * array index of there the process is stored at. - */ - protected int processNum; - - /** The global time. */ - protected long globalTime; - - /** The lamport time. */ - protected long lamportTime; - - /** The local time. */ - protected long localTime; - - /** The Constant DEFAULT_INTEGER_VALUE_KEYS. - * This array contains all Integer prefs of the process which should show - * up in the prefs menu! All keys which dont start with "sim." only show - * up in the extended prefs menu! - */ - protected static final String DEFAULT_INTEGER_VALUE_KEYS[] = { - "process.prob.crash", - "message.prob.outage", - }; - - /** The Constant DEFAULT_LONG_VALUE_KEYS. - * This array contains all Long prefs of the process which should show - * up in the prefs menu! All keys which dont start with "sim." only show - * up in the extended prefs menu! - */ - protected static final String DEFAULT_LONG_VALUE_KEYS[] = { - "message.sendingtime.min", - "message.sendingtime.max", - }; - - /** The Constant DEFAULT_FLOAT_VALUE_KEYS. - * This array contains all Float prefs of the process which should show - * up in the prefs menu! All keys which dont start with "sim." only show - * up in the extended prefs menu! - */ - protected static final String DEFAULT_FLOAT_VALUE_KEYS[] = { - "process.clock.variance", - }; - - /** The Constant DEFAULT_COLOR_VALUE_KEYS. - * This array contains all Color prefs of the process which should show - * up in the prefs menu! All keys which dont start with "sim." only show - * up in the extended prefs menu! - */ - protected static final String DEFAULT_COLOR_VALUE_KEYS[] = { - "col.process.default", - "col.process.running", - "col.process.stopped", - "col.process.highlight", - "col.process.crashed", - }; - - /** The Constant DEFAULT_STRING_VALUE_KEYS. - * This array contains all String prefs of the process which should show - * up in the prefs menu! All keys which dont start with "sim." only show - * up in the extended prefs menu! - */ - protected static final String DEFAULT_STRING_VALUE_KEYS[] = { - }; - - /** - * Instantiates a new process. - *< |