leo/SD
1
0
Fork 0
mirror of https://github.com/davidalves04/Trabalho-Pratico-SD.git synced 2025-12-08 20:43:32 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #37 from davidalves04/javadoc

Browse Source 
Javadoc
This commit is contained in:
Leandro Afonso
2025-12-07 23:18:41 +00:00
committed by GitHub
parent 3a3756f701 926245986f
commit 542ce9c8c0
19 changed files with 1004 additions and 716 deletions
Download Patch File Download Diff File Expand all files Collapse all files

170
main/src/main/java/sd/ExitNodeProcess.java
View File

@@ -27,22 +27,23 @@ import sd.protocol.MessageProtocol;
import sd.protocol.SocketConnection; import sd.protocol.SocketConnection;
/** /**
* Destino final de todos os veículos da simulação (nó de saída S). * Ponto terminal da malha de simulação (Sink Node).
* * <p>
* <p>Opera como sumidouro da rede: * Este processo atua como o sumidouro da rede de filas. A sua função primária é
* <ol> * a <b>coleta de telemetria final</b>. Diferente das interseções, não encaminha veículos;
* <li>Recebe veículos que completaram a viagem * em vez disso, retira-os do sistema, calcula as métricas de latência "end-to-end"
* <li>Regista estatísticas finais (tempo total, espera, travessia) * (tempo no sistema, tempo de espera acumulado) e reporta ao Dashboard.
* <li>Envia métricas ao dashboard em tempo real * <p>
* </ol> * <b>Arquitetura de Concorrência:</b>
* * Utiliza um {@link ServerSocket} multithreaded para aceitar conexões simultâneas de
* <p>Participa no DES rastreando eventos, mas opera principalmente * qualquer interseção de fronteira (Cr1, Cr5, etc.) que envie veículos para fora da malha.
* de forma reativa, aguardando chegadas via socket.
*/ */
public class ExitNodeProcess { public class ExitNodeProcess {
private final SimulationConfig config; private final SimulationConfig config;
private ServerSocket serverSocket; private ServerSocket serverSocket;
/** Pool de threads elástica para tratamento de conexões de entrada. */
private final ExecutorService connectionHandlerPool; private final ExecutorService connectionHandlerPool;
// DES components // DES components
@@ -51,37 +52,37 @@ public class ExitNodeProcess {
private final EventLogger eventLogger; private final EventLogger eventLogger;
private Thread eventProcessorThread; private Thread eventProcessorThread;
/** Flag de controlo (volatile para visibilidade entre threads) */ /** Flag de controlo (volatile para visibilidade entre threads de I/O e lógica). */
private volatile boolean running; private volatile boolean running;
/** Instante de início da simulação (milissegundos) */ /** Instante de início da simulação (milissegundos) sincronizado com o Coordenador. */
private long simulationStartMillis; private long simulationStartMillis;
/** Contador de veículos que completaram a rota */ /** Contador atómico (via synchronized) de throughput total. */
private int totalVehiclesReceived; private int totalVehiclesReceived;
/** Tempo acumulado no sistema de todos os veículos */ /** Tempo acumulado no sistema (System Time) de todos os veículos. */
private double totalSystemTime; private double totalSystemTime;
/** Tempo acumulado em espera de todos os veículos */ /** Tempo acumulado em espera (Waiting Time) de todos os veículos. */
private double totalWaitingTime; private double totalWaitingTime;
/** Tempo acumulado em travessia de todos os veículos */ /** Tempo acumulado em travessia (Service Time) de todos os veículos. */
private double totalCrossingTime; private double totalCrossingTime;
/** Contagem de veículos por tipo */ /** Agregação por categoria de veículo. */
private final Map<VehicleType, Integer> vehicleTypeCount; private final Map<VehicleType, Integer> vehicleTypeCount;
/** Tempo de espera acumulado por tipo de veículo */ /** Latência acumulada por categoria. */
private final Map<VehicleType, Double> vehicleTypeWaitTime; private final Map<VehicleType, Double> vehicleTypeWaitTime;
/** Cliente socket para envio de estatísticas ao dashboard */ /** Cliente TCP persistente para push de métricas ao Dashboard. */
private SocketClient dashboardClient; private SocketClient dashboardClient;
/** /**
* Ponto de entrada do processo. * Bootstrap do processo ExitNode.
* * Carrega configuração, inicializa subsistemas e entra no loop de serviço.
* @param args args[0] (opcional) = caminho do ficheiro de configuração * * @param args Argumentos de CLI (caminho do config).
*/ */
public static void main(String[] args) { public static void main(String[] args) {
System.out.println("=".repeat(60)); System.out.println("=".repeat(60));
@@ -117,13 +118,9 @@ public class ExitNodeProcess {
} }
/** /**
* Configura o Nó de Saída. * Instancia o nó de saída.
* * Prepara os acumuladores estatísticos e a infraestrutura de logging distribuído.
* Inicializamos os nossos contadores, preparamos a pool de threads para tratar * * @param config A configuração global da simulação.
* das ligações de veículos recebidas,
* e configuramos os componentes DES para rastreio de eventos.
*
* @param config A configuração da simulação.
*/ */
public ExitNodeProcess(SimulationConfig config) { public ExitNodeProcess(SimulationConfig config) {
this.config = config; this.config = config;
@@ -157,9 +154,8 @@ public class ExitNodeProcess {
} }
/** /**
* Tenta estabelecer uma ligação ao dashboard. * Estabelece o canal de controlo (Control Plane) com o Dashboard.
* Se for bem-sucedido, poderemos enviar estatísticas em tempo real. Se não, * Essencial para a visualização em tempo real das métricas de saída.
* apenas registamos localmente.
*/ */
public void initialize() { public void initialize() {
System.out.println("Connecting to dashboard..."); System.out.println("Connecting to dashboard...");
@@ -179,10 +175,9 @@ public class ExitNodeProcess {
} }
/** /**
* Starts the DES event processing thread. * Inicia a thread de processamento de eventos DES.
* Currently, ExitNode is primarily reactive (receives vehicles via network), * Embora o ExitNode seja primariamente reativo (Network-driven), o motor DES
* but maintains event queue for potential scheduled events and history * é mantido para consistência de relógio e agendamento de fim de simulação.
* tracking.
*/ */
private void startEventProcessor() { private void startEventProcessor() {
eventProcessorThread = new Thread(() -> { eventProcessorThread = new Thread(() -> {
@@ -218,8 +213,8 @@ public class ExitNodeProcess {
} }
/** /**
* Processes a discrete event based on its type. * Dispatcher de eventos discretos.
* Currently supports VEHICLE_EXIT and SIMULATION_END events. * Trata eventos de fim de simulação. Chegadas de veículos são tratadas via Socket.
*/ */
private void processEvent(SimulationEvent event) { private void processEvent(SimulationEvent event) {
try { try {
@@ -244,7 +239,7 @@ public class ExitNodeProcess {
} }
/** /**
* Handles simulation end event. * Executa a lógica de encerramento desencadeada pelo evento DES.
*/ */
private void handleSimulationEndEvent(SimulationEvent event) { private void handleSimulationEndEvent(SimulationEvent event) {
eventLogger.log(EventType.SIMULATION_STOPPED, "ExitNode", eventLogger.log(EventType.SIMULATION_STOPPED, "ExitNode",
@@ -256,9 +251,8 @@ public class ExitNodeProcess {
} }
/** /**
* Exports the complete event history for the exit node. * Exporta o histórico completo de eventos para auditoria.
* This satisfies the spec requirement: "Deve ser possível verificar a lista * Requisito funcional para verificação de trace.
* completa de eventos"
*/ */
public void exportEventHistory(String outputPath) { public void exportEventHistory(String outputPath) {
String history = eventQueue.exportEventHistory(); String history = eventQueue.exportEventHistory();
@@ -271,9 +265,8 @@ public class ExitNodeProcess {
} }
/** /**
* Schedules a simulation end event at the specified time. * Agenda o fim determinístico da simulação.
* * * @param endTime Tempo virtual de paragem.
* @param endTime The simulation time when the simulation should end
*/ */
public void scheduleSimulationEnd(double endTime) { public void scheduleSimulationEnd(double endTime) {
SimulationEvent endEvent = new SimulationEvent( SimulationEvent endEvent = new SimulationEvent(
@@ -285,22 +278,16 @@ public class ExitNodeProcess {
} }
/** /**
* Abre o socket do servidor e começa a escutar por veículos. * Inicia o servidor TCP em modo de bloqueio (Blocking I/O).
* * @throws IOException Se ocorrer erro no bind da porta.
* Este é o loop principal. Aceitamos ligações das interseções (de onde vêm os
* veículos)
* e passamo-las para a nossa pool de threads para processamento.
*
* @throws IOException Se não conseguirmos fazer bind à porta.
*/ */
public void start() throws IOException { public void start() throws IOException {
start(true); // Default to DES mode start(true); // Default to DES mode
} }
/** /**
* Starts the exit node process. * Inicia o processo com opção de ativar o rastreio DES.
* * * @param useDES Se verdadeiro, ativa a thread do processador de eventos.
* @param useDES If true, starts event processor for DES mode tracking
*/ */
public void start(boolean useDES) throws IOException { public void start(boolean useDES) throws IOException {
int port = config.getExitPort(); int port = config.getExitPort();
@@ -310,15 +297,15 @@ public class ExitNodeProcess {
System.out.println("Exit node started on port " + port); System.out.println("Exit node started on port " + port);
if (useDES) { if (useDES) {
// Note: ExitNode is primarily reactive (network-driven), but maintains
// event queue for simulation end events and history tracking
System.out.println("Running in DES mode (event history tracking enabled)"); System.out.println("Running in DES mode (event history tracking enabled)");
} }
System.out.println("Waiting for vehicles...\\n"); System.out.println("Waiting for vehicles...\\n");
// Loop de aceitação principal
while (running) { while (running) {
try { try {
Socket clientSocket = serverSocket.accept(); Socket clientSocket = serverSocket.accept();
// Delega o processamento da conexão para o Thread Pool
connectionHandlerPool.submit(() -> handleIncomingConnection(clientSocket)); connectionHandlerPool.submit(() -> handleIncomingConnection(clientSocket));
} catch (IOException e) { } catch (IOException e) {
if (running) { if (running) {
@@ -329,12 +316,11 @@ public class ExitNodeProcess {
} }
/** /**
* Trata uma ligação de uma interseção. * Worker method para tratar uma conexão persistente vinda de uma interseção.
* * <p>
* Mantemos a ligação aberta e escutamos por mensagens `VEHICLE_TRANSFER`. * Mantém o socket aberto e consome mensagens num loop até que a conexão seja fechada
* Cada mensagem contém um veículo que acabou de terminar a sua viagem. * pelo remetente. Responsável pela desserialização polimórfica (JSON/Gson).
* * * @param clientSocket O socket conectado.
* @param clientSocket O socket ligado à interseção.
*/ */
private void handleIncomingConnection(Socket clientSocket) { private void handleIncomingConnection(Socket clientSocket) {
String clientAddress = clientSocket.getInetAddress().getHostAddress(); String clientAddress = clientSocket.getInetAddress().getHostAddress();
@@ -350,14 +336,14 @@ public class ExitNodeProcess {
" from " + message.getSourceNode()); " from " + message.getSourceNode());
if (message.getType() == MessageType.SIMULATION_START) { if (message.getType() == MessageType.SIMULATION_START) {
// Coordinator sends start time - use it instead of our local start // Sincronização de relógio com o Coordenador
simulationStartMillis = ((Number) message.getPayload()).longValue(); simulationStartMillis = ((Number) message.getPayload()).longValue();
System.out.println("[Exit] Simulation start time synchronized"); System.out.println("[Exit] Simulation start time synchronized");
} else if (message.getType() == MessageType.VEHICLE_TRANSFER) { } else if (message.getType() == MessageType.VEHICLE_TRANSFER) {
Object payload = message.getPayload(); Object payload = message.getPayload();
System.out.println("[Exit] Payload type: " + payload.getClass().getName()); System.out.println("[Exit] Payload type: " + payload.getClass().getName());
// Handle Gson LinkedHashMap // Tratamento de artefatos de desserialização do Gson (LinkedTreeMap -> POJO)
Vehicle vehicle; Vehicle vehicle;
if (payload instanceof com.google.gson.internal.LinkedTreeMap || if (payload instanceof com.google.gson.internal.LinkedTreeMap ||
payload instanceof java.util.LinkedHashMap) { payload instanceof java.util.LinkedHashMap) {
@@ -390,26 +376,21 @@ public class ExitNodeProcess {
} }
/** /**
* Processa um veículo que acabou de sair do sistema. * Processa atomicamente a saída de um veículo.
* * <p>
* Calculamos quanto tempo demorou, atualizamos as nossas estatísticas globais e * <b>Secção Crítica:</b> Método {@code synchronized} para garantir que a atualização
* notificamos o dashboard. * das estatísticas globais (totalSystemTime, contadores) é atómica, prevenindo
* Este método é sincronizado porque múltiplos veículos podem chegar ao mesmo * Race Conditions quando múltiplos veículos chegam simultaneamente de interseções diferentes.
* tempo. * * @param vehicle O veículo que completou a rota.
*
* @param vehicle O veículo que completou a sua rota.
*/ */
private synchronized void processExitingVehicle(Vehicle vehicle) { private synchronized void processExitingVehicle(Vehicle vehicle) {
totalVehiclesReceived++; totalVehiclesReceived++;
// Use simulation time instead of wall-clock time // Cálculo de métricas finais baseadas no tempo virtual de simulação acumulado no veículo
// System time = total time vehicle spent in system (wait + crossing times)
// This represents the actual simulation time elapsed, not real-time
double waitTime = vehicle.getTotalWaitingTime(); double waitTime = vehicle.getTotalWaitingTime();
double crossingTime = vehicle.getTotalCrossingTime(); double crossingTime = vehicle.getTotalCrossingTime();
double systemTime = waitTime + crossingTime; double systemTime = waitTime + crossingTime;
// Store times in seconds, will be converted to ms when sending to dashboard
totalSystemTime += systemTime; totalSystemTime += systemTime;
totalWaitingTime += waitTime; totalWaitingTime += waitTime;
totalCrossingTime += crossingTime; totalCrossingTime += crossingTime;
@@ -421,23 +402,20 @@ public class ExitNodeProcess {
System.out.printf("[Exit] Vehicle %s completed (type=%s, system_time=%.2fs, wait=%.2fs, crossing=%.2fs)%n", System.out.printf("[Exit] Vehicle %s completed (type=%s, system_time=%.2fs, wait=%.2fs, crossing=%.2fs)%n",
vehicle.getId(), vehicle.getType(), systemTime, waitTime, crossingTime); vehicle.getId(), vehicle.getType(), systemTime, waitTime, crossingTime);
// Log vehicle exit // Logging estruturado
EventLogger.getInstance().logVehicle(EventType.VEHICLE_EXITED, "ExitNode", vehicle.getId(), EventLogger.getInstance().logVehicle(EventType.VEHICLE_EXITED, "ExitNode", vehicle.getId(),
String.format("Completed - System: %.2fs, Wait: %.2fs, Crossing: %.2fs", systemTime, waitTime, String.format("Completed - System: %.2fs, Wait: %.2fs, Crossing: %.2fs", systemTime, waitTime,
crossingTime)); crossingTime));
// Complete vehicle trace if tracking // Finaliza o trace individual do veículo
VehicleTracer.getInstance().logExit(vehicle, systemTime); VehicleTracer.getInstance().logExit(vehicle, systemTime);
// Send stats after every vehicle to ensure dashboard updates quickly // Push imediato para o Dashboard para visualização em tempo real
sendStatsToDashboard(); sendStatsToDashboard();
} }
/** /**
* Envia as estatísticas mais recentes para o dashboard. * Constrói e transmite o DTO de atualização de estatísticas.
*
* Empacotamos as contagens totais e os tempos médios num `StatsUpdatePayload`
* e enviamo-lo.
*/ */
private void sendStatsToDashboard() { private void sendStatsToDashboard() {
if (dashboardClient == null || !dashboardClient.isConnected()) { if (dashboardClient == null || !dashboardClient.isConnected()) {
@@ -448,29 +426,28 @@ public class ExitNodeProcess {
// Create stats payload // Create stats payload
StatsUpdatePayload payload = new StatsUpdatePayload(); StatsUpdatePayload payload = new StatsUpdatePayload();
// Set global stats - convert seconds to milliseconds // Set global stats - convert seconds to milliseconds for display consistency
payload.setTotalVehiclesCompleted(totalVehiclesReceived); payload.setTotalVehiclesCompleted(totalVehiclesReceived);
payload.setTotalSystemTime((long) (totalSystemTime * 1000.0)); // s -> ms payload.setTotalSystemTime((long) (totalSystemTime * 1000.0));
payload.setTotalWaitingTime((long) (totalWaitingTime * 1000.0)); // s -> ms payload.setTotalWaitingTime((long) (totalWaitingTime * 1000.0));
// Set intersection-like stats so it shows up correctly in the dashboard table // Hack: Usar campos de interseção para mostrar throughput no dashboard
payload.setIntersectionArrivals(totalVehiclesReceived); payload.setIntersectionArrivals(totalVehiclesReceived);
payload.setIntersectionDepartures(totalVehiclesReceived); payload.setIntersectionDepartures(totalVehiclesReceived);
payload.setIntersectionQueueSize(0); payload.setIntersectionQueueSize(0);
// Set vehicle type stats // Detailed breakdown
Map<VehicleType, Integer> typeCounts = new HashMap<>(); Map<VehicleType, Integer> typeCounts = new HashMap<>();
Map<VehicleType, Long> typeWaitTimes = new HashMap<>(); Map<VehicleType, Long> typeWaitTimes = new HashMap<>();
for (VehicleType type : VehicleType.values()) { for (VehicleType type : VehicleType.values()) {
typeCounts.put(type, vehicleTypeCount.get(type)); typeCounts.put(type, vehicleTypeCount.get(type));
typeWaitTimes.put(type, (long) (vehicleTypeWaitTime.get(type) * 1000.0)); // s -> ms typeWaitTimes.put(type, (long) (vehicleTypeWaitTime.get(type) * 1000.0));
} }
payload.setVehicleTypeCounts(typeCounts); payload.setVehicleTypeCounts(typeCounts);
payload.setVehicleTypeWaitTimes(typeWaitTimes); payload.setVehicleTypeWaitTimes(typeWaitTimes);
// Send message
Message message = new Message( Message message = new Message(
MessageType.STATS_UPDATE, MessageType.STATS_UPDATE,
"ExitNode", "ExitNode",
@@ -489,9 +466,8 @@ public class ExitNodeProcess {
} }
/** /**
* Encerra graciosamente o processo. * Encerramento gracioso do processo.
* * Fecha sockets, termina a pool de threads e liberta recursos.
* Imprimimos as estatísticas finais, fechamos ligações e limpamos threads.
*/ */
public void shutdown() { public void shutdown() {
System.out.println("\n[Exit] Shutting down..."); System.out.println("\n[Exit] Shutting down...");
@@ -527,9 +503,7 @@ public class ExitNodeProcess {
} }
/** /**
* Imprime um resumo dos resultados da simulação na consola. * Imprime o relatório final no stdout.
* Isto dá-nos uma visão rápida de como a simulação correu (médias, contagens de
* veículos, etc.).
*/ */
private void printFinalStatistics() { private void printFinalStatistics() {
System.out.println("\n=== EXIT NODE STATISTICS ==="); System.out.println("\n=== EXIT NODE STATISTICS ===");

407
main/src/main/java/sd/IntersectionProcess.java
View File

@@ -33,19 +33,22 @@ import sd.protocol.SocketConnection;
import sd.serialization.SerializationException; import sd.serialization.SerializationException;
/** /**
* Representa uma única interseção na nossa simulação de tráfego distribuída. * Representa um nó de processamento autónomo na malha de simulação distribuída
* * (Worker Node).
* Esta classe opera como um processo independente (uma aplicação Java autónoma) * <p>
* e é responsável por: * Esta classe implementa a lógica de uma interseção rodoviária utilizando uma
* 1. Gerir os semáforos e a sua temporização. * arquitetura híbrida:
* 2. Processar as chegadas e partidas de veículos. * <ol>
* 3. Comunicar com outras interseções e com o dashboard. * <li><b>Reativa (Network I/O):</b> Threads dedicadas aceitam conexões TCP e
* * injetam veículos nas filas de entrada assim que chegam.</li>
* Utiliza uma abordagem de Simulação de Eventos Discretos (DES), onde as * <li><b>Proativa (DES Engine):</b> Uma thread de processamento de eventos gere
* mudanças de estado (como semáforos a mudar para verde) * a lógica temporal (mudança de semáforos, tempos de travessia) baseada num
* são agendadas como eventos numa fila de prioridade, em vez de depender de * relógio virtual monotónico.</li>
* loops contínuos ou threads em espera. * </ol>
* Isto garante uma temporização precisa e uma execução eficiente. * <p>
* A sincronização entre a chegada assíncrona de veículos (Rede) e o
* processamento determinístico (DES) é gerida através de estruturas de dados
* concorrentes e bloqueios justos (Fair Locks).
*/ */
public class IntersectionProcess { public class IntersectionProcess {
@@ -57,48 +60,56 @@ public class IntersectionProcess {
private ServerSocket serverSocket; private ServerSocket serverSocket;
/**
* Tabela de encaminhamento dinâmico para conexões de saída (Next-Hop Cache).
*/
private final Map<String, SocketConnection> outgoingConnections; private final Map<String, SocketConnection> outgoingConnections;
/** Pool de threads para tratamento de I/O de rede (entrada de veículos). */
private final ExecutorService connectionHandlerPool; private final ExecutorService connectionHandlerPool;
private ScheduledExecutorService statsExecutor; private ScheduledExecutorService statsExecutor;
private ScheduledExecutorService departureExecutor; private ScheduledExecutorService departureExecutor;
private volatile boolean running; private volatile boolean running;
/** Escala temporal para visualização: tempo_real = tempo_simulado * escala */ /** Fator de dilatação temporal (0.0 = Velocidade Máxima, 1.0 = Tempo Real). */
private double timeScale; private double timeScale;
/** Relógio central da simulação */ // --- Componentes DES (Simulação de Eventos Discretos) ---
/** Relógio central virtual da interseção. */
private final SimulationClock clock; private final SimulationClock clock;
/** Fila de eventos discretos agendados */ /** Fila de prioridade (Min-Heap) para agendamento temporal de eventos. */
private final EventQueue eventQueue; private final EventQueue eventQueue;
/** Sistema de registo de eventos */
private final EventLogger eventLogger; private final EventLogger eventLogger;
/** Thread dedicada ao processamento sequencial de eventos DES */ /** Thread "Single-Writer" responsável pela mutação de estado da simulação. */
private Thread eventProcessorThread; private Thread eventProcessorThread;
/** /**
* Lock para exclusão mútua entre semáforos. * Mecanismo de exclusão mútua para controlo de fases semafóricas.
* Garante que apenas um semáforo pode estar verde de cada vez nesta interseção. * Configurado com política de justiça (fairness=true) para evitar inanição
* (starvation) de direções com menos tráfego.
*/ */
private final Lock trafficCoordinationLock; private final Lock trafficCoordinationLock;
/** /**
* Regista qual direção tem atualmente o sinal verde. * Estado volátil que indica a direção ativa. Apenas uma direção pode deter o
* {@code null} significa que todos os semáforos estão vermelhos. * token 'Green' por vez.
*/ */
private volatile String currentGreenDirection; private volatile String currentGreenDirection;
private SocketClient dashboardClient; private SocketClient dashboardClient;
// Métricas voláteis para acesso atómico sem bloqueio
private volatile int totalArrivals = 0; private volatile int totalArrivals = 0;
private volatile int totalDepartures = 0; private volatile int totalDepartures = 0;
/** /**
* Inicializa o processo da interseção. * Inicializa o processo da interseção, carregando a topologia e preparando o
* motor DES.
* *
* @param intersectionId O identificador único para esta interseção (ex: "Cr1"). * @param intersectionId O identificador único na malha (ex: "Cr1").
* @param configFilePath O caminho para o ficheiro de configuração. * @param configFilePath Caminho para o ficheiro de propriedades.
* @throws IOException Se houver algum problema ao ler a configuração. * @throws IOException Se falhar o bind da porta ou leitura de config.
*/ */
public IntersectionProcess(String intersectionId, String configFilePath) throws IOException { public IntersectionProcess(String intersectionId, String configFilePath) throws IOException {
this.intersectionId = intersectionId; this.intersectionId = intersectionId;
@@ -127,13 +138,16 @@ public class IntersectionProcess {
} }
/** /**
* Inicia o ciclo de processamento de eventos. * Inicia o ciclo principal do motor de simulação (DES Engine Loop).
* * <p>
* Esta thread é o coração do modelo DES para esta interseção. Retira eventos da * Executa o ciclo "Fetch-Decode-Execute":
* fila * <ol>
* e executa-os por ordem cronológica. Enquanto a thread principal trata das * <li>Remove o evento com menor timestamp da fila (Fetch).</li>
* operações de I/O de rede (receção de veículos), * <li>Avança o relógio virtual para o tempo do evento.</li>
* esta thread trata da lógica da simulação (semáforos, travessias de veículos). * <li>Aplica atraso artificial se {@code timeScale > 0} (para visualização
* humana).</li>
* <li>Despacha o evento para o manipulador apropriado (Execute).</li>
* </ol>
*/ */
private void startEventProcessor() { private void startEventProcessor() {
eventProcessorThread = new Thread(() -> { eventProcessorThread = new Thread(() -> {
@@ -145,9 +159,9 @@ public class IntersectionProcess {
while (running) { while (running) {
SimulationEvent event = eventQueue.poll(); SimulationEvent event = eventQueue.poll();
if (event == null) { if (event == null) {
// No events currently, wait a bit before checking again // Backoff exponencial ou sleep curto para evitar busy-waiting em idle
try { try {
Thread.sleep(50); // Short sleep to avoid busy-waiting Thread.sleep(50);
} catch (InterruptedException e) { } catch (InterruptedException e) {
Thread.currentThread().interrupt(); Thread.currentThread().interrupt();
break; break;
@@ -155,7 +169,7 @@ public class IntersectionProcess {
continue; continue;
} }
// Apply time scaling for visualization // Aplicação de escala temporal (Throttle)
if (timeScale > 0) { if (timeScale > 0) {
double simTimeDelta = event.getTimestamp() - lastTime; double simTimeDelta = event.getTimestamp() - lastTime;
long realDelayMs = (long) (simTimeDelta * timeScale * 1000); long realDelayMs = (long) (simTimeDelta * timeScale * 1000);
@@ -170,10 +184,10 @@ public class IntersectionProcess {
lastTime = event.getTimestamp(); lastTime = event.getTimestamp();
} }
// Advance clock to event time // Atualização atómica do tempo de simulação
clock.advanceTo(event.getTimestamp()); clock.advanceTo(event.getTimestamp());
// Process the event // Processamento polimórfico
processEvent(event); processEvent(event);
} }
@@ -185,10 +199,12 @@ public class IntersectionProcess {
} }
/** /**
* Processa um evento da fila de simulação. * Despachante central de eventos.
* Cada tipo de evento é encaminhado para o seu tratador específico. * <p>
* Encaminha o evento para a lógica de negócio específica baseada no tipo
* {@link DESEventType}.
* *
* @param event o evento a processar * @param event O evento de simulação a ser processado.
*/ */
private void processEvent(SimulationEvent event) { private void processEvent(SimulationEvent event) {
try { try {
@@ -198,8 +214,8 @@ public class IntersectionProcess {
break; break;
case VEHICLE_ARRIVAL: case VEHICLE_ARRIVAL:
// Vehicle arrivals are still handled via network messages // Chegadas são tratadas reativamente via Socket, mas eventos podem ser usados
// This event type is for internal scheduling if needed // para métricas
break; break;
case VEHICLE_CROSSING_START: case VEHICLE_CROSSING_START:
@@ -225,12 +241,18 @@ public class IntersectionProcess {
} }
/** /**
* Trata da mudança dos semáforos. * Gere a máquina de estados dos semáforos.
* <p>
* O fluxo de execução é o seguinte:
* <ol>
* <li>Atualiza o estado do semáforo (Verde <-> Vermelho).</li>
* <li>Se o novo estado for Verde: Calcula a capacidade de vazão e agenda
* travessias (Service Events).</li>
* <li>Agenda recursivamente a próxima mudança de estado para manter o ciclo
* infinito.</li>
* </ol>
* *
* Quando um semáforo muda de estado, registamos o evento, atualizamos o modelo * @param event O evento que desencadeou a mudança de estado.
* e, se tiver mudado para VERDE,
* verificamos imediatamente se há veículos à espera para atravessar.
* Também agendamos aqui o *próximo* evento de mudança, mantendo o ciclo ativo.
*/ */
private void handleTrafficLightChangeEvent(SimulationEvent event) { private void handleTrafficLightChangeEvent(SimulationEvent event) {
TrafficLightEvent tlEvent = (TrafficLightEvent) event.getPayload(); TrafficLightEvent tlEvent = (TrafficLightEvent) event.getPayload();
@@ -252,12 +274,12 @@ public class IntersectionProcess {
String.format("Direction %s changed to %s at time %.2f", String.format("Direction %s changed to %s at time %.2f",
direction, newState, event.getTimestamp())); direction, newState, event.getTimestamp()));
// If light turned GREEN, process queued vehicles // Processamento de lote (Batch Processing) para a fase Verde
if (newState == TrafficLightState.GREEN) { if (newState == TrafficLightState.GREEN) {
processQueuedVehiclesForLight(light, event.getTimestamp()); processQueuedVehiclesForLight(light, event.getTimestamp());
} }
// Schedule next state change // Agendamento do próximo ciclo (Feedback Loop)
double nextChangeTime = event.getTimestamp() + double nextChangeTime = event.getTimestamp() +
(newState == TrafficLightState.GREEN ? light.getGreenTime() : light.getRedTime()); (newState == TrafficLightState.GREEN ? light.getGreenTime() : light.getRedTime());
@@ -269,23 +291,19 @@ public class IntersectionProcess {
} }
/** /**
* Processa a fila de veículos quando um semáforo fica verde. * Calcula a vazão da interseção durante uma fase verde.
*
* <p> * <p>
* Para cada veículo na fila: * Implementa uma lógica de previsão ("Look-ahead"):
* </p>
* <ol> * <ol>
* <li>Calcula o tempo de travessia com base no tipo de veículo</li> * <li>Itera sobre a fila de espera do semáforo.</li>
* <li>Verifica se cabe na duração restante do sinal verde</li> * <li>Calcula o tempo de serviço acumulado (Service Time) baseado no tipo de
* <li>Agenda o evento de partida do veículo</li> * veículo.</li>
* <li>Agenda a partida apenas se o veículo couber na janela temporal restante
* do sinal verde.</li>
* </ol> * </ol>
* *
* <p> * @param light O semáforo ativo.
* Os veículos que não couberem no tempo verde ficam à espera do próximo ciclo. * @param currentTime O instante de início da fase verde.
* </p>
*
* @param light o semáforo que acabou de ficar verde
* @param currentTime o tempo atual da simulação em segundos
*/ */
private void processQueuedVehiclesForLight(TrafficLight light, double currentTime) { private void processQueuedVehiclesForLight(TrafficLight light, double currentTime) {
double greenDuration = light.getGreenTime(); double greenDuration = light.getGreenTime();
@@ -295,30 +313,29 @@ public class IntersectionProcess {
System.out.printf("[%s] Processing queue for %s (GREEN for %.2fs, queue size: %d, currentTime=%.2f)%n", System.out.printf("[%s] Processing queue for %s (GREEN for %.2fs, queue size: %d, currentTime=%.2f)%n",
intersectionId, light.getId(), greenDuration, queueSize, currentTime); intersectionId, light.getId(), greenDuration, queueSize, currentTime);
// Process vehicles while queue not empty and within green light duration // Algoritmo de esvaziamento de fila baseado em Time Budget
while (light.getQueueSize() > 0) { while (light.getQueueSize() > 0) {
// Calculate crossing time for next vehicle (peek at queue size to estimate) // Estimativa inicial (optimista)
// We'll use LIGHT vehicle as default for estimation
double crossingTime = config.getLightVehicleCrossingTime(); double crossingTime = config.getLightVehicleCrossingTime();
// Check if another vehicle can fit in remaining green time // Verificação de limite de tempo (Hard Deadline do sinal vermelho)
if (timeOffset + crossingTime > greenDuration) { if (timeOffset + crossingTime > greenDuration) {
break; // No more vehicles can cross this green phase break; // Veículo não cabe no ciclo atual
} }
// Remove vehicle from queue with current simulation time // Commit: Remove da fila
Vehicle vehicle = light.removeVehicle(currentTime + timeOffset); Vehicle vehicle = light.removeVehicle(currentTime + timeOffset);
if (vehicle == null) if (vehicle == null)
break; break;
// Get actual crossing time for this vehicle // Recálculo preciso baseado no tipo real do veículo
crossingTime = getCrossingTimeForVehicle(vehicle); crossingTime = getCrossingTimeForVehicle(vehicle);
// Schedule crossing // Agendamento do evento futuro de término de travessia
double crossingStartTime = currentTime + timeOffset; double crossingStartTime = currentTime + timeOffset;
scheduleVehicleCrossing(vehicle, crossingStartTime, crossingTime); scheduleVehicleCrossing(vehicle, crossingStartTime, crossingTime);
// Update offset for next vehicle // Incrementa offset para serializar as travessias (Head-of-Line Blocking)
timeOffset += crossingTime; timeOffset += crossingTime;
System.out.printf("[%s] Scheduled vehicle %s to cross at t=%.2f (duration=%.2fs)%n", System.out.printf("[%s] Scheduled vehicle %s to cross at t=%.2f (duration=%.2fs)%n",
@@ -327,12 +344,11 @@ public class IntersectionProcess {
} }
/** /**
* Agenda a travessia e partida de um veículo. * Cria e agenda o evento de conclusão de travessia (Partida).
* Cria um evento de fim de travessia agendado para o tempo correto.
* *
* @param vehicle o veículo que vai atravessar * @param vehicle O veículo que está a atravessar.
* @param startTime quando a travessia começa (segundos de simulação) * @param startTime Instante de início da travessia.
* @param crossingDuration quanto tempo demora a atravessar (segundos) * @param crossingDuration Duração estimada da travessia.
*/ */
private void scheduleVehicleCrossing(Vehicle vehicle, double startTime, double crossingDuration) { private void scheduleVehicleCrossing(Vehicle vehicle, double startTime, double crossingDuration) {
// Schedule crossing end (when vehicle departs) // Schedule crossing end (when vehicle departs)
@@ -351,11 +367,10 @@ public class IntersectionProcess {
} }
/** /**
* Calcula o tempo de travessia com base no tipo de veículo. * Determina o custo temporal da travessia baseado na física do veículo.
* Bicicletas são mais rápidas, veículos pesados mais lentos.
* *
* @param vehicle o veículo para calcular o tempo * @param vehicle O veículo em questão.
* @return tempo de travessia em segundos * @return O tempo em segundos necessário para atravessar a interseção.
*/ */
private double getCrossingTimeForVehicle(Vehicle vehicle) { private double getCrossingTimeForVehicle(Vehicle vehicle) {
return switch (vehicle.getType()) { return switch (vehicle.getType()) {
@@ -367,36 +382,45 @@ public class IntersectionProcess {
} }
/** /**
* Trata o evento de início de travessia de um veículo. * Manipula o evento de início de travessia de um veículo.
* (Implementação futura - atualmente apenas regista o evento) * <p>
* Atualmente serve como placeholder para lógica futura de animação ou
* ocupação de zonas críticas na interseção.
* *
* @param event o evento de início de travessia * @param event O evento de início de travessia.
*/ */
private void handleVehicleCrossingStartEvent(SimulationEvent event) { private void handleVehicleCrossingStartEvent(SimulationEvent event) {
// Implementation will depend on how vehicle crossing is modeled // Placeholder para lógica futura de animação ou ocupação de zona crítica
// For now, log the event
eventLogger.log(sd.logging.EventType.VEHICLE_DEPARTED, intersectionId, eventLogger.log(sd.logging.EventType.VEHICLE_DEPARTED, intersectionId,
"Vehicle crossing started at time " + event.getTimestamp()); "Vehicle crossing started at time " + event.getTimestamp());
} }
/** /**
* Trata o fim da travessia de um veículo pela interseção. * Finaliza a lógica de travessia e inicia a transferência (handover) para o
* Atualiza estatísticas, regista o tempo de travessia e envia o veículo * próximo nó.
* para o próximo destino na sua rota. * <p>
* Este método é invocado quando o tempo de travessia expira no relógio virtual.
* Executa as seguintes ações:
* <ol>
* <li>Atualiza as métricas de tempo de travessia do veículo.</li>
* <li>Incrementa contadores locais de veículos processados.</li>
* <li>Transfere a responsabilidade do veículo para a rede, enviando-o ao
* próximo destino.</li>
* </ol>
* *
* @param event evento contendo o veículo que terminou a travessia * @param event O evento de fim de travessia.
*/ */
private void handleVehicleCrossingEndEvent(SimulationEvent event) { private void handleVehicleCrossingEndEvent(SimulationEvent event) {
Vehicle vehicle = (Vehicle) event.getPayload(); Vehicle vehicle = (Vehicle) event.getPayload();
// Add crossing time to vehicle stats // Atualiza métricas do veículo
double crossingTime = getCrossingTimeForVehicle(vehicle); double crossingTime = getCrossingTimeForVehicle(vehicle);
vehicle.addCrossingTime(crossingTime); vehicle.addCrossingTime(crossingTime);
// Update intersection statistics // Atualiza métricas locais
intersection.incrementVehiclesSent(); intersection.incrementVehiclesSent();
// Send vehicle to next destination // Handover: Transfere a responsabilidade do veículo para a rede
sendVehicleToNextDestination(vehicle); sendVehicleToNextDestination(vehicle);
eventLogger.log(sd.logging.EventType.VEHICLE_DEPARTED, intersectionId, eventLogger.log(sd.logging.EventType.VEHICLE_DEPARTED, intersectionId,
@@ -404,10 +428,9 @@ public class IntersectionProcess {
} }
/** /**
* Trata o evento de fim da simulação. * Finaliza a execução do processo de simulação.
* Define a flag de execução como falsa para terminar o processamento.
* *
* @param event o evento de fim de simulação * @param event O evento de fim de simulação.
*/ */
private void handleSimulationEndEvent(SimulationEvent event) { private void handleSimulationEndEvent(SimulationEvent event) {
eventLogger.log(sd.logging.EventType.SIMULATION_STOPPED, intersectionId, eventLogger.log(sd.logging.EventType.SIMULATION_STOPPED, intersectionId,
@@ -416,10 +439,9 @@ public class IntersectionProcess {
} }
/** /**
* Exporta o histórico completo de eventos para um ficheiro. * Exporta o histórico completo de eventos para análise post-mortem.
* Útil para análise posterior e debugging da simulação.
* *
* @param outputPath caminho do ficheiro onde guardar o histórico * @param outputPath O caminho do ficheiro onde o histórico será guardado.
*/ */
public void exportEventHistory(String outputPath) { public void exportEventHistory(String outputPath) {
String history = eventQueue.exportEventHistory(); String history = eventQueue.exportEventHistory();
@@ -431,7 +453,12 @@ public class IntersectionProcess {
} }
} }
// Main entry point for running an intersection process /**
* Ponto de entrada principal da aplicação.
*
* @param args Argumentos da linha de comando (ID da interseção e ficheiro de
* configuração opcional).
*/
public static void main(String[] args) { public static void main(String[] args) {
if (args.length < 1) { if (args.length < 1) {
System.err.println("Usage: java IntersectionProcess <intersectionId> [configFile]"); System.err.println("Usage: java IntersectionProcess <intersectionId> [configFile]");
@@ -460,6 +487,12 @@ public class IntersectionProcess {
} }
} }
/**
* Realiza o bootstrap dos componentes lógicos e de rede da interseção.
* <p>
* Inclui a criação de semáforos, configuração de encaminhamento e conexão ao
* Dashboard.
*/
public void initialize() { public void initialize() {
System.out.println("\n[" + intersectionId + "] Initializing intersection..."); System.out.println("\n[" + intersectionId + "] Initializing intersection...");
@@ -473,7 +506,7 @@ public class IntersectionProcess {
} }
/** /**
* Estabelece ligação ao servidor do dashboard para reportar estatísticas. * Estabelece a conexão com o Dashboard para envio de telemetria em tempo real.
*/ */
private void connectToDashboard() { private void connectToDashboard() {
try { try {
@@ -497,9 +530,7 @@ public class IntersectionProcess {
} }
/** /**
* Cria os semáforos para esta interseção com base nas suas ligações físicas. * Inicializa os semáforos da interseção com base na configuração carregada.
* Cada interseção tem um número e direções de semáforos diferentes de acordo
* com a topologia da rede.
*/ */
private void createTrafficLights() { private void createTrafficLights() {
System.out.println("\n[" + intersectionId + "] Creating traffic lights..."); System.out.println("\n[" + intersectionId + "] Creating traffic lights...");
@@ -528,6 +559,13 @@ public class IntersectionProcess {
} }
} }
/**
* Obtém a configuração específica para esta interseção a partir da configuração
* global.
*
* @return O objeto de configuração da interseção.
* @throws RuntimeException Se a configuração estiver em falta.
*/
private SimulationConfig.IntersectionConfig getIntersectionConfig() { private SimulationConfig.IntersectionConfig getIntersectionConfig() {
if (config.getNetworkConfig() == null || config.getNetworkConfig().getIntersections() == null) { if (config.getNetworkConfig() == null || config.getNetworkConfig().getIntersections() == null) {
throw new RuntimeException("Network configuration not loaded or empty."); throw new RuntimeException("Network configuration not loaded or empty.");
@@ -538,6 +576,11 @@ public class IntersectionProcess {
.orElseThrow(() -> new RuntimeException("Intersection config not found for " + intersectionId)); .orElseThrow(() -> new RuntimeException("Intersection config not found for " + intersectionId));
} }
/**
* Configura a tabela de encaminhamento (routing) da interseção.
* <p>
* Define para cada destino qual a direção de saída (semáforo) correspondente.
*/
private void configureRouting() { private void configureRouting() {
System.out.println("\n[" + intersectionId + "] Configuring routing..."); System.out.println("\n[" + intersectionId + "] Configuring routing...");
@@ -559,11 +602,10 @@ public class IntersectionProcess {
} }
/** /**
* Solicita permissão para um semáforo ficar verde. * Primitiva de bloqueio: Solicita acesso exclusivo à zona crítica da
* Bloqueia até que a permissão seja concedida (nenhum outro semáforo está * interseção.
* verde).
* *
* @param direction A direção que solicita o sinal verde * @param direction A direção que solicita passagem.
*/ */
public void requestGreenLight(String direction) { public void requestGreenLight(String direction) {
trafficCoordinationLock.lock(); trafficCoordinationLock.lock();
@@ -571,10 +613,9 @@ public class IntersectionProcess {
} }
/** /**
* Liberta a permissão de sinal verde, permitindo que outro semáforo fique * Primitiva de bloqueio: Liberta o acesso exclusivo à zona crítica.
* verde.
* *
* @param direction A direção que liberta o sinal verde * @param direction A direção que está a libertar a passagem.
*/ */
public void releaseGreenLight(String direction) { public void releaseGreenLight(String direction) {
if (direction.equals(currentGreenDirection)) { if (direction.equals(currentGreenDirection)) {
@@ -584,8 +625,10 @@ public class IntersectionProcess {
} }
/** /**
* Modo DES: Agenda os eventos iniciais de mudança de semáforo. * Inicializa o estado dos semáforos no arranque da simulação (t=0).
* Isto substitui a antiga abordagem baseada em threads startTrafficLights(). * <p>
* Garante que apenas um semáforo começa em Verde e os restantes em Vermelho,
* agendando os eventos iniciais na fila do DES.
*/ */
private void scheduleInitialTrafficLightEvents() { private void scheduleInitialTrafficLightEvents() {
System.out.println("\n[" + intersectionId + "] Scheduling initial traffic light events (DES mode)..."); System.out.println("\n[" + intersectionId + "] Scheduling initial traffic light events (DES mode)...");
@@ -596,12 +639,12 @@ public class IntersectionProcess {
for (TrafficLight light : intersection.getTrafficLights()) { for (TrafficLight light : intersection.getTrafficLights()) {
String direction = light.getDirection(); String direction = light.getDirection();
// Set initial state (first light starts green, others red) // Lógica de arranque: Primeiro da lista = Verde, outros = Vermelho
boolean isFirstLight = intersection.getTrafficLights().indexOf(light) == 0; boolean isFirstLight = intersection.getTrafficLights().indexOf(light) == 0;
TrafficLightState initialState = isFirstLight ? TrafficLightState.GREEN : TrafficLightState.RED; TrafficLightState initialState = isFirstLight ? TrafficLightState.GREEN : TrafficLightState.RED;
light.changeState(initialState); light.changeState(initialState);
// Schedule first state change // Agenda a primeira transição
double firstChangeTime = currentTime + double firstChangeTime = currentTime +
(initialState == TrafficLightState.GREEN ? light.getGreenTime() : light.getRedTime()); (initialState == TrafficLightState.GREEN ? light.getGreenTime() : light.getRedTime());
@@ -624,14 +667,16 @@ public class IntersectionProcess {
} }
/** /**
* Envia um veículo para o seu próximo destino via ligação socket. * Encaminhamento de rede: Serializa e envia o objeto veículo para o próximo nó.
* <p>
* Calcula também o tempo de viagem virtual entre nós (Edge Weight).
* *
* @param vehicle O veículo que atravessou esta interseção. * @param vehicle O veículo a ser enviado.
*/ */
public void sendVehicleToNextDestination(Vehicle vehicle) { public void sendVehicleToNextDestination(Vehicle vehicle) {
String nextDestination = vehicle.getCurrentDestination(); String nextDestination = vehicle.getCurrentDestination();
// Calculate travel time // Cálculo de latência de viagem (Edge Weight)
double baseTime = config.getBaseTravelTime(); double baseTime = config.getBaseTravelTime();
double multiplier = 1.0; double multiplier = 1.0;
switch (vehicle.getType()) { switch (vehicle.getType()) {
@@ -644,22 +689,25 @@ public class IntersectionProcess {
System.out.printf("[%s] Vehicle %s departing to %s. Travel time: %.2fs%n", System.out.printf("[%s] Vehicle %s departing to %s. Travel time: %.2fs%n",
intersectionId, vehicle.getId(), nextDestination, travelTime); intersectionId, vehicle.getId(), nextDestination, travelTime);
// Record departure immediately as it leaves the intersection
recordVehicleDeparture(); recordVehicleDeparture();
// In DES mode, send immediately (no real-time delay) // Envio imediato (o delay de viagem é implícito no tempo de chegada no próximo
// nó ou simulado aqui)
sendVehicleImmediately(vehicle, nextDestination); sendVehicleImmediately(vehicle, nextDestination);
} }
/** /**
* Envia imediatamente um veículo para o seu destino via rede. * Envia o veículo imediatamente para o próximo nó via conexão TCP persistente.
*
* @param vehicle O veículo a ser enviado.
* @param nextDestination O identificador do próximo nó destino.
*/ */
private void sendVehicleImmediately(Vehicle vehicle, String nextDestination) { private void sendVehicleImmediately(Vehicle vehicle, String nextDestination) {
try { try {
// Get or create connection to next destination // Lazy loading da conexão
SocketConnection connection = getOrCreateConnection(nextDestination); SocketConnection connection = getOrCreateConnection(nextDestination);
// Create and send message using Message class // Encapsulamento da mensagem
MessageProtocol message = new Message( MessageProtocol message = new Message(
MessageType.VEHICLE_TRANSFER, MessageType.VEHICLE_TRANSFER,
intersectionId, intersectionId,
@@ -672,8 +720,6 @@ public class IntersectionProcess {
System.out.println("[" + intersectionId + "] Vehicle " + vehicle.getId() + System.out.println("[" + intersectionId + "] Vehicle " + vehicle.getId() +
" arrived at " + nextDestination + " (msg sent)"); " arrived at " + nextDestination + " (msg sent)");
// Note: vehicle route is advanced when it arrives at the next intersection
} catch (IOException | InterruptedException e) { } catch (IOException | InterruptedException e) {
System.err.println("[" + intersectionId + "] Failed to send vehicle " + System.err.println("[" + intersectionId + "] Failed to send vehicle " +
vehicle.getId() + " to " + nextDestination + ": " + e.getMessage()); vehicle.getId() + " to " + nextDestination + ": " + e.getMessage());
@@ -681,12 +727,15 @@ public class IntersectionProcess {
} }
/** /**
* Obtém uma ligação existente para um destino ou cria uma nova. * Obtém ou cria uma conexão para o destino especificado (Singleton por
* destino).
* <p>
* Este método é thread-safe.
* *
* @param destinationId O ID do nó de destino. * @param destinationId O identificador do nó destino.
* @return A SocketConnection para esse destino. * @return A conexão TCP estabelecida.
* @throws IOException Se a ligação não puder ser estabelecida. * @throws IOException Se ocorrer um erro de I/O na criação da conexão.
* @throws InterruptedException Se a tentativa de ligação for interrompida. * @throws InterruptedException Se a thread for interrompida durante a espera.
*/ */
private synchronized SocketConnection getOrCreateConnection(String destinationId) private synchronized SocketConnection getOrCreateConnection(String destinationId)
throws IOException, InterruptedException { throws IOException, InterruptedException {
@@ -706,10 +755,10 @@ public class IntersectionProcess {
} }
/** /**
* Obtém o endereço host para um nó de destino a partir da configuração. * Resolve o hostname ou endereço IP para um determinado destino.
* *
* @param destinationId O ID do nó de destino. * @param destinationId O ID do destino.
* @return O endereço host. * @return O endereço do host.
*/ */
private String getHostForDestination(String destinationId) { private String getHostForDestination(String destinationId) {
if (destinationId.equals("S")) { if (destinationId.equals("S")) {
@@ -720,9 +769,9 @@ public class IntersectionProcess {
} }
/** /**
* Obtém o número da porta para um nó de destino a partir da configuração. * Resolve a porta TCP para um determinado destino.
* *
* @param destinationId O ID do nó de destino. * @param destinationId O ID do destino.
* @return O número da porta. * @return O número da porta.
*/ */
private int getPortForDestination(String destinationId) { private int getPortForDestination(String destinationId) {
@@ -734,10 +783,11 @@ public class IntersectionProcess {
} }
/** /**
* Inicia o socket do servidor e começa a aceitar ligações recebidas. * Inicia o servidor e o loop de aceitação de conexões.
* Este é o loop principal de escuta do processo. * <p>
* Este método bloqueia a thread chamadora durante a execução do servidor.
* *
* @throws IOException Se o socket do servidor não puder ser criado. * @throws IOException Se ocorrer um erro ao fazer bind da porta.
*/ */
public void start() throws IOException { public void start() throws IOException {
int port = config.getIntersectionPort(intersectionId); int port = config.getIntersectionPort(intersectionId);
@@ -751,12 +801,12 @@ public class IntersectionProcess {
startEventProcessor(); startEventProcessor();
System.out.println("[" + intersectionId + "] Running in DES mode"); System.out.println("[" + intersectionId + "] Running in DES mode");
// Start stats updater // Background task para telemetria
statsExecutor.scheduleAtFixedRate(this::sendStatsToDashboard, 1, 1, TimeUnit.SECONDS); statsExecutor.scheduleAtFixedRate(this::sendStatsToDashboard, 1, 1, TimeUnit.SECONDS);
System.out.println("[" + intersectionId + "] Waiting for incoming connections...\n"); System.out.println("[" + intersectionId + "] Waiting for incoming connections...\n");
// Main accept loop // Loop principal de aceitação de conexões
while (running) { while (running) {
try { try {
Socket clientSocket = serverSocket.accept(); Socket clientSocket = serverSocket.accept();
@@ -764,13 +814,12 @@ public class IntersectionProcess {
System.out.println("[" + intersectionId + "] New connection accepted from " + System.out.println("[" + intersectionId + "] New connection accepted from " +
clientSocket.getInetAddress().getHostAddress()); clientSocket.getInetAddress().getHostAddress());
// Check running flag again before handling
if (!running) { if (!running) {
clientSocket.close(); clientSocket.close();
break; break;
} }
// **Set timeout before submitting to handler** // Configura timeout para evitar bloqueios infinitos em leitura
try { try {
clientSocket.setSoTimeout(1000); clientSocket.setSoTimeout(1000);
} catch (java.net.SocketException e) { } catch (java.net.SocketException e) {
@@ -779,13 +828,12 @@ public class IntersectionProcess {
continue; continue;
} }
// Handle each connection in a separate thread // Delega processamento para thread pool (NIO style)
connectionHandlerPool.submit(() -> handleIncomingConnection(clientSocket)); connectionHandlerPool.submit(() -> handleIncomingConnection(clientSocket));
} catch (IOException e) { } catch (IOException e) {
// Expected when serverSocket.close() is called during shutdown
if (!running) { if (!running) {
break; // Normal shutdown break; // Shutdown normal
} }
System.err.println("[" + intersectionId + "] Error accepting connection: " + System.err.println("[" + intersectionId + "] Error accepting connection: " +
e.getMessage()); e.getMessage());
@@ -794,10 +842,13 @@ public class IntersectionProcess {
} }
/** /**
* Trata uma ligação recebida de outro processo. * Lógica de tratamento de conexões de entrada (Consumer).
* Escuta continuamente mensagens de transferência de veículos. * <p>
* Lê continuamente do socket até que a conexão seja fechada, processando
* mensagens
* de chegada de veículos ou comandos de simulação.
* *
* @param clientSocket A ligação socket aceite. * @param clientSocket O socket do cliente conectado.
*/ */
private void handleIncomingConnection(Socket clientSocket) { private void handleIncomingConnection(Socket clientSocket) {
try { try {
@@ -813,27 +864,24 @@ public class IntersectionProcess {
System.out.println("[" + intersectionId + "] New connection accepted from " + System.out.println("[" + intersectionId + "] New connection accepted from " +
clientSocket.getInetAddress().getHostAddress()); clientSocket.getInetAddress().getHostAddress());
// Continuously receive messages while connection is active
while (running && connection.isConnected()) { while (running && connection.isConnected()) {
try { try {
MessageProtocol message = connection.receiveMessage(); MessageProtocol message = connection.receiveMessage();
// Handle simulation start time synchronization
if (message.getType() == MessageType.SIMULATION_START) { if (message.getType() == MessageType.SIMULATION_START) {
System.out.println("[" + intersectionId + "] Simulation start time synchronized"); System.out.println("[" + intersectionId + "] Simulation start time synchronized");
continue; continue;
} }
// Accept both VEHICLE_TRANSFER and VEHICLE_SPAWN (from coordinator)
if (message.getType() == MessageType.VEHICLE_TRANSFER || if (message.getType() == MessageType.VEHICLE_TRANSFER ||
message.getType() == MessageType.VEHICLE_SPAWN) { message.getType() == MessageType.VEHICLE_SPAWN) {
// Cast payload to Vehicle - handle Gson deserialization
// Lógica de desserialização polimórfica (Vehicle ou Map)
Vehicle vehicle; Vehicle vehicle;
Object payload = message.getPayload(); Object payload = message.getPayload();
if (payload instanceof Vehicle) { if (payload instanceof Vehicle) {
vehicle = (Vehicle) payload; vehicle = (Vehicle) payload;
} else if (payload instanceof java.util.Map) { } else if (payload instanceof java.util.Map) {
// Gson deserialized as LinkedHashMap - re-serialize and deserialize as Vehicle
com.google.gson.Gson gson = new com.google.gson.Gson(); com.google.gson.Gson gson = new com.google.gson.Gson();
String json = gson.toJson(payload); String json = gson.toJson(payload);
vehicle = gson.fromJson(json, Vehicle.class); vehicle = gson.fromJson(json, Vehicle.class);
@@ -845,43 +893,37 @@ public class IntersectionProcess {
System.out.println("[" + intersectionId + "] Received vehicle: " + System.out.println("[" + intersectionId + "] Received vehicle: " +
vehicle.getId() + " from " + message.getSourceNode()); vehicle.getId() + " from " + message.getSourceNode());
// Advance vehicle to next destination in its route // Lógica de Roteamento Local
vehicle.advanceRoute(); vehicle.advanceRoute();
// Add vehicle to appropriate queue with current simulation time
intersection.receiveVehicle(vehicle, clock.getCurrentTime()); intersection.receiveVehicle(vehicle, clock.getCurrentTime());
// Log queue status after adding vehicle
System.out.printf("[%s] Vehicle %s queued. Total queue size: %d%n", System.out.printf("[%s] Vehicle %s queued. Total queue size: %d%n",
intersectionId, vehicle.getId(), intersection.getTotalQueueSize()); intersectionId, vehicle.getId(), intersection.getTotalQueueSize());
// Record arrival for statistics
recordVehicleArrival(); recordVehicleArrival();
} else if (message.getType() == MessageType.SHUTDOWN) { } else if (message.getType() == MessageType.SHUTDOWN) {
System.out.println( System.out.println(
"[" + intersectionId + "] Received SHUTDOWN command from " + message.getSourceNode()); "[" + intersectionId + "] Received SHUTDOWN command from " + message.getSourceNode());
running = false; running = false;
// Close this specific connection
break; break;
} }
} catch (java.net.SocketTimeoutException e) { } catch (java.net.SocketTimeoutException e) {
// Timeout - check running flag and continue
if (!running) { if (!running) {
break; break;
} }
// Continue waiting for next message
} catch (ClassNotFoundException e) { } catch (ClassNotFoundException e) {
System.err.println("[" + intersectionId + "] Unknown message type received: " + System.err.println("[" + intersectionId + "] Unknown message type received: " +
e.getMessage()); e.getMessage());
break; // Invalid message, close connection break;
} catch (IOException e) { } catch (IOException e) {
if (running) { if (running) {
System.err.println("[" + intersectionId + "] Failed to deserialize message: " + System.err.println("[" + intersectionId + "] Failed to deserialize message: " +
e.getMessage()); e.getMessage());
e.printStackTrace(); // For debugging - maybe change//remove later e.printStackTrace();
} }
break; // Connection error, close connection break;
} }
} }
@@ -889,27 +931,29 @@ public class IntersectionProcess {
if (running) { if (running) {
System.err.println("[" + intersectionId + "] Connection error: " + e.getMessage()); System.err.println("[" + intersectionId + "] Connection error: " + e.getMessage());
} }
// Expected during shutdown
} }
} }
/** /**
* Stops the intersection process gracefully. * Procedimento de Encerramento Gracioso (Graceful Shutdown).
* Shuts down all threads and closes all connections. * <ol>
* <li>Para a aceitação de novas conexões.</li>
* <li>Envia últimas estatísticas.</li>
* <li>Encerra pools de threads.</li>
* <li>Fecha sockets ativos.</li>
* </ol>
*/ */
public void shutdown() { public void shutdown() {
// Check if already shutdown
if (!running) { if (!running) {
return; // Already shutdown, do nothing return;
} }
System.out.println("\n[" + intersectionId + "] Shutting down..."); System.out.println("\n[" + intersectionId + "] Shutting down...");
running = false; running = false;
// Send final stats before closing connections
sendStatsToDashboard(); sendStatsToDashboard();
// 1. Close ServerSocket first // 1. Close ServerSocket
if (serverSocket != null && !serverSocket.isClosed()) { if (serverSocket != null && !serverSocket.isClosed()) {
try { try {
serverSocket.close(); serverSocket.close();
@@ -918,8 +962,7 @@ public class IntersectionProcess {
} }
} }
// 2. Shutdown thread pools with force // 2. Shutdown thread pools
if (connectionHandlerPool != null && !connectionHandlerPool.isShutdown()) { if (connectionHandlerPool != null && !connectionHandlerPool.isShutdown()) {
connectionHandlerPool.shutdownNow(); connectionHandlerPool.shutdownNow();
} }
@@ -930,9 +973,8 @@ public class IntersectionProcess {
departureExecutor.shutdownNow(); departureExecutor.shutdownNow();
} }
// 3. Wait briefly for termination (don't block forever) // 3. Wait briefly for termination
try { try {
if (connectionHandlerPool != null) { if (connectionHandlerPool != null) {
connectionHandlerPool.awaitTermination(1, TimeUnit.SECONDS); connectionHandlerPool.awaitTermination(1, TimeUnit.SECONDS);
} }
@@ -968,31 +1010,32 @@ public class IntersectionProcess {
} }
/** /**
* Gets the Intersection object managed by this process. * Obtém o modelo de dados da interseção.
* Useful for testing and monitoring.
* *
* @return The Intersection object. * @return O objeto Intersection.
*/ */
public Intersection getIntersection() { public Intersection getIntersection() {
return intersection; return intersection;
} }
/** /**
* Records that a vehicle has arrived at this intersection. * Regista a chegada de um novo veículo para fins estatísticos.
*/ */
public void recordVehicleArrival() { public void recordVehicleArrival() {
totalArrivals++; totalArrivals++;
} }
/** /**
* Records that a vehicle has departed from this intersection. * Regista a partida de um veículo para fins estatísticos.
*/ */
public void recordVehicleDeparture() { public void recordVehicleDeparture() {
totalDepartures++; totalDepartures++;
} }
/** /**
* Sends current statistics to the dashboard server. * Envia um "snapshot" do estado atual para o Dashboard (Telemetria Push).
* <p>
* Inclui o número acumulado de chegadas, partidas e o tamanho atual das filas.
*/ */
private void sendStatsToDashboard() { private void sendStatsToDashboard() {
if (dashboardClient == null || !dashboardClient.isConnected()) { if (dashboardClient == null || !dashboardClient.isConnected()) {
@@ -1000,7 +1043,6 @@ public class IntersectionProcess {
} }
try { try {
// Calculate current queue size
int currentQueueSize = intersection.getTrafficLights().stream() int currentQueueSize = intersection.getTrafficLights().stream()
.mapToInt(TrafficLight::getQueueSize) .mapToInt(TrafficLight::getQueueSize)
.sum(); .sum();
@@ -1010,7 +1052,6 @@ public class IntersectionProcess {
.setIntersectionDepartures(totalDepartures) .setIntersectionDepartures(totalDepartures)
.setIntersectionQueueSize(currentQueueSize); .setIntersectionQueueSize(currentQueueSize);
// Send StatsUpdatePayload directly as the message payload
sd.model.Message message = new sd.model.Message( sd.model.Message message = new sd.model.Message(
MessageType.STATS_UPDATE, MessageType.STATS_UPDATE,
intersectionId, intersectionId,

94
main/src/main/java/sd/dashboard/DashboardUI.java
View File

@@ -30,8 +30,22 @@ import sd.config.SimulationConfig;
import sd.model.VehicleType; import sd.model.VehicleType;
/** /**
* JavaFX-based Dashboard UI for displaying real-time simulation statistics. * Interface Gráfica (GUI) baseada em JavaFX para visualização de telemetria em tempo real.
* Provides a graphical interface with auto-updating statistics panels. * <p>
* Esta classe atua como a camada de apresentação (View) do sistema. Implementa o padrão
* <i>Observer</i> (via polling) para refletir o estado do modelo {@link DashboardStatistics}
* nos componentes visuais.
* <p>
* <b>Aspetos Técnicos Relevantes:</b>
* <ul>
* <li><b>Concorrência de UI:</b> Utiliza um {@link ScheduledExecutorService} para buscar dados
* em background e {@link Platform#runLater(Runnable)} para injetar atualizações na
* <i>JavaFX Application Thread</i>, evitando exceções de "Not on FX application thread".</li>
* <li><b>Data Binding:</b> Utiliza {@link TableView} com classes internas (DTOs) para
* renderização tabular eficiente de tipos de veículos e interseções.</li>
* <li><b>Controlo de Processos:</b> Integra com {@link SimulationProcessManager} para orquestrar
* o ciclo de vida (spawn/kill) dos processos externos da simulação.</li>
* </ul>
*/ */
public class DashboardUI extends Application { public class DashboardUI extends Application {
@@ -52,7 +66,7 @@ public class DashboardUI extends Application {
// Intersection Table // Intersection Table
private TableView<IntersectionRow> intersectionTable; private TableView<IntersectionRow> intersectionTable;
// Update scheduler // Update scheduler (Background Thread)
private ScheduledExecutorService updateScheduler; private ScheduledExecutorService updateScheduler;
// Configuration controls // Configuration controls
@@ -60,6 +74,10 @@ public class DashboardUI extends Application {
private String selectedConfigFile = "simulation.properties"; private String selectedConfigFile = "simulation.properties";
private Label configInfoLabel; private Label configInfoLabel;
/**
* Ponto de entrada da aplicação JavaFX.
* Configura o Stage primário, inicializa o servidor de backend e constrói a árvore de cena (Scene Graph).
*/
@Override @Override
public void start(Stage primaryStage) { public void start(Stage primaryStage) {
try { try {
@@ -72,29 +90,27 @@ public class DashboardUI extends Application {
server = new DashboardServer(config); server = new DashboardServer(config);
statistics = server.getStatistics(); statistics = server.getStatistics();
// Start the dashboard server // Start the dashboard server (Backend listening port)
server.start(); server.start();
// Build UI // Build UI Layout
BorderPane root = new BorderPane(); BorderPane root = new BorderPane();
root.getStyleClass().add("root"); root.getStyleClass().add("root");
// Header // Header (Top)
VBox header = createHeader(); VBox header = createHeader();
root.setTop(header); root.setTop(header);
// Main content // Main content (Center)
VBox mainContent = createMainContent(); VBox mainContent = createMainContent();
root.setCenter(mainContent); root.setCenter(mainContent);
// Footer // Footer (Bottom)
HBox footer = createFooter(); HBox footer = createFooter();
root.setBottom(footer); root.setBottom(footer);
// Create scene // Create scene & apply CSS
Scene scene = new Scene(root, 1200, 850); Scene scene = new Scene(root, 1200, 850);
// Load CSS
String cssUrl = getClass().getResource("/dashboard.css").toExternalForm(); String cssUrl = getClass().getResource("/dashboard.css").toExternalForm();
scene.getStylesheets().add(cssUrl); scene.getStylesheets().add(cssUrl);
@@ -102,10 +118,10 @@ public class DashboardUI extends Application {
primaryStage.setScene(scene); primaryStage.setScene(scene);
primaryStage.show(); primaryStage.show();
// Start periodic updates // Start periodic updates loop
startPeriodicUpdates(); startPeriodicUpdates();
// Handle window close // Handle window close (Graceful shutdown)
primaryStage.setOnCloseRequest(event -> { primaryStage.setOnCloseRequest(event -> {
shutdown(); shutdown();
}); });
@@ -149,6 +165,8 @@ public class DashboardUI extends Application {
// Passar o ficheiro de configuração selecionado // Passar o ficheiro de configuração selecionado
processManager.setConfigFile(selectedConfigFile); processManager.setConfigFile(selectedConfigFile);
processManager.startSimulation(); processManager.startSimulation();
// Toggle UI state
btnStart.setDisable(true); btnStart.setDisable(true);
btnStop.setDisable(false); btnStop.setDisable(false);
configFileSelector.setDisable(true); // Bloquear mudanças durante simulação configFileSelector.setDisable(true); // Bloquear mudanças durante simulação
@@ -159,6 +177,8 @@ public class DashboardUI extends Application {
btnStop.setOnAction(e -> { btnStop.setOnAction(e -> {
processManager.stopSimulation(); processManager.stopSimulation();
// Toggle UI state
btnStart.setDisable(false); btnStart.setDisable(false);
btnStop.setDisable(true); btnStop.setDisable(true);
configFileSelector.setDisable(false); // Desbloquear para nova simulação configFileSelector.setDisable(false); // Desbloquear para nova simulação
@@ -435,13 +455,23 @@ public class DashboardUI extends Application {
grid.add(container, colGroup, row); grid.add(container, colGroup, row);
} }
/**
* Inicia o ciclo de polling em background.
* Atualiza a UI a cada 100ms.
*/
private void startPeriodicUpdates() { private void startPeriodicUpdates() {
updateScheduler = Executors.newSingleThreadScheduledExecutor(); updateScheduler = Executors.newSingleThreadScheduledExecutor();
updateScheduler.scheduleAtFixedRate(() -> { updateScheduler.scheduleAtFixedRate(() -> {
// Crucial: Encapsular atualização de UI em Platform.runLater
// para garantir execução na JavaFX Application Thread
Platform.runLater(this::updateUI); Platform.runLater(this::updateUI);
}, 0, 100, TimeUnit.MILLISECONDS); }, 0, 100, TimeUnit.MILLISECONDS);
} }
/**
* Sincroniza o estado atual do objeto Statistics com os controlos JavaFX.
* Chamado periodicamente pela thread de UI.
*/
private void updateUI() { private void updateUI() {
// Update global statistics // Update global statistics
lblVehiclesGenerated.setText(String.valueOf(statistics.getTotalVehiclesGenerated())); lblVehiclesGenerated.setText(String.valueOf(statistics.getTotalVehiclesGenerated()));
@@ -548,7 +578,9 @@ public class DashboardUI extends Application {
launch(args); launch(args);
} }
// Inner classes for TableView data models // --- DTOs para Data Binding nas Tabelas ---
/** DTO para linhas da tabela de Tipos de Veículo. */
public static class VehicleTypeRow { public static class VehicleTypeRow {
private final String vehicleType; private final String vehicleType;
private final int count; private final int count;
@@ -560,19 +592,12 @@ public class DashboardUI extends Application {
this.avgWaitTime = avgWaitTime; this.avgWaitTime = avgWaitTime;
} }
public String getVehicleType() { public String getVehicleType() { return vehicleType; }
return vehicleType; public int getCount() { return count; }
} public String getAvgWaitTime() { return avgWaitTime; }
public int getCount() {
return count;
}
public String getAvgWaitTime() {
return avgWaitTime;
}
} }
/** DTO para linhas da tabela de Interseções. */
public static class IntersectionRow { public static class IntersectionRow {
private final String intersectionId; private final String intersectionId;
private final int arrivals; private final int arrivals;
@@ -586,20 +611,9 @@ public class DashboardUI extends Application {
this.queueSize = queueSize; this.queueSize = queueSize;
} }
public String getIntersectionId() { public String getIntersectionId() { return intersectionId; }
return intersectionId; public int getArrivals() { return arrivals; }
} public int getDepartures() { return departures; }
public int getQueueSize() { return queueSize; }
public int getArrivals() {
return arrivals;
}
public int getDepartures() {
return departures;
}
public int getQueueSize() {
return queueSize;
}
} }
} }

59
main/src/main/java/sd/dashboard/SimulationProcessManager.java
View File

@@ -6,9 +6,17 @@ import java.util.ArrayList;
import java.util.List; import java.util.List;
/** /**
* Gere o ciclo de vida dos processos de simulação (Intersections, Exit Node, * Orquestrador de processos para o ambiente de simulação distribuída.
* Coordinator). * <p>
* Permite iniciar e parar a simulação distribuída dentro da aplicação Java. * Esta classe atua como um supervisor (Process Manager), responsável pelo <i>bootstrapping</i>
* e <i>teardown</i> das múltiplas Java Virtual Machines (JVMs) que compõem o sistema.
* <p>
* Funcionalidades principais:
* <ul>
* <li><b>Isolamento:</b> Cada nó (Interseção, Coordinator, ExitNode) corre no seu próprio processo OS.</li>
* <li><b>Ordem de Arranque:</b> Garante que os servidores (Interseções) estão online antes dos clientes (Coordenador).</li>
* <li><b>Gestão de Logs:</b> Redireciona stdout/stderr de cada processo filho para ficheiros temporários para facilitar o debug.</li>
* </ul>
*/ */
public class SimulationProcessManager { public class SimulationProcessManager {
@@ -16,6 +24,10 @@ public class SimulationProcessManager {
private final String classpath; private final String classpath;
private String configFile; private String configFile;
/**
* Inicializa o gestor capturando o classpath da JVM atual.
* Isto garante que os processos filhos herdam as mesmas dependências e configurações de ambiente.
*/
public SimulationProcessManager() { public SimulationProcessManager() {
this.runningProcesses = new ArrayList<>(); this.runningProcesses = new ArrayList<>();
this.classpath = System.getProperty("java.class.path"); this.classpath = System.getProperty("java.class.path");
@@ -23,9 +35,9 @@ public class SimulationProcessManager {
} }
/** /**
* Define o ficheiro de configuração a usar. * Define o perfil de configuração a ser injetado nos processos filhos.
* * Útil para alternar entre cenários (Low/Medium/High Load) dinamicamente.
* @param configFile nome do ficheiro (ex: "simulation-low.properties") * * @param configFile Nome do ficheiro de propriedades (ex: "simulation-low.properties").
*/ */
public void setConfigFile(String configFile) { public void setConfigFile(String configFile) {
this.configFile = "src/main/resources/" + configFile; this.configFile = "src/main/resources/" + configFile;
@@ -33,9 +45,16 @@ public class SimulationProcessManager {
} }
/** /**
* Inicia a simulação completa: 5 Intersections, 1 Exit Node, e 1 Coordinator. * Executa o procedimento de arranque (Bootstrap) da simulação distribuída.
* * <p>
* @throws IOException se um processo falhar ao iniciar * A ordem de inicialização é crítica para evitar <i>Race Conditions</i> na conexão TCP:
* <ol>
* <li><b>Workers (Interseções):</b> Iniciam os ServerSockets.</li>
* <li><b>Sink (Exit Node):</b> Prepara-se para receber métricas finais.</li>
* <li><b>Delay de Estabilização:</b> Pausa de 1s para garantir que os sockets estão em LISTENING.</li>
* <li><b>Source (Coordinator):</b> Inicia a geração de carga e conecta-se aos nós.</li>
* </ol>
* * @throws IOException Se falhar o fork de algum processo.
*/ */
public void startSimulation() throws IOException { public void startSimulation() throws IOException {
if (!runningProcesses.isEmpty()) { if (!runningProcesses.isEmpty()) {
@@ -65,8 +84,11 @@ public class SimulationProcessManager {
} }
/** /**
* Checks if the coordinator process (last process started) is still running. * Verifica o estado de "liveness" da simulação monitorizando o processo Coordenador.
* When the coordinator finishes, the simulation is complete. * <p>
* Como o Coordenador gere o relógio DES e a geração de eventos, a sua terminação
* (após o drain time) sinaliza o fim efetivo da simulação.
* * @return true se o Coordenador ainda estiver ativo (alive).
*/ */
public boolean isSimulationRunning() { public boolean isSimulationRunning() {
if (runningProcesses.isEmpty()) { if (runningProcesses.isEmpty()) {
@@ -78,8 +100,10 @@ public class SimulationProcessManager {
} }
/** /**
* Waits for the simulation to complete naturally. * Bloqueia a thread atual até que a simulação termine naturalmente ou ocorra timeout.
* Returns true if completed, false if timeout. * * @param timeoutSeconds Tempo máximo de espera.
* @return true se terminou, false se o timeout expirou.
* @throws InterruptedException Se a espera for interrompida.
*/ */
public boolean waitForCompletion(long timeoutSeconds) throws InterruptedException { public boolean waitForCompletion(long timeoutSeconds) throws InterruptedException {
if (runningProcesses.isEmpty()) { if (runningProcesses.isEmpty()) {
@@ -91,7 +115,11 @@ public class SimulationProcessManager {
} }
/** /**
* Stops all running simulation processes. * Executa o procedimento de encerramento (Teardown) de todos os processos.
* <p>
* Tenta primeiro uma paragem graciosa (`SIGTERM`), aguarda meio segundo, e
* força a paragem (`SIGKILL`) para processos persistentes, garantindo que não
* ficam processos órfãos no SO.
*/ */
public void stopSimulation() { public void stopSimulation() {
System.out.println("Stopping simulation processes..."); System.out.println("Stopping simulation processes...");
@@ -120,7 +148,8 @@ public class SimulationProcessManager {
} }
/** /**
* Helper para iniciar um único processo Java. * Helper de baixo nível para construção e lançamento de processos Java.
* Configura o redirecionamento de I/O para ficheiros de log na diretoria temporária do SO.
*/ */
private void startProcess(String className, String arg) throws IOException { private void startProcess(String className, String arg) throws IOException {
String javaBin = System.getProperty("java.home") + File.separator + "bin" + File.separator + "java"; String javaBin = System.getProperty("java.home") + File.separator + "bin" + File.separator + "java";

33
main/src/main/java/sd/dashboard/StatsMessage.java
View File

@@ -4,7 +4,14 @@ import sd.model.MessageType;
import sd.protocol.MessageProtocol; import sd.protocol.MessageProtocol;
/** /**
* Message wrapper for sending statistics to the dashboard. * Implementação concreta do protocolo de mensagens destinada ao transporte de telemetria.
* <p>
* Esta classe atua como um envelope especializado para o envio de dados estatísticos
* (encapsulados em {@link StatsUpdatePayload}) dos nós operacionais (Interseções, Coordenador)
* para o servidor de Dashboard centralizado.
* <p>
* Diferencia-se das mensagens de controlo genéricas por ter o destino fixado no
* "DashboardServer" e um tipo de mensagem imutável ({@code STATS_UPDATE}).
*/ */
public class StatsMessage implements MessageProtocol { public class StatsMessage implements MessageProtocol {
@@ -14,27 +21,49 @@ public class StatsMessage implements MessageProtocol {
private final String destinationNode; private final String destinationNode;
private final StatsUpdatePayload payload; private final StatsUpdatePayload payload;
/**
* Cria uma nova mensagem de estatística.
*
* @param sourceNode O ID do nó que gerou as estatísticas (ex: "Cr1", "ExitNode").
* @param payload O objeto DTO contendo os dados estatísticos brutos ou agregados.
*/
public StatsMessage(String sourceNode, StatsUpdatePayload payload) { public StatsMessage(String sourceNode, StatsUpdatePayload payload) {
this.sourceNode = sourceNode; this.sourceNode = sourceNode;
this.destinationNode = "DashboardServer"; this.destinationNode = "DashboardServer"; // Destino implícito e fixo
this.payload = payload; this.payload = payload;
} }
/**
* Retorna o tipo da mensagem, que identifica semanticamente o conteúdo para o recetor.
* @return Sempre {@link MessageType#STATS_UPDATE}.
*/
@Override @Override
public MessageType getType() { public MessageType getType() {
return MessageType.STATS_UPDATE; return MessageType.STATS_UPDATE;
} }
/**
* Obtém a carga útil da mensagem.
* @return O objeto {@link StatsUpdatePayload} associado.
*/
@Override @Override
public Object getPayload() { public Object getPayload() {
return payload; return payload;
} }
/**
* Identifica a origem da mensagem.
* @return O ID do nó remetente.
*/
@Override @Override
public String getSourceNode() { public String getSourceNode() {
return sourceNode; return sourceNode;
} }
/**
* Identifica o destino da mensagem.
* @return Sempre "DashboardServer".
*/
@Override @Override
public String getDestinationNode() { public String getDestinationNode() {
return destinationNode; return destinationNode;

41
main/src/main/java/sd/dashboard/StatsUpdatePayload.java
View File

@@ -7,25 +7,60 @@ import java.util.Map;
import sd.model.VehicleType; import sd.model.VehicleType;
/** /**
* DTO para atualizações de estatísticas ao dashboard. * Objeto de Transferência de Dados (DTO) otimizado para transporte de telemetria.
* Campos com valor -1 não são atualizados nesta mensagem. * <p>
* Esta classe encapsula as métricas de desempenho enviadas pelos nós da simulação (Coordenador,
* Interseções, ExitNode) para o Dashboard. Foi desenhada para suportar <b>atualizações parciais</b>
* (Sparse Updates):
* <ul>
* <li>Campos globais inicializados com {@code -1} indicam "sem alteração" (no-op). O Dashboard
* deve ignorar estes campos e manter o valor acumulado anterior.</li>
* <li>Campos de interseção ({@code arrivals}, {@code departures}) representam deltas ou snapshots
* específicos do nó remetente.</li>
* </ul>
* Implementa {@link Serializable} para transmissão direta via Java Sockets.
*
[Image of data transfer object pattern]
*/ */
public class StatsUpdatePayload implements Serializable { public class StatsUpdatePayload implements Serializable {
private static final long serialVersionUID = 1L; private static final long serialVersionUID = 1L;
// Global Metrics (Coordinator/ExitNode)
/** Total gerado. Valor -1 indica que este campo deve ser ignorado na atualização. */
private int totalVehiclesGenerated = -1; private int totalVehiclesGenerated = -1;
/** Total completado. Valor -1 indica que este campo deve ser ignorado. */
private int totalVehiclesCompleted = -1; private int totalVehiclesCompleted = -1;
/** Tempo total de sistema acumulado (ms). Valor -1 indica que deve ser ignorado. */
private long totalSystemTime = -1; private long totalSystemTime = -1;
/** Tempo total de espera acumulado (ms). Valor -1 indica que deve ser ignorado. */
private long totalWaitingTime = -1; private long totalWaitingTime = -1;
// Intersection Metrics (Worker Nodes)
/** Número de veículos que entraram na interseção desde o último reporte. */
private int intersectionArrivals = 0; private int intersectionArrivals = 0;
/** Número de veículos que saíram da interseção desde o último reporte. */
private int intersectionDepartures = 0; private int intersectionDepartures = 0;
/** Snapshot do tamanho atual da fila na interseção. */
private int intersectionQueueSize = 0; private int intersectionQueueSize = 0;
// Detailed Breakdowns
/** Contagem acumulada por tipo de veículo. */
private Map<VehicleType, Integer> vehicleTypeCounts; private Map<VehicleType, Integer> vehicleTypeCounts;
/** Tempos de espera acumulados por tipo de veículo. */
private Map<VehicleType, Long> vehicleTypeWaitTimes; private Map<VehicleType, Long> vehicleTypeWaitTimes;
/**
* Inicializa o payload com os mapas vazios e contadores globais a -1 (estado neutro).
*/
public StatsUpdatePayload() { public StatsUpdatePayload() {
this.vehicleTypeCounts = new HashMap<>(); this.vehicleTypeCounts = new HashMap<>();
this.vehicleTypeWaitTimes = new HashMap<>(); this.vehicleTypeWaitTimes = new HashMap<>();
@@ -67,6 +102,8 @@ public class StatsUpdatePayload implements Serializable {
return vehicleTypeWaitTimes; return vehicleTypeWaitTimes;
} }
// Setters implementam Fluent Interface para construção encadeada
public StatsUpdatePayload setTotalVehiclesGenerated(int totalVehiclesGenerated) { public StatsUpdatePayload setTotalVehiclesGenerated(int totalVehiclesGenerated) {
this.totalVehiclesGenerated = totalVehiclesGenerated; this.totalVehiclesGenerated = totalVehiclesGenerated;
return this; return this;

66
main/src/main/java/sd/des/SimulationEvent.java
View File

@@ -3,31 +3,46 @@ package sd.des;
import java.io.Serializable; import java.io.Serializable;
/** /**
* Evento discreto da simulação. * Representa um evento atómico e imutável no contexto da Simulação de Eventos Discretos (DES).
* * <p>
* <p>Unidade fundamental de execução num sistema DES: * Esta classe é a unidade fundamental de processamento. Numa arquitetura DES, o estado do sistema
* não muda continuamente, mas sim em instantes discretos definidos por estes eventos.
* <p>
* Características principais:
* <ul> * <ul>
* <li>timestamp - quando ocorre * <li><b>Ordenação Temporal:</b> Implementa {@link Comparable} para ser armazenado numa Fila de
* <li>type - o que acontece * Eventos Futuros (FEL - Future Event List), garantindo execução cronológica.</li>
* <li>payload - dados associados * <li><b>Distribuído:</b> Implementa {@link Serializable} para permitir que eventos gerados num nó
* <li>location - qual processo o trata * (ex: Coordenador) sejam transmitidos e executados noutro (ex: Interseção).</li>
* <li><b>Polimórfico:</b> Transporta um {@code payload} genérico, permitindo associar qualquer
* entidade (Veículo, Sinal, etc.) ao evento.</li>
* </ul> * </ul>
*/ */
public class SimulationEvent implements Comparable<SimulationEvent>, Serializable { public class SimulationEvent implements Comparable<SimulationEvent>, Serializable {
private static final long serialVersionUID = 1L; private static final long serialVersionUID = 1L;
/** O instante virtual exato em que o evento deve ser processado. */
private final double timestamp; private final double timestamp;
/** A categoria do evento (ex: VEHICLE_ARRIVAL, LIGHT_CHANGE). */
private final DESEventType type; private final DESEventType type;
/** Dados contextuais associados (ex: o objeto Vehicle que chegou). */
private final Object payload; private final Object payload;
private final String location; // Process ID (e.g., "Cr1", "Coordinator", "Exit")
/** /**
* Cria um novo evento de simulação. * O identificador do nó de destino onde o evento deve ser executado.
* (ex: "Cr1", "Coordinator", "ExitNode"). Se null, é um evento local.
*/
private final String location;
/**
* Instancia um novo evento de simulação completo.
* *
* @param timestamp instante do evento (tempo de simulação em segundos) * @param timestamp Instante de execução (segundos virtuais).
* @param type tipo de evento * @param type Tipo enumerado do evento.
* @param payload dados associados (ex: objeto Vehicle) * @param payload Objeto de dados associado (pode ser null).
* @param location processo que trata o evento * @param location ID do processo alvo para execução distribuída.
*/ */
public SimulationEvent(double timestamp, DESEventType type, Object payload, String location) { public SimulationEvent(double timestamp, DESEventType type, Object payload, String location) {
this.timestamp = timestamp; this.timestamp = timestamp;
@@ -36,7 +51,14 @@ public class SimulationEvent implements Comparable<SimulationEvent>, Serializabl
this.location = location; this.location = location;
} }
/** Cria evento sem localização (para eventos locais) */ /**
* Construtor de conveniência para eventos locais (dentro do mesmo processo).
* Define {@code location} como null.
*
* @param timestamp Instante de execução.
* @param type Tipo do evento.
* @param payload Objeto de dados associado.
*/
public SimulationEvent(double timestamp, DESEventType type, Object payload) { public SimulationEvent(double timestamp, DESEventType type, Object payload) {
this(timestamp, type, payload, null); this(timestamp, type, payload, null);
} }
@@ -58,8 +80,18 @@ public class SimulationEvent implements Comparable<SimulationEvent>, Serializabl
} }
/** /**
* Ordena eventos por timestamp (mais cedo primeiro). * Define a ordem natural de processamento na Fila de Prioridade.
* Em caso de empate, ordena por tipo para determinismo. * <p>
* <b>Lógica de Ordenação:</b>
* <ol>
* <li><b>Primária (Tempo):</b> Eventos com menor timestamp ocorrem primeiro.</li>
* <li><b>Secundária (Determinismo):</b> Em caso de empate temporal (simultaneidade),
* ordena alfabeticamente pelo nome do tipo. Isto garante que execuções repetidas
* da simulação produzam exatamente o mesmo resultado (determinismo estrito).</li>
* </ol>
*
* @param other O outro evento a comparar.
* @return Inteiro negativo, zero ou positivo conforme a ordem.
*/ */
@Override @Override
public int compareTo(SimulationEvent other) { public int compareTo(SimulationEvent other) {
@@ -67,7 +99,7 @@ public class SimulationEvent implements Comparable<SimulationEvent>, Serializabl
if (timeComparison != 0) { if (timeComparison != 0) {
return timeComparison; return timeComparison;
} }
// Tie-breaker: order by event type name // Tie-breaker: order by event type name to ensure reproducible runs
return this.type.name().compareTo(other.type.name()); return this.type.name().compareTo(other.type.name());
} }

23
main/src/main/java/sd/des/TrafficLightEvent.java
View File

@@ -3,28 +3,47 @@ package sd.des;
import sd.model.TrafficLight; import sd.model.TrafficLight;
/** /**
* Payload for traffic light change events. * Encapsula o contexto de dados para eventos de mudança de estado de semáforos.
* Contains the traffic light and its direction. * <p>
* Este objeto atua como o <i>payload</i> transportado por um {@link SimulationEvent}
* quando o tipo de evento é relacionado com controlo de tráfego (ex: mudança Verde -> Amarelo).
* Permite que o motor DES identifique exatamente qual instância de {@link TrafficLight}
* deve ser atualizada numa determinada interseção e direção.
*/ */
public class TrafficLightEvent { public class TrafficLightEvent {
private final TrafficLight light; private final TrafficLight light;
private final String direction; private final String direction;
private final String intersectionId; private final String intersectionId;
/**
* Cria um novo payload de evento de semáforo.
* @param light A instância do objeto semáforo a ser manipulado.
* @param direction A direção cardeal associada (ex: "North", "East").
* @param intersectionId O identificador da interseção onde o semáforo reside.
*/
public TrafficLightEvent(TrafficLight light, String direction, String intersectionId) { public TrafficLightEvent(TrafficLight light, String direction, String intersectionId) {
this.light = light; this.light = light;
this.direction = direction; this.direction = direction;
this.intersectionId = intersectionId; this.intersectionId = intersectionId;
} }
/**
* @return A referência direta para o objeto de domínio do semáforo.
*/
public TrafficLight getLight() { public TrafficLight getLight() {
return light; return light;
} }
/**
* @return A direção do fluxo controlado por este semáforo.
*/
public String getDirection() { public String getDirection() {
return direction; return direction;
} }
/**
* @return O ID da interseção pai.
*/
public String getIntersectionId() { public String getIntersectionId() {
return intersectionId; return intersectionId;
} }

80
main/src/main/java/sd/logging/EventLogger.java
View File

@@ -11,10 +11,19 @@ import java.util.concurrent.LinkedBlockingQueue;
import java.util.concurrent.atomic.AtomicBoolean; import java.util.concurrent.atomic.AtomicBoolean;
/** /**
* Sistema de registo centralizado de eventos para a simulação distribuída. * Motor de logging assíncrono e thread-safe para a simulação distribuída.
* * <p>
* <p>Regista todos os eventos da simulação num ficheiro com timestamps e categorização. * Implementa o padrão <i>Singleton</i> para garantir um ponto centralizado de registo.
* Thread-safe e não-bloqueante para impacto mínimo na performance.</p> * Utiliza o padrão <i>Producer-Consumer</i> com uma {@link BlockingQueue} para desacoplar
* a geração de eventos (crítica para a performance da simulação) da persistência em disco
* (operação de I/O lenta).
* <p>
* <b>Garantias:</b>
* <ul>
* <li>Non-blocking writes (para a thread chamadora, na maioria dos casos).</li>
* <li>Ordering cronológico aproximado (FIFO na fila).</li>
* <li>Graceful Shutdown (flush de logs pendentes ao terminar).</li>
* </ul>
*/ */
public class EventLogger { public class EventLogger {
@@ -22,20 +31,33 @@ public class EventLogger {
private static final Object instanceLock = new Object(); private static final Object instanceLock = new Object();
private final PrintWriter writer; private final PrintWriter writer;
/** Buffer de memória para absorver picos de eventos (Burst traffic). */
private final BlockingQueue<LogEntry> logQueue; private final BlockingQueue<LogEntry> logQueue;
/** Thread dedicada (Consumer) para escrita em ficheiro. */
private final Thread writerThread; private final Thread writerThread;
private final AtomicBoolean running; private final AtomicBoolean running;
private final SimpleDateFormat timestampFormat; private final SimpleDateFormat timestampFormat;
private final long simulationStartMillis; private final long simulationStartMillis;
/** Construtor privado para padrão singleton */ /**
* Inicializa o sistema de logs.
* Abre o ficheiro, escreve o cabeçalho e inicia a thread consumidora.
*
* @param logFilePath Caminho relativo ou absoluto do ficheiro de log.
* @throws IOException Se não for possível criar ou escrever no ficheiro.
*/
private EventLogger(String logFilePath) throws IOException { private EventLogger(String logFilePath) throws IOException {
// Auto-flush ativado para garantir persistência, mas gerido pelo buffer do BufferedWriter
this.writer = new PrintWriter(new BufferedWriter(new FileWriter(logFilePath, false)), true); this.writer = new PrintWriter(new BufferedWriter(new FileWriter(logFilePath, false)), true);
this.logQueue = new LinkedBlockingQueue<>(10000); this.logQueue = new LinkedBlockingQueue<>(10000); // Backpressure: limita a 10k eventos pendentes
this.running = new AtomicBoolean(true); this.running = new AtomicBoolean(true);
this.timestampFormat = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss.SSS"); this.timestampFormat = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss.SSS");
this.simulationStartMillis = System.currentTimeMillis(); this.simulationStartMillis = System.currentTimeMillis();
// Header inicial do log
writer.println("=".repeat(80)); writer.println("=".repeat(80));
writer.println("SIMULATION EVENT LOG"); writer.println("SIMULATION EVENT LOG");
writer.println("Started: " + timestampFormat.format(new Date())); writer.println("Started: " + timestampFormat.format(new Date()));
@@ -47,11 +69,16 @@ public class EventLogger {
writer.flush(); writer.flush();
this.writerThread = new Thread(this::processLogQueue, "EventLogger-Writer"); this.writerThread = new Thread(this::processLogQueue, "EventLogger-Writer");
this.writerThread.setDaemon(true); this.writerThread.setDaemon(true); // Permite que a JVM termine se apenas esta thread sobrar
this.writerThread.start(); this.writerThread.start();
} }
/** Obtém ou cria a instância singleton */ /**
* Obtém a instância única do logger (Lazy Initialization).
* Se não existir, cria uma predefinida em "logs/simulation-events.log".
*
* @return A instância singleton.
*/
public static EventLogger getInstance() { public static EventLogger getInstance() {
if (instance == null) { if (instance == null) {
synchronized (instanceLock) { synchronized (instanceLock) {
@@ -72,7 +99,8 @@ public class EventLogger {
} }
/** /**
* Initialize with custom log file path. * Reinicializa o logger com um ficheiro específico.
* Útil para testes ou configurações personalizadas.
*/ */
public static void initialize(String logFilePath) throws IOException { public static void initialize(String logFilePath) throws IOException {
synchronized (instanceLock) { synchronized (instanceLock) {
@@ -84,7 +112,13 @@ public class EventLogger {
} }
/** /**
* Logs an event (non-blocking). * Regista um evento genérico.
* Esta operação é não-bloqueante (retorna imediatamente após colocar na fila),
* exceto se a fila estiver cheia (backpressure).
*
* @param eventType Categoria do evento.
* @param component Nome do componente (ex: "Coordinator", "IntersectionProcess").
* @param description Detalhes do evento.
*/ */
public void log(EventType eventType, String component, String description) { public void log(EventType eventType, String component, String description) {
if (!running.get()) return; if (!running.get()) return;
@@ -96,7 +130,7 @@ public class EventLogger {
description description
); );
// Non-blocking offer - if queue is full, drop oldest // Non-blocking offer - if queue is full, drop oldest or warn
if (!logQueue.offer(entry)) { if (!logQueue.offer(entry)) {
// Queue full - this shouldn't happen with 10k buffer, but handle gracefully // Queue full - this shouldn't happen with 10k buffer, but handle gracefully
System.err.println("EventLogger queue full - dropping event: " + eventType); System.err.println("EventLogger queue full - dropping event: " + eventType);
@@ -104,14 +138,14 @@ public class EventLogger {
} }
/** /**
* Logs an event with vehicle context. * Regista um evento associado a um veículo específico (Helper method).
*/ */
public void logVehicle(EventType eventType, String component, String vehicleId, String description) { public void logVehicle(EventType eventType, String component, String vehicleId, String description) {
log(eventType, component, "[" + vehicleId + "] " + description); log(eventType, component, "[" + vehicleId + "] " + description);
} }
/** /**
* Logs an error event. * Regista um erro ou exceção com formatação apropriada.
*/ */
public void logError(String component, String description, Exception e) { public void logError(String component, String description, Exception e) {
String fullDescription = description + (e != null ? ": " + e.getMessage() : ""); String fullDescription = description + (e != null ? ": " + e.getMessage() : "");
@@ -119,11 +153,13 @@ public class EventLogger {
} }
/** /**
* Background thread that writes log entries to file. * Lógica da thread consumidora (Worker Thread).
* Retira eventos da fila e escreve no disco continuamente.
*/ */
private void processLogQueue() { private void processLogQueue() {
while (running.get() || !logQueue.isEmpty()) { while (running.get() || !logQueue.isEmpty()) {
try { try {
// Poll com timeout para permitir verificar a flag 'running' periodicamente
LogEntry entry = logQueue.poll(100, java.util.concurrent.TimeUnit.MILLISECONDS); LogEntry entry = logQueue.poll(100, java.util.concurrent.TimeUnit.MILLISECONDS);
if (entry != null) { if (entry != null) {
writeEntry(entry); writeEntry(entry);
@@ -134,7 +170,7 @@ public class EventLogger {
} }
} }
// Flush remaining entries // Flush final: garantir que eventos restantes na fila são escritos antes de morrer
while (!logQueue.isEmpty()) { while (!logQueue.isEmpty()) {
LogEntry entry = logQueue.poll(); LogEntry entry = logQueue.poll();
if (entry != null) { if (entry != null) {
@@ -144,7 +180,7 @@ public class EventLogger {
} }
/** /**
* Writes a single log entry to file. * Formata e escreve uma entrada de log no PrintWriter.
*/ */
private void writeEntry(LogEntry entry) { private void writeEntry(LogEntry entry) {
String timestamp = timestampFormat.format(new Date(entry.timestampMillis)); String timestamp = timestampFormat.format(new Date(entry.timestampMillis));
@@ -158,7 +194,7 @@ public class EventLogger {
entry.description entry.description
); );
// Flush periodically for real-time viewing // Flush periódico inteligente: se a carga for baixa, garante que vemos logs em tempo real
if (logQueue.size() < 10) { if (logQueue.size() < 10) {
writer.flush(); writer.flush();
} }
@@ -170,15 +206,17 @@ public class EventLogger {
} }
/** /**
* Shuts down the logger and flushes all pending entries. * Encerra o logger de forma segura.
* Desativa a aceitação de novos eventos, aguarda que a fila esvazie (flush)
* e fecha o ficheiro.
*/ */
public void shutdown() { public void shutdown() {
if (!running.compareAndSet(true, false)) { if (!running.compareAndSet(true, false)) {
return; // Already shut down return; // Já encerrado
} }
try { try {
// Wait for writer thread to finish // Wait for writer thread to finish flushing
writerThread.join(5000); // Wait up to 5 seconds writerThread.join(5000); // Wait up to 5 seconds
// Write footer // Write footer
@@ -195,7 +233,7 @@ public class EventLogger {
} }
/** /**
* Internal class to represent a log entry. * DTO interno imutável para armazenar dados do evento na fila.
*/ */
private static class LogEntry { private static class LogEntry {
final long timestampMillis; final long timestampMillis;

16
main/src/main/java/sd/logging/EventType.java
View File

@@ -1,34 +1,46 @@
package sd.logging; package sd.logging;
/** /**
* Tipos de eventos que podem ocorrer na simulação. * Taxonomia oficial de eventos para o subsistema de logging centralizado.
* Usados para categorizar e filtrar logs. * <p>
* Este enumerado padroniza a categorização de todas as ocorrências na simulação, permitindo:
* <ul>
* <li>Filtragem granular de logs (ex: ver apenas erros ou apenas tráfego de rede).</li>
* <li>Análise estatística post-mortem (parsear logs para calcular latências).</li>
* <li>Correlação de eventos distribuídos (seguir o rastro de um veículo através de vários nós).</li>
* </ul>
*/ */
public enum EventType { public enum EventType {
// --- Ciclo de Vida do Veículo ---
VEHICLE_GENERATED("Vehicle Generated"), VEHICLE_GENERATED("Vehicle Generated"),
VEHICLE_ARRIVED("Vehicle Arrived"), VEHICLE_ARRIVED("Vehicle Arrived"),
VEHICLE_QUEUED("Vehicle Queued"), VEHICLE_QUEUED("Vehicle Queued"),
VEHICLE_DEPARTED("Vehicle Departed"), VEHICLE_DEPARTED("Vehicle Departed"),
VEHICLE_EXITED("Vehicle Exited"), VEHICLE_EXITED("Vehicle Exited"),
// --- Controlo de Semáforos e Exclusão Mútua ---
LIGHT_CHANGED_GREEN("Light Changed to Green"), LIGHT_CHANGED_GREEN("Light Changed to Green"),
LIGHT_CHANGED_RED("Light Changed to Red"), LIGHT_CHANGED_RED("Light Changed to Red"),
LIGHT_REQUEST_GREEN("Light Requested Green"), LIGHT_REQUEST_GREEN("Light Requested Green"),
LIGHT_RELEASE_GREEN("Light Released Green"), LIGHT_RELEASE_GREEN("Light Released Green"),
// --- Ciclo de Vida da Simulação/Processos ---
SIMULATION_STARTED("Simulation Started"), SIMULATION_STARTED("Simulation Started"),
SIMULATION_STOPPED("Simulation Stopped"), SIMULATION_STOPPED("Simulation Stopped"),
PROCESS_STARTED("Process Started"), PROCESS_STARTED("Process Started"),
PROCESS_STOPPED("Process Stopped"), PROCESS_STOPPED("Process Stopped"),
// --- Configuração e Telemetria ---
STATS_UPDATE("Statistics Update"), STATS_UPDATE("Statistics Update"),
CONFIG_CHANGED("Configuration Changed"), CONFIG_CHANGED("Configuration Changed"),
// --- Camada de Rede (TCP/Sockets) ---
CONNECTION_ESTABLISHED("Connection Established"), CONNECTION_ESTABLISHED("Connection Established"),
CONNECTION_LOST("Connection Lost"), CONNECTION_LOST("Connection Lost"),
MESSAGE_SENT("Message Sent"), MESSAGE_SENT("Message Sent"),
MESSAGE_RECEIVED("Message Received"), MESSAGE_RECEIVED("Message Received"),
// --- Tratamento de Exceções ---
ERROR("Error"); ERROR("Error");
private final String displayName; private final String displayName;

77
main/src/main/java/sd/logging/VehicleTracer.java
View File

@@ -12,16 +12,18 @@ import java.util.concurrent.ConcurrentHashMap;
import sd.model.Vehicle; import sd.model.Vehicle;
/** /**
* Rastreia e regista a viagem completa de veículos individuais. * Subsistema de auditoria granular responsável pelo rastreio detalhado (Tracing) de veículos individuais.
*
* <p> * <p>
* Cria ficheiros de trace detalhados com: * Diferente do {@link EventLogger} (que regista eventos globais do sistema), esta classe foca-se
* na perspetiva do <b>agente</b>. Cria um ficheiro de rastro dedicado (`.trace`) para cada veículo
* monitorizado, registando cronologicamente cada interação com a infraestrutura (interseções,
* filas, semáforos).
* <p>
* <b>Funcionalidades:</b>
* <ul> * <ul>
* <li>Timestamps de todos os eventos * <li>Análise forense de percursos individuais.</li>
* <li>Localizações (interseções) * <li>Validação de tempos de espera e travessia por nó.</li>
* <li>Tempos de espera em cada semáforo * <li>Cálculo de eficiência de rota (tempo em movimento vs. tempo parado).</li>
* <li>Tempos de travessia
* <li>Tempo total no sistema
* </ul> * </ul>
*/ */
public class VehicleTracer { public class VehicleTracer {
@@ -29,12 +31,18 @@ public class VehicleTracer {
private static VehicleTracer instance; private static VehicleTracer instance;
private static final Object instanceLock = new Object(); private static final Object instanceLock = new Object();
/** Mapa thread-safe de sessões de trace ativas (VehicleID -> TraceHandler). */
private final Map<String, VehicleTrace> trackedVehicles; private final Map<String, VehicleTrace> trackedVehicles;
private final SimpleDateFormat timestampFormat; private final SimpleDateFormat timestampFormat;
private final long simulationStartMillis; private final long simulationStartMillis;
private final String traceDirectory; private final String traceDirectory;
/** Construtor privado (singleton) */ /**
* Inicializa o tracer e prepara o diretório de saída.
*
* @param traceDirectory Caminho para armazenamento dos ficheiros .trace.
*/
private VehicleTracer(String traceDirectory) { private VehicleTracer(String traceDirectory) {
this.trackedVehicles = new ConcurrentHashMap<>(); this.trackedVehicles = new ConcurrentHashMap<>();
this.timestampFormat = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss.SSS"); this.timestampFormat = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss.SSS");
@@ -48,7 +56,10 @@ public class VehicleTracer {
} }
} }
/** Obtém ou cria a instância singleton */ /**
* Obtém a instância única do tracer (Singleton).
* @return A instância global.
*/
public static VehicleTracer getInstance() { public static VehicleTracer getInstance() {
if (instance == null) { if (instance == null) {
synchronized (instanceLock) { synchronized (instanceLock) {
@@ -60,7 +71,10 @@ public class VehicleTracer {
return instance; return instance;
} }
/** Inicializa com diretório de trace customizado */ /**
* Reinicializa o tracer com um diretório personalizado.
* Útil para isolar logs de diferentes execuções em lote.
*/
public static void initialize(String traceDirectory) { public static void initialize(String traceDirectory) {
synchronized (instanceLock) { synchronized (instanceLock) {
if (instance != null) { if (instance != null) {
@@ -71,12 +85,14 @@ public class VehicleTracer {
} }
/** /**
* Começa a rastrear um veículo específico. * Inicia a sessão de rastreio para um veículo específico.
* Cria ficheiro de trace para este veículo. * Cria o ficheiro {@code logs/traces/vehicle-{id}.trace} e escreve o cabeçalho.
*
* @param vehicleId O identificador único do veículo.
*/ */
public void startTracking(String vehicleId) { public void startTracking(String vehicleId) {
if (trackedVehicles.containsKey(vehicleId)) { if (trackedVehicles.containsKey(vehicleId)) {
return; // Already tracking return; // Já está a ser rastreado
} }
VehicleTrace trace = new VehicleTrace(vehicleId, traceDirectory); VehicleTrace trace = new VehicleTrace(vehicleId, traceDirectory);
@@ -86,7 +102,7 @@ public class VehicleTracer {
} }
/** /**
* Stops tracking a vehicle and closes its trace file. * Encerra a sessão de rastreio, fecha o descritor de ficheiro e remove da memória.
*/ */
public void stopTracking(String vehicleId) { public void stopTracking(String vehicleId) {
VehicleTrace trace = trackedVehicles.remove(vehicleId); VehicleTrace trace = trackedVehicles.remove(vehicleId);
@@ -97,14 +113,14 @@ public class VehicleTracer {
} }
/** /**
* Checks if a vehicle is being tracked. * Verifica se um veículo está atualmente sob auditoria.
*/ */
public boolean isTracking(String vehicleId) { public boolean isTracking(String vehicleId) {
return trackedVehicles.containsKey(vehicleId); return trackedVehicles.containsKey(vehicleId);
} }
/** /**
* Logs when a vehicle is generated. * Regista o evento de instanciação do veículo pelo Coordenador.
*/ */
public void logGenerated(Vehicle vehicle) { public void logGenerated(Vehicle vehicle) {
if (!isTracking(vehicle.getId())) if (!isTracking(vehicle.getId()))
@@ -119,7 +135,7 @@ public class VehicleTracer {
} }
/** /**
* Logs when a vehicle arrives at an intersection. * Regista a chegada física do veículo à zona de deteção de uma interseção.
*/ */
public void logArrival(String vehicleId, String intersection, double simulationTime) { public void logArrival(String vehicleId, String intersection, double simulationTime) {
if (!isTracking(vehicleId)) if (!isTracking(vehicleId))
@@ -133,7 +149,7 @@ public class VehicleTracer {
} }
/** /**
* Logs when a vehicle is queued at a traffic light. * Regista a entrada do veículo na estrutura de fila de um semáforo.
*/ */
public void logQueued(String vehicleId, String intersection, String direction, int queuePosition) { public void logQueued(String vehicleId, String intersection, String direction, int queuePosition) {
if (!isTracking(vehicleId)) if (!isTracking(vehicleId))
@@ -147,7 +163,7 @@ public class VehicleTracer {
} }
/** /**
* Logs when a vehicle starts waiting at a red light. * Regista o início da espera ativa (veículo parado no Vermelho).
*/ */
public void logWaitingStart(String vehicleId, String intersection, String direction) { public void logWaitingStart(String vehicleId, String intersection, String direction) {
if (!isTracking(vehicleId)) if (!isTracking(vehicleId))
@@ -161,7 +177,8 @@ public class VehicleTracer {
} }
/** /**
* Logs when a vehicle finishes waiting (light turns green). * Regista o fim da espera (Sinal Verde).
* @param waitTime Duração total da paragem nesta instância.
*/ */
public void logWaitingEnd(String vehicleId, String intersection, String direction, double waitTime) { public void logWaitingEnd(String vehicleId, String intersection, String direction, double waitTime) {
if (!isTracking(vehicleId)) if (!isTracking(vehicleId))
@@ -175,7 +192,7 @@ public class VehicleTracer {
} }
/** /**
* Logs when a vehicle starts crossing an intersection. * Regista o início da travessia da interseção (ocupação da zona crítica).
*/ */
public void logCrossingStart(String vehicleId, String intersection, String direction) { public void logCrossingStart(String vehicleId, String intersection, String direction) {
if (!isTracking(vehicleId)) if (!isTracking(vehicleId))
@@ -189,7 +206,7 @@ public class VehicleTracer {
} }
/** /**
* Logs when a vehicle finishes crossing an intersection. * Regista a libertação da zona crítica da interseção.
*/ */
public void logCrossingEnd(String vehicleId, String intersection, double crossingTime) { public void logCrossingEnd(String vehicleId, String intersection, double crossingTime) {
if (!isTracking(vehicleId)) if (!isTracking(vehicleId))
@@ -203,7 +220,7 @@ public class VehicleTracer {
} }
/** /**
* Logs when a vehicle departs from an intersection. * Regista a partida da interseção em direção ao próximo nó.
*/ */
public void logDeparture(String vehicleId, String intersection, String nextDestination) { public void logDeparture(String vehicleId, String intersection, String nextDestination) {
if (!isTracking(vehicleId)) if (!isTracking(vehicleId))
@@ -217,7 +234,10 @@ public class VehicleTracer {
} }
/** /**
* Logs when a vehicle exits the system. * Regista a saída do sistema (no Exit Node).
* <p>
* Este método também desencadeia a escrita do <b>Sumário de Viagem</b> no final do log
* e fecha o ficheiro automaticamente.
*/ */
public void logExit(Vehicle vehicle, double systemTime) { public void logExit(Vehicle vehicle, double systemTime) {
if (!isTracking(vehicle.getId())) if (!isTracking(vehicle.getId()))
@@ -229,7 +249,7 @@ public class VehicleTracer {
String.format("Exited system - Total time: %.2fs, Waiting: %.2fs, Crossing: %.2fs", String.format("Exited system - Total time: %.2fs, Waiting: %.2fs, Crossing: %.2fs",
systemTime, vehicle.getTotalWaitingTime(), vehicle.getTotalCrossingTime())); systemTime, vehicle.getTotalWaitingTime(), vehicle.getTotalCrossingTime()));
// Write summary // Escreve estatísticas sumarizadas
trace.writeSummary(vehicle, systemTime); trace.writeSummary(vehicle, systemTime);
// Stop tracking and close file // Stop tracking and close file
@@ -238,7 +258,8 @@ public class VehicleTracer {
} }
/** /**
* Shuts down the tracer and closes all trace files. * Fecha forçosamente todos os traces abertos.
* Deve ser chamado no shutdown da simulação para evitar corrupção de logs.
*/ */
public void shutdown() { public void shutdown() {
for (VehicleTrace trace : trackedVehicles.values()) { for (VehicleTrace trace : trackedVehicles.values()) {
@@ -248,7 +269,7 @@ public class VehicleTracer {
} }
/** /**
* Internal class to handle tracing for a single vehicle. * Classe interna auxiliar que gere o descritor de ficheiro e a formatação para um único veículo.
*/ */
private class VehicleTrace { private class VehicleTrace {
private final String vehicleId; private final String vehicleId;

78
main/src/main/java/sd/model/Message.java
View File

@@ -5,41 +5,52 @@ import java.util.UUID;
import sd.protocol.MessageProtocol; import sd.protocol.MessageProtocol;
/** /**
* Representa uma mensagem trocada entre processos na simulação distribuída. * Envelope fundamental do protocolo de comunicação entre processos distribuídos (IPC).
* * <p>
* <p>Cada mensagem tem um ID único, tipo, remetente, destino e payload. * Esta classe atua como a Unidade de Dados de Aplicação (ADU), encapsulando tanto
* Implementa {@link MessageProtocol} que estende Serializable para transmissão pela rede.</p> * os metadados de roteamento (origem, destino, tipo) quanto a carga útil (payload)
* polimórfica. É agnóstica ao conteúdo, servindo como contentor genérico para
* transferência de estado (Veículos, Estatísticas) ou sinais de controlo (Semáforos).
* <p>
* A imutabilidade dos campos (exceto via serialização) garante a integridade da mensagem
* durante o trânsito na rede.
*/ */
public class Message implements MessageProtocol { public class Message implements MessageProtocol {
private static final long serialVersionUID = 1L; private static final long serialVersionUID = 1L;
/** Identificador único desta mensagem */ /** * Identificador único universal (UUID).
* Essencial para rastreabilidade (tracing), logs de auditoria e mecanismos de deduplicação.
*/
private final String messageId; private final String messageId;
/** Tipo desta mensagem (ex: VEHICLE_TRANSFER, STATS_UPDATE) */ /** Discriminador semântico que define como o recetor deve processar o payload. */
private final MessageType type; private final MessageType type;
/** Identificador do processo que enviou esta mensagem */ /** Identificador lógico do nó emissor (ex: "Cr1", "Coordinator"). */
private final String senderId; private final String senderId;
/** Identificador do processo de destino (pode ser null para broadcast) */ /** * Identificador lógico do nó recetor.
* Se {@code null}, a mensagem deve ser tratada como <b>Broadcast</b>.
*/
private final String destinationId; private final String destinationId;
/** Dados a serem transmitidos (o tipo depende do tipo de mensagem) */ /** * Carga útil polimórfica.
* Deve implementar {@link java.io.Serializable} para garantir transmissão correta.
*/
private final Object payload; private final Object payload;
/** Timestamp de criação da mensagem (tempo de simulação ou real) */ /** Marca temporal da criação da mensagem (Unix Timestamp), usada para cálculo de latência de rede. */
private final long timestamp; private final long timestamp;
/** /**
* Cria uma nova mensagem com todos os parâmetros. * Construtor completo para reconstrução de mensagens ou envio com timestamp manual.
* *
* @param type tipo da mensagem * @param type Classificação semântica da mensagem.
* @param senderId ID do processo remetente * @param senderId ID do processo origem.
* @param destinationId ID do processo de destino (null para broadcast) * @param destinationId ID do processo destino (ou null para broadcast).
* @param payload conteúdo da mensagem * @param payload Objeto de domínio a ser transportado.
* @param timestamp timestamp de criação da mensagem * @param timestamp Instante de criação (ms).
*/ */
public Message(MessageType type, String senderId, String destinationId, public Message(MessageType type, String senderId, String destinationId,
Object payload, long timestamp) { Object payload, long timestamp) {
@@ -52,23 +63,24 @@ public class Message implements MessageProtocol {
} }
/** /**
* Cria uma nova mensagem usando o tempo atual do sistema como timestamp. * Construtor de conveniência que atribui automaticamente o timestamp atual do sistema.
* *
* @param type tipo da mensagem * @param type Classificação semântica.
* @param senderId ID do processo remetente * @param senderId ID do processo origem.
* @param destinationId ID do processo de destino * @param destinationId ID do processo destino.
* @param payload conteúdo da mensagem * @param payload Objeto de domínio.
*/ */
public Message(MessageType type, String senderId, String destinationId, Object payload) { public Message(MessageType type, String senderId, String destinationId, Object payload) {
this(type, senderId, destinationId, payload, System.currentTimeMillis()); this(type, senderId, destinationId, payload, System.currentTimeMillis());
} }
/** /**
* Cria uma mensagem de broadcast (sem destino específico). * Construtor de conveniência para mensagens de difusão (Broadcast).
* Define {@code destinationId} como null.
* *
* @param type tipo da mensagem * @param type Classificação semântica.
* @param senderId ID do processo remetente * @param senderId ID do processo origem.
* @param payload conteúdo da mensagem * @param payload Objeto de domínio.
*/ */
public Message(MessageType type, String senderId, Object payload) { public Message(MessageType type, String senderId, Object payload) {
this(type, senderId, null, payload, System.currentTimeMillis()); this(type, senderId, null, payload, System.currentTimeMillis());
@@ -101,21 +113,23 @@ public class Message implements MessageProtocol {
} }
/** /**
* Checks if this is a broadcast message (no specific destination). * Verifica se a mensagem se destina a todos os nós da rede.
* *
* @return true if destinationId is null, false otherwise * @return {@code true} se o destinationId for nulo.
*/ */
public boolean isBroadcast() { public boolean isBroadcast() {
return destinationId == null; return destinationId == null;
} }
/** /**
* Gets the payload cast to a specific type. * Utilitário para casting seguro e fluente do payload.
* Use with caution and ensure type safety. * <p>
* Evita a necessidade de casts explícitos e supressão de warnings no código cliente.
* *
* @param <T> The expected payload type * @param <T> O tipo esperado do payload.
* @return The payload cast to type T * @param clazz A classe do tipo esperado para verificação em runtime (opcional no uso, mas boa prática).
* @throws ClassCastException if the payload is not of type T * @return O payload convertido para o tipo T.
* @throws ClassCastException Se o payload não for compatível com o tipo solicitado.
*/ */
@SuppressWarnings("unchecked") @SuppressWarnings("unchecked")
public <T> T getPayloadAs(Class<T> clazz) { public <T> T getPayloadAs(Class<T> clazz) {

103
main/src/main/java/sd/protocol/SocketConnection.java
View File

@@ -16,10 +16,17 @@ import sd.serialization.MessageSerializer;
import sd.serialization.SerializationException; import sd.serialization.SerializationException;
import sd.serialization.SerializerFactory; import sd.serialization.SerializerFactory;
/** /**
* Simplifica comunicação via sockets. * Wrapper de alto nível para gestão robusta de conexões TCP.
* Inclui lógica de retry para robustez. * <p>
* Esta classe abstrai a complexidade da API nativa {@link java.net.Socket}, oferecendo:
* <ol>
* <li><b>Resiliência:</b> Lógica de reconexão automática (Retry Loop) no arranque, crucial para sistemas
* distribuídos onde a ordem de inicialização dos nós não é garantida.</li>
* <li><b>Framing:</b> Implementação transparente do protocolo "Length-Prefix" (4 bytes de tamanho + payload),
* resolvendo o problema de fragmentação de stream TCP.</li>
* <li><b>Serialização:</b> Integração direta com a camada de serialização JSON.</li>
* </ol>
*/ */
public class SocketConnection implements Closeable { public class SocketConnection implements Closeable {
@@ -28,20 +35,24 @@ public class SocketConnection implements Closeable {
private final InputStream inputStream; private final InputStream inputStream;
private final MessageSerializer serializer; private final MessageSerializer serializer;
/** Número máximo de tentativas de ligação */ /** Número máximo de tentativas de ligação antes de desistir (Fail-fast). */
private static final int MAX_RETRIES = 5; private static final int MAX_RETRIES = 5;
/** Atraso entre tentativas (milissegundos) */
/** Janela de espera (backoff) linear entre tentativas (em milissegundos). */
private static final long RETRY_DELAY_MS = 1000; private static final long RETRY_DELAY_MS = 1000;
/** /**
* Construtor do cliente que inicia a ligação. * Construtor para clientes (Active Open).
* Tenta ligar a um servidor já em escuta, com retry. * Tenta estabelecer uma conexão TCP com um servidor, aplicando lógica de retry.
* <p>
* Este comportamento é vital quando o processo Coordenador inicia antes das Interseções estarem
* prontas para aceitar conexões ({@code accept()}).
* *
* @param host endereço do host (ex: "localhost") * @param host Endereço do nó de destino (ex: "localhost").
* @param port número da porta * @param port Porta de serviço.
* @throws IOException se falhar após todas as tentativas * @throws IOException Se a conexão falhar após todas as {@code MAX_RETRIES} tentativas.
* @throws UnknownHostException se o host não for encontrado * @throws UnknownHostException Se o DNS não resolver o hostname.
* @throws InterruptedException se a thread for interrompida * @throws InterruptedException Se a thread for interrompida durante o sleep de retry.
*/ */
public SocketConnection(String host, int port) throws IOException, UnknownHostException, InterruptedException { public SocketConnection(String host, int port) throws IOException, UnknownHostException, InterruptedException {
Socket tempSocket = null; Socket tempSocket = null;
@@ -52,7 +63,7 @@ public class SocketConnection implements Closeable {
// --- Retry Loop --- // --- Retry Loop ---
for (int attempt = 1; attempt <= MAX_RETRIES; attempt++) { for (int attempt = 1; attempt <= MAX_RETRIES; attempt++) {
try { try {
// Try to establish the connection // Try to establish the connection (SYN -> SYN-ACK -> ACK)
tempSocket = new Socket(host, port); tempSocket = new Socket(host, port);
// If successful, break out of the retry loop // If successful, break out of the retry loop
@@ -61,17 +72,17 @@ public class SocketConnection implements Closeable {
break; break;
} catch (ConnectException | SocketTimeoutException e) { } catch (ConnectException | SocketTimeoutException e) {
// These are common errors indicating the server might not be ready. // Common errors: "Connection refused" (server not up) or "Timeout" (firewall/network)
lastException = e; lastException = e;
System.out.printf("[SocketConnection] Attempt %d/%d failed: %s. Retrying in %d ms...%n", System.out.printf("[SocketConnection] Attempt %d/%d failed: %s. Retrying in %d ms...%n",
attempt, MAX_RETRIES, e.getMessage(), RETRY_DELAY_MS); attempt, MAX_RETRIES, e.getMessage(), RETRY_DELAY_MS);
if (attempt < MAX_RETRIES) { if (attempt < MAX_RETRIES) {
// Wait before the next attempt // Blocking wait before next attempt
TimeUnit.MILLISECONDS.sleep(RETRY_DELAY_MS); TimeUnit.MILLISECONDS.sleep(RETRY_DELAY_MS);
} }
} catch (IOException e) { } catch (IOException e) {
// Other IOExceptions might be more permanent, but we retry anyway. // Other IO errors
lastException = e; lastException = e;
System.out.printf("[SocketConnection] Attempt %d/%d failed with IOException: %s. Retrying in %d ms...%n", System.out.printf("[SocketConnection] Attempt %d/%d failed with IOException: %s. Retrying in %d ms...%n",
attempt, MAX_RETRIES, e.getMessage(), RETRY_DELAY_MS); attempt, MAX_RETRIES, e.getMessage(), RETRY_DELAY_MS);
@@ -81,51 +92,49 @@ public class SocketConnection implements Closeable {
} }
} // --- End of Retry Loop --- } // --- End of Retry Loop ---
// If after all retries tempSocket is still null, it means connection failed permanently. // Final validation
if (tempSocket == null) { if (tempSocket == null) {
System.err.printf("[SocketConnection] Failed to connect to %s:%d after %d attempts.%n", host, port, MAX_RETRIES); System.err.printf("[SocketConnection] Failed to connect to %s:%d after %d attempts.%n", host, port, MAX_RETRIES);
if (lastException != null) { if (lastException != null) {
throw lastException; // Throw the last exception encountered throw lastException; // Propagate the root cause
} else { } else {
// Should not happen if loop ran, but as a fallback
throw new IOException("Failed to connect after " + MAX_RETRIES + " attempts, reason unknown."); throw new IOException("Failed to connect after " + MAX_RETRIES + " attempts, reason unknown.");
} }
} }
// If connection was successful, assign to final variable and create streams // Initialize streams
this.socket = tempSocket; this.socket = tempSocket;
this.outputStream = socket.getOutputStream(); this.outputStream = socket.getOutputStream();
this.inputStream = socket.getInputStream(); this.inputStream = socket.getInputStream();
this.serializer = SerializerFactory.createDefault(); this.serializer = SerializerFactory.createDefault();
} }
/** /**
* Constructor for the "Server" (who accepts the connection). * Construtor para servidores (Passive Open).
* Receives a Socket that has already been accepted by a ServerSocket. * Envolve um socket já conectado (retornado por {@code serverSocket.accept()}).
* No retry logic needed here as the connection is already established. * Não necessita de retry logic pois a conexão física já existe.
* *
* @param acceptedSocket The Socket returned by serverSocket.accept(). * @param acceptedSocket O socket ativo retornado pelo SO.
* @throws IOException If stream creation fails. * @throws IOException Se falhar a obtenção dos streams de I/O.
*/ */
public SocketConnection(Socket acceptedSocket) throws IOException { public SocketConnection(Socket acceptedSocket) throws IOException {
this.socket = acceptedSocket; this.socket = acceptedSocket;
this.outputStream = socket.getOutputStream(); this.outputStream = socket.getOutputStream();
this.inputStream = socket.getInputStream(); this.inputStream = socket.getInputStream();
this.serializer = SerializerFactory.createDefault(); this.serializer = SerializerFactory.createDefault();
} }
/** /**
* Sends (serializes) a MessageProtocol object over the socket. * Serializa e transmite uma mensagem através do canal.
* <p>
* Utiliza sincronização ({@code synchronized}) para garantir que escritas concorrentes
* na mesma conexão não corrompem a stream de bytes (thread-safety).
* *
* @param message The "envelope" (which contains the Vehicle) to be sent. * @param message O objeto de protocolo a enviar.
* @throws IOException If writing to the stream fails or socket is not connected. * @throws IOException Se o socket estiver fechado ou ocorrer erro de escrita.
*/ */
public synchronized void sendMessage(MessageProtocol message) throws IOException { public synchronized void sendMessage(MessageProtocol message) throws IOException {
if (socket == null || !socket.isConnected()) { if (socket == null || !socket.isConnected()) {
throw new IOException("Socket is not connected"); throw new IOException("Socket is not connected");
} }
@@ -133,11 +142,11 @@ public class SocketConnection implements Closeable {
// Serializa para bytes JSON // Serializa para bytes JSON
byte[] data = serializer.serialize(message); byte[] data = serializer.serialize(message);
// Write 4-byte length prefix // Write 4-byte length prefix (Framing)
DataOutputStream dataOut = new DataOutputStream(outputStream); DataOutputStream dataOut = new DataOutputStream(outputStream);
dataOut.writeInt(data.length); dataOut.writeInt(data.length);
dataOut.write(data); dataOut.write(data);
dataOut.flush(); dataOut.flush(); // Force transmission immediately
} catch (SerializationException e) { } catch (SerializationException e) {
throw new IOException("Failed to serialize message", e); throw new IOException("Failed to serialize message", e);
@@ -145,11 +154,14 @@ public class SocketConnection implements Closeable {
} }
/** /**
* Tries to read (deserialize) a MessageProtocol object from the socket. * Bloqueia à espera de uma mensagem completa do socket.
* <p>
* Lê primeiro o cabeçalho de tamanho (4 bytes) e depois o payload exato,
* garantindo que processa mensagens completas mesmo se chegarem fragmentadas em múltiplos pacotes TCP.
* *
* @return The "envelope" (MessageProtocol) that was received. * @return O objeto {@link MessageProtocol} reconstruído.
* @throws IOException If the connection is lost, the stream is corrupted, or socket is not connected. * @throws IOException Se a conexão for perdida (EOF) ou o stream corrompido.
* @throws ClassNotFoundException If the received object is unknown. * @throws ClassNotFoundException Se o tipo desserializado não for encontrado no classpath.
*/ */
public MessageProtocol receiveMessage() throws IOException, ClassNotFoundException { public MessageProtocol receiveMessage() throws IOException, ClassNotFoundException {
if (socket == null || !socket.isConnected()) { if (socket == null || !socket.isConnected()) {
@@ -161,15 +173,16 @@ public class SocketConnection implements Closeable {
DataInputStream dataIn = new DataInputStream(inputStream); DataInputStream dataIn = new DataInputStream(inputStream);
int length = dataIn.readInt(); int length = dataIn.readInt();
if (length <= 0 || length > 10_000_000) { // Sanity check (10MB max) // Sanity check para evitar OutOfMemory em caso de corrupção de stream
if (length <= 0 || length > 10_000_000) { // Max 10MB payload
throw new IOException("Invalid message length: " + length); throw new IOException("Invalid message length: " + length);
} }
// Ler dados da mensagem // Ler dados exatos da mensagem
byte[] data = new byte[length]; byte[] data = new byte[length];
dataIn.readFully(data); dataIn.readFully(data);
// Deserialize do JSON - use concrete Message class, not interface // Deserialize do JSON - força o tipo concreto Message
return serializer.deserialize(data, sd.model.Message.class); return serializer.deserialize(data, sd.model.Message.class);
} catch (SerializationException e) { } catch (SerializationException e) {
@@ -178,7 +191,8 @@ public class SocketConnection implements Closeable {
} }
/** /**
* Closes the socket and all streams (Input and Output). * Encerra a conexão e liberta os descritores de ficheiro.
* Operação idempotente.
*/ */
@Override @Override
public void close() throws IOException { public void close() throws IOException {
@@ -188,7 +202,8 @@ public class SocketConnection implements Closeable {
} }
/** /**
* @return true if the socket is still connected and not closed. * Verifica o estado operacional da conexão.
* @return true se o socket está aberto e conectado.
*/ */
public boolean isConnected() { public boolean isConnected() {
return socket != null && socket.isConnected() && !socket.isClosed(); return socket != null && socket.isConnected() && !socket.isClosed();

66
main/src/main/java/sd/serialization/JsonMessageSerializer.java
View File

@@ -1,26 +1,25 @@
package sd.serialization; package sd.serialization;
import java.nio.charset.StandardCharsets;
import com.google.gson.Gson; import com.google.gson.Gson;
import com.google.gson.GsonBuilder; import com.google.gson.GsonBuilder;
import com.google.gson.JsonSyntaxException; import com.google.gson.JsonSyntaxException;
import java.nio.charset.StandardCharsets;
/** /**
* JSON-based implementation of {@link MessageSerializer} using Google's Gson library. * Implementação baseada em JSON da estratégia {@link MessageSerializer}, utilizando a biblioteca Gson.
* * <p>
* This serializer converts objects to JSON format for transmission, providing: * Este serializador converte objetos Java para o formato de texto JSON antes da transmissão.
* - Human-readable message format (easy debugging) * Oferece várias vantagens técnicas sobre a serialização nativa do Java:
* - Cross-platform compatibility * <ul>
* - Smaller message sizes compared to Java native serialization * <li><b>Legibilidade:</b> O formato de texto facilita a depuração (sniffing de rede) sem ferramentas especializadas.</li>
* - Better security (no code execution during deserialization) * <li><b>Interoperabilidade:</b> Permite futura integração com componentes não-Java (ex: Dashboards web em JS).</li>
* * <li><b>Segurança:</b> Reduz a superfície de ataque para execução remota de código (RCE), pois não desserializa classes arbitrárias, apenas dados.</li>
* The serializer is configured with pretty printing disabled by default for * </ul>
* production use, but can be enabled for debugging purposes. * <p>
* * <b>Thread-Safety:</b> A instância interna do {@code Gson} é imutável e thread-safe, permitindo
* Thread-safety: This class is thread-safe as Gson instances are thread-safe. * que este serializador seja partilhado entre múltiplas threads (ex: no pool do DashboardServer).
* * * @see MessageSerializer
* @see MessageSerializer
*/ */
public class JsonMessageSerializer implements MessageSerializer { public class JsonMessageSerializer implements MessageSerializer {
@@ -28,16 +27,16 @@ public class JsonMessageSerializer implements MessageSerializer {
private final boolean prettyPrint; private final boolean prettyPrint;
/** /**
* Creates a new JSON serializer with default configuration (no pretty printing). * Cria um novo serializador JSON com configuração otimizada para produção (compacto).
*/ */
public JsonMessageSerializer() { public JsonMessageSerializer() {
this(false); this(false);
} }
/** /**
* Creates a new JSON serializer with optional pretty printing. * Cria um novo serializador JSON com formatação opcional.
* * * @param prettyPrint Se {@code true}, o JSON gerado incluirá indentação e quebras de linha.
* @param prettyPrint If true, JSON output will be formatted with indentation * Útil para debug, mas aumenta significativamente o tamanho do payload.
*/ */
public JsonMessageSerializer(boolean prettyPrint) { public JsonMessageSerializer(boolean prettyPrint) {
this.prettyPrint = prettyPrint; this.prettyPrint = prettyPrint;
@@ -53,6 +52,13 @@ public class JsonMessageSerializer implements MessageSerializer {
this.gson = builder.create(); this.gson = builder.create();
} }
/**
* Converte um objeto em memória para um array de bytes JSON (UTF-8).
*
* @param object O objeto a ser serializado.
* @return O payload em bytes pronto para transmissão TCP.
* @throws SerializationException Se o objeto não for compatível com JSON ou ocorrer erro de encoding.
*/
@Override @Override
public byte[] serialize(Object object) throws SerializationException { public byte[] serialize(Object object) throws SerializationException {
if (object == null) { if (object == null) {
@@ -68,6 +74,16 @@ public class JsonMessageSerializer implements MessageSerializer {
} }
} }
/**
* Reconstrói um objeto Java a partir de um array de bytes JSON.
* <p>
* Realiza a validação sintática do JSON e a validação de tipo baseada na classe alvo.
*
* @param data O array de bytes recebido da rede.
* @param clazz A classe do objeto esperado (Type Token).
* @return A instância do objeto reconstruído.
* @throws SerializationException Se o JSON for malformado ou incompatível com a classe alvo.
*/
@Override @Override
public <T> T deserialize(byte[] data, Class<T> clazz) throws SerializationException { public <T> T deserialize(byte[] data, Class<T> clazz) throws SerializationException {
if (data == null) { if (data == null) {
@@ -95,18 +111,16 @@ public class JsonMessageSerializer implements MessageSerializer {
} }
/** /**
* Returns the underlying Gson instance for advanced usage. * Retorna a instância subjacente do Gson para configurações avançadas.
* * * @return A instância Gson configurada.
* @return The Gson instance
*/ */
public Gson getGson() { public Gson getGson() {
return gson; return gson;
} }
/** /**
* Checks if pretty printing is enabled. * Verifica se a formatação "pretty print" está ativa.
* * * @return true se a indentação estiver habilitada.
* @return true if pretty printing is enabled
*/ */
public boolean isPrettyPrint() { public boolean isPrettyPrint() {
return prettyPrint; return prettyPrint;

59
main/src/main/java/sd/serialization/MessageSerializer.java
View File

@@ -1,47 +1,48 @@
package sd.serialization; package sd.serialization;
/** /**
* Interface for serializing and deserializing objects for network transmission. * Interface que define o contrato para estratégias de serialização e desserialização de objetos.
* * <p>
* This interface provides a common abstraction for different serialization strategies * Esta abstração permite desacoplar a camada de transporte (Sockets TCP) da camada de
* allowing the system to switch between implementations without changing the communication layer. * apresentação de dados. Ao implementar o padrão <b>Strategy</b>, o sistema ganha flexibilidade
* * para alternar entre diferentes formatos de codificação (JSON, Binário Nativo, XML, Protobuf)
* Implementations must ensure: * sem necessidade de refatorização da lógica de rede.
* - Thread-safety if used in concurrent contexts * <p>
* - Proper exception handling with meaningful error messages * <b>Requisitos para Implementações:</b>
* - Preservation of object state during round-trip serialization * <ul>
* * <li><b>Thread-Safety:</b> As implementações devem ser seguras para uso concorrente, dado que
* @see JsonMessageSerializer * instâncias únicas podem ser partilhadas por múltiplos <i>ClientHandlers</i>.</li>
* <li><b>Robustez:</b> Falhas de parsing devem resultar em exceções tipificadas ({@link SerializationException}),
* nunca em falhas silenciosas ou estados inconsistentes.</li>
* </ul>
* * @see JsonMessageSerializer
*/ */
public interface MessageSerializer { public interface MessageSerializer {
/** /**
* Serializes an object into a byte array for transmission. * Converte (Marshals) um objeto em memória para uma sequência de bytes para transmissão.
* * * @param object O objeto de domínio a ser serializado (não pode ser nulo).
* @param object The object to serialize (must not be null) * @return Um array de bytes contendo a representação codificada do objeto.
* @return A byte array containing the serialized representation * @throws SerializationException Se ocorrer um erro durante a codificação (ex: ciclo de referências).
* @throws SerializationException If serialization fails * @throws IllegalArgumentException Se o objeto fornecido for nulo.
* @throws IllegalArgumentException If object is null
*/ */
byte[] serialize(Object object) throws SerializationException; byte[] serialize(Object object) throws SerializationException;
/** /**
* Deserializes a byte array back into an object of the specified type. * Reconstrói (Unmarshals) um objeto a partir de uma sequência de bytes.
* * * @param <T> O tipo genérico do objeto esperado.
* @param <T> The expected type of the deserialized object * @param data O array de bytes contendo os dados serializados (não pode ser nulo).
* @param data The byte array containing serialized data (must not be null) * @param clazz A classe do tipo esperado para verificação e instancialização.
* @param clazz The class of the expected object type (must not be null) * @return A instância do objeto reconstruído com o seu estado restaurado.
* @return The deserialized object * @throws SerializationException Se os dados estiverem corrompidos ou incompatíveis com a classe alvo.
* @throws SerializationException If deserialization fails * @throws IllegalArgumentException Se os dados ou a classe forem nulos.
* @throws IllegalArgumentException If data or clazz is null
*/ */
<T> T deserialize(byte[] data, Class<T> clazz) throws SerializationException; <T> T deserialize(byte[] data, Class<T> clazz) throws SerializationException;
/** /**
* Gets the name of this serialization strategy (e.g., "JSON", "Java Native"). * Obtém o identificador legível desta estratégia de serialização (ex: "JSON (Gson)", "Native").
* Useful for logging and debugging. * Utilizado primariamente para logging, auditoria e negociação de conteúdo.
* * * @return O nome descritivo do serializador.
* @return The serializer name
*/ */
String getName(); String getName();

29
main/src/main/java/sd/serialization/SerializationException.java
View File

@@ -1,39 +1,38 @@
package sd.serialization; package sd.serialization;
/** /**
* Exception thrown when serialization or deserialization operations fail. * Exceção verificada (Checked Exception) que sinaliza falhas no processo de transformação de dados.
* * <p>
* This exception wraps underlying errors (I/O exceptions, parsing errors, etc.) * Esta classe atua como um wrapper unificador para erros ocorridos na camada de serialização,
* and provides context about what went wrong during the serialization process. * abstraindo falhas de baixo nível (como erros de I/O, sintaxe JSON inválida ou incompatibilidade
* de tipos) numa única exceção de domínio. Permite que o código cliente trate falhas de
* protocolo de forma consistente, independentemente da implementação subjacente (Gson, Nativa, etc.).
*/ */
public class SerializationException extends Exception { public class SerializationException extends Exception {
private static final long serialVersionUID = 1L; // Long(64bits) instead of int(32bits) private static final long serialVersionUID = 1L; // Long(64bits) instead of int(32bits)
/** /**
* Constructs a new serialization exception with the specified detail message. * Constrói uma nova exceção de serialização com uma mensagem descritiva.
* * * @param message A mensagem detalhando o erro.
* @param message The detail message
*/ */
public SerializationException(String message) { public SerializationException(String message) {
super(message); super(message);
} }
/** /**
* Constructs a new serialization exception with the specified detail message * Constrói uma nova exceção encapsulando a causa raiz do problema.
* and cause. * Útil para preservar a stack trace original de erros de bibliotecas terceiras (ex: Gson).
* * * @param message A mensagem detalhando o erro.
* @param message The detail message * @param cause A exceção original que causou a falha.
* @param cause The cause of this exception
*/ */
public SerializationException(String message, Throwable cause) { public SerializationException(String message, Throwable cause) {
super(message, cause); super(message, cause);
} }
/** /**
* Constructs a new serialization exception with the specified cause. * Constrói uma nova exceção baseada apenas na causa raiz.
* * * @param cause A exceção original.
* @param cause The cause of this exception
*/ */
public SerializationException(Throwable cause) { public SerializationException(Throwable cause) {
super(cause); super(cause);

48
main/src/main/java/sd/serialization/SerializerFactory.java
View File

@@ -1,14 +1,14 @@
package sd.serialization; package sd.serialization;
/** /**
* Factory for creating {@link MessageSerializer} instances. * Fábrica estática (Factory Pattern) para instanciação controlada de {@link MessageSerializer}.
* * <p>
* This factory provides a centralized way to create and configure JSON serializers * Esta classe centraliza a criação de estratégias de serialização, garantindo consistência
* using Gson, making it easy to configure serialization throughout the application. * de configuração em todo o sistema distribuído. Permite a injeção de configurações via
* * Propriedades de Sistema (System Properties), facilitando a alternância entre modos de
* The factory can be configured via system properties for easy deployment configuration. * depuração (Pretty Print) e produção (Compacto) sem recompilação.
* * <p>
* Example usage: * <b>Exemplo de Uso:</b>
* <pre> * <pre>
* MessageSerializer serializer = SerializerFactory.createDefault(); * MessageSerializer serializer = SerializerFactory.createDefault();
* byte[] data = serializer.serialize(myObject); * byte[] data = serializer.serialize(myObject);
@@ -17,28 +17,27 @@ package sd.serialization;
public class SerializerFactory { public class SerializerFactory {
/** /**
* System property key for enabling pretty-print in JSON serialization. * Chave da propriedade de sistema para ativar a formatação JSON legível (Pretty Print).
* Set to "true" for debugging, "false" for production. * Defina {@code -Dsd.serialization.json.prettyPrint=true} na JVM para ativar.
*/ */
public static final String JSON_PRETTY_PRINT_PROPERTY = "sd.serialization.json.prettyPrint"; public static final String JSON_PRETTY_PRINT_PROPERTY = "sd.serialization.json.prettyPrint";
// Default configuration // Default configuration (Production-ready)
private static final boolean DEFAULT_JSON_PRETTY_PRINT = false; private static final boolean DEFAULT_JSON_PRETTY_PRINT = false;
/** /**
* Private constructor to prevent instantiation. * Construtor privado para prevenir instanciação acidental desta classe utilitária.
*/ */
private SerializerFactory() { private SerializerFactory() {
throw new UnsupportedOperationException("Factory class cannot be instantiated"); throw new UnsupportedOperationException("Factory class cannot be instantiated");
} }
/** /**
* Creates a JSON serializer based on system configuration. * Cria um serializador JSON configurado dinamicamente pelo ambiente.
* * <p>
* Pretty-print is determined by checking the system property * Verifica a propriedade de sistema {@value #JSON_PRETTY_PRINT_PROPERTY}.
* {@value #JSON_PRETTY_PRINT_PROPERTY}. If not set, defaults to false. * Se não definida, assume o padrão de produção (falso/compacto).
* * * @return Uma instância configurada de {@link JsonMessageSerializer}.
* @return A configured JsonMessageSerializer instance
*/ */
public static MessageSerializer createDefault() { public static MessageSerializer createDefault() {
boolean prettyPrint = Boolean.getBoolean(JSON_PRETTY_PRINT_PROPERTY); boolean prettyPrint = Boolean.getBoolean(JSON_PRETTY_PRINT_PROPERTY);
@@ -46,19 +45,18 @@ public class SerializerFactory {
} }
/** /**
* Creates a JSON serializer with default configuration (no pretty printing). * Cria um serializador JSON com configuração padrão otimizada (sem indentação).
* * Ideal para ambientes de produção onde a largura de banda é prioritária.
* @return A JsonMessageSerializer instance * * @return Uma instância compacta de {@link JsonMessageSerializer}.
*/ */
public static MessageSerializer createSerializer() { public static MessageSerializer createSerializer() {
return createSerializer(DEFAULT_JSON_PRETTY_PRINT); return createSerializer(DEFAULT_JSON_PRETTY_PRINT);
} }
/** /**
* Creates a JSON serializer with specified pretty-print setting. * Cria um serializador JSON com configuração explícita de formatação.
* * * @param prettyPrint {@code true} para ativar indentação (Debug), {@code false} para compacto.
* @param prettyPrint Whether to enable pretty printing * @return Uma instância personalizada de {@link JsonMessageSerializer}.
* @return A JsonMessageSerializer instance
*/ */
public static MessageSerializer createSerializer(boolean prettyPrint) { public static MessageSerializer createSerializer(boolean prettyPrint) {
return new JsonMessageSerializer(prettyPrint); return new JsonMessageSerializer(prettyPrint);

96
main/src/main/java/sd/util/RandomGenerator.java
View File

@@ -3,82 +3,88 @@ package sd.util;
import java.util.Random; import java.util.Random;
/** /**
* Utilitário para gerar valores aleatórios usados na simulação. * Utilitário central de geração estocástica para a simulação.
* * <p>
* <p>Fornece métodos estáticos para:</p> * Esta classe fornece primitivas para geração de números pseudo-aleatórios, abstraindo
* a complexidade de distribuições estatísticas.
* <p>
* <b>Funcionalidades Principais:</b>
* <ul> * <ul>
* <li>Gerar intervalos exponencialmente distribuídos (processos de Poisson)</li> * <li><b>Modelagem de Poisson:</b> Geração de tempos entre chegadas usando distribuição exponencial inversa.</li>
* <li>Gerar inteiros e doubles aleatórios num intervalo</li> * <li><b>Amostragem Uniforme:</b> Geração de inteiros e doubles em intervalos fechados/abertos.</li>
* <li>Tomar decisões baseadas em probabilidade</li> * <li><b>Decisão Probabilística:</b> Avaliação de eventos booleanos baseados em pesos (Bernoulli trials).</li>
* <li>Escolher elementos aleatórios de um array</li> * <li><b>Determinismo:</b> Suporte a sementes (seeds) manuais para reprodutibilidade exata de cenários de teste.</li>
* </ul> * </ul>
*
* <p>Usa uma única instância estática de {@link Random}.</p>
*/ */
public class RandomGenerator { public class RandomGenerator {
/** Instância partilhada de Random para toda a simulação */ /** * Instância singleton estática do gerador PRNG (Pseudo-Random Number Generator).
* Thread-safe (java.util.Random é sincronizado), embora possa haver contenção em alta concorrência.
*/
private static final Random random = new Random(); private static final Random random = new Random();
/** /**
* Retorna um intervalo de tempo que segue uma distribuição exponencial. * Gera um intervalo de tempo seguindo uma Distribuição Exponencial.
* <p>
* Este método implementa o algoritmo de <i>Inverse Transform Sampling</i> para simular
* um Processo de Poisson homogêneo. É fundamental para modelar a chegada natural de
* veículos, onde eventos independentes ocorrem a uma taxa média constante.
* <p>
* <b>Fórmula Matemática:</b> {@code T = -ln(1 - U) / λ}
* <br>Onde:
* <ul>
* <li>{@code U}: Variável aleatória uniforme no intervalo [0, 1).</li>
* <li>{@code λ (lambda)}: Taxa média de eventos por unidade de tempo (ex: veículos/segundo).</li>
* </ul>
* *
* <p>Componente essencial para modelar processos de Poisson, onde os * @param lambda A taxa média de chegada (λ > 0).
* tempos entre chegadas seguem uma distribuição exponencial.</p> * @return O intervalo de tempo (delta t) até o próximo evento, em segundos.
*
* <p>Fórmula: {@code Time = -ln(1 - U) / λ}<br>
* onde U é um número aleatório uniforme [0, 1) e λ (lambda) é a taxa média de chegada.</p>
*
* @param lambda taxa média de chegada λ (ex: 0.5 veículos por segundo)
* @return intervalo de tempo (segundos) até à próxima chegada
*/ */
public static double generateExponentialInterval(double lambda) { public static double generateExponentialInterval(double lambda) {
return Math.log(1 - random.nextDouble()) / -lambda; return Math.log(1 - random.nextDouble()) / -lambda;
} }
/** /**
* Retorna um inteiro aleatório entre {@code min} e {@code max}, inclusive. * Gera um número inteiro uniformemente distribuído no intervalo fechado {@code [min, max]}.
* *
* @param min valor mínimo possível * @param min Limite inferior (inclusivo).
* @param max valor máximo possível * @param max Limite superior (inclusivo).
* @return inteiro aleatório no intervalo [min, max] * @return Um inteiro aleatório I tal que {@code min <= I <= max}.
*/ */
public static int generateRandomInt(int min, int max) { public static int generateRandomInt(int min, int max) {
return random.nextInt(max - min + 1) + min; return random.nextInt(max - min + 1) + min;
} }
/** /**
* Retorna um double aleatório entre {@code min} (inclusive) e {@code max} (exclusivo). * Gera um número de ponto flutuante uniformemente distribuído no intervalo semi-aberto {@code [min, max)}.
* *
* @param min valor mínimo possível * @param min Limite inferior (inclusivo).
* @param max valor máximo possível * @param max Limite superior (exclusivo).
* @return double aleatório no intervalo [min, max) * @return Um double aleatório D tal que {@code min <= D < max}.
*/ */
public static double generateRandomDouble(double min, double max) { public static double generateRandomDouble(double min, double max) {
return min + (max - min) * random.nextDouble(); return min + (max - min) * random.nextDouble();
} }
/** /**
* Retorna {@code true} com uma dada probabilidade. * Realiza um teste de Bernoulli (Sim/Não) com uma probabilidade de sucesso especificada.
* <p>
* Utilizado para decisões de ramificação estocástica (ex: "Este veículo é um camião?").
* *
* <p>Útil para tomar decisões ponderadas. Por exemplo, * @param probability A probabilidade de retorno {@code true} (0.0 a 1.0).
* {@code occursWithProbability(0.3)} retorna {@code true} * @return {@code true} se o evento ocorrer, {@code false} caso contrário.
* aproximadamente 30% das vezes.</p>
*
* @param probability valor entre 0.0 (nunca) e 1.0 (sempre)
* @return {@code true} ou {@code false}, baseado na probabilidade
*/ */
public static boolean occursWithProbability(double probability) { public static boolean occursWithProbability(double probability) {
return random.nextDouble() < probability; return random.nextDouble() < probability;
} }
/** /**
* Escolhe um elemento aleatório do array fornecido. * Seleciona aleatoriamente um elemento de um array genérico (Amostragem Uniforme Discreta).
* *
* @param <T> tipo genérico do array * @param <T> O tipo dos elementos no array.
* @param array array de onde escolher * @param array A população de onde escolher.
* @return elemento selecionado aleatoriamente * @return O elemento selecionado.
* @throws IllegalArgumentException se o array for null ou vazio * @throws IllegalArgumentException Se o array for nulo ou vazio.
*/ */
public static <T> T chooseRandom(T[] array) { public static <T> T chooseRandom(T[] array) {
if (array == null || array.length == 0) { if (array == null || array.length == 0) {
@@ -88,13 +94,13 @@ public class RandomGenerator {
} }
/** /**
* Define a seed do gerador de números aleatórios partilhado. * Reinicializa a semente (seed) do gerador global.
* <p>
* <b>Importância Crítica:</b> Permite tornar a simulação determinística. Ao fixar a seed,
* a sequência de números "aleatórios" gerada será idêntica em execuções subsequentes,
* facilitando a depuração de race conditions ou lógica complexa.
* *
* <p>Extremamente útil para debugging e testes, pois permite executar * @param seed O valor da semente inicial (ex: timestamp ou constante).
* a simulação múltiplas vezes com a mesma sequência de eventos "aleatórios",
* tornando os resultados reproduzíveis.</p>
*
* @param seed seed a usar
*/ */
public static void setSeed(long seed) { public static void setSeed(long seed) {
random.setSeed(seed); random.setSeed(seed);

117
main/src/main/java/sd/util/VehicleGenerator.java
View File

@@ -9,55 +9,58 @@ import sd.model.VehicleType;
import sd.routing.RouteSelector; import sd.routing.RouteSelector;
/** /**
* Gera veículos para a simulação. * Motor de injeção de carga (Load Injector) para a simulação de tráfego.
* * <p>
* <p>Esta classe é responsável por duas tarefas principais:</p> * Esta classe atua como uma fábrica estocástica de veículos, sendo responsável por:
* <ol> * <ol>
* <li>Determinar <em>quando</em> o próximo veículo deve chegar, baseado no * <li><b>Modelagem Temporal:</b> Determinar os instantes de chegada (Inter-arrival times)
* modelo de chegada (POISSON ou FIXED) da {@link SimulationConfig}</li> * usando processos de Poisson (estocástico) ou intervalos determinísticos.</li>
* <li>Criar um novo objeto {@link Vehicle} com tipo e rota selecionados pela * <li><b>Caracterização da Entidade:</b> Atribuir tipos de veículo (Bike, Light, Heavy)
* política de roteamento configurada ({@link RouteSelector})</li> * baseado numa Distribuição de Probabilidade Cumulativa (CDF).</li>
* <li><b>Inicialização Espacial:</b> Distribuir a carga uniformemente entre os pontos de entrada (E1-E3).</li>
* <li><b>Atribuição de Rota:</b> Delegar a escolha do percurso à estratégia {@link RouteSelector} ativa.</li>
* </ol> * </ol>
*
* <p>As rotas são selecionadas usando uma política de roteamento que pode ser:
* aleatória, caminho mais curto, menor congestionamento, etc.</p>
*/ */
public class VehicleGenerator { public class VehicleGenerator {
private final SimulationConfig config; private final SimulationConfig config;
private final String arrivalModel; private final String arrivalModel;
/** Lambda (λ) para modelo POISSON */
/** Parâmetro Lambda (λ) para a distribuição de Poisson (taxa de chegada). */
private final double arrivalRate; private final double arrivalRate;
/** Intervalo para modelo FIXED */
/** Intervalo determinístico para geração constante (modo debug/teste). */
private final double fixedInterval; private final double fixedInterval;
/** Política de roteamento usada para selecionar rotas */ /** * Estratégia de roteamento atual.
* Não é final para permitir Hot-Swapping durante a execução.
*/
private RouteSelector routeSelector; private RouteSelector routeSelector;
/** /**
* Cria um novo gerador de veículos com a política de roteamento especificada. * Inicializa o gerador com as configurações de simulação e estratégia de roteamento.
* Lê a configuração necessária.
* *
* @param config objeto de {@link SimulationConfig} * @param config A configuração global contendo as taxas e probabilidades.
* @param routeSelector política de roteamento a usar para selecionar rotas * @param routeSelector A estratégia inicial de seleção de rotas.
*/ */
public VehicleGenerator(SimulationConfig config, RouteSelector routeSelector) { public VehicleGenerator(SimulationConfig config, RouteSelector routeSelector) {
this.config = config; this.config = config;
this.routeSelector = routeSelector; this.routeSelector = routeSelector;
// Cache configuration values for performance // Cache de valores de configuração para evitar lookups repetitivos em hot-path
this.arrivalModel = config.getArrivalModel(); this.arrivalModel = config.getArrivalModel();
this.arrivalRate = config.getArrivalRate(); this.arrivalRate = config.getArrivalRate();
this.fixedInterval = config.getFixedArrivalInterval(); this.fixedInterval = config.getFixedArrivalInterval();
} }
/** /**
* Calcula o tempo <em>absoluto</em> da próxima chegada de veículo * Calcula o timestamp absoluto para a próxima injeção de veículo.
* baseado no modelo configurado. * <p>
* * Se o modelo for "POISSON", utiliza a técnica de <i>Inverse Transform Sampling</i>
* @param currentTime tempo atual da simulação, usado como base * (via {@link RandomGenerator}) para gerar intervalos exponencialmente distribuídos,
* @return tempo absoluto (ex: {@code currentTime + intervalo}) * simulando a aleatoriedade natural do tráfego.
* em que o próximo veículo deve ser gerado * * @param currentTime O tempo atual da simulação (base de cálculo).
* @return O instante futuro (t + delta) para agendamento do evento de geração.
*/ */
public double getNextArrivalTime(double currentTime) { public double getNextArrivalTime(double currentTime) {
if ("POISSON".equalsIgnoreCase(arrivalModel)) { if ("POISSON".equalsIgnoreCase(arrivalModel)) {
@@ -69,19 +72,19 @@ public class VehicleGenerator {
} }
/** /**
* Gera um novo objeto {@link Vehicle}. * Instancia (Spawn) um novo veículo configurado e roteado.
* * <p>
* <p>Passos executados:</p> * O processo de criação segue um pipeline:
* <ol> * <ol>
* <li>Seleciona um {@link VehicleType} aleatório baseado em probabilidades</li> * <li>Seleção de Tipo (Roda da Fortuna / CDF).</li>
* <li>Seleciona um ponto de entrada aleatório (E1, E2, E3)</li> * <li>Seleção de Entrada (Uniforme).</li>
* <li>Usa a política de roteamento para escolher a rota</li> * <li>Cálculo de Rota (Delegado ao Strategy).</li>
* </ol> * </ol>
* *
* @param vehicleId identificador único do novo veículo (ex: "V123") * @param vehicleId O identificador único sequencial (ex: "V104").
* @param entryTime tempo de simulação em que o veículo é criado * @param entryTime O timestamp de criação.
* @param queueSizes mapa com tamanho das filas (opcional, pode ser null) * @param queueSizes Snapshot atual das filas (usado apenas por estratégias dinâmicas como LEAST_CONGESTED).
* @return novo objeto {@link Vehicle} configurado * @return A entidade {@link Vehicle} pronta para inserção na malha.
*/ */
public Vehicle generateVehicle(String vehicleId, double entryTime, Map<String, Integer> queueSizes) { public Vehicle generateVehicle(String vehicleId, double entryTime, Map<String, Integer> queueSizes) {
VehicleType type = selectVehicleType(); VehicleType type = selectVehicleType();
@@ -92,18 +95,12 @@ public class VehicleGenerator {
} }
/** /**
* Seleciona um {@link VehicleType} (BIKE, LIGHT, HEAVY) baseado nas * Seleciona o tipo de veículo usando Amostragem por Probabilidade Cumulativa.
* probabilidades definidas na {@link SimulationConfig}. * <p>
* Normaliza as probabilidades configuradas e mapeia um número aleatório [0, 1)
* para o intervalo correspondente ao tipo de veículo.
* *
* <p>Usa técnica de "probabilidade cumulativa":</p> * @return O tipo enumerado {@link VehicleType} selecionado.
* <ol>
* <li>Obtém número aleatório {@code rand} de [0, 1)</li>
* <li>Se {@code rand < P(Bike)}, retorna BIKE</li>
* <li>Senão se {@code rand < P(Bike) + P(Light)}, retorna LIGHT</li>
* <li>Caso contrário, retorna HEAVY</li>
* </ol>
*
* @return tipo de veículo selecionado
*/ */
private VehicleType selectVehicleType() { private VehicleType selectVehicleType() {
double bikeProbability = config.getBikeVehicleProbability(); double bikeProbability = config.getBikeVehicleProbability();
@@ -111,7 +108,9 @@ public class VehicleGenerator {
double heavyProbability = config.getHeavyVehicleProbability(); double heavyProbability = config.getHeavyVehicleProbability();
double total = bikeProbability + lightProbability + heavyProbability; double total = bikeProbability + lightProbability + heavyProbability;
if (total == 0) return VehicleType.LIGHT; // Avoid division by zero if (total == 0) return VehicleType.LIGHT; // Fallback de segurança
// Normalização
bikeProbability /= total; bikeProbability /= total;
lightProbability /= total; lightProbability /= total;
@@ -127,10 +126,10 @@ public class VehicleGenerator {
} }
/** /**
* Seleciona aleatoriamente um ponto de entrada (E1, E2 ou E3). * Seleciona um ponto de injeção na borda da rede (Edge Node).
* Cada ponto tem probabilidade igual (1/3). * Distribuição Uniforme: ~33.3% para cada entrada (E1, E2, E3).
* *
* @return ponto de entrada selecionado ("E1", "E2" ou "E3") * @return O ID da interseção de entrada.
*/ */
private String selectRandomEntryPoint() { private String selectRandomEntryPoint() {
double rand = Math.random(); double rand = Math.random();
@@ -145,23 +144,19 @@ public class VehicleGenerator {
} }
/** /**
* Altera dinamicamente o RouteSelector usado para gerar rotas. * Atualiza a estratégia de roteamento em tempo de execução (Hot-Swap).
* Permite mudar a política de roteamento durante a simulação. * <p>
* * Permite que o Coordenador altere o comportamento da frota (ex: de RANDOM para SHORTEST_PATH)
* @param newRouteSelector novo seletor de rotas * sem necessidade de reiniciar a simulação.
* * @param newRouteSelector A nova implementação de estratégia a utilizar.
*/ */
public void setRouteSelector(RouteSelector newRouteSelector) { public void setRouteSelector(RouteSelector newRouteSelector) {
// Note: In Java, we can't directly modify the 'final' field, this.routeSelector = newRouteSelector;
// but we can create a new VehicleGenerator with the new selector.
// For this implementation, we'll need to remove 'final' from routeSelector.
// This is acceptable since we want dynamic policy changes.
throw new UnsupportedOperationException(
"VehicleGenerator is immutable. Use CoordinatorProcess.changeRoutingPolicy() instead."
);
} }
/** /**
* @return A string providing information about the generator's configuration. * Retorna uma representação textual do estado interno do gerador.
* Útil para logs de auditoria e debugging.
*/ */
public String getInfo() { public String getInfo() {
return String.format( return String.format(