From d20040835c301b4847472cb6717a781eb616df1a Mon Sep 17 00:00:00 2001 From: David Alves Date: Thu, 23 Oct 2025 20:28:43 +0100 Subject: [PATCH] README --- README.md | 625 ++++++++++++++++++ main/src/main/java/sd/serialization/README.md | 283 -------- 2 files changed, 625 insertions(+), 283 deletions(-) create mode 100644 README.md delete mode 100644 main/src/main/java/sd/serialization/README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..c5fe0a6 --- /dev/null +++ b/README.md @@ -0,0 +1,625 @@ +# Sistema de Simulação de Tráfego Distribuído + +Sistema distribuído de simulação de tráfego. +--- + +## Índice + +- [Visão Geral](#visão-geral) +- [Arquitetura](#arquitetura) +- [Protocolo de Comunicação](#protocolo-de-comunicação) +- [Estrutura do Projeto](#estrutura-do-projeto) +- [Instalação e Execução](#instalação-e-execução) +- [Documentação](#documentação) +- [Desenvolvimento](#desenvolvimento) + +--- + +## Visão Geral + +Este projeto implementa uma simulação distribuída de tráfego veicular numa rede de cruzamentos. O sistema utiliza: + +- **Processos independentes** para cada cruzamento +- **Threads** para controlar os semáforos dentro de cada cruzamento +- **Comunicação via sockets** para transferência de veículos entre cruzamentos +- **Simulação de eventos discretos** (DES) para gerir o tempo de simulação + +### Características Principais + +- Simulação determinística e reproduzível +- Comunicação assíncrona entre processos +- Protocolo de mensagens baseado em JSON +- Dashboard em tempo real (planeado) +- Estatísticas detalhadas de desempenho + +--- + +## Arquitetura + +### Visão Geral do Sistema + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ SISTEMA DISTRIBUÍDO │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌──────────────┐ ┌──────────────┐ │ +│ │ Coordenador │ ────────────────────────>│ Dashboard │ │ +│ │ / Gerador │ │ │ +│ └──────┬───────┘ └──────▲───────┘ │ +│ │ │ │ +│ │ Gera veículos Stats │ │ +│ │ │ │ +│ ▼ │ │ +│ ┌─────────────────────────────────────────────────┴──────┐ │ +│ │ Rede de Cruzamentos (Processos) │ │ +│ │ │ │ +│ │ ┌────┐ ┌────┐ ┌────┐ │ │ +│ │ │Cr1 │◄───────►│Cr2 │◄───────►│Cr3 │ │ │ +│ │ └─┬──┘ └─┬──┘ └─┬──┘ │ │ +│ │ │ │ │ │ │ +│ │ │ ┌────▼────┐ │ │ │ +│ │ └────────►│ Cr4 │◄────────┘ │ │ +│ │ └────┬────┘ │ │ +│ │ │ │ │ +│ │ ┌────▼────┐ │ │ +│ │ │ Cr5 │ │ │ +│ │ └────┬────┘ │ │ +│ └───────────────────┼─────────────────────────────────────┤ │ +│ │ │ │ +│ ▼ │ │ +│ ┌──────────────┐ │ │ +│ │ Nó de Saída │ │ │ +│ │ (S) │ │ │ +│ └──────────────┘ │ │ +│ │ │ +└────────────────────────────────────────────────────────────┘ │ +``` + +### Componentes + +1. **Coordenador/Gerador**: Gera veículos e injeta no sistema +2. **Cruzamentos (Cr1-Cr5)**: Processos independentes que gerem tráfego local +3. **Nó de Saída (S)**: Recolhe estatísticas de veículos que saem do sistema +4. **Dashboard Server**: Agrega e exibe dados em tempo real + +--- + +## Protocolo de Comunicação + +### Formato de Serialização: JSON (Gson) + +O sistema utiliza JSON como formato de serialização por ser: +- Legível e fácil de debugar +- 54% menor que Java Serialization (300 vs 657 bytes) +- Compatível com ferramentas web/REST +- Seguro (sem vulnerabilidades de desserialização) + +### Estrutura de Mensagens + +Todas as mensagens seguem o formato base: + +```json +{ + "messageId": "uuid", + "type": "MESSAGE_TYPE", + "senderId": "sender_id", + "destinationId": "destination_id", + "timestamp": 1729595234567, + "payload": { ... } +} +``` + +### Tipos de Mensagens + +#### 1. VEHICLE_TRANSFER + +Transfere um veículo entre cruzamentos. + +**Estrutura:** +```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 + } +} +``` + +**Fluxo:** +1. Veículo completa travessia no Cr1 +2. Cr1 serializa mensagem VEHICLE_TRANSFER +3. Envia para Cr2 via socket +4. Cr2 desserializa e adiciona veículo à fila + +#### 2. STATS_UPDATE + +Envia estatísticas de um cruzamento para o Dashboard. + +**Estrutura:** +```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, + "currentTime": 123.45 + } +} +``` + +**Frequência:** A cada 10 segundos (configurável) + +#### 3. VEHICLE_EXIT + +Notifica quando um veículo sai do sistema. + +**Estrutura:** +```json +{ + "messageId": "c5e7f9a1-3456-7890-12bc-def123456789", + "type": "VEHICLE_EXIT", + "senderId": "Cr5", + "destinationId": "ExitNode", + "timestamp": 1729595234890, + "payload": { + "id": "V123", + "type": "LIGHT", + "entryTime": 15.7, + "exitTime": 45.2, + "totalSystemTime": 29.5, + "totalWaitingTime": 8.3, + "totalCrossingTime": 4.8, + "routeTaken": ["Cr1", "Cr2", "Cr5", "S"] + } +} +``` + +#### 4. HEARTBEAT + +Mantém a ligação ativa e monitoriza a saúde dos processos. + +**Estrutura:** +```json +{ + "messageId": "d6e8f0a2-4567-8901-23cd-ef1234567890", + "type": "HEARTBEAT", + "senderId": "Cr1", + "destinationId": "Coordinator", + "timestamp": 1729595235000, + "payload": { + "status": "RUNNING", + "uptime": 120.5, + "vehiclesInQueue": 12 + } +} +``` + +**Frequência:** A cada 5 segundos + +#### 5. LIGHT_CHANGE + +Notifica mudança de estado de semáforo (para logging/debugging). + +**Estrutura:** +```json +{ + "messageId": "e7f9a1b3-5678-9012-34de-f12345678901", + "type": "LIGHT_CHANGE", + "senderId": "Cr1-North", + "destinationId": "Dashboard", + "timestamp": 1729595235100, + "payload": { + "lightId": "Cr1-North", + "previousState": "RED", + "newState": "GREEN", + "queueSize": 5 + } +} +``` + +### Tipos de Veículos + +```json +{ + "BIKE": { + "probability": 0.20, + "crossingTime": 1.5 + }, + "LIGHT": { + "probability": 0.60, + "crossingTime": 2.0 + }, + "HEAVY": { + "probability": 0.20, + "crossingTime": 4.0 + } +} +``` + +### Estados dos Semáforos + +``` +RED → Veículos aguardam na fila +GREEN → Veículos podem atravessar +``` + +### Exemplo de Comunicação Completa + +``` +Tempo Processo Ação Mensagem +------ --------- ------------------------------------- ------------------ +15.7s Gerador Gera veículo V123 - +15.7s Gerador → Injeta V123 em Cr1 VEHICLE_TRANSFER +18.2s Cr1 V123 inicia travessia - +20.2s Cr1 V123 completa travessia - +20.2s Cr1 → Cr2 Transfere V123 para Cr2 VEHICLE_TRANSFER +23.5s Cr2 V123 inicia travessia - +25.5s Cr2 V123 completa travessia - +25.5s Cr2 → Cr5 Transfere V123 para Cr5 VEHICLE_TRANSFER +28.0s Cr5 V123 inicia travessia - +30.0s Cr5 V123 completa travessia - +30.0s Cr5 → Exit V123 sai do sistema VEHICLE_EXIT +30.0s Exit → Dash Estatísticas de V123 STATS_UPDATE +``` + +--- + +## Estrutura do Projeto + +``` +Trabalho-Pratico-SD/ +├── README.md # Este ficheiro +├── TODO.md # Plano de desenvolvimento +├── main/ +│ ├── pom.xml # Configuração Maven +│ ├── docs/ +│ │ ├── README.md # Índice da documentação +│ │ ├── SERIALIZATION_SPECIFICATION.md +│ │ ├── SERIALIZATION_DECISION.md +│ │ ├── SERIALIZATION_SUMMARY.md +│ │ └── SERIALIZATION_ARCHITECTURE.md +│ ├── src/ +│ │ ├── main/java/sd/ +│ │ │ ├── Entry.java # Ponto de entrada +│ │ │ ├── config/ +│ │ │ │ └── SimulationConfig.java +│ │ │ ├── engine/ +│ │ │ │ └── SimulationEngine.java +│ │ │ ├── model/ +│ │ │ │ ├── Event.java +│ │ │ │ ├── EventType.java +│ │ │ │ ├── Intersection.java +│ │ │ │ ├── Message.java # Estrutura de mensagens +│ │ │ │ ├── MessageType.java # Tipos de mensagens +│ │ │ │ ├── TrafficLight.java +│ │ │ │ ├── Vehicle.java +│ │ │ │ └── VehicleType.java +│ │ │ ├── serialization/ # Sistema de serialização +│ │ │ │ ├── MessageSerializer.java +│ │ │ │ ├── SerializationException.java +│ │ │ │ ├── JsonMessageSerializer.java +│ │ │ │ ├── JavaMessageSerializer.java +│ │ │ │ ├── SerializerFactory.java +│ │ │ │ ├── SerializationExample.java +│ │ │ │ └── README.md +│ │ │ └── util/ +│ │ │ ├── RandomGenerator.java +│ │ │ ├── StatisticsCollector.java +│ │ │ └── VehicleGenerator.java +│ │ └── test/java/ +│ │ ├── SimulationTest.java +│ │ └── sd/serialization/ +│ │ └── SerializationTest.java +│ └── target/ # Ficheiros compilados +└── .vscode/ # Configuração do VS Code +``` + +--- + +## Instalação e Execução + +### Pré-requisitos + +- **Java 17** ou superior +- **Maven 3.8+** +- **Git** + +### Instalação + +```bash +# Clonar o repositório +git clone https://github.com/davidalves04/Trabalho-Pratico-SD.git +cd Trabalho-Pratico-SD/main + +# Compilar o projeto +mvn clean compile + +# Executar os testes +mvn test +``` + +### Execução + +#### Simulação Básica (Single Process) + +```bash +mvn exec:java -Dexec.mainClass="sd.Entry" +``` + +#### Exemplo de Serialização + +```bash +mvn exec:java -Dexec.mainClass="sd.serialization.SerializationExample" +``` + +#### Configuração + +Editar `src/main/resources/simulation.properties`: + +```properties +# Duração da simulação (segundos) +simulation.duration=60.0 + +# Modelo de chegada: FIXED ou POISSON +arrival.model=POISSON + +# Taxa de chegada (veículos/segundo) +arrival.rate=0.5 + +# Intervalo de atualização de estatísticas (segundos) +stats.update.interval=10.0 + +# Distribuição de tipos de veículos +vehicle.type.bike.probability=0.20 +vehicle.type.light.probability=0.60 +vehicle.type.heavy.probability=0.20 + +# Tempos de travessia por tipo (segundos) +vehicle.type.bike.crossing.time=1.5 +vehicle.type.light.crossing.time=2.0 +vehicle.type.heavy.crossing.time=4.0 +``` + +--- + +## Documentação + +### Documentação de Serialização + +A documentação completa sobre o protocolo de serialização está disponível em: + +- **[Índice Completo](./main/docs/README.md)** - Navegação da documentação +- **[Especificação](./main/docs/SERIALIZATION_SPECIFICATION.md)** - Design detalhado +- **[Guia de Decisão](./main/docs/SERIALIZATION_DECISION.md)** - Porquê JSON? +- **[Resumo](./main/docs/SERIALIZATION_SUMMARY.md)** - Estado de implementação +- **[Arquitetura](./main/docs/SERIALIZATION_ARCHITECTURE.md)** - Diagramas visuais + +### Guias de Utilização + +- **[Serialization README](./main/src/main/java/sd/serialization/README.md)** - Como utilizar os serializers + +### Exemplos de Código + +```java +// Criar serializer +MessageSerializer serializer = SerializerFactory.createDefault(); + +// Serializar mensagem +Vehicle vehicle = new Vehicle("V123", VehicleType.LIGHT, 10.5, route); +Message message = new Message( + MessageType.VEHICLE_TRANSFER, + "Cr1", + "Cr2", + vehicle +); +byte[] data = serializer.serialize(message); + +// Enviar via socket +outputStream.write(data); + +// Receber e desserializar +byte[] received = inputStream.readAllBytes(); +Message msg = serializer.deserialize(received, Message.class); +Vehicle v = msg.getPayloadAs(Vehicle.class); +``` + +--- + +## Desenvolvimento + +### Estado do Projeto + +| Componente | Estado | Notas | +|------------|--------|-------| +| Modelo de Dados | Completo | Vehicle, Message, Event, etc. | +| Simulação DES | Completo | Single-process funcional | +| Serialização | Completo | JSON e Java implementados | +| Testes | 14/14 | Suite de serialização | +| Processos Distribuídos | Planeado | Próxima etapa | +| Comunicação Sockets | Planeado | Em design | +| Dashboard | Planeado | UI web | + +### Roteiro de Desenvolvimento + +#### Fase 1: Fundações (Concluído) +- Modelação de classes +- Simulação DES single-process +- Design de protocolo de serialização +- Implementação JSON/Java serialization +- Testes unitários + +#### Fase 2: Distribuição (Em Curso) +- Implementar comunicação via sockets +- Separar cruzamentos em processos +- Implementar threads de semáforos +- Testar comunicação entre processos + +#### Fase 3: Dashboard e Monitorização +- Dashboard server +- UI web em tempo real +- Visualização de estatísticas +- Logs estruturados + +#### Fase 4: Optimização e Análise +- Testes de carga +- Análise de diferentes políticas +- Recolha de métricas +- Relatório final + +### Executar Testes + +```bash +# Todos os testes +mvn test + +# Apenas testes de serialização +mvn test -Dtest=SerializationTest + +# Com relatório de cobertura +mvn test jacoco:report +``` + +### Contribuir + +1. Fork o projeto +2. Criar uma branch para a funcionalidade (`git checkout -b feature/MinhaFuncionalidade`) +3. Commit das alterações (`git commit -m 'Adiciona MinhaFuncionalidade'`) +4. Push para a branch (`git push origin feature/MinhaFuncionalidade`) +5. Abrir um Pull Request + +--- + +## Métricas de Desempenho + +### Serialização + +| Formato | Tamanho | Latência | Throughput | +|---------|---------|----------|------------| +| JSON | 300 bytes | 40.79 μs | ~24k msgs/s | +| Java | 657 bytes | 33.34 μs | ~30k msgs/s | + +**Conclusão**: JSON é 54% menor com overhead desprezível (7 μs) + +### Simulação + +- **Veículos gerados/s**: ~0.5-1.0 (configurável) +- **Throughput**: ~0.2 veículos/s (saída) +- **Tempo de execução**: 140ms para 60s de simulação +- **Overhead**: < 0.25% do tempo simulado + +--- + +## Protocolo de Mensagens - Resumo + +### Formato Base + +``` ++------------------+ +| Message Header | +|------------------| +| messageId | UUID único +| type | Enum MessageType +| senderId | ID do processo remetente +| destinationId | ID do processo destino (null = broadcast) +| timestamp | Tempo de criação (ms) ++------------------+ +| Payload | +|------------------| +| Object | Dados específicos do tipo de mensagem ++------------------+ +``` + +### Serialização + +- **Formato**: JSON (UTF-8) +- **Biblioteca**: Gson 2.10.1 +- **Codificação**: UTF-8 +- **Compressão**: Opcional (gzip) + +### Transporte + +- **Protocolo**: TCP/IP +- **Porta base**: 5000+ (configurável) +- **Timeout**: 30s +- **Keep-alive**: Heartbeat a cada 5s + +--- + +## Segurança + +### Considerações + +1. **Validação de Mensagens** + - Verificar tipos esperados + - Validar intervalos de valores + - Rejeitar mensagens malformadas + +2. **Autenticação** (Planeado) + - Autenticação baseada em token + - Whitelist de processos + +3. **Encriptação** (Opcional) + - TLS/SSL para produção + - Não necessário para ambiente de desenvolvimento local + +--- + +## Licença + +Este projeto é desenvolvido para fins académicos no âmbito da disciplina de Sistemas Distribuídos (SD) do Instituto Politécnico do Porto. + +--- + +## Equipa + +**Instituição**: Instituto Politécnico do Porto +**Curso**: Sistemas Distribuídos +**Ano Letivo**: 2025-2026 (1º Semestre) + +--- + +## Suporte + +Para questões ou problemas: + +1. Consultar a [documentação](./main/docs/README.md) +2. Ver [exemplos de código](./main/src/main/java/sd/serialization/SerializationExample.java) +3. Executar testes: `mvn test` +4. Abrir issue no GitHub + +--- + +## Ligações Úteis + +- [Documentação do Projeto](./main/docs/README.md) +- [Plano de Desenvolvimento](./TODO.md) +- [Especificação de Serialização](./main/docs/SERIALIZATION_SPECIFICATION.md) +- [Guia de Serialização](./main/src/main/java/sd/serialization/README.md) + +--- + +**Última actualização**: 23 de outubro de 2025 +**Versão**: 1.0.0 +**Estado**: Em Desenvolvimento Activo diff --git a/main/src/main/java/sd/serialization/README.md b/main/src/main/java/sd/serialization/README.md deleted file mode 100644 index 186e36b..0000000 --- a/main/src/main/java/sd/serialization/README.md +++ /dev/null @@ -1,283 +0,0 @@ -# Serialization Package - -Este pacote fornece implementações de serialização para comunicação entre processos no sistema de simulação de tráfego distribuído. - -## Visão Geral - -O pacote `sd.serialization` oferece uma interface unificada para serializar e desserializar objetos Java, permitindo a comunicação através de sockets entre diferentes processos (cruzamentos, coordenador, dashboard). - -## Arquitetura - -``` -MessageSerializer (interface) - ├── JsonMessageSerializer (Gson-based) - └── JavaMessageSerializer (native) - -SerializerFactory (factory pattern) -SerializationException (custom exception) -``` - -## Uso Rápido - -### Exemplo Básico - -```java -// Criar um serializer (JSON recomendado) -MessageSerializer serializer = SerializerFactory.createDefault(); - -// Serializar um objeto -Vehicle vehicle = new Vehicle("V001", VehicleType.LIGHT, 10.5, route); -byte[] data = serializer.serialize(vehicle); - -// Enviar através de socket -outputStream.write(data); - -// Receber e desserializar -byte[] received = inputStream.readAllBytes(); -Vehicle deserialized = serializer.deserialize(received, Vehicle.class); -``` - -### Usando JSON (Recomendado) - -```java -// JSON com formatação legível (debugging) -MessageSerializer serializer = new JsonMessageSerializer(true); - -// JSON compacto (produção) -MessageSerializer serializer = new JsonMessageSerializer(false); - -// Ou via factory -MessageSerializer serializer = SerializerFactory.createJsonSerializer(); -``` - -### Usando Java Serialization - -```java -// Direto -MessageSerializer serializer = new JavaMessageSerializer(); - -// Ou via factory -MessageSerializer serializer = SerializerFactory.createJavaSerializer(); -``` - -## Configuração - -### Propriedades do Sistema - -Configure o serializer padrão através de propriedades: - -```bash -# Definir tipo de serialização (JSON ou JAVA_NATIVE) -java -Dsd.serialization.type=JSON -jar app.jar - -# Habilitar pretty-print no JSON (debugging) -java -Dsd.serialization.json.prettyPrint=true -jar app.jar -``` - -### Programaticamente - -```java -// Definir antes de iniciar a aplicação -System.setProperty("sd.serialization.type", "JSON"); -System.setProperty("sd.serialization.json.prettyPrint", "true"); - -MessageSerializer serializer = SerializerFactory.createDefault(); -``` - -## Comparação: JSON vs Java Serialization - -| Característica | JSON (Gson) | Java Native | -|----------------|-------------|-------------| -| **Legibilidade** | ✅ Texto legível | ❌ Binário | -| **Tamanho** | ✅ ~40% menor | ❌ Maior | -| **Debugging** | ✅ Fácil | ❌ Difícil | -| **Performance** | ⚠️ ~20% mais lento | ✅ Mais rápido | -| **Interoperabilidade** | ✅ Universal | ❌ Só Java | -| **Segurança** | ✅ Mais seguro | ⚠️ Vulnerabilidades | -| **Dependências** | ⚠️ Gson | ✅ Nativo | -| **Evolução** | ✅ Flexível | ⚠️ serialVersionUID | - -### Recomendação: **JSON (Gson)** ✅ - -Para este projeto, JSON é recomendado porque: -- Facilita debugging durante desenvolvimento -- Tamanho menor de mensagens -- Mais fácil de manter e evoluir -- Permite integração futura (dashboard web) -- Performance suficiente para o volume esperado - -## Tratamento de Erros - -```java -try { - byte[] data = serializer.serialize(object); - // ... enviar ... -} catch (SerializationException e) { - // Log e tratamento - logger.error("Failed to serialize: " + e.getMessage(), e); -} - -try { - Object obj = serializer.deserialize(data, MyClass.class); -} catch (SerializationException e) { - // Dados corrompidos ou incompatíveis - logger.error("Failed to deserialize: " + e.getMessage(), e); -} -``` - -## Exemplos de Mensagens - -### Vehicle Transfer - -```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 - } -} -``` - -### Statistics Update - -```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 - } -} -``` - -## Testes - -Execute os testes de serialização: - -```bash -mvn test -Dtest=SerializationTest -``` - -Execute o exemplo de demonstração: - -```bash -mvn exec:java -Dexec.mainClass="sd.serialization.SerializationExample" -``` - -## Performance - -### Métricas Típicas (Rede Local) - -**JSON:** -- Tamanho médio: 250-350 bytes -- Latência: 0.8-1.5 ms -- Throughput: ~8,000 msgs/s - -**Java Serialization:** -- Tamanho médio: 400-600 bytes -- Latência: 0.5-1.0 ms -- Throughput: ~10,000 msgs/s - -Para o volume esperado no projeto (~100-1000 msgs/s), ambos são mais que suficientes. - -## Extensibilidade - -### Adicionar Novo Tipo de Serialização - -1. Implementar `MessageSerializer` -2. Adicionar tipo em `SerializerFactory.SerializationType` -3. Atualizar `SerializerFactory.create()` - -Exemplo: - -```java -public class ProtobufMessageSerializer implements MessageSerializer { - @Override - public byte[] serialize(Object object) throws SerializationException { - // Implementação - } - - @Override - public T deserialize(byte[] data, Class clazz) throws SerializationException { - // Implementação - } - - @Override - public String getName() { - return "Protocol Buffers"; - } -} -``` - -### Custom Type Adapters (JSON) - -Para tipos complexos ou customização: - -```java -GsonBuilder builder = new GsonBuilder(); -builder.registerTypeAdapter(MyClass.class, new MyClassAdapter()); -Gson gson = builder.create(); -``` - -## Boas Práticas - -1. **Validação**: Sempre validar objetos após desserialização -2. **Logging**: Logar mensagens em desenvolvimento, desabilitar em produção -3. **Versionamento**: Incluir versão nas mensagens para evolução -4. **Exceções**: Tratar `SerializationException` apropriadamente -5. **Testes**: Testar serialização round-trip para todos os tipos - -## Troubleshooting - -### "SerializationException: Failed to serialize" -- Verificar se o objeto é Serializable (Java) ou tem getters/setters (JSON) -- Verificar se há referências circulares - -### "SerializationException: Failed to parse JSON" -- Dados corrompidos na rede -- Incompatibilidade de versão entre classes -- JSON malformado - -### Messages muito grandes -- Revisar estrutura de dados -- Considerar compressão (gzip) -- Enviar apenas dados necessários - -### Performance issues -- Verificar se está usando pretty-print em produção (desabilitar) -- Considerar pool de serializers -- Medir com profiler - -## Recursos Adicionais - -- [Especificação Completa](../docs/SERIALIZATION_SPECIFICATION.md) -- [Gson Documentation](https://github.com/google/gson/blob/master/UserGuide.md) -- [Java Serialization Spec](https://docs.oracle.com/javase/8/docs/platform/serialization/spec/serialTOC.html) - -## Suporte - -Para questões ou problemas, consultar: -1. Documentação completa: `docs/SERIALIZATION_SPECIFICATION.md` -2. Testes unitários: `test/java/sd/serialization/SerializationTest.java` -3. Exemplo de uso: `main/java/sd/serialization/SerializationExample.java`