Package com.qfs.dic

Interface IDictionary<K>

Type Parameters:
K - type of the indexed objects
All Superinterfaces:
ICompressible, IMemoryMonitored, Serializable
All Known Subinterfaces:
ICharSequenceDictionary<C>, IConcurrentDictionary<K>, IFixedLengthIntegerArrayDictionary, IIntegerArrayDictionary, IWritableDictionary<K>, IWritableDictionary.IDoubleDictionary, IWritableDictionary.IFloatDictionary, IWritableDictionary.IIntegerDictionary, IWritableDictionary.ILongDictionary, IWritableIntegerArrayDictionary
All Known Implementing Classes:
AbstractDictionary, AChristmasDictionary, AChristmasDictionaryArray, AChristmasDictionaryArray.ChristmasDictionaryDoubleArray, AChristmasDictionaryArray.ChristmasDictionaryFloatArray, AChristmasDictionaryArray.ChristmasDictionaryIntegerArray, AChristmasDictionaryArray.ChristmasDictionaryLongArray, AChristmasDictionaryArray.ChristmasDictionaryObjectArray, AFixedLengthIntegerArrayDictionary, BucketedIntegerArrayDictionary, BufferIntegerDictionary, ChristmasDictionary, ChristmasDictionary.ChristmasDictionaryString, ChristmasDictionaryDouble, ChristmasDictionaryFloat, ChristmasDictionaryInteger, ChristmasDictionaryLong, ColumnarIntegerArrayDictionary, Dictionary, FixedLengthIntegerArrayDictionary, IntegerArrayDictionary, IntegerArrayDictionaryWithHash, IntegerArrayPermutationDictionary, IntegerDictionary, LocationDictionary, LongDictionary, NullableDictionary, PackedIntDictionary, PairDictionary, SharedDelegateDictionary, StrategyDictionary, StringDictionary, TranslatedIntegerArrayDictionary, TupleDictionary
public interface IDictionary<K> extends Serializable, IMemoryMonitored, ICompressible
A dictionary dynamically maintains a collection of key objects Once inserted, the dictionary guarantees that each key remains at its insertion position, even when new keys are inserted or when the dictionary buffer is expanded.
A dictionary allows to reference objects by their position (efficiently using a primitive integer) instead of a costlier object reference.

Keys receive their integer address in sequence, the first object receives address '0', the second object receives address '1'...

The dictionary defines a dynamic order, a dictionary of order k can contain up to 2^k objects. It means that a dictionary of order 8 can contain 256 objects, and the respective addresses can be coded using a byte. A dictionary of order 16 can contain 65536 objects, and the respective addresses can be coded using a short...

When the dictionary grows it may have to change its order, dictionary listeners are warned about the order change so that they can themselves upgrade their data structure.

