mirror of
https://github.com/davidalves04/Trabalho-Pratico-SD.git
synced 2025-12-08 20:43:32 +00:00
Design serialization format
JSON
This commit is contained in:
David Alves
250
main/docs/README.md
Normal file
250
main/docs/README.md
Normal file
@@ -0,0 +1,250 @@
|
||||
# 📚 Í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)
|
||||
Reference in New Issue
Block a user