# Sistema de Simulação de Tráfego Distribuído Sistema distribuído de simulação de tráfego. --- ## Índice - [Visão Geral](#visão-geral) - [Arquitetura](#arquitetura) - [Protocolo de Comunicação](#protocolo-de-comunicação) - [Estrutura do Projeto](#estrutura-do-projeto) - [Instalação e Execução](#instalação-e-execução) - [Documentação](#documentação) - [Desenvolvimento](#desenvolvimento) --- ## Visão Geral Este projeto implementa uma simulação distribuída de tráfego veicular numa rede de cruzamentos. O sistema utiliza: - **Processos independentes** para cada cruzamento - **Threads** para controlar os semáforos dentro de cada cruzamento - **Comunicação via sockets** para transferência de veículos entre cruzamentos - **Simulação de eventos discretos** (DES) para gerir o tempo de simulação ### Características Principais - Simulação determinística e reproduzível - Comunicação assíncrona entre processos - Protocolo de mensagens baseado em JSON - Dashboard em tempo real (planeado) - Estatísticas detalhadas de desempenho --- ## Arquitetura ### Visão Geral do Sistema ``` ┌─────────────────────────────────────────────────────────────────┐ │ SISTEMA DISTRIBUÍDO │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────┐ ┌──────────────┐ │ │ │ Coordenador │ ────────────────────────>│ Dashboard │ │ │ │ / Gerador │ │ │ │ └──────┬───────┘ └──────▲───────┘ │ │ │ │ │ │ │ Gera veículos Stats │ │ │ │ │ │ │ ▼ │ │ │ ┌─────────────────────────────────────────────────┴──────┐ │ │ │ Rede de Cruzamentos (Processos) │ │ │ │ │ │ │ │ ┌────┐ ┌────┐ ┌────┐ │ │ │ │ │Cr1 │◄───────►│Cr2 │◄───────►│Cr3 │ │ │ │ │ └─┬──┘ └─┬──┘ └─┬──┘ │ │ │ │ │ │ │ │ │ │ │ │ ┌────▼────┐ │ │ │ │ │ └────────►│ Cr4 │◄────────┘ │ │ │ │ └────┬────┘ │ │ │ │ │ │ │ │ │ ┌────▼────┐ │ │ │ │ │ Cr5 │ │ │ │ │ └────┬────┘ │ │ │ └───────────────────┼─────────────────────────────────────┤ │ │ │ │ │ │ ▼ │ │ │ ┌──────────────┐ │ │ │ │ Nó de Saída │ │ │ │ │ (S) │ │ │ │ └──────────────┘ │ │ │ │ │ └────────────────────────────────────────────────────────────┘ │ ``` ### Componentes 1. **Coordenador/Gerador**: Gera veículos e injeta no sistema 2. **Cruzamentos (Cr1-Cr5)**: Processos independentes que gerem tráfego local 3. **Nó de Saída (S)**: Recolhe estatísticas de veículos que saem do sistema 4. **Dashboard Server**: Agrega e exibe dados em tempo real --- ## Protocolo de Comunicação ### Formato de Serialização: JSON (Gson) O sistema utiliza JSON como formato de serialização por ser mais rápido, seguro e legível que a serialização em Java. ### Estrutura de Mensagens Todas as mensagens seguem o formato base: ```json { "messageId": "uuid", "type": "MESSAGE_TYPE", "senderId": "sender_id", "destinationId": "destination_id", "timestamp": 1729595234567, "payload": { ... } } ``` ### Tipos de Mensagens #### 1. VEHICLE_TRANSFER Transfere um veículo entre cruzamentos. **Estrutura:** ```json { "messageId": "a3c5e7f9-1234-5678-90ab-cdef12345678", "type": "VEHICLE_TRANSFER", "senderId": "Cr1", "destinationId": "Cr2", "timestamp": 1729595234567, "payload": { "id": "V123", "type": "LIGHT", "entryTime": 15.7, "route": ["Cr1", "Cr2", "Cr5", "S"], "currentRouteIndex": 1, "totalWaitingTime": 3.2, "totalCrossingTime": 1.8 } } ``` **Fluxo:** 1. Veículo completa travessia no Cr1 2. Cr1 serializa mensagem VEHICLE_TRANSFER 3. Envia para Cr2 via socket 4. Cr2 desserializa e adiciona veículo à fila #### 2. STATS_UPDATE Envia estatísticas de um cruzamento para o Dashboard. **Estrutura:** ```json { "messageId": "b4d6e8f0-2345-6789-01bc-def123456789", "type": "STATS_UPDATE", "senderId": "Cr3", "destinationId": "Dashboard", "timestamp": 1729595234789, "payload": { "intersectionId": "Cr3", "queueLengths": { "North": 5, "South": 3, "East": 7, "West": 2 }, "vehiclesProcessed": 142, "averageWaitTime": 4.5, "currentTime": 123.45 } } ``` **Frequência:** A cada 10 segundos (configurável) #### 3. VEHICLE_EXIT Notifica quando um veículo sai do sistema. **Estrutura:** ```json { "messageId": "c5e7f9a1-3456-7890-12bc-def123456789", "type": "VEHICLE_EXIT", "senderId": "Cr5", "destinationId": "ExitNode", "timestamp": 1729595234890, "payload": { "id": "V123", "type": "LIGHT", "entryTime": 15.7, "exitTime": 45.2, "totalSystemTime": 29.5, "totalWaitingTime": 8.3, "totalCrossingTime": 4.8, "routeTaken": ["Cr1", "Cr2", "Cr5", "S"] } } ``` #### 4. HEARTBEAT Mantém a ligação ativa e monitoriza a saúde dos processos. **Estrutura:** ```json { "messageId": "d6e8f0a2-4567-8901-23cd-ef1234567890", "type": "HEARTBEAT", "senderId": "Cr1", "destinationId": "Coordinator", "timestamp": 1729595235000, "payload": { "status": "RUNNING", "uptime": 120.5, "vehiclesInQueue": 12 } } ``` **Frequência:** A cada 5 segundos #### 5. LIGHT_CHANGE Notifica mudança de estado de semáforo (para logging/debugging). **Estrutura:** ```json { "messageId": "e7f9a1b3-5678-9012-34de-f12345678901", "type": "LIGHT_CHANGE", "senderId": "Cr1-North", "destinationId": "Dashboard", "timestamp": 1729595235100, "payload": { "lightId": "Cr1-North", "previousState": "RED", "newState": "GREEN", "queueSize": 5 } } ``` ### Tipos de Veículos ```json { "BIKE": { "probability": 0.20, "crossingTime": 1.5 }, "LIGHT": { "probability": 0.60, "crossingTime": 2.0 }, "HEAVY": { "probability": 0.20, "crossingTime": 4.0 } } ``` ### Estados dos Semáforos ``` RED → Veículos aguardam na fila GREEN → Veículos podem atravessar ``` ### Exemplo de Comunicação Completa ``` Tempo Processo Ação Mensagem ------ --------- ------------------------------------- ------------------ 15.7s Gerador Gera veículo V123 - 15.7s Gerador → Injeta V123 em Cr1 VEHICLE_TRANSFER 18.2s Cr1 V123 inicia travessia - 20.2s Cr1 V123 completa travessia - 20.2s Cr1 → Cr2 Transfere V123 para Cr2 VEHICLE_TRANSFER 23.5s Cr2 V123 inicia travessia - 25.5s Cr2 V123 completa travessia - 25.5s Cr2 → Cr5 Transfere V123 para Cr5 VEHICLE_TRANSFER 28.0s Cr5 V123 inicia travessia - 30.0s Cr5 V123 completa travessia - 30.0s Cr5 → Exit V123 sai do sistema VEHICLE_EXIT 30.0s Exit → Dash Estatísticas de V123 STATS_UPDATE ``` --- ## Estrutura do Projeto ``` Trabalho-Pratico-SD/ ├── README.md # Este ficheiro ├── TODO.md # Plano de desenvolvimento ├── main/ │ ├── pom.xml # Configuração Maven │ ├── docs/ │ │ ├── README.md # Índice da documentação │ │ ├── SERIALIZATION_SPECIFICATION.md │ │ ├── SERIALIZATION_DECISION.md │ │ ├── SERIALIZATION_SUMMARY.md │ │ └── SERIALIZATION_ARCHITECTURE.md │ ├── src/ │ │ ├── main/java/sd/ │ │ │ ├── Entry.java # Ponto de entrada │ │ │ ├── config/ │ │ │ │ └── SimulationConfig.java │ │ │ ├── engine/ │ │ │ │ └── SimulationEngine.java │ │ │ ├── model/ │ │ │ │ ├── Event.java │ │ │ │ ├── EventType.java │ │ │ │ ├── Intersection.java │ │ │ │ ├── Message.java # Estrutura de mensagens │ │ │ │ ├── MessageType.java # Tipos de mensagens │ │ │ │ ├── TrafficLight.java │ │ │ │ ├── Vehicle.java │ │ │ │ └── VehicleType.java │ │ │ ├── serialization/ # Sistema de serialização │ │ │ │ ├── MessageSerializer.java │ │ │ │ ├── SerializationException.java │ │ │ │ ├── JsonMessageSerializer.java │ │ │ │ ├── SerializerFactory.java │ │ │ │ ├── SerializationExample.java │ │ │ │ └── README.md │ │ │ └── util/ │ │ │ ├── RandomGenerator.java │ │ │ ├── StatisticsCollector.java │ │ │ └── VehicleGenerator.java │ │ └── test/java/ │ │ ├── SimulationTest.java │ │ └── sd/serialization/ │ │ └── SerializationTest.java │ └── target/ # Ficheiros compilados └── .vscode/ # Configuração do VS Code ``` --- ## Instalação e Execução ### Pré-requisitos - **Java 17** ou superior - **Maven 3.8+** - **Git** ### Instalação ```bash # Clonar o repositório git clone https://github.com/davidalves04/Trabalho-Pratico-SD.git cd Trabalho-Pratico-SD/main # Compilar o projeto mvn clean compile # Executar os testes mvn test ``` ### Execução #### Simulação Básica (Single Process) ```bash mvn exec:java -Dexec.mainClass="sd.Entry" ``` #### Exemplo de Serialização ```bash mvn exec:java -Dexec.mainClass="sd.serialization.SerializationExample" ``` #### Configuração Editar `src/main/resources/simulation.properties`: ```properties # Duração da simulação (segundos) simulation.duration=60.0 # Modelo de chegada: FIXED ou POISSON arrival.model=POISSON # Taxa de chegada (veículos/segundo) arrival.rate=0.5 # Intervalo de atualização de estatísticas (segundos) stats.update.interval=10.0 # Distribuição de tipos de veículos vehicle.type.bike.probability=0.20 vehicle.type.light.probability=0.60 vehicle.type.heavy.probability=0.20 # Tempos de travessia por tipo (segundos) vehicle.type.bike.crossing.time=1.5 vehicle.type.light.crossing.time=2.0 vehicle.type.heavy.crossing.time=4.0 ``` --- ## Documentação ### Documentação de Serialização A documentação completa sobre o protocolo de serialização está disponível em: - **[Índice Completo](./main/docs/README.md)** - Navegação da documentação - **[Especificação](./main/docs/SERIALIZATION_SPECIFICATION.md)** - Design detalhado - **[Guia de Decisão](./main/docs/SERIALIZATION_DECISION.md)** - Porquê JSON? - **[Resumo](./main/docs/SERIALIZATION_SUMMARY.md)** - Estado de implementação - **[Arquitetura](./main/docs/SERIALIZATION_ARCHITECTURE.md)** - Diagramas visuais ### Guias de Utilização - **[Serialization README](./main/src/main/java/sd/serialization/README.md)** - Como utilizar os serializers ### Exemplos de Código ```java // Criar serializer MessageSerializer serializer = SerializerFactory.createDefault(); // Serializar mensagem Vehicle vehicle = new Vehicle("V123", VehicleType.LIGHT, 10.5, route); Message message = new Message( MessageType.VEHICLE_TRANSFER, "Cr1", "Cr2", vehicle ); byte[] data = serializer.serialize(message); // Enviar via socket outputStream.write(data); // Receber e desserializar byte[] received = inputStream.readAllBytes(); Message msg = serializer.deserialize(received, Message.class); Vehicle v = msg.getPayloadAs(Vehicle.class); ``` --- ## Desenvolvimento ### Estado do Projeto | Componente | Estado | Notas | |------------|--------|-------| | Modelo de Dados | Completo | Vehicle, Message, Event, etc. | | Simulação DES | Completo | Single-process funcional | | Serialização | Completo | JSON e Java implementados | | Testes | 14/14 | Suite de serialização | | Processos Distribuídos | Planeado | Próxima etapa | | Comunicação Sockets | Planeado | Em design | | Dashboard | Planeado | UI web | ### Roteiro de Desenvolvimento #### Fase 1: Fundações (Concluído) - Modelação de classes - Simulação DES single-process - Design de protocolo de serialização - Implementação JSON/Java serialization - Testes unitários #### Fase 2: Distribuição (Em Curso) - Implementar comunicação via sockets - Separar cruzamentos em processos - Implementar threads de semáforos - Testar comunicação entre processos #### Fase 3: Dashboard e Monitorização - Dashboard server - UI web em tempo real - Visualização de estatísticas - Logs estruturados #### Fase 4: Optimização e Análise - Testes de carga - Análise de diferentes políticas - Recolha de métricas - Relatório final ### Executar Testes ```bash # Todos os testes mvn test # Apenas testes de serialização mvn test -Dtest=SerializationTest # Com relatório de cobertura mvn test jacoco:report ``` ### Contribuir 1. Fork o projeto 2. Criar uma branch para a funcionalidade (`git checkout -b feature/MinhaFuncionalidade`) 3. Commit das alterações (`git commit -m 'Adiciona MinhaFuncionalidade'`) 4. Push para a branch (`git push origin feature/MinhaFuncionalidade`) 5. Abrir um Pull Request --- ## Métricas de Desempenho ### Serialização | Formato | Tamanho | Latência | Throughput | |---------|---------|----------|------------| | JSON | 300 bytes | 40.79 μs | ~24k msgs/s | | Java | 657 bytes | 33.34 μs | ~30k msgs/s | **Conclusão**: JSON é 54% menor com overhead desprezível (7 μs) ### Simulação - **Veículos gerados/s**: ~0.5-1.0 (configurável) - **Throughput**: ~0.2 veículos/s (saída) - **Tempo de execução**: 140ms para 60s de simulação - **Overhead**: < 0.25% do tempo simulado --- ## Protocolo de Mensagens - Resumo ### Formato Base ``` +------------------+ | Message Header | |------------------| | messageId | UUID único | type | Enum MessageType | senderId | ID do processo remetente | destinationId | ID do processo destino (null = broadcast) | timestamp | Tempo de criação (ms) +------------------+ | Payload | |------------------| | Object | Dados específicos do tipo de mensagem +------------------+ ``` ### Serialização - **Formato**: JSON (UTF-8) - **Biblioteca**: Gson 2.10.1 - **Codificação**: UTF-8 - **Compressão**: Opcional (gzip) ### Transporte - **Protocolo**: TCP/IP - **Porta base**: 5000+ (configurável) - **Timeout**: 30s - **Keep-alive**: Heartbeat a cada 5s --- ## Segurança ### Considerações 1. **Validação de Mensagens** - Verificar tipos esperados - Validar intervalos de valores - Rejeitar mensagens malformadas 2. **Autenticação** (Planeado) - Autenticação baseada em token - Whitelist de processos 3. **Encriptação** (Opcional) - TLS/SSL para produção - Não necessário para ambiente de desenvolvimento local --- ## Licença Este projeto é desenvolvido para fins académicos no âmbito da disciplina de Sistemas Distribuídos (SD) do Instituto Politécnico do Porto. --- ## Equipa **Instituição**: Instituto Politécnico do Porto **Curso**: Sistemas Distribuídos **Ano Letivo**: 2025-2026 (1º Semestre) --- ## Suporte Para questões ou problemas: 1. Consultar a [documentação](./main/docs/README.md) 2. Ver [exemplos de código](./main/src/main/java/sd/serialization/SerializationExample.java) 3. Executar testes: `mvn test` 4. Abrir issue no GitHub --- ## Ligações Úteis - [Documentação do Projeto](./main/docs/README.md) - [Plano de Desenvolvimento](./TODO.md) - [Especificação de Serialização](./main/docs/SERIALIZATION_SPECIFICATION.md) - [Guia de Serialização](./main/src/main/java/sd/serialization/README.md) --- **Última actualização**: 23 de outubro de 2025 **Versão**: 1.0.0 **Estado**: Em Desenvolvimento Activo