Class ClientSerializer

java.lang.Object
com.loomcache.client.ClientSerializer
public final class ClientSerializer extends Object
Type-safe, locale-independent serializer for client proxy classes.

Replaces the previous use of String.valueOf() which is semantically lossy: distinct objects with identical toString() would collide (e.g., an Integer and a Long with the same numeric value, or locale-dependent decimal formatting).

This serializer produces deterministic string representations for supported types by encoding a single-character type tag followed by the value. The type tag ensures that values of different types never collide, even if their string representations are identical.

Type Tags

  S: String          I: Integer        L: Long           D: Double
  F: Float           H: Short          Y: Byte           C: Character
  B: Boolean         G: BigDecimal     J: BigInteger     U: UUID
  A: byte[]          N: null           O: legacy unsupported object payload

Thread Safety

This class is stateless and thread-safe. All methods are static.
Since:
1.1

  • Method Details

    • serialize

      public static String serialize(@Nullable Object obj)
      Serialize an object to a type-tagged string representation.

      The result is deterministic, locale-independent, and round-trippable via deserialize(String) for supported types. Different types with the same string representation will produce different serialized forms (e.g., Integer(42) vs Long(42L)). Unsupported types are rejected instead of being serialized lossy.

      Parameters:
      obj - the object to serialize (may be null)
      Returns:
      a type-tagged string, or the null sentinel "N" if obj is null
      Throws:
      SerializationException - if obj has an unsupported type

    • deserialize

      public static @Nullable Object deserialize(@Nullable String tagged)
      Deserialize a type-tagged string back to its original object.

      This is the inverse of serialize(Object) for supported tagged values. The type tag determines the target type, ensuring type fidelity across serialization boundaries.

      Parameters:
      tagged - the type-tagged string produced by serialize(Object)
      Returns:
      the deserialized object, or null if the input represents null
      Throws:
      IllegalArgumentException - if the tagged string has a malformed supported payload or an unknown type tag
      SerializationException - if the tagged string uses the unsupported legacy object payload tag

    • serializeToBytes

      public static byte[] serializeToBytes(@Nullable Object obj)
      Serialize an object to a UTF-8 byte array suitable for wire transmission.

      Convenience method that combines serialize(Object) with UTF-8 encoding, matching the existing wire protocol format used by LoomClient.

      Parameters:
      obj - the object to serialize (may be null)
      Returns:
      UTF-8 encoded bytes of the type-tagged string

    • deserializeFromBytes

      public static @Nullable Object deserializeFromBytes(byte @Nullable [] bytes)
      Deserialize a UTF-8 byte array back to its original object.

      Convenience method that combines UTF-8 decoding with deserialize(String).

      Parameters:
      bytes - the UTF-8 encoded type-tagged string (may be null or empty)
      Returns:
      the deserialized object, or null if input is null/empty

    • isLegacyFormat

      public static boolean isLegacyFormat(String value)
      Check if a serialized string uses the legacy String.valueOf() format (no type tag prefix).

      Used for backward compatibility: if existing data was stored with the old format, it can be detected and handled gracefully.

      Parameters:
      value - the stored string to check (must not be null)
      Returns:
      true if the value appears to be in legacy (untagged) format

    • deserializeWithLegacyFallback

      public static @Nullable Object deserializeWithLegacyFallback(@Nullable String value)
      Deserialize a value through the current wire decoder.

      The method name is retained for existing callers, but LoomCache is pre-production and no longer accepts unframed legacy payloads.

      Parameters:
      value - the stored value to deserialize (may be null)
      Returns:
      the deserialized object, or null