org.xlattice.crypto.filters

## Class KeySelector

- java.lang.Object
- - org.xlattice.crypto.filters.KeySelector

-     public class KeySelector
      extends Object

  Utility class for extracting word and bit offsets from cryptographic keys for Bloom filter operations.

  KeySelector provides the core functionality needed to map cryptographic keys to the specific bit and word positions used by Bloom filter hash functions. This is essential for implementing efficient Bloom filters where each hash function needs to examine specific bits or words from the key.

  The class supports two types of selectors:

  - BitSelector: Extracts individual bit positions (5-bit stride)
  - WordSelector: Extracts word positions ((m-5)-bit stride)

  Usage example: Create a KeySelector with m and k parameters, then call getOffsets() to extract bit and word offsets from a key.

  Example: new KeySelector(1024, 5) creates a selector for m=1024, k=5.

  Constraints and limitations:

  - Maximum supported for 32-byte keys: m=23, k=11
  - Formula constraint: ((5k + (k-1)(m-5)) / 8) + 2 ≤ keySizeInBytes
  - All methods are thread-safe for concurrent access

  Algorithm details:

  - Bit selectors use 5-bit stride for optimal distribution
  - Word selectors use (m-5)-bit stride to avoid bit selector overlap
  - Both use lookup tables (UNMASK/MASK) for efficient bit operations

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `KeySelector.BitSelector` Interface for extracting bit offsets from cryptographic keys for Bloom filter operations.
    `class` | `KeySelector.GenericBitSelector` Generic implementation of BitSelector for extracting bit offsets from cryptographic keys.
    `class` | `KeySelector.GenericWordSelector` Generic implementation of WordSelector for extracting word offsets from cryptographic keys.
    `static interface` | `KeySelector.WordSelector` Interface for extracting word offsets from cryptographic keys for Bloom filter operations.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `KeySelector(int m, int k)` Creates a key selector for a Bloom filter with specified parameters.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `getOffsets(byte[] key, int[] bitOffset, int[] wordOffset)` Given a key, populate the word and bit offset arrays, each of which has k elements.
    `void` | `getOffsets(byte[] key, int off, int len, int[] bitOffset, int[] wordOffset)` Given a key, populate the word and bit offset arrays, each of which has k elements.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### KeySelector

          public KeySelector(int m,
                             int k)

      Creates a key selector for a Bloom filter with specified parameters.

      This constructor initializes both bit and word selectors with the appropriate algorithms for the given m and k values. The selectors will then be used to extract offsets from keys for Bloom filter operations.

      Performance characteristics:
      - Bit selection: O(k) time complexity, constant space
      - Word selection: O(k) time complexity, constant space
      - Both implementations use lookup tables for efficiency
      - Thread-safe: no shared mutable state

      Memory usage: O(1) additional space for lookup tables and selector instances.

      Parameters:
        `m` - size of filter as a power of 2 (determines stride)
        `k` - number of 'hash functions' (determines number of offsets to extract)
      Throws:
        `IllegalArgumentException` - if parameters exceed implementation limits

        Implementation constraints:
        - Maximum for 32-byte keys: m=23, k=11
        - Formula constraint: ((5k + (k-1)(m-5)) / 8) + 2 ≤ keySizeInBytes
        - Larger values may cause ArrayIndexOutOfBoundsException
        - m must be ≥ 2 for valid stride calculations

        Note: The constraint formula ensures that the calculated offsets don't exceed the key boundaries. For larger m/k values, consider using larger key sizes or alternative selection algorithms.

  - ### Method Detail

    - #### getOffsets

          public void getOffsets(byte[] key,
                                 int[] bitOffset,
                                 int[] wordOffset)

      Given a key, populate the word and bit offset arrays, each of which has k elements.
      Parameters:
        `key` - cryptographic key used in populating the arrays
        `bitOffset` - Out parameter of length k
        `wordOffset` - Out parameter of length k

    - #### getOffsets

          public void getOffsets(byte[] key,
                                 int off,
                                 int len,
                                 int[] bitOffset,
                                 int[] wordOffset)

      Given a key, populate the word and bit offset arrays, each of which has k elements.
      Parameters:
        `key` - cryptographic key used in populating the arrays
        `off` - starting position within the key array
        `len` - number of bytes to process from the key
        `bitOffset` - Out parameter of length k
        `wordOffset` - Out parameter of length k