/*******************************************************************************
* Copyright 2014 Trevor Robinson
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
******************************************************************************/
package com.scurrilous.circe;
import java.nio.ByteBuffer;
/**
* 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.
* <p>
* Stateful hash functions can be incremental or non-incremental. Incremental
* hashing allows calling the {@link #update} methods to continue hashing using
* accumulated state after calling any of the output methods (such as
* {@link #getBytes}). Non-incremental hash functions <i>require</i> calling
* {@link #reset} to reinitialize the state between calling an output method and
* an update method.
*/
public interface StatefulHash extends Hash {
/**
* Returns a new instance of this stateful hash function reset to the
* initial state.
*
* @return a new instance of this hash in the initial state
*/
StatefulHash createNew();
/**
* Returns whether this hash function supports incremental hashing.
* Incremental hashing allows calling the {@link #update} methods to
* continue hashing using accumulated state after calling any of the output
* methods (such as {@link #getBytes}). Non-incremental hash functions
* require calling {@link #reset} to reinitialize the state between calling
* an output method and an update method.
*
* @return true if incremental hashing is supported, false if not
*/
boolean supportsIncremental();
/**
* 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.
*/
void reset();
/**
* Updates the state of this hash function with the entire given input
* array.
*
* @param 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 {@link #reset}
*/
void update(byte[] input);
/**
* Updates the state of this hash function with the given range of the given
* input array.
*
* @param input the input array
* @param index the starting index of the first input byte
* @param length the length of the input range
* @throws IllegalArgumentException if length is negative
* @throws IndexOutOfBoundsException if index is negative or
* {@code index + length} is greater than the array length
* @throws IllegalStateException if this hash function is not incremental
* but an output method has been called without an intervening
* call to {@link #reset}
*/
void update(byte[] input, int index, int length);
/**
* 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.
*
* @param 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 {@link #reset}
*/
void update(ByteBuffer input);
/**
* 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.
*
* @param address the base address of the input
* @param length the length of the input
* @throws UnsupportedOperationException if this function does not support
* unsafe memory access
* @throws IllegalStateException if this hash function is not incremental
* but an output method has been called without an intervening
* call to {@link #reset}
* @see #supportsUnsafe()
*/
void update(long address, long length);
/**
* Returns a new byte array containing the output of this hash function. The
* caller may freely modify the contents of the array.
*
* @return a new byte array containing the hash output
*/
byte[] getBytes();
/**
* Writes the output of this hash function into the given byte array at the
* given offset.
*
* @param output the destination array for the output
* @param index the starting index of the first output byte
* @param maxLength the maximum number of bytes to write
* @return the number of bytes written
* @throws IllegalArgumentException if {@code maxLength} is negative
* @throws IndexOutOfBoundsException if {@code index} is negative or if
* {@code index + maxLength} is greater than the array length
*/
int getBytes(byte[] output, int index, int maxLength);
/**
* Returns the first byte of the output of this hash function.
*
* @return the first output byte
*/
byte getByte();
/**
* Returns the first two bytes of the output of this hash function as a
* little-endian {@code short}. If the output is less than two bytes, the
* remaining bytes are set to 0.
*
* @return the first two output bytes as a short
*/
short getShort();
/**
* Returns the first four bytes of the output of this hash function as a
* little-endian {@code int}. If the output is less than four bytes, the
* remaining bytes are set to 0.
*
* @return the first four output bytes as an int
*/
int getInt();
/**
* Returns the first eight bytes of the output of this hash function as a
* little-endian {@code long}. If the output is less than eight bytes, the
* remaining bytes are set to 0.
*
* @return the first eight output bytes as a long
*/
long getLong();
}