┌─────────────────────────────────────────────────────────────────┐
│                    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

Coordenador/Gerador: Gera veículos e injeta no sistema
Cruzamentos (Cr1-Cr5): Processos independentes que gerem tráfego local
Nó de Saída (S): Recolhe estatísticas de veículos que saem do sistema
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:

{
  "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:

{
  "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:

Veículo completa travessia no Cr1
Cr1 serializa mensagem VEHICLE_TRANSFER
Envia para Cr2 via socket
Cr2 desserializa e adiciona veículo à fila

2. STATS_UPDATE

Envia estatísticas de um cruzamento para o Dashboard.

Estrutura:

{
  "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:

{
  "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:

{
  "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:

{
  "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

{
  "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 do 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

# 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)

mvn exec:java -Dexec.mainClass="sd.Entry"

Exemplo de Serialização

mvn exec:java -Dexec.mainClass="sd.serialization.SerializationExample"

Configuração

Editar src/main/resources/simulation.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 - Navegação da documentação
Especificação - Design detalhado
Guia de Decisão - Porquê JSON?
Resumo - Estado de implementação
Arquitetura - Diagramas visuais

Guias de Utilização

Serialization README - Como utilizar os serializers

Exemplos de Código

// 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

# Todos os testes
mvn test

# Apenas testes de serialização
mvn test -Dtest=SerializationTest

# Com relatório de cobertura
mvn test jacoco:report

Contribuir

Fork o projeto
Criar uma branch para a funcionalidade (git checkout -b feature/MinhaFuncionalidade)
Commit das alterações (git commit -m 'Adiciona MinhaFuncionalidade')
Push para a branch (git push origin feature/MinhaFuncionalidade)
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

Validação de Mensagens
- Verificar tipos esperados
- Validar intervalos de valores
- Rejeitar mensagens malformadas
Autenticação (Planeado)
- Autenticação baseada em token
- Whitelist de processos
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:

Consultar a documentação
Ver exemplos de código
Executar testes: mvn test
Abrir issue no GitHub

Ligações Úteis

Última actualização: 23 de outubro de 2025
Versão: 1.0.0
Estado: Em Desenvolvimento Activo