Author:
ActiveViam

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    DEFAULT_INITIAL_CAPACITY
    The default initial capacity for dictionaries.
    static final LongSupplier
    ID_GENERATOR
    The generator for unique IDs for the dictionaries.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    copyInto(int position, IWritableCell cell)
    Copies the de-dictionarized value at a given position into the provided cell.
    long
    getDictionaryId()
    Gets the unique ID of this dictionary useful for monitoring).
    int
    getDoublePosition(double key)
    Searches for a double in the dictionary.
    default List<String>
    getFirstElements()
    MONITORING:
    The list of the first 100 elements.
    int
    getFloatPosition(float key)
    Searches for a float in the dictionary.
    int
    getIntPosition(int key)
    Searches for an integer in the dictionary.
    int
    getLongPosition(long key)
    Searches for a long in the dictionary.
    int
    getOrder()
    Gets the order of that dictionary.
    int
    getPosition(K key)
    Searches for a key in the dictionary.
    default int
    getSize()
    MONITORING:
    The size of the dictionary.
    default String
    getType()
    MONITORING:
    The type of the dictionary (ie the type of the instance).
    boolean
    isNullable()
    Returns whether this dictionary is nullable (it is capable to map the null key).
    K
    read(int position)
    Reads the object stored at a given dictionary position.
    double
    readDouble(int position)
    Reads the double stored at a given dictionary position.
    float
    readFloat(int position)
    Reads the float stored at a given dictionary position.
    int
    readInt(int position)
    Reads the integer stored at a given dictionary position.
    long
    readLong(int position)
    Reads the long stored at a given dictionary position.
    int
    size()
    Gets the size (number of entries) of this dictionary.
    boolean
    supportConcurrentReads()
    Returns whether the dictionary supports Single Writer/Multiple Reader (SWMR).

    Methods inherited from interface com.qfs.memory.ICompressible

    compress, compress

    Methods inherited from interface com.qfs.monitoring.memory.IMemoryMonitored

    getMemoryStatistic

  • Field Details

    • DEFAULT_INITIAL_CAPACITY

      static final int DEFAULT_INITIAL_CAPACITY
      The default initial capacity for dictionaries.
      See Also:

    • ID_GENERATOR

      static final LongSupplier ID_GENERATOR
      The generator for unique IDs for the dictionaries.

  • Method Details

    • getDictionaryId

      long getDictionaryId()
      Gets the unique ID of this dictionary useful for monitoring).
      Returns:
      the ID of this dictionary (unique amongst all dictionaries used in the application)

    • supportConcurrentReads

      boolean supportConcurrentReads()
      Returns whether the dictionary supports Single Writer/Multiple Reader (SWMR).
      Returns:
      true if the dictionary supports SWMR, false otherwise

    • read

      K read(int position)
      Reads the object stored at a given dictionary position.
      Parameters:
      position - the position in the dictionary where to read the object
      Returns:
      the Object at the given position

    • copyInto

      void copyInto(int position, IWritableCell cell)
      Copies the de-dictionarized value at a given position into the provided cell.
      Parameters:
      position - dictionarized value to read
      cell - cell filled with the corresponding value

    • readInt

      int readInt(int position)
      Reads the integer stored at a given dictionary position.

      Will throw UnsupportedOperationException if the stored object in the dictionary is not of type Int.

      Parameters:
      position - the position in the dictionary
      Returns:
      the integer stored at the given position

    • readLong

      long readLong(int position)
      Reads the long stored at a given dictionary position.

      Will throw UnsupportedOperationException if the stored object in the dictionary is not of type Long.

      Parameters:
      position - the position in the dictionary
      Returns:
      the long stored at the given position

    • readFloat

      float readFloat(int position)
      Reads the float stored at a given dictionary position.

      Will throw UnsupportedOperationException if the stored object in the dictionary is not of type Float.

      Parameters:
      position - the position in the dictionary
      Returns:
      the float stored at the given position

    • readDouble

      double readDouble(int position)
      Reads the double stored at a given dictionary position.

      Will throw UnsupportedOperationException if the stored object in the dictionary is not of type Double.

      Parameters:
      position - the position in the dictionary
      Returns:
      the double stored at the given position

    • size

      int size()
      Gets the size (number of entries) of this dictionary.
      Returns:
      the size

    • getOrder

      int getOrder()
      Gets the order of that dictionary.

      The order of a dictionary is the number of bits required to represent any encoded value within that dictionary.

      Returns:
      the order

    • isNullable

      boolean isNullable()
      Returns whether this dictionary is nullable (it is capable to map the null key).

      Trying to map or search the null element on a dictionary that is non-nullable will at some point throw a NullPointerException.

      Returns:
      true if this dictionary is nullable, false otherwise

    • getPosition

      int getPosition(K key)
      Searches for a key in the dictionary.
      Parameters:
      key - the object we are looking for
      Returns:
      position of the key in the dictionary, or -1 if the key is not in the dictionary

    • getIntPosition

      int getIntPosition(int key)
      Searches for an integer in the dictionary.

      Will throw UnsupportedOperationException if the stored object in the dictionary is not of type Int.

      Parameters:
      key - the integer
      Returns:
      position of the key in the dictionary, or -1 if the key is not in the dictionary

    • getLongPosition

      int getLongPosition(long key)
      Searches for a long in the dictionary.

      Will throw UnsupportedOperationException if the stored object in the dictionary is not of type Long.

      Parameters:
      key - the long
      Returns:
      position of the key in the dictionary, or -1 if the key is not in the dictionary

    • getFloatPosition

      int getFloatPosition(float key)
      Searches for a float in the dictionary.

      Will throw UnsupportedOperationException if the stored object in the dictionary is not of type Float.

      Parameters:
      key - the float
      Returns:
      position of the key in the dictionary, or -1 if the key is not in the dictionary

    • getDoublePosition

      int getDoublePosition(double key)
      Searches for a double in the dictionary.

      Will throw UnsupportedOperationException if the stored object in the dictionary is not of type Double.

      Parameters:
      key - the double
      Returns:
      position of the key in the dictionary, or -1 if the key is not in the dictionary

    • getType

      default String getType()
      MONITORING:
      The type of the dictionary (ie the type of the instance).
      Returns:
      the type of the dictionary

    • getSize

      default int getSize()
      MONITORING:
      The size of the dictionary.
      Returns:
      the size of the dictionary
      See Also:

    • getFirstElements

      default List<String> getFirstElements()
      MONITORING:
      The list of the first 100 elements.
      Returns:
      the list of the first 100 elements