io.deephaven.util.codec.ObjectCodec Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of deephaven-codec-api Show documentation

Codec API: The base package for column codecs

The newest version!

//
// Copyright (c) 2016-2024 Deephaven Data Labs and Patent Pending
//
package io.deephaven.util.codec;

import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;

/**
 * 
 * Codec interface for Object translation to/from byte arrays for serialization and deserialization.
 * 

 * Implementations must follow several rules to enable correct usage:
 * 

 * They must be stateless or designed for concurrent use (e.g. by using only ThreadLocal state), as they will
 * generally be cached and re-used.
 * They must not modify their inputs in any way, retain references to their inputs, or return results that retain
 * references to their inputs.
 * They should provide a public constructor that takes a single String argument, in order to allow
 * configuration-driven reflective instantiation.
 * 
 */
public interface ObjectCodec extends ObjectDecoder {

    /**
     * Encode the specified input as an array of bytes. Note that it is up to the implementation how to encode null
     * inputs. The use of a zero-length byte array is strongly encouraged.
     *
     * @param input The input object, possibly null
     * @return The output byte array
     */
    byte @NotNull [] encode(@Nullable TYPE input);

    /**
     * Does this codec support encoding of null values?
     *
     * @return if null values are supported
     */
    boolean isNullable();

    /**
     * If applicable, the maximum encodable precision. If precision is not applicable (i.e. for non-numeric types) this
     * method should return zero.
     *
     * @return the numeric precision supported by this codec
     */
    int getPrecision();

    /**
     * If applicable, the maximum encodable scale. If scale is not applicable (i.e. for non-numeric types) this method
     * should return zero.
     *
     * @return the numeric scale (digits after the decimal point) supported by this codec
     */
    int getScale();
}