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(java.nio.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 Detail

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:

java.lang.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:

java.lang.IllegalArgumentException - if length is negative

java.lang.IndexOutOfBoundsException - if index is negative or index + length is greater than the array length

java.lang.IllegalStateException - if this hash function is not incremental but an output method has been called without an intervening call to reset()

update

void update(java.nio.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:

java.lang.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:

java.lang.UnsupportedOperationException - if this function does not support unsafe memory access

java.lang.IllegalStateException - if this hash function is not incremental but an output method has been called without an intervening call to reset()

See Also:

Hash.supportsUnsafe()

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:

java.lang.IllegalArgumentException - if maxLength is negative

java.lang.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