io.goshawkdb.collections.linearhash

Class LinearHash

java.lang.Object

io.goshawkdb.collections.linearhash.LinearHash

public class LinearHash
extends java.lang.Object

A LinearHash is a map structure using the linear-hashing algorithm. This implementation uses the SipHash hashing algorithm, which is available on many platforms and languages, and uses msgpack as the serialization format for the LinearHash state, which again, is widely available. Multiple connections may interact with the same underlying LHash objects at the same time, as GoshawkDB ensures through the use of strong serialization that any dependent operations are safely ordered.

Field Summary

Fields

Modifier and Type	Field and Description
io.goshawkdb.client.Connection	conn The connection used to create this LinearHash object.
io.goshawkdb.client.GoshawkObjRef	objRef The underlying Object in GoshawkDB which holds the root data for the LHash.

Constructor Summary

Constructors

Constructor and Description
LinearHash(io.goshawkdb.client.Connection c, io.goshawkdb.client.GoshawkObjRef ref) Create a LinearHash object from an existing given GoshawkDB Object.

Method Summary

Modifier and Type	Method and Description
static LinearHash	createEmpty(io.goshawkdb.client.Connection c) Create a brand new empty LinearHash.
io.goshawkdb.client.GoshawkObjRef	find(byte[] key) Search the LinearHash for the given key.
void	forEach(java.util.function.BiConsumer<? super byte[],? super io.goshawkdb.client.GoshawkObjRef> action) Iterate over the entries in the LinearHash.
void	put(byte[] key, io.goshawkdb.client.GoshawkObjRef value) Idempotently add the given key and value to the LinearHash.
void	remove(byte[] key) Idempotently remove any matching entry from the LinearHash.
int	size() Returns the number of entries in the LinearHash.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

conn

public final io.goshawkdb.client.Connection conn

The connection used to create this LinearHash object. As usual with GoshawkDB, objects are scoped to connections so you should not use the same LinearHash object from multiple connections. You can have multiple LinearHash objects for the same underlying set of GoshawkDB objects.

objRef

public io.goshawkdb.client.GoshawkObjRef objRef

The underlying Object in GoshawkDB which holds the root data for the LHash.

Constructor Detail

LinearHash

public LinearHash(io.goshawkdb.client.Connection c,
                  io.goshawkdb.client.GoshawkObjRef ref)

Create a LinearHash object from an existing given GoshawkDB Object. Use this to regain access to an existing LinearHash which has already been created. This function does not do any initialisation: it assumes the GoshawkObjRef passed is already initialised for LinearHash.

Parameters:

c - The connection this LinearHash object will be scoped to.

ref - The GoshawkObjRef which contains the root state of the LinearHash

Method Detail

createEmpty

public static LinearHash createEmpty(io.goshawkdb.client.Connection c)
                              throws java.lang.Exception

Create a brand new empty LinearHash. This creates a new GoshawkDB Object and initialises it for use as an LHash.

Parameters:

c - The connection this LinearHash object will be scoped to.

Returns:

The new LinearHash

Throws:

java.lang.Exception - if an unexpected error occurs during the transactions.

find

public io.goshawkdb.client.GoshawkObjRef find(byte[] key)
                                       throws java.lang.Exception

Search the LinearHash for the given key. The key is hashed using the SipHash algorithm, and comparison between keys is done with Arrays.equals. If no matching key is found, null is returned.

Parameters:

key - The key to search for

Returns:

The corresponding value if the key is found; null otherwise.

Throws:

java.lang.Exception - if an unexpected error occurs during the transactions.

put

public void put(byte[] key,
                io.goshawkdb.client.GoshawkObjRef value)
         throws java.lang.Exception

Idempotently add the given key and value to the LinearHash. The key is hashed using the SipHash algorithm, and comparison between keys is done with Arrays.equals. If a matching key is found, the corresponding value is updated.

Parameters:

key - The key to search for and add.

value - The value to associate with the key.

Throws:

java.lang.Exception - if an unexpected error occurs during the transactions.

remove

public void remove(byte[] key)
            throws java.lang.Exception

Idempotently remove any matching entry from the LinearHash. The key is hashed using the SipHash algorithm, and comparison between keys is done with Arrays.equals.

Parameters:

key - The to search for and remove.

Throws:

java.lang.Exception - if an unexpected error occurs during the transactions.

forEach

public void forEach(java.util.function.BiConsumer<? super byte[],? super io.goshawkdb.client.GoshawkObjRef> action)
             throws java.lang.Exception

Iterate over the entries in the LinearHash. Iteration order is undefined. Also note that as usual, the transaction in which the iteration is occurring may need to restart one or more times in which case the callback may be invoked several times for the same entry. To detect this, call forEach from within a transaction of your own. Iteration will stop as soon as the callback throws an error, which will also abort the transaction.

Parameters:

action - The action to be performed for each entry

Throws:

java.lang.Exception - if an unexpected error occurs during the transactions.

size

public int size()
         throws java.lang.Exception

Returns the number of entries in the LinearHash.

Returns:

the number of entries in the LinearHash.

Throws:

java.lang.Exception - if an unexpected error occurs during the transactions.