Package convex.core.data

Class Hash

java.lang.Object

convex.core.data.AObject

convex.core.data.ACell

convex.core.data.ACountable<T>

convex.core.data.ABlobLike<CVMLong>

convex.core.data.ABlob

convex.core.data.AArrayBlob

convex.core.data.Hash

All Implemented Interfaces:

IValidated, IWriteable, Comparable<ABlob>

public class Hash
extends AArrayBlob

Class used to represent an immutable 32-byte Hash value. The Hash algorithm used may depend on context. This is intended to help with type safety vs. regular Blob objects and as a useful type as a key in relevant data structures. "Companies spend millions of dollars on firewalls, encryption and secure access devices, and it's money wasted, because none of these measures address the weakest link in the security chain." - Kevin Mitnick

Field Summary

Fields

Modifier and Type	Field	Description
static final Hash	EMPTY_HASH
static final Hash	FALSE_HASH
static final int	LENGTH	Standard length of a Hash in bytes
static final Hash	NULL_HASH
static final Hash	TRUE_HASH
static final AType	TYPE	Type of Hash values is just a regular Blob

Fields inherited from class convex.core.data.AArrayBlob

length, offset, store

Fields inherited from class convex.core.data.ABlob

contentHash

Fields inherited from class convex.core.data.ACell

cachedRef, EMPTY_ARRAY

Fields inherited from class convex.core.data.AObject

encoding

Method Summary

Modifier and Type	Method	Description
final int	compareTo(Hash b)	Optimised compareTo for Hashes.
static Hash	compute(ACell value)	Computes the Hash for any ACell value.
int	encode(byte[] bs, int pos)	Writes this Cell's encoding to a byte array, including a tag byte which will be written first.
boolean	equals(Hash other)	Tests if the Hash value is precisely equal to another non-null Hash value.
int	estimatedEncodingSize()	Estimate the encoded data size for this Cell.
int	firstInt()	Get the first 32 bits of this Hash.
static Hash	fromHex(String hexString)	Constructs a Hash object from a hex string
Blob	getChunk(long i)	Gets a chunk of this Blob, as a canonical Blob up to the maximum chunk size.
int	getEncodingLength()	Method to calculate the encoding length of a Cell.
boolean	isCanonical()	Returns true if this Cell is in a canonical representation for message writing.
boolean	isEmbedded()	Determines if this Cell Represents an embedded object.
static Hash	parse(Object o)	Best effort attempt to parse a Hash.
static Hash	parse(String s)	Best effort attempt to parse a Hash.
static Hash	readRaw(ByteBuffer bb)	Reads a Hash from a ByteBuffer Assumes no Tag or count, i.e.
Blob	toCanonical()	Converts this Cell to its canonical version.
void	validateCell()	Validates the local structure and invariants of this cell.
static Hash	wrap(byte[] hashBytes)	Wraps the specified bytes as a Data object Warning: underlying bytes are used directly.
static Hash	wrap(byte[] hashBytes, int offset)	Wraps the specified bytes as a Data object Warning: underlying bytes are used directly.
static Hash	wrap(AArrayBlob data)	Wraps the specified blob data as a Hash, sharing the underlying byte array.
static Hash	wrap(AArrayBlob data, int pos)	Wraps the specified blob data as a Hash, sharing the underlying byte array.
static Hash	wrap(ABlob a)	Wraps the Blob as a Hash if possible

Methods inherited from class convex.core.data.AArrayBlob

append, appendHex, appendSmall, byteAt, byteAtUnchecked, commonHexPrefixLength, compareTo, compareTo, count, encodeRaw, equals, equalsBytes, equalsBytes, getByteBuffer, getBytes, getHexDigit, getInternalArray, getInternalOffset, getRefCount, getTag, hexMatches, hexMatchLength, longAt, longValue, rangeMatches, rangeMatches, shortAt, slice, toExactLong, toFlatBlob, updateDigest, validate

Methods inherited from class convex.core.data.ABlob

computeHash, empty, equals, get, getContentHash, getElementRef, getType, hashCode, hexEquals, hexEquals, hexLength, isCVMValue, isRegularBlob, print, slice, toByteBuffer, toHexString, toHexString

Methods inherited from class convex.core.data.ABlobLike

getBytes

Methods inherited from class convex.core.data.ACountable

isEmpty, size

Methods inherited from class convex.core.data.ACell

announce, announce, attachMemorySize, attachRef, cachedEncoding, cachedHash, calcMemorySize, createAnnounced, createEncoding, createPersisted, createPersisted, createRef, equals, getCanonical, getChildRefs, getEncoding, getHash, getMemorySize, getRef, getRef, isCompletelyEncoded, mark, mark, toCVMString, toString, updateRefs

Methods inherited from class convex.core.data.AObject

attachEncoding, print, print

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Details

LENGTH

public static final int LENGTH

Standard length of a Hash in bytes

See Also:

• Constant Field Values

TYPE

public static final AType TYPE

Type of Hash values is just a regular Blob

NULL_HASH

public static final Hash NULL_HASH

TRUE_HASH

public static final Hash TRUE_HASH

FALSE_HASH

public static final Hash FALSE_HASH

EMPTY_HASH

public static final Hash EMPTY_HASH

Method Details

wrap

public static Hash wrap(byte[] hashBytes)

Wraps the specified bytes as a Data object Warning: underlying bytes are used directly. Use only if no external references to the byte array will be retained.

Parameters:

hashBytes - Bytes to wrap (must be correct length)

Returns:

Hash wrapping the given byte array

wrap

public static Hash wrap(ABlob a)

Wraps the Blob as a Hash if possible

