Package com.scurrilous.circe

Interface StatefulHash

All Superinterfaces:
Hash
All Known Subinterfaces:
StatefulIntHash, StatefulLongHash
All Known Implementing Classes:
AbstractStatefulHash, IncrementalIntStatefulHash, IncrementalLongStatefulHash, IntStatefulLongHash, JavaCrc32
public interface StatefulHash extends Hash
Represents a stateful hash function, which can accumulate input from multiple method calls and provide output in various forms. Stateful hash functions should not be used concurrently from multiple threads.

Stateful hash functions can be incremental or non-incremental. Incremental hashing allows calling the update(byte[]) methods to continue hashing using accumulated state after calling any of the output methods (such as getBytes()). Non-incremental hash functions require calling reset() to reinitialize the state between calling an output method and an update method.

  • Method Summary

    Modifier and Type
    Method
    Description
    StatefulHash
    createNew()
    Returns a new instance of this stateful hash function reset to the initial state.
    byte
    getByte()
    Returns the first byte of the output of this hash function.
    byte[]
    getBytes()
    Returns a new byte array containing the output of this hash function.
    int
    getBytes(byte[] output, int index, int maxLength)
    Writes the output of this hash function into the given byte array at the given offset.
    int
    getInt()
    Returns the first four bytes of the output of this hash function as a little-endian int.
    long
    getLong()
    Returns the first eight bytes of the output of this hash function as a little-endian long.
    short
    getShort()
    Returns the first two bytes of the output of this hash function as a little-endian short.
    void
    reset()
    Resets this hash function to its initial state.
    boolean
    supportsIncremental()
    Returns whether this hash function supports incremental hashing.
    void
    update(byte[] input)
    Updates the state of this hash function with the entire given input array.
    void
    update(byte[] input, int index, int length)
    Updates the state of this hash function with the given range of the given input array.
    void
    update(long address, long length)
    Updates the state of this hash function with memory with the given address and length.
    void
    update(ByteBuffer input)
    Updates the state of this hash function with the remaining contents of the given input buffer.

    Methods inherited from interface com.scurrilous.circe.Hash

    algorithm, length, supportsUnsafe

  • Method Details

    • createNew

      StatefulHash createNew()
      Returns a new instance of this stateful hash function reset to the initial state.
      Returns:
      a new instance of this hash in the initial state

    • supportsIncremental

      boolean supportsIncremental()
      Returns whether this hash function supports incremental hashing. Incremental hashing allows calling the update(byte[]) methods to continue hashing using accumulated state after calling any of the output methods (such as getBytes()). Non-incremental hash functions require calling reset() to reinitialize the state between calling an output method and an update method.
      Returns:
      true if incremental hashing is supported, false if not

    • reset

      void reset()
      Resets this hash function to its initial state. Resetting the state is required for non-incremental hash functions after any output methods have been called.

    • update

      void update(byte[] input)
      Updates the state of this hash function with the entire given input array.
      Parameters:
      input - the input array
      Throws:
      IllegalStateException - if this hash function is not incremental but an output method has been called without an intervening call to reset()

    • update

      void update(byte[] input, int index, int length)
      Updates the state of this hash function with the given range of the given input array.
      Parameters:
      input - the input array
      index - the starting index of the first input byte
      length - the length of the input range
      Throws:
      IllegalArgumentException - if length is negative
      IndexOutOfBoundsException - if index is negative or index + length is greater than the array length
      IllegalStateException - if this hash function is not incremental but an output method has been called without an intervening call to reset()

    • update

      void update(ByteBuffer input)
      Updates the state of this hash function with the remaining contents of the given input buffer. This method leaves the buffer position at the limit.
      Parameters:
      input - the input buffer
      Throws:
      IllegalStateException - if this hash function is not incremental but an output method has been called without an intervening call to reset()

    • update

      void update(long address, long length)
      Updates the state of this hash function with memory with the given address and length. The arguments are generally not checked in any way and will likely lead to a VM crash or undefined results if invalid.
      Parameters:
      address - the base address of the input
      length - the length of the input
      Throws:
      UnsupportedOperationException - if this function does not support unsafe memory access
      IllegalStateException - if this hash function is not incremental but an output method has been called without an intervening call to reset()
      See Also:

    • getBytes

      byte[] getBytes()
      Returns a new byte array containing the output of this hash function. The caller may freely modify the contents of the array.
      Returns:
      a new byte array containing the hash output

    • getBytes

      int getBytes(byte[] output, int index, int maxLength)
      Writes the output of this hash function into the given byte array at the given offset.
      Parameters:
      output - the destination array for the output
      index - the starting index of the first output byte
      maxLength - the maximum number of bytes to write
      Returns:
      the number of bytes written
      Throws:
      IllegalArgumentException - if maxLength is negative
      IndexOutOfBoundsException - if index is negative or if index + maxLength is greater than the array length

    • getByte

      byte getByte()
      Returns the first byte of the output of this hash function.
      Returns:
      the first output byte

    • getShort

      short getShort()
      Returns the first two bytes of the output of this hash function as a little-endian short. If the output is less than two bytes, the remaining bytes are set to 0.
      Returns:
      the first two output bytes as a short

    • getInt

      int getInt()
      Returns the first four bytes of the output of this hash function as a little-endian int. If the output is less than four bytes, the remaining bytes are set to 0.
      Returns:
      the first four output bytes as an int

    • getLong

      long getLong()
      Returns the first eight bytes of the output of this hash function as a little-endian long. If the output is less than eight bytes, the remaining bytes are set to 0.
      Returns:
      the first eight output bytes as a long