| /******************************************************************************* |
| * 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(); |
| } |