package sd.serialization;

/**
 * Interface que define o contrato para estratégias de serialização e desserialização de objetos.
 * <p>
 * Esta abstração permite desacoplar a camada de transporte (Sockets TCP) da camada de
 * apresentação de dados. Ao implementar o padrão <b>Strategy</b>, o sistema ganha flexibilidade
 * para alternar entre diferentes formatos de codificação (JSON, Binário Nativo, XML, Protobuf)
 * sem necessidade de refatorização da lógica de rede.
 * <p>
 * <b>Requisitos para Implementações:</b>
 * <ul>
 * <li><b>Thread-Safety:</b> As implementações devem ser seguras para uso concorrente, dado que
 * instâncias únicas podem ser partilhadas por múltiplos <i>ClientHandlers</i>.</li>
 * <li><b>Robustez:</b> Falhas de parsing devem resultar em exceções tipificadas ({@link SerializationException}),
 * nunca em falhas silenciosas ou estados inconsistentes.</li>
 * </ul>
 * * @see JsonMessageSerializer
 */
public interface MessageSerializer {
    
    /**
     * Converte (Marshals) um objeto em memória para uma sequência de bytes para transmissão.
     * * @param object O objeto de domínio a ser serializado (não pode ser nulo).
     * @return Um array de bytes contendo a representação codificada do objeto.
     * @throws SerializationException Se ocorrer um erro durante a codificação (ex: ciclo de referências).
     * @throws IllegalArgumentException Se o objeto fornecido for nulo.
     */
    byte[] serialize(Object object) throws SerializationException;
    
    /**
     * Reconstrói (Unmarshals) um objeto a partir de uma sequência de bytes.
     * * @param <T> O tipo genérico do objeto esperado.
     * @param data O array de bytes contendo os dados serializados (não pode ser nulo).
     * @param clazz A classe do tipo esperado para verificação e instancialização.
     * @return A instância do objeto reconstruído com o seu estado restaurado.
     * @throws SerializationException Se os dados estiverem corrompidos ou incompatíveis com a classe alvo.
     * @throws IllegalArgumentException Se os dados ou a classe forem nulos.
     */
    <T> T deserialize(byte[] data, Class<T> clazz) throws SerializationException;
    
    /**
     * Obtém o identificador legível desta estratégia de serialização (ex: "JSON (Gson)", "Native").
     * Utilizado primariamente para logging, auditoria e negociação de conteúdo.
     * * @return O nome descritivo do serializador.
     */
    String getName();
    
}