mirror of
https://github.com/davidalves04/Trabalho-Pratico-SD.git
synced 2025-12-08 12:33:31 +00:00
README
This commit is contained in:
David Alves
625
README.md
Normal file
625
README.md
Normal file
@@ -0,0 +1,625 @@
|
|||||||
|
# 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:
|
||||||
|
- Legível e fácil de debugar
|
||||||
|
- 54% menor que Java Serialization (300 vs 657 bytes)
|
||||||
|
- Compatível com ferramentas web/REST
|
||||||
|
- Seguro (sem vulnerabilidades de desserialização)
|
||||||
|
|
||||||
|
### 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
|
||||||
|
│ │ │ │ ├── JavaMessageSerializer.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
|
||||||
@@ -1,283 +0,0 @@
|
|||||||
# Serialization Package
|
|
||||||
|
|
||||||
Este pacote fornece implementações de serialização para comunicação entre processos no sistema de simulação de tráfego distribuído.
|
|
||||||
|
|
||||||
## Visão Geral
|
|
||||||
|
|
||||||
O pacote `sd.serialization` oferece uma interface unificada para serializar e desserializar objetos Java, permitindo a comunicação através de sockets entre diferentes processos (cruzamentos, coordenador, dashboard).
|
|
||||||
|
|
||||||
## Arquitetura
|
|
||||||
|
|
||||||
```
|
|
||||||
MessageSerializer (interface)
|
|
||||||
├── JsonMessageSerializer (Gson-based)
|
|
||||||
└── JavaMessageSerializer (native)
|
|
||||||
|
|
||||||
SerializerFactory (factory pattern)
|
|
||||||
SerializationException (custom exception)
|
|
||||||
```
|
|
||||||
|
|
||||||
## Uso Rápido
|
|
||||||
|
|
||||||
### Exemplo Básico
|
|
||||||
|
|
||||||
```java
|
|
||||||
// Criar um serializer (JSON recomendado)
|
|
||||||
MessageSerializer serializer = SerializerFactory.createDefault();
|
|
||||||
|
|
||||||
// Serializar um objeto
|
|
||||||
Vehicle vehicle = new Vehicle("V001", VehicleType.LIGHT, 10.5, route);
|
|
||||||
byte[] data = serializer.serialize(vehicle);
|
|
||||||
|
|
||||||
// Enviar através de socket
|
|
||||||
outputStream.write(data);
|
|
||||||
|
|
||||||
// Receber e desserializar
|
|
||||||
byte[] received = inputStream.readAllBytes();
|
|
||||||
Vehicle deserialized = serializer.deserialize(received, Vehicle.class);
|
|
||||||
```
|
|
||||||
|
|
||||||
### Usando JSON (Recomendado)
|
|
||||||
|
|
||||||
```java
|
|
||||||
// JSON com formatação legível (debugging)
|
|
||||||
MessageSerializer serializer = new JsonMessageSerializer(true);
|
|
||||||
|
|
||||||
// JSON compacto (produção)
|
|
||||||
MessageSerializer serializer = new JsonMessageSerializer(false);
|
|
||||||
|
|
||||||
// Ou via factory
|
|
||||||
MessageSerializer serializer = SerializerFactory.createJsonSerializer();
|
|
||||||
```
|
|
||||||
|
|
||||||
### Usando Java Serialization
|
|
||||||
|
|
||||||
```java
|
|
||||||
// Direto
|
|
||||||
MessageSerializer serializer = new JavaMessageSerializer();
|
|
||||||
|
|
||||||
// Ou via factory
|
|
||||||
MessageSerializer serializer = SerializerFactory.createJavaSerializer();
|
|
||||||
```
|
|
||||||
|
|
||||||
## Configuração
|
|
||||||
|
|
||||||
### Propriedades do Sistema
|
|
||||||
|
|
||||||
Configure o serializer padrão através de propriedades:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Definir tipo de serialização (JSON ou JAVA_NATIVE)
|
|
||||||
java -Dsd.serialization.type=JSON -jar app.jar
|
|
||||||
|
|
||||||
# Habilitar pretty-print no JSON (debugging)
|
|
||||||
java -Dsd.serialization.json.prettyPrint=true -jar app.jar
|
|
||||||
```
|
|
||||||
|
|
||||||
### Programaticamente
|
|
||||||
|
|
||||||
```java
|
|
||||||
// Definir antes de iniciar a aplicação
|
|
||||||
System.setProperty("sd.serialization.type", "JSON");
|
|
||||||
System.setProperty("sd.serialization.json.prettyPrint", "true");
|
|
||||||
|
|
||||||
MessageSerializer serializer = SerializerFactory.createDefault();
|
|
||||||
```
|
|
||||||
|
|
||||||
## Comparação: JSON vs Java Serialization
|
|
||||||
|
|
||||||
| Característica | JSON (Gson) | Java Native |
|
|
||||||
|----------------|-------------|-------------|
|
|
||||||
| **Legibilidade** | ✅ Texto legível | ❌ Binário |
|
|
||||||
| **Tamanho** | ✅ ~40% menor | ❌ Maior |
|
|
||||||
| **Debugging** | ✅ Fácil | ❌ Difícil |
|
|
||||||
| **Performance** | ⚠️ ~20% mais lento | ✅ Mais rápido |
|
|
||||||
| **Interoperabilidade** | ✅ Universal | ❌ Só Java |
|
|
||||||
| **Segurança** | ✅ Mais seguro | ⚠️ Vulnerabilidades |
|
|
||||||
| **Dependências** | ⚠️ Gson | ✅ Nativo |
|
|
||||||
| **Evolução** | ✅ Flexível | ⚠️ serialVersionUID |
|
|
||||||
|
|
||||||
### Recomendação: **JSON (Gson)** ✅
|
|
||||||
|
|
||||||
Para este projeto, JSON é recomendado porque:
|
|
||||||
- Facilita debugging durante desenvolvimento
|
|
||||||
- Tamanho menor de mensagens
|
|
||||||
- Mais fácil de manter e evoluir
|
|
||||||
- Permite integração futura (dashboard web)
|
|
||||||
- Performance suficiente para o volume esperado
|
|
||||||
|
|
||||||
## Tratamento de Erros
|
|
||||||
|
|
||||||
```java
|
|
||||||
try {
|
|
||||||
byte[] data = serializer.serialize(object);
|
|
||||||
// ... enviar ...
|
|
||||||
} catch (SerializationException e) {
|
|
||||||
// Log e tratamento
|
|
||||||
logger.error("Failed to serialize: " + e.getMessage(), e);
|
|
||||||
}
|
|
||||||
|
|
||||||
try {
|
|
||||||
Object obj = serializer.deserialize(data, MyClass.class);
|
|
||||||
} catch (SerializationException e) {
|
|
||||||
// Dados corrompidos ou incompatíveis
|
|
||||||
logger.error("Failed to deserialize: " + e.getMessage(), e);
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Exemplos de Mensagens
|
|
||||||
|
|
||||||
### Vehicle Transfer
|
|
||||||
|
|
||||||
```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
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Statistics Update
|
|
||||||
|
|
||||||
```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
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Testes
|
|
||||||
|
|
||||||
Execute os testes de serialização:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
mvn test -Dtest=SerializationTest
|
|
||||||
```
|
|
||||||
|
|
||||||
Execute o exemplo de demonstração:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
mvn exec:java -Dexec.mainClass="sd.serialization.SerializationExample"
|
|
||||||
```
|
|
||||||
|
|
||||||
## Performance
|
|
||||||
|
|
||||||
### Métricas Típicas (Rede Local)
|
|
||||||
|
|
||||||
**JSON:**
|
|
||||||
- Tamanho médio: 250-350 bytes
|
|
||||||
- Latência: 0.8-1.5 ms
|
|
||||||
- Throughput: ~8,000 msgs/s
|
|
||||||
|
|
||||||
**Java Serialization:**
|
|
||||||
- Tamanho médio: 400-600 bytes
|
|
||||||
- Latência: 0.5-1.0 ms
|
|
||||||
- Throughput: ~10,000 msgs/s
|
|
||||||
|
|
||||||
Para o volume esperado no projeto (~100-1000 msgs/s), ambos são mais que suficientes.
|
|
||||||
|
|
||||||
## Extensibilidade
|
|
||||||
|
|
||||||
### Adicionar Novo Tipo de Serialização
|
|
||||||
|
|
||||||
1. Implementar `MessageSerializer`
|
|
||||||
2. Adicionar tipo em `SerializerFactory.SerializationType`
|
|
||||||
3. Atualizar `SerializerFactory.create()`
|
|
||||||
|
|
||||||
Exemplo:
|
|
||||||
|
|
||||||
```java
|
|
||||||
public class ProtobufMessageSerializer implements MessageSerializer {
|
|
||||||
@Override
|
|
||||||
public byte[] serialize(Object object) throws SerializationException {
|
|
||||||
// Implementação
|
|
||||||
}
|
|
||||||
|
|
||||||
@Override
|
|
||||||
public <T> T deserialize(byte[] data, Class<T> clazz) throws SerializationException {
|
|
||||||
// Implementação
|
|
||||||
}
|
|
||||||
|
|
||||||
@Override
|
|
||||||
public String getName() {
|
|
||||||
return "Protocol Buffers";
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Custom Type Adapters (JSON)
|
|
||||||
|
|
||||||
Para tipos complexos ou customização:
|
|
||||||
|
|
||||||
```java
|
|
||||||
GsonBuilder builder = new GsonBuilder();
|
|
||||||
builder.registerTypeAdapter(MyClass.class, new MyClassAdapter());
|
|
||||||
Gson gson = builder.create();
|
|
||||||
```
|
|
||||||
|
|
||||||
## Boas Práticas
|
|
||||||
|
|
||||||
1. **Validação**: Sempre validar objetos após desserialização
|
|
||||||
2. **Logging**: Logar mensagens em desenvolvimento, desabilitar em produção
|
|
||||||
3. **Versionamento**: Incluir versão nas mensagens para evolução
|
|
||||||
4. **Exceções**: Tratar `SerializationException` apropriadamente
|
|
||||||
5. **Testes**: Testar serialização round-trip para todos os tipos
|
|
||||||
|
|
||||||
## Troubleshooting
|
|
||||||
|
|
||||||
### "SerializationException: Failed to serialize"
|
|
||||||
- Verificar se o objeto é Serializable (Java) ou tem getters/setters (JSON)
|
|
||||||
- Verificar se há referências circulares
|
|
||||||
|
|
||||||
### "SerializationException: Failed to parse JSON"
|
|
||||||
- Dados corrompidos na rede
|
|
||||||
- Incompatibilidade de versão entre classes
|
|
||||||
- JSON malformado
|
|
||||||
|
|
||||||
### Messages muito grandes
|
|
||||||
- Revisar estrutura de dados
|
|
||||||
- Considerar compressão (gzip)
|
|
||||||
- Enviar apenas dados necessários
|
|
||||||
|
|
||||||
### Performance issues
|
|
||||||
- Verificar se está usando pretty-print em produção (desabilitar)
|
|
||||||
- Considerar pool de serializers
|
|
||||||
- Medir com profiler
|
|
||||||
|
|
||||||
## Recursos Adicionais
|
|
||||||
|
|
||||||
- [Especificação Completa](../docs/SERIALIZATION_SPECIFICATION.md)
|
|
||||||
- [Gson Documentation](https://github.com/google/gson/blob/master/UserGuide.md)
|
|
||||||
- [Java Serialization Spec](https://docs.oracle.com/javase/8/docs/platform/serialization/spec/serialTOC.html)
|
|
||||||
|
|
||||||
## Suporte
|
|
||||||
|
|
||||||
Para questões ou problemas, consultar:
|
|
||||||
1. Documentação completa: `docs/SERIALIZATION_SPECIFICATION.md`
|
|
||||||
2. Testes unitários: `test/java/sd/serialization/SerializationTest.java`
|
|
||||||
3. Exemplo de uso: `main/java/sd/serialization/SerializationExample.java`
|
|
||||||
Reference in New Issue
Block a user