Access (Zero-allocation Hashing 0.5 API)

java.lang.Object
- net.openhft.hashing.Access<T>

Type Parameters:

T - the type of the object to access
```
public abstract class Access<T>
extends Object
```
Strategy of reading bytes, defines the abstraction of T class instances as ordered byte sequence. All getXXX(input, offset) should be consistent to each other in terms of ordered byte sequence each T instance represents. For example, if some Access implementation returns ByteOrder.LITTLE_ENDIAN on byteOrder(input) call, the following expressions should always have the same value:
- getLong(input, 0)
- getUnsignedInt(input, 0) | (getUnsignedInt(input, 4) << 32)
- ```
 getUnsignedInt(input, 0) |
    ((long) getUnsignedShort(input, 4) << 32) |
    ((long) getUnsignedByte(input, 6) << 48) |
    ((long) getUnsignedByte(input, 7) << 56)
```
- And so on
getXXX(input, offset) methods could throw unchecked exceptions when requested bytes range is outside of the bounds of the byte sequence, represented by the given input. However, they could omit checks for better performance.
Only getByte(Object, long) and byteOrder(Object) methods are abstract in this class, so implementing them is sufficient for valid Access instance, but for efficiency your should override methods used by target LongHashFunction implementation.
Access API is designed for inputs, that actually represent byte sequences that lay continuously in memory. Theoretically Access strategy could be implemented for non-continuous byte sequences, or abstractions which aren't actually present in memory as they are accessed, but this should be awkward, and hashing using such Access is expected to be slow.
See Also:

LongHashFunction.hash(Object, Access, long, long)

Constructor Summary

Constructors
Modifier Constructor and Description

protected Access()
Constructor for use in subclasses.

Constructors
Modifier	Constructor and Description
`protected`	`Access()` Constructor for use in subclasses.

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`abstract ByteOrder`	`byteOrder(T input)` The byte order in which all multi-byte `getXXX()` reads from the given `input` are performed.
`abstract int`	`getByte(T input, long offset)` Reads a single byte at the given `offset` in the byte sequence represented by the given `input`, returned widened to `int`.
`int`	`getInt(T input, long offset)` Reads `[offset, offset + 3]` bytes of the byte sequence represented by the given `input` as a single `int` value.
`long`	`getLong(T input, long offset)` Reads `[offset, offset + 7]` bytes of the byte sequence represented by the given `input` as a single `long` value.
`int`	`getShort(T input, long offset)` Reads `[offset, offset + 1]` bytes of the byte sequence represented by the given `input` as a single `short` value, returned widened to `int`.
`int`	`getUnsignedByte(T input, long offset)` Shortcut for `getByte(input, offset) & 0xFF`.
`long`	`getUnsignedInt(T input, long offset)` Shortcut for `getInt(input, offset) & 0xFFFFFFFFL`.
`int`	`getUnsignedShort(T input, long offset)` Shortcut for `getShort(input, offset) & 0xFFFF`.
`static Access<ByteBuffer>`	`toByteBuffer()` Returns the `Access` to any `ByteBuffer`.
`static <T extends CharSequence> Access<T>`	`toCharSequence(ByteOrder backingOrder)` Returns the `Access` to `CharSequence`s backed by `char` reads made in the specified byte order.
`static <T extends CharSequence> Access<T>`	`toNativeCharSequence()` Returns the `Access` to `CharSequence`s backed by native `char` reads, typically from `char[]` array.
`static <T> Access<T>`	`unsafe()` Returns the `Access` delegating `getXXX(input, offset)` methods to `sun.misc.Unsafe.getXXX(input, offset)`.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - Access
```
protected Access()
```
    Constructor for use in subclasses.
- Method Detail
  - unsafe
```
public static <T> Access<T> unsafe()
```
    Returns the Access delegating getXXX(input, offset) methods to sun.misc.Unsafe.getXXX(input, offset).
    Usage example:
```
 class Pair {
     long first, second;

     static final long pairDataOffset =
         theUnsafe.objectFieldOffset(Pair.class.getDeclaredField("first"));

     static long hashPair(Pair pair, LongHashFunction hashFunction) {
         return hashFunction.hash(pair, Access.unsafe(), pairDataOffset, 16L);
     }
 }
```
    null is a valid input, on accepting null Unsafe just interprets the given offset as a wild memory address. Note that for hashing memory by address there is a shortcut hashMemory(address, len) method.
    Type Parameters:
    
    T - the type of objects to access
    
    Returns:
    
    the unsafe memory Access
  - toByteBuffer
```
public static Access<ByteBuffer> toByteBuffer()
```
    Returns the Access to any ByteBuffer. This Access isn't useful in the user code, because methods LongHashFunction.hashBytes(ByteBuffer) and LongHashFunction.hashBytes(ByteBuffer, int, int) exist. This Access could be used in new LongHashFunction implementations.
    
    Returns:
    
    the Access to ByteBuffers
  - toNativeCharSequence
