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)

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