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