```
public static <T extends CharSequence> Access<T> toNativeCharSequence()
```
    Returns the Access to CharSequences backed by native char reads, typically from char[] array.
    Usage example:
```
 static long hashStringBuffer(StringBuffer buffer, LongHashFunction hashFunction) {
     return hashFunction.hash(buffer, Access.toNativeCharSequence(),
         // * 2L because length is passed in bytes, not chars
         0L, buffer.length() * 2L);
 }
```
    This method is a shortcut for Access.toCharSequence(ByteOrder.nativeOrder()).
    Type Parameters:
    
    T - the CharSequence subtype (backed by native char reads) to access
    
    Returns:
    
    the Access to CharSequences backed by native char reads
    
    See Also:
    
    toCharSequence(ByteOrder)
  - toCharSequence
```
public static <T extends CharSequence> Access<T> toCharSequence(ByteOrder backingOrder)
```
    Returns the Access to CharSequences backed by char reads made in the specified byte order.
    Usage example:
```
 static long hashCharBuffer(CharBuffer buffer, LongHashFunction hashFunction) {
     return hashFunction.hash(buffer, Access.toCharSequence(buffer.order()),
         // * 2L because length is passed in bytes, not chars
         0L, buffer.length() * 2L);
 }
```
    Type Parameters:
    
    T - the CharSequence subtype to access
    
    Parameters:
    
    backingOrder - the byte order of char reads backing CharSequences to access
    
    Returns:
    
    the Access to CharSequences backed by char reads made in the specified byte order
    
    See Also:
    
    toNativeCharSequence()
  - getLong
```
public long getLong(T input,
                    long offset)
```
    Reads [offset, offset + 7] bytes of the byte sequence represented by the given input as a single long value.
    
    Parameters:
    
    input - the object to access
    
    offset - offset to the first byte to read within the byte sequence represented by the given object
    
    Returns:
    
    eight bytes as a long value, in the expected order
  - getUnsignedInt
```
public long getUnsignedInt(T input,
                           long offset)
```
    Shortcut for getInt(input, offset) & 0xFFFFFFFFL. Could be implemented more efficiently.
    
    Parameters:
    
    input - the object to access
    
    offset - offset to the first byte to read within the byte sequence represented by the given object
    
    Returns:
    
    four bytes as an unsigned int value, in the expected order
  - getInt
```
public int getInt(T input,
                  long offset)
```
    Reads [offset, offset + 3] bytes of the byte sequence represented by the given input as a single int value.
    
    Parameters:
    
    input - the object to access
    
    offset - offset to the first byte to read within the byte sequence represented by the given object
    
    Returns:
    
    four bytes as an int value, in the expected order
  - getUnsignedShort
```
public int getUnsignedShort(T input,
                            long offset)
```
    Shortcut for getShort(input, offset) & 0xFFFF. Could be implemented more efficiently.
    
    Parameters:
    
    input - the object to access
    
    offset - offset to the first byte to read within the byte sequence represented by the given object
    
    Returns:
    
    two bytes as an unsigned short value, in the expected order
  - getShort
```
public int getShort(T input,
                    long offset)
```
    Reads [offset, offset + 1] bytes of the byte sequence represented by the given input as a single short value, returned widened to int.
    
    Parameters:
    
    input - the object to access
    
    offset - offset to the first byte to read within the byte sequence represented by the given object
    
    Returns:
    
    two bytes as a short value, in the expected order, widened to int
  - getUnsignedByte
```
public int getUnsignedByte(T input,
                           long offset)
```
    Shortcut for getByte(input, offset) & 0xFF. Could be implemented more efficiently.
    
    Parameters:
    
    input - the object to access
    
    offset - offset to the byte to read within the byte sequence represented by the given object
    
    Returns:
    
    a byte by the given offset, interpreted as unsigned
  - getByte
```
public abstract int getByte(T input,
                            long offset)
```
    Reads a single byte at the given offset in the byte sequence represented by the given input, returned widened to int.
    
    Parameters:
    
    input - the object to access
    
    offset - offset to the byte to read within the byte sequence represented by the given object
    
    Returns:
    
    a byte by the given offset, widened to int
  - byteOrder
```
public abstract ByteOrder byteOrder(T input)
```
    The byte order in which all multi-byte getXXX() reads from the given input are performed.
    
    Parameters:
    
    input - the accessed object
    
    Returns:
    
    the byte order of all multi-byte reads from the given input

Class Access<T>

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Access

Method Detail

unsafe

toByteBuffer

toNativeCharSequence

toCharSequence

getLong

getUnsignedInt

getInt

getUnsignedShort

getShort

getUnsignedByte

getByte

byteOrder