From 2399b4b4720a5d548e16b019e13a3a4859e0459b Mon Sep 17 00:00:00 2001 From: David Alves <159618343+davidalves04@users.noreply.github.com> Date: Thu, 23 Oct 2025 20:22:53 +0100 Subject: [PATCH] Delete main/docs directory --- main/docs/README.md | 250 --------------- main/docs/SERIALIZATION_ARCHITECTURE.md | 337 --------------------- main/docs/SERIALIZATION_DECISION.md | 281 ----------------- main/docs/SERIALIZATION_SPECIFICATION.md | 370 ----------------------- main/docs/SERIALIZATION_SUMMARY.md | 224 -------------- 5 files changed, 1462 deletions(-) delete mode 100644 main/docs/README.md delete mode 100644 main/docs/SERIALIZATION_ARCHITECTURE.md delete mode 100644 main/docs/SERIALIZATION_DECISION.md delete mode 100644 main/docs/SERIALIZATION_SPECIFICATION.md delete mode 100644 main/docs/SERIALIZATION_SUMMARY.md diff --git a/main/docs/README.md b/main/docs/README.md deleted file mode 100644 index 6b97373..0000000 --- a/main/docs/README.md +++ /dev/null @@ -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) diff --git a/main/docs/SERIALIZATION_ARCHITECTURE.md b/main/docs/SERIALIZATION_ARCHITECTURE.md deleted file mode 100644 index 167a2e7..0000000 --- a/main/docs/SERIALIZATION_ARCHITECTURE.md +++ /dev/null @@ -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 deserialize(byte[], Class) │ │ -│ │ + 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 diff --git a/main/docs/SERIALIZATION_DECISION.md b/main/docs/SERIALIZATION_DECISION.md deleted file mode 100644 index 8650fad..0000000 --- a/main/docs/SERIALIZATION_DECISION.md +++ /dev/null @@ -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) diff --git a/main/docs/SERIALIZATION_SPECIFICATION.md b/main/docs/SERIALIZATION_SPECIFICATION.md deleted file mode 100644 index a0a0880..0000000 --- a/main/docs/SERIALIZATION_SPECIFICATION.md +++ /dev/null @@ -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 │ -└─────────────────┬───────────────────────┘ - │ - ┌─────────┴─────────┐ - │ │ -┌───────▼──────┐ ┌────────▼─────────┐ -│ 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 diff --git a/main/docs/SERIALIZATION_SUMMARY.md b/main/docs/SERIALIZATION_SUMMARY.md deleted file mode 100644 index 506ec95..0000000 --- a/main/docs/SERIALIZATION_SUMMARY.md +++ /dev/null @@ -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.