Parameters:

a - Any ABlob instance

Returns:

Hash instance, or null if argument is null or wrong length

wrap

public static Hash wrap(AArrayBlob data)

Wraps the specified blob data as a Hash, sharing the underlying byte array.

Parameters:

data - Blob data of correct size for a Hash. Must have at least enough bytes for a Hash

Returns:

Wrapped data as a Hash

wrap

public static Hash wrap(AArrayBlob data,
 int pos)

Wraps the specified blob data as a Hash, sharing the underlying byte array.

Parameters:

data - Blob data of correct size for a Hash. Must have at least enough bytes for a Hash

pos - Position ib Blob to read from

Returns:

Wrapped data as a Hash, or null if insufficent bytes in source Blob

wrap

public static Hash wrap(byte[] hashBytes,
 int offset)

Wraps the specified bytes as a Data object Warning: underlying bytes are used directly. Use only if no external references to the byte array will be retained.

Parameters:

hashBytes - Byte array containing hash value

offset - Offset into byte array for start of hash value

Returns:

Hash wrapping the given byte array segment

firstInt

public int firstInt()

Get the first 32 bits of this Hash. Used for Java hashCodes

Returns:

Int representing the first 32 bits

fromHex

public static Hash fromHex(String hexString)

Constructs a Hash object from a hex string

Parameters:

hexString - Hex String

Returns:

Hash with the given hex string value, or null is String is not valid

parse

public static Hash parse(Object o)

Best effort attempt to parse a Hash. Must parse as a blob of correct length

Parameters:

o - Object expected to contain a Hash value

Returns:

Hash value, or null is not parseable

parse

public static Hash parse(String s)

Best effort attempt to parse a Hash. Must parse as a blob of correct length. Leading "0x" optional.

Parameters:

s - String expected to contain a Hash value

Returns:

Hash value, or null is not parseable

compute

public static Hash compute(ACell value)

Computes the Hash for any ACell value. May return a cached Hash if available in memory.

Parameters:

value - Any Cell

Returns:

Hash of the encoded data for the given value

readRaw

public static Hash readRaw(ByteBuffer bb)

Reads a Hash from a ByteBuffer Assumes no Tag or count, i.e. just Hash.LENGTH for the hash is read.

Parameters:

bb - ByteBuffer to read from

Returns:

Hash object read from ByteBuffer

encode

public int encode(byte[] bs,
 int pos)

Description copied from class: ACell

Writes this Cell's encoding to a byte array, including a tag byte which will be written first. Cell must be canonical, or else an error may occur.

Specified by:

encode in interface IWriteable

Specified by:

encode in class ACell

Parameters:

bs - A byte array to which to write the encoding

pos - The offset into the byte array

Returns:

New position after writing

isCanonical

public boolean isCanonical()

Description copied from class: ACell

Returns true if this Cell is in a canonical representation for message writing. Non-canonical objects may be used on a temporary internal basis, they must always be converted to canonical representations for external use (e.g. Encoding).

Specified by:

isCanonical in class ACell

Returns:

true if the object is in canonical format, false otherwise

toCanonical

public Blob toCanonical()

Description copied from class: ACell

Converts this Cell to its canonical version. Must return this Cell if already canonical, may be O(n) in size of value otherwise.

Specified by:

toCanonical in class ABlob

Returns:

Canonical version of Cell

estimatedEncodingSize

public int estimatedEncodingSize()

Description copied from interface: IWriteable

Estimate the encoded data size for this Cell. Used for quickly sizing buffers. Implementations should try to return a size that is highly likely to contain the entire object when encoded, including the tag byte. Should not traverse soft Refs, i.e. must be usable on arbitrary partial data structures

Returns:

The estimated size for the binary representation of this object.

getEncodingLength

public int getEncodingLength()

Description copied from class: ACell

Method to calculate the encoding length of a Cell. May be overridden to avoid creating encodings during memory size calculations. This reduces hashing!

Overrides:

getEncodingLength in class ACell

Returns:

Exact encoding length of this Cell

getChunk

public Blob getChunk(long i)

Description copied from class: ABlob

Gets a chunk of this Blob, as a canonical Blob up to the maximum chunk size. Returns empty Blob if and only if referencing the end of a Blob with fully packed chunks

Specified by:

getChunk in class ABlob

Parameters:

i - Index of chunk

Returns:

A Blob containing the specified chunk data.

validateCell

public void validateCell()
                  throws InvalidDataException

Description copied from class: ACell

Validates the local structure and invariants of this cell. Called by validate() super implementation. Should validate directly contained data, but should not validate all other structure of this cell. In particular, should not traverse potentially missing child Refs.

Overrides:

validateCell in class AArrayBlob

Throws:

InvalidDataException - If the Cell is invalid

isEmbedded

public boolean isEmbedded()

Description copied from class: ACell

Determines if this Cell Represents an embedded object. Embedded objects are encoded directly into the encoding of the containing Cell (avoiding the need for a hashed reference). Subclasses should override this if they have a cheap O(1) way to determine if they are embedded or otherwise.

Overrides:

isEmbedded in class ACell

Returns:

true if Cell is embedded, false otherwise

compareTo

public final int compareTo(Hash b)

Optimised compareTo for Hashes. Needed for MapLeaf, SetLeaf etc.

Parameters:

b - Other Hash to compare with

Returns:

Negative if this is "smaller", 0 if this "equals" b, positive if this is "larger"

equals

public boolean equals(Hash other)

Tests if the Hash value is precisely equal to another non-null Hash value.

Parameters:

other - Hash to compare with

Returns:

true if Hashes are equal, false otherwise.