mirror of
https://github.com/davidalves04/Trabalho-Pratico-SD.git
synced 2025-12-08 20:43:32 +00:00
251 lines
7.7 KiB
Markdown
251 lines
7.7 KiB
Markdown
# 📚 Í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)
|