Package space.arim.dazzleconf.engine.liaison

Class CollectionLiaison

java.lang.Object
space.arim.dazzleconf.engine.liaison.CollectionLiaison
All Implemented Interfaces:
TypeLiaison
public final class CollectionLiaison extends Object implements TypeLiaison
Liaison for lists, sets, and collections.

This liaison will match all of Collection<E>, List<E>, and Set<E>. It will use the relevant serializer for E to build the relevant collection in deserialization, or to serialize the elements (in the sequence given by the collection type) during serialization.

If a Set is requested, but the user input contains a duplicate element, it will be silently skipped.

Limitations

This liaison does not, and cannot, preserve entry metadata, such as comments, on list entries across separate acts of deserialization and serialization. Only a SerializeDeserialize.deserializeUpdate(space.arim.dazzleconf.engine.DeserializeInput, space.arim.dazzleconf.engine.SerializeOutput) operation can preserve this entry metadata.

Effective consistent order

This liaison chose the following implementation details, in order to service the requested types:

Thus, all collections, including Collection and Set, are in fact internally implemented using a consistent order. This means that from an end-user perspective, they will be indistinguishable from List: e.g., they will be deserialized and serialized in the same order, the only difference being that duplicate Set elements (if relevant) will be removed.

This class, CollectionLiaison, decided to adopt this behavior to reflect the fact that Collection, Set, and List are programmer-facing types: users likely have little knowledge of the difference. These types exist mainly from a developer's perspective. We could think of their purpose as follows:

  • Collection: an ordered sequence for the user, an unordered bag for the developer
  • List: an ordered sequence, both for the user and the developer
  • Set: an ordered sequence for the user (with duplicates ignored), a set for the developer

  • Constructor Details

    • CollectionLiaison

      public CollectionLiaison()
      Creates the liaison

  • Method Details

    • makeAgent

      @SideEffectFree public <V> @Nullable TypeLiaison.Agent<V> makeAgent(@NonNull TypeToken<V> typeToken, @NonNull TypeLiaison.Handshake handshake)
      Description copied from interface: TypeLiaison
      Attempts to support the following type.

      If supported, an agent is returned that handles type serialization, deserialization, and defaults. Note that implementations may need casting at the source level to satisfy the generic argument of the token requested.

      Specified by:
      makeAgent in interface TypeLiaison
      Type Parameters:
      V - the type being requested
      Parameters:
      typeToken - the type token
      handshake - the handshake
      Returns:
      the agent if supported, or null otherwise