Package com.apple.foundationdb.map

Interface BunchedSerializer<K,V>

Type Parameters:
K - type of the keys in the BunchedMap
V - type of the values in the BunchedMap
All Known Implementing Classes:
BunchedTupleSerializer
@API(EXPERIMENTAL) public interface BunchedSerializer<K,V>
A class to serialize and deserialize entries of a BunchedMap. This is fairly standard in that it serializes and deserializes keys and values to and from byte arrays.

  • Method Summary

    Modifier and Type
    Method
    Description
    default boolean
    canAppend()
    Whether the output from serializeEntry can be appended to an existing serialized entry list to produce a new bunched value.
    List<Map.Entry<K,V>>
    deserializeEntries(K key, byte[] data)
    Deserialize raw data to a list of entries.
    default K
    deserializeKey(byte[] data)
    Deserialize a byte array into a key.
    default K
    deserializeKey(byte[] data, int offset)
    Deserialize a slice of a byte array into a key.
    K
    deserializeKey(byte[] data, int offset, int length)
    Deserialize a slice of a byte array into a key.
    default List<K>
    deserializeKeys(K key, byte[] data)
    Deserialize raw data to a list of keys.
    byte[]
    serializeEntries(List<Map.Entry<K,V>> entries)
    Serialize a list of entries.
    default byte[]
    serializeEntry(Map.Entry<K,V> entry)
    Serialize a single entry to bytes.
    byte[]
    serializeEntry(K key, V value)
    Serialize a single entry to bytes.
    byte[]
    serializeKey(K key)
    Serialize a key to bytes.

  • Method Details

    • serializeKey

      @Nonnull byte[] serializeKey(@Nonnull K key)
      Serialize a key to bytes. These bytes will be used by the BunchedMap to write a FoundationDB key. As a result, the sort order of the serialized bytes should match the sort order of the underlying keys of the map. (The comparison of bytes is done using unsigned byte comparison.)
      Parameters:
      key - key to serialize to bytes
      Returns:
      the serialized key
      Throws:
      BunchedSerializationException - if serializing the key fails

    • serializeEntry

      @Nonnull byte[] serializeEntry(@Nonnull K key, @Nonnull V value)
      Serialize a single entry to bytes. This serializes a single key and value to bytes. This function will be used in the case that canAppend() returns true and the BunchedMap can optimize what gets written by appending an entry to the end of an existing entry.
      Parameters:
      key - the key of the map entry
      value - the value of the map entry
      Returns:
      the serialized entry
      Throws:
      BunchedSerializationException - if serializing the entry fails

    • serializeEntry

      @Nonnull default byte[] serializeEntry(@Nonnull Map.Entry<K,V> entry)
      Serialize a single entry to bytes. This has the same semantics as calling serializeEntry(Object, Object) with the key and value contained within the entry provided.
      Parameters:
      entry - the map entry to serialize
      Returns:
      the serialized entry
      Throws:
      BunchedSerializationException - if serializing the entry fails

    • serializeEntries

      @Nonnull byte[] serializeEntries(@Nonnull List<Map.Entry<K,V>> entries)
      Serialize a list of entries. This will be used when multiple keys and values are serialized together in a single key/value pair in the underlying FoundationDB cluster. The BunchedMap class guarantees that when it serializes the entry list, it will store it under a key corresponding to the first entry in the list, so implementations can choose to omit the first entry's key to save space. That key will then be passed back to the serializer by deserializeEntries().
      Parameters:
      entries - the list of entries to serialize
      Returns:
      the serialized list
      Throws:
      BunchedSerializationException - if serializing the entries fails

    • deserializeKey

      @Nonnull default K deserializeKey(@Nonnull byte[] data)
      Deserialize a byte array into a key. This assumes that the entire array is being used to store the data for the key. This function should be the inverse of serializeKey.
      Parameters:
      data - source data to deserialize
      Returns:
      key deserialized from reading data
      Throws:
      BunchedSerializationException - if deserializing the key fails

    • deserializeKey

      @Nonnull default K deserializeKey(@Nonnull byte[] data, int offset)
      Deserialize a slice of a byte array into a key. This will only deserialize the portion of the array starting at offset and going to the end.
      Parameters:
      data - source data to deserialize
      offset - beginning offset of serialized key (indexed from 0)
      Returns:
      key deserialized from reading data
      Throws:
      BunchedSerializationException - if deserializing the key fails

    • deserializeKey

      @Nonnull K deserializeKey(@Nonnull byte[] data, int offset, int length)
      Deserialize a slice of a byte array into a key. This will only deserialize the portion of the array starting at offset and going for length bytes.
      Parameters:
      data - source data to deserialize
      offset - beginning offset of serialized key (indexed from 0)
      length - length of serialized key
      Returns:
      key deserialized from reading data
      Throws:
      BunchedSerializationException - if deserializing the key fails

    • deserializeEntries

      @Nonnull List<Map.Entry<K,V>> deserializeEntries(@Nonnull K key, @Nonnull byte[] data)
      Deserialize raw data to a list of entries. This should be the inverse of serializeEntries. Note that the order of elements returned within the list should be the same as their sort order. The key that this entry list is stored under is passed in so that implementations that wish to can choose to omit the first key of the entry list from the serialized value.
      Parameters:
      key - key under which the serialized entry list was stored
      data - source list to deserialize
      Returns:
      entry list deserialized from reading data
      Throws:
      BunchedSerializationException - if deserializing the entries fails

    • deserializeKeys

      @Nonnull default List<K> deserializeKeys(@Nonnull K key, @Nonnull byte[] data)
      Deserialize raw data to a list of keys. This expects that data contains both the keys and values for the various entries within. However, this function will only return the keys. By default, this will deserialize both the keys and the values contained within and just throw away the values, but implementations may decide to do this more efficiently if there is a way to do so.
      Parameters:
      key - key under which the serialized entry list was stored
      data - source data to deserialize
      Returns:
      key list deserialized from reading data
      Throws:
      BunchedSerializationException - if deserializing the keys fails

    • canAppend

      default boolean canAppend()
      Whether the output from serializeEntry can be appended to an existing serialized entry list to produce a new bunched value. That is, if this function returns true, then if some entry list l1 is a prefix of another entry list l2, then the serialization of l1 is also a serialization of the list l2. If this is the case, than the BunchedMap class can make certain optimizations during value insertion.
      Returns:
      whether this serializer will serialize entry lists in a way that allows entries to be appended to existing entry lists