SD/main/docs/SERIALIZATION_DECISION.md

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)

// 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

// 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)

• Adicionar dependência Gson ao pom.xml
• Criar JsonMessageSerializer
• Configurar SerializerFactory
• Implementar testes
• Integrar com sockets
• Adicionar logging de mensagens

Para Java Native (Fallback)

• Implementar JavaMessageSerializer
• Garantir Serializable em todas as classes
• Definir serialVersionUID
• Documentar formato binário
• Criar ferramentas de inspeção

---

Migração e Compatibilidade

Trocar de Java → JSON

// 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)

// 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

// Produção
MessageSerializer serializer = SerializerFactory.createJsonSerializer(false);

// Desenvolvimento
MessageSerializer serializer = SerializerFactory.createJsonSerializer(true);

---

Referências Rápidas

• Especificação Completa
• Código de Exemplo
• Testes
• README do Pacote

---

Última atualização: 22 de outubro de 2025
Decisão: JSON (Gson) recomendado
Confiança: Alta (8/10)