mirror of
https://github.com/davidalves04/Trabalho-Pratico-SD.git
synced 2025-12-08 20:43:32 +00:00
Delete main/docs directory
This commit is contained in:
David Alves
@@ -1,250 +0,0 @@
|
||||
# 📚 Índice da Documentação de Serialização
|
||||
|
||||
## Visão Geral
|
||||
|
||||
Esta pasta contém toda a documentação relacionada ao design e implementação do formato de serialização para o sistema de simulação de tráfego distribuído.
|
||||
|
||||
---
|
||||
|
||||
## 📄 Documentos Disponíveis
|
||||
|
||||
### 1. [SERIALIZATION_SPECIFICATION.md](./SERIALIZATION_SPECIFICATION.md)
|
||||
**📖 Especificação Completa**
|
||||
|
||||
Documento técnico detalhado contendo:
|
||||
- Análise completa de requisitos
|
||||
- Comparação Java Serialization vs JSON
|
||||
- Justificativa da decisão
|
||||
- Estrutura de mensagens
|
||||
- Plano de implementação
|
||||
- Considerações de segurança e performance
|
||||
|
||||
**Quando usar**: Para entender a fundo todo o processo de decisão e detalhes técnicos.
|
||||
|
||||
---
|
||||
|
||||
### 2. [SERIALIZATION_DECISION.md](./SERIALIZATION_DECISION.md)
|
||||
**⚡ Guia Rápido de Decisão**
|
||||
|
||||
Documento executivo com:
|
||||
- TL;DR (resumo executivo)
|
||||
- Tabela de decisão rápida
|
||||
- Critérios por cenário
|
||||
- Análise de impacto
|
||||
- Checklist de implementação
|
||||
|
||||
**Quando usar**: Para referência rápida ou ao explicar a decisão a outros.
|
||||
|
||||
---
|
||||
|
||||
### 3. [SERIALIZATION_SUMMARY.md](./SERIALIZATION_SUMMARY.md)
|
||||
**✅ Resumo de Implementação**
|
||||
|
||||
Sumário executivo contendo:
|
||||
- Status de implementação
|
||||
- Arquivos criados
|
||||
- Métricas de performance
|
||||
- Exemplos de uso
|
||||
- Próximos passos
|
||||
|
||||
**Quando usar**: Para ver o que foi implementado e como usar.
|
||||
|
||||
---
|
||||
|
||||
### 4. [SERIALIZATION_ARCHITECTURE.md](./SERIALIZATION_ARCHITECTURE.md)
|
||||
**🏗️ Diagramas de Arquitetura**
|
||||
|
||||
Documentação visual com:
|
||||
- Diagramas ASCII da arquitetura
|
||||
- Fluxos de serialização
|
||||
- Comparação de formatos
|
||||
- Integração com o sistema
|
||||
- Cenários de uso
|
||||
|
||||
**Quando usar**: Para entender visualmente a arquitetura e fluxos.
|
||||
|
||||
---
|
||||
|
||||
## 🗂️ Estrutura do Projeto
|
||||
|
||||
```
|
||||
docs/
|
||||
├── SERIALIZATION_SPECIFICATION.md # Especificação completa
|
||||
├── SERIALIZATION_DECISION.md # Guia de decisão
|
||||
├── SERIALIZATION_SUMMARY.md # Resumo de implementação
|
||||
├── SERIALIZATION_ARCHITECTURE.md # Diagramas
|
||||
└── README.md # Este arquivo (índice)
|
||||
|
||||
src/main/java/sd/serialization/
|
||||
├── MessageSerializer.java # Interface
|
||||
├── SerializationException.java # Exceção
|
||||
├── JsonMessageSerializer.java # Implementação JSON
|
||||
├── JavaMessageSerializer.java # Implementação Java
|
||||
├── SerializerFactory.java # Factory
|
||||
├── SerializationExample.java # Exemplo de uso
|
||||
└── README.md # Guia do pacote
|
||||
|
||||
src/test/java/sd/serialization/
|
||||
└── SerializationTest.java # Testes unitários
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Início Rápido
|
||||
|
||||
### Para Desenvolvedores
|
||||
|
||||
1. **Entender a decisão**
|
||||
→ Ler [SERIALIZATION_DECISION.md](./SERIALIZATION_DECISION.md)
|
||||
|
||||
2. **Ver exemplos de uso**
|
||||
→ Ler [../src/main/java/sd/serialization/README.md](../src/main/java/sd/serialization/README.md)
|
||||
|
||||
3. **Executar exemplo**
|
||||
```bash
|
||||
mvn exec:java -Dexec.mainClass="sd.serialization.SerializationExample"
|
||||
```
|
||||
|
||||
4. **Executar testes**
|
||||
```bash
|
||||
mvn test -Dtest=SerializationTest
|
||||
```
|
||||
|
||||
### Para Arquitetos/Gestores
|
||||
|
||||
1. **Resumo executivo**
|
||||
→ Ler [SERIALIZATION_SUMMARY.md](./SERIALIZATION_SUMMARY.md)
|
||||
|
||||
2. **Justificativa técnica**
|
||||
→ Ler [SERIALIZATION_SPECIFICATION.md](./SERIALIZATION_SPECIFICATION.md) (Seção 4)
|
||||
|
||||
3. **Arquitetura visual**
|
||||
→ Ler [SERIALIZATION_ARCHITECTURE.md](./SERIALIZATION_ARCHITECTURE.md)
|
||||
|
||||
---
|
||||
|
||||
## 📊 Decisão Final
|
||||
|
||||
### ✅ JSON (Gson) - Recomendado
|
||||
|
||||
**Justificativa em uma frase**:
|
||||
JSON oferece 54% menos tamanho, debugging superior e extensibilidade futura, com overhead de performance desprezível (7 μs) para nosso caso de uso.
|
||||
|
||||
**Métricas chave**:
|
||||
- Tamanho: 300 bytes (vs 657 Java)
|
||||
- Latência: 40.79 μs (vs 33.34 Java)
|
||||
- Legibilidade: Alta (vs Baixa Java)
|
||||
- Impacto no sistema: < 0.1%
|
||||
|
||||
---
|
||||
|
||||
## 🔗 Links Rápidos
|
||||
|
||||
### Documentação
|
||||
- [Especificação Completa](./SERIALIZATION_SPECIFICATION.md)
|
||||
- [Guia de Decisão](./SERIALIZATION_DECISION.md)
|
||||
- [Resumo](./SERIALIZATION_SUMMARY.md)
|
||||
- [Arquitetura](./SERIALIZATION_ARCHITECTURE.md)
|
||||
|
||||
### Código
|
||||
- [Package README](../src/main/java/sd/serialization/README.md)
|
||||
- [MessageSerializer.java](../src/main/java/sd/serialization/MessageSerializer.java)
|
||||
- [JsonMessageSerializer.java](../src/main/java/sd/serialization/JsonMessageSerializer.java)
|
||||
- [SerializerFactory.java](../src/main/java/sd/serialization/SerializerFactory.java)
|
||||
|
||||
### Exemplos e Testes
|
||||
- [SerializationExample.java](../src/main/java/sd/serialization/SerializationExample.java)
|
||||
- [SerializationTest.java](../src/test/java/sd/serialization/SerializationTest.java)
|
||||
|
||||
### Recursos Externos
|
||||
- [Gson User Guide](https://github.com/google/gson/blob/master/UserGuide.md)
|
||||
- [Java Serialization Spec](https://docs.oracle.com/javase/8/docs/platform/serialization/spec/serialTOC.html)
|
||||
- [JSON Schema](https://json-schema.org/)
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Casos de Uso
|
||||
|
||||
### Cenário 1: Transferir Veículo entre Cruzamentos
|
||||
```java
|
||||
MessageSerializer serializer = SerializerFactory.createDefault();
|
||||
Message msg = new Message(MessageType.VEHICLE_TRANSFER, "Cr1", "Cr2", vehicle);
|
||||
byte[] data = serializer.serialize(msg);
|
||||
socket.getOutputStream().write(data);
|
||||
```
|
||||
|
||||
**Documento relevante**: [Package README](../src/main/java/sd/serialization/README.md)
|
||||
|
||||
### Cenário 2: Enviar Estatísticas para Dashboard
|
||||
```java
|
||||
MessageSerializer serializer = new JsonMessageSerializer(false);
|
||||
StatsUpdate stats = collectStats();
|
||||
byte[] data = serializer.serialize(stats);
|
||||
sendToDashboard(data);
|
||||
```
|
||||
|
||||
**Documento relevante**: [SERIALIZATION_ARCHITECTURE.md](./SERIALIZATION_ARCHITECTURE.md) - Seção "Integração Futura"
|
||||
|
||||
### Cenário 3: Debugging de Mensagens
|
||||
```java
|
||||
MessageSerializer serializer = new JsonMessageSerializer(true); // Pretty print
|
||||
byte[] data = serializer.serialize(message);
|
||||
logger.debug("Sent: " + new String(data)); // Legível!
|
||||
```
|
||||
|
||||
**Documento relevante**: [SERIALIZATION_DECISION.md](./SERIALIZATION_DECISION.md) - Seção "Debugging"
|
||||
|
||||
---
|
||||
|
||||
## ❓ FAQ
|
||||
|
||||
### Por que não Protocol Buffers ou MessagePack?
|
||||
R: Para este projeto, JSON oferece o melhor balanço entre simplicidade, debugging e performance. Protobuf seria overkill para o volume de mensagens esperado.
|
||||
|
||||
### Posso mudar de JSON para Java Serialization depois?
|
||||
R: Sim! A interface `MessageSerializer` permite trocar a implementação mudando apenas uma linha de código.
|
||||
|
||||
### Como debug mensagens binárias (Java)?
|
||||
R: Não é trivial. Por isso JSON é recomendado. Veja [SERIALIZATION_DECISION.md](./SERIALIZATION_DECISION.md) para detalhes.
|
||||
|
||||
### JSON é suficientemente rápido?
|
||||
R: Sim. A diferença de 7 μs é desprezível comparado à latência de rede (~1000 μs). Veja [SERIALIZATION_SPECIFICATION.md](./SERIALIZATION_SPECIFICATION.md) - Seção 3.2.
|
||||
|
||||
### Como adicionar novo tipo de mensagem?
|
||||
R: Basta criar a classe com getters/setters. JSON funciona automaticamente. Veja [Package README](../src/main/java/sd/serialization/README.md).
|
||||
|
||||
---
|
||||
|
||||
## 📝 Histórico de Versões
|
||||
|
||||
| Versão | Data | Alterações |
|
||||
|--------|------|------------|
|
||||
| 1.0 | 2025-10-22 | Implementação inicial completa |
|
||||
| | | - Especificação de design |
|
||||
| | | - Implementação JSON e Java |
|
||||
| | | - Testes unitários (14/14) |
|
||||
| | | - Documentação completa |
|
||||
|
||||
---
|
||||
|
||||
## 👥 Contribuidores
|
||||
|
||||
- **Design e Implementação**: Equipa SD - Trabalho Prático
|
||||
- **Revisão Técnica**: GitHub Copilot
|
||||
- **Testes**: Suite automatizada JUnit 5
|
||||
|
||||
---
|
||||
|
||||
## 📧 Suporte
|
||||
|
||||
Para questões ou problemas:
|
||||
1. Consultar documentação relevante acima
|
||||
2. Ver exemplos de código em `SerializationExample.java`
|
||||
3. Executar testes: `mvn test -Dtest=SerializationTest`
|
||||
4. Contactar equipa do projeto
|
||||
|
||||
---
|
||||
|
||||
**Última atualização**: 22 de outubro de 2025
|
||||
**Status**: ✅ Completo e Pronto para Uso
|
||||
**Próximo passo**: Integração com camada de comunicação (sockets)
|
||||
@@ -1,337 +0,0 @@
|
||||
# Arquitetura de Serialização - Diagrama Visual
|
||||
|
||||
## Visão Geral da Arquitetura
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ APPLICATION LAYER │
|
||||
│ ┌──────────┐ ┌─────────┐ ┌─────────┐ ┌──────────────────┐ │
|
||||
│ │ Vehicle │ │ Message │ │ Stats │ │ Other Objects │ │
|
||||
│ └──────────┘ └─────────┘ └─────────┘ └──────────────────┘ │
|
||||
└────────────────────────────┬────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ SERIALIZATION INTERFACE │
|
||||
│ │
|
||||
│ ┌────────────────────────────────────────────────────────────┐ │
|
||||
│ │ MessageSerializer (interface) │ │
|
||||
│ │ + byte[] serialize(Object) │ │
|
||||
│ │ + <T> T deserialize(byte[], Class<T>) │ │
|
||||
│ │ + String getName() │ │
|
||||
│ │ + boolean supports(Class<?>) │ │
|
||||
│ └────────────────────────────────────────────────────────────┘ │
|
||||
└────────────────────────────┬────────────────────────────────────┘
|
||||
│
|
||||
┌──────────────┴──────────────┐
|
||||
│ │
|
||||
▼ ▼
|
||||
┌─────────────────────────┐ ┌─────────────────────────────┐
|
||||
│ JsonMessageSerializer │ │ JavaMessageSerializer │
|
||||
│ (Gson-based) │ │ (ObjectStream-based) │
|
||||
├─────────────────────────┤ ├─────────────────────────────┤
|
||||
│ - Gson gson │ │ + serialize(): byte[] │
|
||||
│ - boolean prettyPrint │ │ + deserialize(): T │
|
||||
├─────────────────────────┤ ├─────────────────────────────┤
|
||||
│ + serialize(): byte[] │ │ Uses: │
|
||||
│ + deserialize(): T │ │ - ObjectOutputStream │
|
||||
│ │ │ - ObjectInputStream │
|
||||
│ Uses: │ └─────────────────────────────┘
|
||||
│ - gson.toJson() │
|
||||
│ - gson.fromJson() │ │
|
||||
└─────────────────────────┘ │
|
||||
│ │
|
||||
└──────────────┬──────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ NETWORK TRANSPORT │
|
||||
│ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ Sockets │ <--> │ Sockets │ │
|
||||
│ │ (Sender) │ │ (Receiver) │ │
|
||||
│ └──────────────┘ └──────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Factory Pattern
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ SerializerFactory │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ createDefault() │
|
||||
│ │ │
|
||||
│ ├─> Check System Property "sd.serialization.type" │
|
||||
│ │ │
|
||||
│ └─> Return appropriate serializer │
|
||||
│ │
|
||||
│ create(SerializationType) │
|
||||
│ │ │
|
||||
│ ├─> JSON -> JsonMessageSerializer │
|
||||
│ └─> JAVA_NATIVE -> JavaMessageSerializer │
|
||||
│ │
|
||||
│ createJsonSerializer(boolean prettyPrint) │
|
||||
│ └─> new JsonMessageSerializer(prettyPrint) │
|
||||
│ │
|
||||
│ createJavaSerializer() │
|
||||
│ └─> new JavaMessageSerializer() │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Fluxo de Serialização (JSON)
|
||||
|
||||
```
|
||||
┌──────────────┐
|
||||
│ Object │ (e.g., Vehicle, Message)
|
||||
│ (in memory) │
|
||||
└──────┬───────┘
|
||||
│
|
||||
│ serialize()
|
||||
▼
|
||||
┌──────────────────────────────┐
|
||||
│ JsonMessageSerializer │
|
||||
│ │
|
||||
│ 1. Validate object != null │
|
||||
│ 2. gson.toJson(object) │
|
||||
│ 3. Convert to UTF-8 bytes │
|
||||
└──────┬───────────────────────┘
|
||||
│
|
||||
│ byte[]
|
||||
▼
|
||||
┌──────────────────────────────┐
|
||||
│ Network Layer │
|
||||
│ (OutputStream) │
|
||||
└──────┬───────────────────────┘
|
||||
│
|
||||
│ TCP/IP
|
||||
▼
|
||||
┌──────────────────────────────┐
|
||||
│ Network Layer │
|
||||
│ (InputStream) │
|
||||
└──────┬───────────────────────┘
|
||||
│
|
||||
│ byte[]
|
||||
▼
|
||||
┌──────────────────────────────┐
|
||||
│ JsonMessageSerializer │
|
||||
│ │
|
||||
│ 1. Validate data != null │
|
||||
│ 2. Convert to String (UTF-8)│
|
||||
│ 3. gson.fromJson(json, cls) │
|
||||
└──────┬───────────────────────┘
|
||||
│
|
||||
│ deserialize()
|
||||
▼
|
||||
┌──────────────┐
|
||||
│ Object │
|
||||
│ (in memory) │
|
||||
└──────────────┘
|
||||
```
|
||||
|
||||
## Comparação de Formato de Dados
|
||||
|
||||
### JSON Format (Legível)
|
||||
```json
|
||||
{
|
||||
"messageId": "abc-123",
|
||||
"type": "VEHICLE_TRANSFER",
|
||||
"senderId": "Cr1",
|
||||
"destinationId": "Cr2",
|
||||
"timestamp": 1729595234567,
|
||||
"payload": {
|
||||
"id": "V123",
|
||||
"type": "LIGHT",
|
||||
"entryTime": 15.7,
|
||||
"route": ["Cr1", "Cr2", "S"],
|
||||
"currentRouteIndex": 1,
|
||||
"totalWaitingTime": 3.2,
|
||||
"totalCrossingTime": 1.8
|
||||
}
|
||||
}
|
||||
```
|
||||
**Tamanho**: ~300 bytes
|
||||
**Legibilidade**: ✅ Alta
|
||||
**Debugging**: ✅ Fácil
|
||||
|
||||
### Java Binary Format (Não Legível)
|
||||
```
|
||||
AC ED 00 05 73 72 00 10 73 64 2E 6D 6F 64 65 6C
|
||||
2E 4D 65 73 73 61 67 65 00 00 00 00 00 00 00 01
|
||||
02 00 06 4A 00 09 74 69 6D 65 73 74 61 6D 70 4C
|
||||
...
|
||||
```
|
||||
**Tamanho**: ~657 bytes
|
||||
**Legibilidade**: ❌ Baixa (binário)
|
||||
**Debugging**: ❌ Difícil
|
||||
|
||||
## Uso em Contexto Real
|
||||
|
||||
### Cenário: Transferência de Veículo entre Cruzamentos
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────────────┐
|
||||
│ Processo Cr1 │
|
||||
│ │
|
||||
│ 1. Vehicle arrives at intersection │
|
||||
│ 2. Create Message with Vehicle payload │
|
||||
│ 3. MessageSerializer serializer = SerializerFactory.create() │
|
||||
│ 4. byte[] data = serializer.serialize(message) │
|
||||
│ 5. socket.getOutputStream().write(data) │
|
||||
│ │
|
||||
└───────────────────────────┬──────────────────────────────────────┘
|
||||
│
|
||||
│ Network (TCP/IP)
|
||||
│ JSON: 300 bytes
|
||||
│ Latency: ~1ms
|
||||
│
|
||||
┌───────────────────────────▼──────────────────────────────────────┐
|
||||
│ Processo Cr2 │
|
||||
│ │
|
||||
│ 1. byte[] data = socket.getInputStream().readAllBytes() │
|
||||
│ 2. MessageSerializer serializer = SerializerFactory.create() │
|
||||
│ 3. Message msg = serializer.deserialize(data, Message.class) │
|
||||
│ 4. Vehicle vehicle = msg.getPayloadAs(Vehicle.class) │
|
||||
│ 5. Process vehicle (add to queue, etc.) │
|
||||
│ │
|
||||
└──────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Tratamento de Erros
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Handling Flow │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ try { │
|
||||
│ byte[] data = serializer.serialize(object); │
|
||||
│ send(data); │
|
||||
│ } │
|
||||
│ catch (SerializationException e) { │
|
||||
│ │ │
|
||||
│ ├─> Log error │
|
||||
│ ├─> Increment error counter │
|
||||
│ ├─> Notify monitoring system │
|
||||
│ └─> Retry with fallback serializer (optional) │
|
||||
│ } │
|
||||
│ │
|
||||
│ try { │
|
||||
│ byte[] data = receive(); │
|
||||
│ Message msg = serializer.deserialize(data, Message.class); │
|
||||
│ } │
|
||||
│ catch (SerializationException e) { │
|
||||
│ │ │
|
||||
│ ├─> Log corrupted data │
|
||||
│ ├─> Request retransmission │
|
||||
│ └─> Discard message │
|
||||
│ } │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Performance Comparison Diagram
|
||||
|
||||
```
|
||||
Serialization Time (microseconds)
|
||||
0 10 20 30 40 50
|
||||
├────────┼────────┼────────┼────────┼────────┤
|
||||
│
|
||||
JSON: ████████████████████████████████████████ 40.79 μs
|
||||
Java: █████████████████████████████████ 33.34 μs
|
||||
│
|
||||
Difference: 7.45 μs (< 0.01 ms - NEGLIGIBLE)
|
||||
|
||||
|
||||
Message Size (bytes)
|
||||
0 200 400 600 800
|
||||
├────────┼────────┼────────┼────────┤
|
||||
│
|
||||
JSON: ██████████████████ 300 bytes
|
||||
Java: █████████████████████████████████ 657 bytes
|
||||
│
|
||||
Difference: 357 bytes (54% smaller - SIGNIFICANT)
|
||||
|
||||
|
||||
Legibilidade
|
||||
Low High
|
||||
├────────────────────────────┤
|
||||
│
|
||||
JSON: ████████████████████████████ High (text)
|
||||
Java: █ Low (binary)
|
||||
```
|
||||
|
||||
## Decisão Matrix
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ Serialization Decision Matrix │
|
||||
├─────────────────┬──────────────┬─────────────┬──────────┤
|
||||
│ Criteria │ JSON │ Java │ Winner │
|
||||
├─────────────────┼──────────────┼─────────────┼──────────┤
|
||||
│ Size │ 300 bytes │ 657 bytes │ ✅ JSON │
|
||||
│ Performance │ 40.79 μs │ 33.34 μs │ ⚖️ Tie │
|
||||
│ Readability │ High │ Low │ ✅ JSON │
|
||||
│ Debugging │ Easy │ Hard │ ✅ JSON │
|
||||
│ Security │ Better │ Vulnerable │ ✅ JSON │
|
||||
│ Interop │ Universal │ Java only │ ✅ JSON │
|
||||
│ Dependencies │ Gson (small) │ None │ ⚖️ Tie │
|
||||
│ Evolution │ Flexible │ Rigid │ ✅ JSON │
|
||||
├─────────────────┴──────────────┴─────────────┴──────────┤
|
||||
│ FINAL SCORE │
|
||||
│ JSON: 6 | Java: 0 | Tie: 2 │
|
||||
│ │
|
||||
│ RECOMMENDATION: JSON (Gson) ✅ │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Integração Futura
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ Current System │
|
||||
│ │
|
||||
│ Cruzamento 1 <--[JSON]--> Cruzamento 2 │
|
||||
│ │ │ │
|
||||
│ └────────[JSON]──────────────┘ │
|
||||
│ │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
|
||||
Future Extensions (Easy with JSON)
|
||||
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ Extended System │
|
||||
│ │
|
||||
│ Cruzamento 1 <--[JSON]--> Cruzamento 2 │
|
||||
│ │ │ │
|
||||
│ ├────────[JSON]──────────────┤ │
|
||||
│ │ │ │
|
||||
│ ▼ ▼ │
|
||||
│ ┌─────────────────────────────────────────┐ │
|
||||
│ │ Dashboard (Web) │ │
|
||||
│ │ - React/Vue frontend │ │
|
||||
│ │ - Consumes JSON directly │ │
|
||||
│ │ - No conversion needed │ │
|
||||
│ └─────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────┐ │
|
||||
│ │ REST API │ │
|
||||
│ │ - External monitoring │ │
|
||||
│ │ - JSON responses │ │
|
||||
│ └─────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────┐ │
|
||||
│ │ Log Aggregation │ │
|
||||
│ │ - ELK Stack, Splunk │ │
|
||||
│ │ - JSON log parsing │ │
|
||||
│ └─────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Diagrama criado**: 22 de outubro de 2025
|
||||
**Formato**: ASCII Art (compatível com markdown)
|
||||
**Licença**: Projeto SD - Trabalho Prático
|
||||
@@ -1,281 +0,0 @@
|
||||
# Guia Rápido de Decisão: Java Serialization vs JSON
|
||||
|
||||
## TL;DR (Resumo Executivo)
|
||||
|
||||
**Recomendação: Use JSON (Gson)** ✅
|
||||
|
||||
Para este projeto de simulação de tráfego distribuído, JSON é a escolha recomendada devido a:
|
||||
- Melhor debugging
|
||||
- Mensagens menores
|
||||
- Mais fácil de manter
|
||||
- Performance adequada
|
||||
|
||||
---
|
||||
|
||||
## Tabela de Decisão Rápida
|
||||
|
||||
| Critério | JSON (Gson) | Java Native | Vencedor |
|
||||
|----------|-------------|-------------|----------|
|
||||
| **Tamanho de Mensagem** | 300 bytes | 657 bytes | ✅ JSON (54% menor) |
|
||||
| **Performance** | ~40 μs | ~33 μs | ⚖️ Empate (diferença < 1ms) |
|
||||
| **Legibilidade** | Texto claro | Binário | ✅ JSON |
|
||||
| **Debugging** | Fácil | Difícil | ✅ JSON |
|
||||
| **Segurança** | Mais seguro | Vulnerabilidades | ✅ JSON |
|
||||
| **Interoperabilidade** | Universal | Só Java | ✅ JSON |
|
||||
| **Dependências** | Gson (pequeno) | Nativo | ⚖️ Neutro |
|
||||
| **Evolução** | Flexível | serialVersionUID | ✅ JSON |
|
||||
|
||||
**Pontuação: JSON 6 - Java 0 - Empate 2**
|
||||
|
||||
---
|
||||
|
||||
## Critérios de Decisão por Cenário
|
||||
|
||||
### Use JSON quando:
|
||||
|
||||
✅ **Desenvolvimento/Debugging**
|
||||
- Necessita inspecionar mensagens facilmente
|
||||
- Quer logs legíveis
|
||||
- Está desenvolvendo novos recursos
|
||||
|
||||
✅ **Mensagens Pequenas/Médias**
|
||||
- Objetos simples (< 1000 campos)
|
||||
- Sem grafos complexos
|
||||
- Dados estruturados
|
||||
|
||||
✅ **Extensibilidade Futura**
|
||||
- Pode adicionar dashboard web
|
||||
- Integração com outras linguagens
|
||||
- APIs REST potenciais
|
||||
|
||||
✅ **Segurança Importa**
|
||||
- Sistema exposto externamente
|
||||
- Dados sensíveis
|
||||
- Conformidade necessária
|
||||
|
||||
### Use Java Serialization quando:
|
||||
|
||||
⚠️ **Performance Crítica**
|
||||
- Volume > 100k msgs/s
|
||||
- Latência < 100 μs obrigatória
|
||||
- Cada microssegundo conta
|
||||
|
||||
⚠️ **Objetos Complexos**
|
||||
- Grafos com referências circulares
|
||||
- Necessita preservar tipo exato
|
||||
- Serialização de locks/threads
|
||||
|
||||
⚠️ **Ambiente Controlado**
|
||||
- Garantia 100% Java
|
||||
- Sem interoperabilidade necessária
|
||||
- Controle total de versões
|
||||
|
||||
⚠️ **Sem Dependências**
|
||||
- Não pode usar bibliotecas externas
|
||||
- JAR mínimo obrigatório
|
||||
|
||||
---
|
||||
|
||||
## Análise de Requisitos do Projeto
|
||||
|
||||
### Características do Sistema
|
||||
|
||||
| Requisito | Impacto | Favorece |
|
||||
|-----------|---------|----------|
|
||||
| Volume de mensagens | ~100-1000/s | Ambos OK |
|
||||
| Tipo de rede | Local (baixa latência) | Ambos OK |
|
||||
| Fase do projeto | Desenvolvimento | **JSON** |
|
||||
| Equipe | Estudantes/Aprendizado | **JSON** |
|
||||
| Dashboard | UI necessária | **JSON** |
|
||||
| Extensão futura | Provável | **JSON** |
|
||||
| Debugging | Frequente | **JSON** |
|
||||
|
||||
### Conclusão: JSON vence por 5-0-2
|
||||
|
||||
---
|
||||
|
||||
## Impacto nos Componentes do Sistema
|
||||
|
||||
### Cruzamentos (Processos)
|
||||
- **JSON**: Mensagens legíveis nos logs ✅
|
||||
- **Java**: Mensagens binárias ❌
|
||||
|
||||
### Dashboard
|
||||
- **JSON**: Integração direta com UI web ✅
|
||||
- **Java**: Conversão necessária ❌
|
||||
|
||||
### Testes
|
||||
- **JSON**: Assert em strings JSON ✅
|
||||
- **Java**: Comparação binária complexa ❌
|
||||
|
||||
### Logs
|
||||
- **JSON**: Pode logar mensagem direto ✅
|
||||
- **Java**: Hex dump ilegível ❌
|
||||
|
||||
---
|
||||
|
||||
## Métricas de Performance Reais
|
||||
|
||||
### Teste: Simulação 60s, 34 veículos
|
||||
|
||||
| Métrica | JSON | Java | Diferença |
|
||||
|---------|------|------|-----------|
|
||||
| **Tempo total** | 140 ms | 120 ms | +20 ms |
|
||||
| **% do tempo de simulação** | 0.23% | 0.20% | 0.03% |
|
||||
| **Impacto perceptível** | Não | Não | Nenhum |
|
||||
|
||||
**Conclusão**: Diferença de performance é **irrelevante** para este projeto.
|
||||
|
||||
### Cálculo de Banda
|
||||
|
||||
Assumindo 1000 msgs/s (pico):
|
||||
|
||||
| Formato | Tamanho/msg | Banda |
|
||||
|---------|-------------|-------|
|
||||
| JSON | 300 bytes | 300 KB/s |
|
||||
| Java | 657 bytes | 657 KB/s |
|
||||
|
||||
Rede local suporta > 100 MB/s → **Ambos OK**
|
||||
|
||||
---
|
||||
|
||||
## Cenários de Uso no Projeto
|
||||
|
||||
### 1. Transferência de Veículo (Cr1 → Cr2)
|
||||
|
||||
```java
|
||||
// JSON: Pode logar e ver exatamente o que foi enviado
|
||||
logger.info("Sending vehicle: " + new String(data));
|
||||
// Output: {"id":"V123", "type":"LIGHT", "route":["Cr1","Cr2","S"], ...}
|
||||
```
|
||||
|
||||
**Vantagem JSON**: Debugging instantâneo ✅
|
||||
|
||||
### 2. Estatísticas para Dashboard
|
||||
|
||||
```java
|
||||
// JSON: Dashboard pode consumir diretamente
|
||||
fetch('/api/stats')
|
||||
.then(res => res.json())
|
||||
.then(data => updateUI(data));
|
||||
```
|
||||
|
||||
**Vantagem JSON**: Zero conversão ✅
|
||||
|
||||
### 3. Logs de Desenvolvimento
|
||||
|
||||
```
|
||||
[Cr1] Sent: {"messageId":"abc123", "type":"VEHICLE_TRANSFER", ...}
|
||||
[Cr2] Received: {"messageId":"abc123", "type":"VEHICLE_TRANSFER", ...}
|
||||
```
|
||||
|
||||
**Vantagem JSON**: Rastreamento visual ✅
|
||||
|
||||
---
|
||||
|
||||
## Casos Extremos
|
||||
|
||||
### Quando Java seria melhor?
|
||||
|
||||
Apenas se **TODOS** forem verdadeiros:
|
||||
1. ❌ Volume > 100k msgs/s
|
||||
2. ❌ Latência < 100 μs obrigatória
|
||||
3. ❌ Sem dashboard web futuro
|
||||
4. ❌ Sem necessidade de debugging
|
||||
5. ❌ Equipe experiente com serialVersionUID
|
||||
|
||||
**No nosso projeto**: Nenhum é verdadeiro → JSON vence
|
||||
|
||||
---
|
||||
|
||||
## Checklist de Implementação
|
||||
|
||||
### Para JSON (Recomendado)
|
||||
|
||||
- [x] Adicionar dependência Gson ao pom.xml
|
||||
- [x] Criar JsonMessageSerializer
|
||||
- [x] Configurar SerializerFactory
|
||||
- [x] Implementar testes
|
||||
- [ ] Integrar com sockets
|
||||
- [ ] Adicionar logging de mensagens
|
||||
|
||||
### Para Java Native (Fallback)
|
||||
|
||||
- [x] Implementar JavaMessageSerializer
|
||||
- [x] Garantir Serializable em todas as classes
|
||||
- [x] Definir serialVersionUID
|
||||
- [ ] Documentar formato binário
|
||||
- [ ] Criar ferramentas de inspeção
|
||||
|
||||
---
|
||||
|
||||
## Migração e Compatibilidade
|
||||
|
||||
### Trocar de Java → JSON
|
||||
|
||||
```java
|
||||
// Antes
|
||||
MessageSerializer serializer = new JavaMessageSerializer();
|
||||
|
||||
// Depois (uma linha!)
|
||||
MessageSerializer serializer = new JsonMessageSerializer();
|
||||
```
|
||||
|
||||
**Custo**: 0 mudanças no código, apenas troca de serializer ✅
|
||||
|
||||
### Trocar de JSON → Java
|
||||
|
||||
Mesmo processo (interface comum) ✅
|
||||
|
||||
### Usar Ambos (Negociação)
|
||||
|
||||
```java
|
||||
// Cliente envia tipo preferido
|
||||
String preferredFormat = "JSON";
|
||||
|
||||
// Servidor escolhe
|
||||
MessageSerializer serializer =
|
||||
"JSON".equals(preferredFormat)
|
||||
? SerializerFactory.createJsonSerializer()
|
||||
: SerializerFactory.createJavaSerializer();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Decisão Final
|
||||
|
||||
### Para este projeto: **JSON (Gson)** ✅
|
||||
|
||||
**Razões principais:**
|
||||
1. 🐛 **Debugging mais fácil** → Economiza horas de desenvolvimento
|
||||
2. 📊 **Dashboard futuro** → Integração simples
|
||||
3. 📚 **Aprendizado** → Padrão da indústria
|
||||
4. 🔒 **Segurança** → Menos vulnerabilidades
|
||||
5. 📦 **Tamanho menor** → Menos banda
|
||||
|
||||
**Performance**: Diferença de 7 μs é irrelevante (< 0.01% do tempo)
|
||||
|
||||
### Configuração Recomendada
|
||||
|
||||
```java
|
||||
// Produção
|
||||
MessageSerializer serializer = SerializerFactory.createJsonSerializer(false);
|
||||
|
||||
// Desenvolvimento
|
||||
MessageSerializer serializer = SerializerFactory.createJsonSerializer(true);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Referências Rápidas
|
||||
|
||||
- [Especificação Completa](../docs/SERIALIZATION_SPECIFICATION.md)
|
||||
- [Código de Exemplo](../src/main/java/sd/serialization/SerializationExample.java)
|
||||
- [Testes](../src/test/java/sd/serialization/SerializationTest.java)
|
||||
- [README do Pacote](../src/main/java/sd/serialization/README.md)
|
||||
|
||||
---
|
||||
|
||||
**Última atualização**: 22 de outubro de 2025
|
||||
**Decisão**: JSON (Gson) recomendado
|
||||
**Confiança**: Alta (8/10)
|
||||
@@ -1,370 +0,0 @@
|
||||
# Especificação do Formato de Serialização
|
||||
|
||||
## 1. Visão Geral
|
||||
|
||||
Este documento descreve as estratégias de serialização para a comunicação entre processos no sistema de simulação de tráfego distribuído. A serialização é necessária para transmitir objetos Java através de sockets entre diferentes processos (cruzamentos, coordenador, dashboard).
|
||||
|
||||
## 2. Requisitos
|
||||
|
||||
### 2.1 Objetos a Serializar
|
||||
|
||||
Os principais objetos que precisam ser serializados são:
|
||||
|
||||
- **Vehicle**: Contém estado completo do veículo (id, tipo, rota, métricas)
|
||||
- **Message**: Container para todas as mensagens entre processos
|
||||
- **Estatísticas**: Dados agregados dos cruzamentos e semáforos
|
||||
|
||||
### 2.2 Requisitos Funcionais
|
||||
|
||||
- **Integridade**: Todos os dados devem ser preservados durante a serialização/desserialização
|
||||
- **Compatibilidade**: Suporte para evolução de classes (adicionar campos)
|
||||
- **Performance**: Latência mínima para não impactar a simulação
|
||||
- **Depuração**: Capacidade de inspecionar mensagens facilmente
|
||||
|
||||
### 2.3 Requisitos Não-Funcionais
|
||||
|
||||
- Tamanho da mensagem otimizado
|
||||
- Fácil manutenção e extensibilidade
|
||||
- Compatibilidade com ferramentas de monitorização
|
||||
|
||||
---
|
||||
|
||||
## 3. Comparação: Java Serialization vs JSON
|
||||
|
||||
### 3.1 Java Serialization
|
||||
|
||||
#### Vantagens ✅
|
||||
|
||||
1. **Nativo do Java**
|
||||
- Sem dependências externas
|
||||
- Suporte built-in na JVM
|
||||
- Integração direta com Serializable
|
||||
|
||||
2. **Preservação de Tipos**
|
||||
- Mantém tipos Java exatos
|
||||
- Serializa grafo completo de objetos
|
||||
- Suporte automático para herança
|
||||
|
||||
3. **Performance de Escrita**
|
||||
- Serialização binária mais rápida
|
||||
- Menos overhead de conversão
|
||||
- ObjectOutputStream otimizado
|
||||
|
||||
4. **Facilidade de Implementação**
|
||||
- Basta implementar Serializable
|
||||
- Controle fino com serialVersionUID
|
||||
- Métodos customizados: writeObject/readObject
|
||||
|
||||
#### Desvantagens ❌
|
||||
|
||||
1. **Acoplamento Java**
|
||||
- Apenas entre aplicações Java
|
||||
- Dificulta interoperabilidade futura
|
||||
- Formato proprietário
|
||||
|
||||
2. **Tamanho das Mensagens**
|
||||
- Formato binário verboso
|
||||
- Inclui metadata de classes
|
||||
- 2-3x maior que JSON compacto
|
||||
|
||||
3. **Depuração Difícil**
|
||||
- Formato binário não legível
|
||||
- Necessita ferramentas especiais
|
||||
- Difícil inspecionar mensagens
|
||||
|
||||
4. **Problemas de Segurança**
|
||||
- Vulnerabilidades conhecidas (CVEs)
|
||||
- Desserialização insegura
|
||||
- Necessita validação cuidadosa
|
||||
|
||||
5. **Evolução de Classes**
|
||||
- serialVersionUID requer gestão manual
|
||||
- Quebra compatibilidade facilmente
|
||||
- Difícil manter versões diferentes
|
||||
|
||||
#### Métricas Estimadas
|
||||
```
|
||||
Tamanho Médio: 400-600 bytes (Vehicle completo)
|
||||
Latência: 0.5-1ms (serialização + rede local)
|
||||
Throughput: ~10,000 msgs/s
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3.2 JSON (com Gson/Jackson)
|
||||
|
||||
#### Vantagens ✅
|
||||
|
||||
1. **Legibilidade Humana**
|
||||
- Formato texto simples
|
||||
- Fácil depuração
|
||||
- Inspecionável com ferramentas comuns
|
||||
|
||||
2. **Interoperabilidade**
|
||||
- Padrão universal
|
||||
- Facilita integração futura
|
||||
- Dashboard web, APIs, etc.
|
||||
|
||||
3. **Tamanho Otimizado**
|
||||
- Formato compacto
|
||||
- ~40% menor que Java Serialization
|
||||
- Compressão opcional (gzip)
|
||||
|
||||
4. **Evolução Flexível**
|
||||
- Campos opcionais nativos
|
||||
- Backward/forward compatibility
|
||||
- Versionamento natural
|
||||
|
||||
5. **Ferramentas e Ecossistema**
|
||||
- Bibliotecas maduras (Gson, Jackson)
|
||||
- Validação com JSON Schema
|
||||
- Suporte a logs estruturados
|
||||
|
||||
6. **Segurança**
|
||||
- Sem execução de código
|
||||
- Validação mais simples
|
||||
- Menos vetores de ataque
|
||||
|
||||
#### Desvantagens ❌
|
||||
|
||||
1. **Dependência Externa**
|
||||
- Necessita biblioteca (Gson/Jackson)
|
||||
- Aumenta tamanho do JAR
|
||||
- Possível quebra de dependência
|
||||
|
||||
2. **Performance de Conversão**
|
||||
- Parsing de texto
|
||||
- Reflexão Java
|
||||
- ~20-30% mais lento que binário
|
||||
|
||||
3. **Tipos Perdidos**
|
||||
- Necessita type hints
|
||||
- Problemas com genéricos
|
||||
- Enums requerem atenção
|
||||
|
||||
4. **Memória**
|
||||
- String temporárias
|
||||
- Maior uso de heap
|
||||
- GC mais frequente
|
||||
|
||||
#### Métricas Estimadas
|
||||
```
|
||||
Tamanho Médio: 250-350 bytes (Vehicle completo)
|
||||
Latência: 0.8-1.5ms (conversão + rede local)
|
||||
Throughput: ~8,000 msgs/s
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Decisão e Recomendação
|
||||
|
||||
### 4.1 Análise de Contexto
|
||||
|
||||
**Características do Projeto:**
|
||||
- Sistema distribuído Java-only (curto prazo)
|
||||
- Comunicação intra-rede local (baixa latência)
|
||||
- Volume moderado de mensagens (~100-1000/s)
|
||||
- Necessidade de depuração durante desenvolvimento
|
||||
- Potencial expansão futura (dashboard web)
|
||||
|
||||
### 4.2 Recomendação: **JSON (Gson)**
|
||||
|
||||
#### Justificativa
|
||||
|
||||
1. **Desenvolvimento e Depuração** 🔍
|
||||
- A fase atual do projeto requer debugging extensivo
|
||||
- JSON facilita inspeção de mensagens
|
||||
- Logs legíveis sem ferramentas especiais
|
||||
|
||||
2. **Manutenibilidade** 🔧
|
||||
- Mais fácil para equipe aprender/modificar
|
||||
- Evolução de protocolo mais simples
|
||||
- Menos problemas de compatibilidade
|
||||
|
||||
3. **Extensibilidade** 🚀
|
||||
- Dashboard web futuramente
|
||||
- APIs REST potenciais
|
||||
- Integração com ferramentas de monitorização
|
||||
|
||||
4. **Performance Aceitável** ⚡
|
||||
- Diferença de latência irrelevante (< 1ms)
|
||||
- Volume de mensagens não é crítico
|
||||
- Rede local minimiza overhead
|
||||
|
||||
5. **Segurança** 🔒
|
||||
- Evita vulnerabilidades de Java Serialization
|
||||
- Validação mais simples e segura
|
||||
|
||||
### 4.3 Quando Usar Java Serialization
|
||||
|
||||
Java Serialization seria preferível se:
|
||||
- Performance crítica (> 100k msgs/s)
|
||||
- Objetos muito complexos com referências circulares
|
||||
- Garantia de ambiente Java puro permanente
|
||||
- Necessidade de preservar estado exato (locks, transient)
|
||||
|
||||
---
|
||||
|
||||
## 5. Implementação Recomendada
|
||||
|
||||
### 5.1 Arquitetura de Serialização
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────┐
|
||||
│ Application Layer │
|
||||
│ (Vehicle, Message, Statistics) │
|
||||
└─────────────────┬───────────────────────┘
|
||||
│
|
||||
┌─────────────────▼───────────────────────┐
|
||||
│ Serialization Interface │
|
||||
│ - serialize(Object): byte[] │
|
||||
│ - deserialize(byte[], Class<T>): T │
|
||||
└─────────────────┬───────────────────────┘
|
||||
│
|
||||
┌─────────┴─────────┐
|
||||
│ │
|
||||
┌───────▼──────┐ ┌────────▼─────────┐
|
||||
│ JsonSerializer│ │JavaSerializer │
|
||||
│ (Gson-based) │ │(ObjectStream) │
|
||||
└───────────────┘ └──────────────────┘
|
||||
```
|
||||
|
||||
### 5.2 Estrutura de Mensagens JSON
|
||||
|
||||
#### Exemplo 1: Transferência de Veículo
|
||||
```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
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Exemplo 2: Atualização de Estatísticas
|
||||
```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
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 5.3 Biblioteca Escolhida: **Gson**
|
||||
|
||||
**Por que Gson (não Jackson)?**
|
||||
- ✅ Mais simples e leve
|
||||
- ✅ Menos configuração necessária
|
||||
- ✅ API mais intuitiva para iniciantes
|
||||
- ✅ Melhor para modelos simples (nosso caso)
|
||||
- ⚠️ Jackson seria melhor para: streaming, performance extrema, binding complexo
|
||||
|
||||
---
|
||||
|
||||
## 6. Plano de Implementação
|
||||
|
||||
### Fase 1: Setup
|
||||
- [x] Adicionar dependência Gson ao pom.xml
|
||||
- [ ] Criar interface `MessageSerializer`
|
||||
- [ ] Implementar `JsonMessageSerializer`
|
||||
- [ ] Implementar `JavaMessageSerializer` (fallback)
|
||||
|
||||
### Fase 2: Adapters
|
||||
- [ ] Criar adaptadores Gson para classes do modelo
|
||||
- [ ] Configurar serialização customizada se necessário
|
||||
- [ ] Implementar testes unitários
|
||||
|
||||
### Fase 3: Integração
|
||||
- [ ] Integrar serializer nos sockets
|
||||
- [ ] Adicionar logs de mensagens
|
||||
- [ ] Implementar mecanismo de versionamento
|
||||
|
||||
### Fase 4: Otimização (Opcional)
|
||||
- [ ] Implementar compressão (gzip)
|
||||
- [ ] Pool de serializers
|
||||
- [ ] Métricas de performance
|
||||
|
||||
---
|
||||
|
||||
## 7. Estrutura de Arquivos
|
||||
|
||||
```
|
||||
src/main/java/sd/
|
||||
├── serialization/
|
||||
│ ├── MessageSerializer.java # Interface comum
|
||||
│ ├── JsonMessageSerializer.java # Implementação Gson
|
||||
│ ├── JavaMessageSerializer.java # Implementação nativa
|
||||
│ ├── SerializerFactory.java # Factory pattern
|
||||
│ └── adapters/ # Type adapters Gson
|
||||
│ ├── VehicleAdapter.java
|
||||
│ └── MessageAdapter.java
|
||||
└── network/
|
||||
├── MessageSocket.java # Wrapper para socket
|
||||
└── MessageProtocol.java # Protocolo de comunicação
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Considerações Finais
|
||||
|
||||
### 8.1 Boas Práticas
|
||||
|
||||
1. **Versionamento**: Incluir campo `version` nas mensagens
|
||||
2. **Validação**: Validar mensagens após desserialização
|
||||
3. **Logging**: Logar mensagens em desenvolvimento (desabilitar em produção)
|
||||
4. **Exceções**: Tratar erros de serialização gracefully
|
||||
5. **Testes**: Testar serialização round-trip para todas as classes
|
||||
|
||||
### 8.2 Monitorização
|
||||
|
||||
- Tamanho médio de mensagens
|
||||
- Latência de serialização/desserialização
|
||||
- Taxa de erros de serialização
|
||||
- Throughput de mensagens
|
||||
|
||||
### 8.3 Documentação
|
||||
|
||||
Cada tipo de mensagem deve ser documentado com:
|
||||
- Propósito
|
||||
- Estrutura JSON
|
||||
- Exemplo
|
||||
- Sender/Receiver esperado
|
||||
- Comportamento em caso de erro
|
||||
|
||||
---
|
||||
|
||||
## 9. Referências
|
||||
|
||||
- [Gson User Guide](https://github.com/google/gson/blob/master/UserGuide.md)
|
||||
- [Java Serialization Specification](https://docs.oracle.com/javase/8/docs/platform/serialization/spec/serialTOC.html)
|
||||
- [JSON Schema](https://json-schema.org/)
|
||||
- [Effective Java - Item 87: Consider using a custom serialized form](https://www.oreilly.com/library/view/effective-java/9780134686097/)
|
||||
|
||||
---
|
||||
|
||||
**Documento criado em**: 22 de outubro de 2025
|
||||
**Versão**: 1.0
|
||||
**Autor**: Equipa SD - Trabalho Prático
|
||||
@@ -1,224 +0,0 @@
|
||||
# ✅ Design do Formato de Serialização - CONCLUÍDO
|
||||
|
||||
**Data**: 22 de outubro de 2025
|
||||
**Status**: ✅ Implementado e Testado
|
||||
|
||||
## Resumo da Implementação
|
||||
|
||||
Foi realizada uma análise completa e implementação de dois formatos de serialização para comunicação entre processos no sistema de simulação de tráfego distribuído:
|
||||
|
||||
1. **JSON (Gson)** - Recomendado
|
||||
2. **Java Native Serialization** - Fallback
|
||||
|
||||
## Arquivos Criados
|
||||
|
||||
### Documentação
|
||||
- ✅ `docs/SERIALIZATION_SPECIFICATION.md` - Especificação completa (design, comparação, justificativa)
|
||||
- ✅ `docs/SERIALIZATION_DECISION.md` - Guia rápido de decisão
|
||||
- ✅ `src/main/java/sd/serialization/README.md` - Guia de uso do pacote
|
||||
|
||||
### Código de Produção
|
||||
- ✅ `MessageSerializer.java` - Interface comum para serialização
|
||||
- ✅ `SerializationException.java` - Exceção customizada
|
||||
- ✅ `JsonMessageSerializer.java` - Implementação JSON (Gson)
|
||||
- ✅ `JavaMessageSerializer.java` - Implementação Java nativa
|
||||
- ✅ `SerializerFactory.java` - Factory pattern para criação
|
||||
|
||||
### Exemplos e Testes
|
||||
- ✅ `SerializationExample.java` - Demonstração de uso
|
||||
- ✅ `SerializationTest.java` - Suite de testes unitários (14 testes, todos passando)
|
||||
|
||||
### Configuração
|
||||
- ✅ `pom.xml` - Dependência Gson adicionada
|
||||
|
||||
## Decisão Final: JSON (Gson)
|
||||
|
||||
### Justificativa
|
||||
|
||||
**JSON foi escolhido como formato recomendado porque:**
|
||||
|
||||
1. **Debugging Superior** 🐛
|
||||
- Mensagens legíveis em texto
|
||||
- Logs compreensíveis
|
||||
- Inspeção visual fácil
|
||||
|
||||
2. **Tamanho Otimizado** 📦
|
||||
- 54% menor que Java Serialization (300 vs 657 bytes)
|
||||
- Menos banda de rede
|
||||
- Menor latência de transmissão
|
||||
|
||||
3. **Extensibilidade** 🚀
|
||||
- Dashboard web futuro
|
||||
- APIs REST potenciais
|
||||
- Integração universal
|
||||
|
||||
4. **Segurança** 🔒
|
||||
- Sem vulnerabilidades de desserialização
|
||||
- Validação mais simples
|
||||
- Menos vetores de ataque
|
||||
|
||||
5. **Performance Adequada** ⚡
|
||||
- Diferença: 7 μs (irrelevante)
|
||||
- Volume esperado: ~100-1000 msgs/s (ambos suportam)
|
||||
- Impacto no sistema: < 0.1%
|
||||
|
||||
## Métricas de Performance
|
||||
|
||||
### Testes Realizados (1000 iterações)
|
||||
|
||||
| Métrica | JSON (Gson) | Java Native | Diferença |
|
||||
|---------|-------------|-------------|-----------|
|
||||
| Tamanho médio | 300 bytes | 657 bytes | **-54%** |
|
||||
| Latência média | 40.79 μs | 33.34 μs | +7.45 μs |
|
||||
| Throughput | ~24k msgs/s | ~30k msgs/s | Ambos > requisito |
|
||||
| Legibilidade | ✅ Texto | ❌ Binário | - |
|
||||
|
||||
**Conclusão**: Diferença de performance é desprezível; vantagens do JSON compensam.
|
||||
|
||||
## Exemplos de Mensagens
|
||||
|
||||
### Vehicle Transfer (JSON)
|
||||
```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
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Como Usar
|
||||
|
||||
### Básico
|
||||
```java
|
||||
// Criar serializer (JSON recomendado)
|
||||
MessageSerializer serializer = SerializerFactory.createDefault();
|
||||
|
||||
// Serializar
|
||||
byte[] data = serializer.serialize(message);
|
||||
|
||||
// Desserializar
|
||||
Message msg = serializer.deserialize(data, Message.class);
|
||||
```
|
||||
|
||||
### Configuração via Sistema
|
||||
```bash
|
||||
# Escolher tipo
|
||||
java -Dsd.serialization.type=JSON -jar app.jar
|
||||
|
||||
# Debug mode (pretty print)
|
||||
java -Dsd.serialization.json.prettyPrint=true -jar app.jar
|
||||
```
|
||||
|
||||
## Validação
|
||||
|
||||
### Testes Unitários
|
||||
✅ **14/14 testes passando**
|
||||
|
||||
Cobertura:
|
||||
- ✅ Serialização/desserialização JSON
|
||||
- ✅ Serialização/desserialização Java
|
||||
- ✅ Validação de erros
|
||||
- ✅ Tratamento de exceções
|
||||
- ✅ Comparação de tamanhos
|
||||
- ✅ Integridade de dados
|
||||
- ✅ Factory pattern
|
||||
- ✅ Round-trip completo
|
||||
|
||||
### Exemplo Executado
|
||||
```
|
||||
JSON size: 300 bytes
|
||||
Java size: 657 bytes
|
||||
Difference: 357 bytes (54.3% menor)
|
||||
|
||||
Performance:
|
||||
JSON: 40.79 μs/operation
|
||||
Java: 33.34 μs/operation
|
||||
|
||||
✅ Todos os testes bem-sucedidos
|
||||
```
|
||||
|
||||
## Próximos Passos
|
||||
|
||||
### Integração no Sistema
|
||||
|
||||
1. **Comunicação entre Cruzamentos**
|
||||
```java
|
||||
// No sender (Cr1)
|
||||
MessageSerializer serializer = SerializerFactory.createDefault();
|
||||
byte[] data = serializer.serialize(message);
|
||||
outputStream.write(data);
|
||||
|
||||
// No receiver (Cr2)
|
||||
byte[] received = inputStream.readAllBytes();
|
||||
Message msg = serializer.deserialize(received, Message.class);
|
||||
```
|
||||
|
||||
2. **Dashboard Updates**
|
||||
```java
|
||||
// Serializar estatísticas
|
||||
StatsUpdate stats = new StatsUpdate(...);
|
||||
byte[] data = serializer.serialize(stats);
|
||||
sendToDashboard(data);
|
||||
```
|
||||
|
||||
3. **Logging e Debugging**
|
||||
```java
|
||||
// Logar mensagens (JSON é legível)
|
||||
if (debugMode) {
|
||||
String json = new String(data, StandardCharsets.UTF_8);
|
||||
logger.debug("Sent message: " + json);
|
||||
}
|
||||
```
|
||||
|
||||
## Benefícios para o Projeto
|
||||
|
||||
1. **Desenvolvimento** 💻
|
||||
- Debugging rápido e fácil
|
||||
- Logs legíveis
|
||||
- Menos tempo depurando problemas de serialização
|
||||
|
||||
2. **Manutenção** 🔧
|
||||
- Código mais simples
|
||||
- Evolução de protocolo facilitada
|
||||
- Menos problemas de compatibilidade
|
||||
|
||||
3. **Extensibilidade** 📈
|
||||
- Dashboard web nativo
|
||||
- APIs REST futuras
|
||||
- Integração com ferramentas
|
||||
|
||||
4. **Aprendizado** 📚
|
||||
- Padrão da indústria
|
||||
- Experiência com JSON
|
||||
- Boas práticas de design
|
||||
|
||||
## Referências
|
||||
|
||||
- [Especificação Completa](./SERIALIZATION_SPECIFICATION.md)
|
||||
- [Guia de Decisão](./SERIALIZATION_DECISION.md)
|
||||
- [README do Pacote](../src/main/java/sd/serialization/README.md)
|
||||
- [Código de Exemplo](../src/main/java/sd/serialization/SerializationExample.java)
|
||||
- [Testes](../src/test/java/sd/serialization/SerializationTest.java)
|
||||
|
||||
## Conclusão
|
||||
|
||||
✅ **Formato de serialização definido e implementado**
|
||||
✅ **JSON (Gson) escolhido como padrão**
|
||||
✅ **Implementação completa e testada**
|
||||
✅ **Documentação abrangente criada**
|
||||
✅ **Pronto para integração no sistema distribuído**
|
||||
|
||||
---
|
||||
|
||||
**Próxima etapa recomendada**: Implementar camada de comunicação (sockets) usando os serializers criados.
|
||||
Reference in New Issue
Block a user