net.openhft.chronicle.map

Interface ChronicleMap<K,V>

Type Parameters:

K - the map key type

V - the map value type

All Superinterfaces:

AutoCloseable, ChronicleHash, Closeable, ConcurrentMap<K,V>, Map<K,V>

public interface ChronicleMap<K,V>
extends ConcurrentMap<K,V>, ChronicleHash

Extension of ConcurrentMap interface, stores the data off-heap.

For information on

• how to construct a ChronicleMap
• ChronicleMap flavors and properties
• available configurations

see ChronicleMapBuilder documentation.

Functionally this interface defines some methods supporting garbage-free off-heap programming: getUsing(Object, Object), acquireUsing(Object, Object).

Roughly speaking, ChronicleMap compares keys and values by their binary serialized form, that shouldn't necessary be the same equality relation as defined by built-in Object.equals(Object) method, which is prescribed by general Map contract.

Note that ChronicleMap extends Closeable, don't forget to close map when it is no longer needed.

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

Map.Entry<K,V>

Method Summary

Methods

Modifier and Type	Method and Description
V	acquireUsing(K key, V usingValue) Acquire a value for a key, creating if absent.
WriteContext<K,V>	acquireUsingLocked(K key, V usingValue)
V	get(Object key) Returns the value to which the specified key is mapped, or null if this map contains no mapping for the key.
void	getAll(File toFile) Exports all the entries to a File storing them in JSON format, an attempt is made where possible to use standard java serialisation and keep the data human readable, data serialized using the custom serialises are converted to a binary format which is not human readable but this is only done if the Keys or Values are not Serializable.
<R> R	getMapped(K key, Function<? super V,R> function) Apply a mapping to the value returned by a key and return a result.
V	getUsing(K key, V usingValue) Returns the value to which the specified key is mapped, read to the provided value object, if possible, or returns null, if this map contains no mapping for the key.
ReadContext<K,V>	getUsingLocked(K key, V usingValue) The method is similar getUsing(K key, V usingValue); but in addition read locks the map segment to operations to be performed atomically.
Class<K>	keyClass()
long	longSize() Returns the number of entries in this map.
String	name() the name of the map
K	newKeyInstance() Creates an empty value instance, which can be used with the following methods :
V	newValueInstance() Creates an empty value instance, which can be used with the following methods :
void	putAll(File fromFile) Imports all the entries from a File, the fromFile must be created using or the same format as get(java.lang.Object), this method behaves similar to Map.put(java.lang.Object, java.lang.Object) where existing entries are overwritten.
V	putMapped(K key, UnaryOperator<V> unaryOperator) Apply a unaryOperator to the value for a key and return a result.
K	readKey(Bytes entry, long keyPos)
V	readValue(Bytes entry, long valuePos)
UpdateResult	update(K key, V value) A special operation, similar to replace(key, value, value), but puts the entry even if it was absent in the map.
Class<V>	valueClass()

Methods inherited from interface java.util.concurrent.ConcurrentMap

putIfAbsent, remove, replace, replace

Methods inherited from interface java.util.Map

clear, containsKey, containsValue, entrySet, equals, hashCode, isEmpty, keySet, put, putAll, remove, size, values

Methods inherited from interface net.openhft.chronicle.hash.ChronicleHash

close, file

Method Detail

longSize

long longSize()

Returns the number of entries in this map.

Returns:

number of entries in this map

See Also:

Map.size()

get

V get(Object key)

Returns the value to which the specified key is mapped, or null if this map contains no mapping for the key.

If the value class allows reusing, particularly if it is a Byteable subclass, consider getUsing(Object, Object) method instead of this to reduce garbage creation.

Specified by:

get in interface Map<K,V>

Parameters:

key - the key whose associated value is to be returned

Returns:

the value to which the specified key is mapped after this method call, or null if no value is mapped

See Also:

getUsing(Object, Object)

getUsing

V getUsing(K key,
         V usingValue)

Returns the value to which the specified key is mapped, read to the provided value object, if possible, or returns null, if this map contains no mapping for the key.

If the specified key is present in the map, the value data is read to the provided value object via value marshaller's read(Bytes, value) or value reader's read(Bytes, size, value) method, depending on what deserialization strategy is configured on the builder, using which this map was constructed. If the value deserializer is able to reuse the given value object, calling this method instead of get(Object) could help to reduce garbage creation.

The provided value object is allowed to be null, in this case map.getUsing(key, null) call is semantically equivalent to simple map.get(key) call.

Parameters:

key - the key whose associated value is to be returned

usingValue - the object to read value data in, if possible

Returns:

the value to which the specified key is mapped, or null if this map contains no mapping for the key

See Also:

get(Object), acquireUsing(Object, Object), ChronicleMapBuilder.valueMarshaller(BytesMarshaller)

getUsingLocked

@NotNull
ReadContext<K,V> getUsingLocked(@NotNull
                                      K key,
                                      @NotNull
                                      V usingValue)

The method is similar getUsing(K key, V usingValue); but in addition read locks the map segment to operations to be performed atomically. ( see the example below )

Returns the ReadContext which holds a map segment lock and provides method to get the value ( to which the specified key is mapped) atomically ( see example below for an explanation ), read to the provided value object, if possible, or returns null, if this map contains no mapping for the key.

If the specified key is present in the map, the readContext.value() uses the provided usingValue object via value marshaller's read(Bytes, value) or value reader's read(Bytes, size, value) method, depending on what deserialization strategy is configured on the builder, using which this map was constructed. If the value deserializer is able to reuse the given usingValue object, calling this method instead of get(Object) could help to reduce garbage creation.

try (ReadContext rc = map.getUsingLocked(key, bond)) {
    if (rc.present ()) { // check whether the key was present
    long issueDate = bond.getIssueDate();
    String symbol = bond.getSymbol();
 // add your logic here ( the lock will ensure this bond can not be changed by another thread
 )
 }
 } // the read lock is released here
 

To ensure that you can read the 'issueDate' and 'symbol' can be read atomically, these values must be read while the segment lock is in place.

The provided value object is allowed to be null, in this case

Parameters:

key - the key whose associated value is to be returned

usingValue - the object to read value data in, if possible

Returns:

the read context containing the value to which the specified key is mapped

no mapping for the key

See Also:

get(Object), getUsing(Object, Object), ChronicleMapBuilder.valueMarshaller(BytesMarshaller)

acquireUsing

V acquireUsing(@NotNull
             K key,
             V usingValue)

Acquire a value for a key, creating if absent.

If the specified key is absent in the map, default value is taken or default value provider is called. Then this object is put to this map for the specified key.

Then, either if the key was initially absent in the map or already present, the value is deserialized just as during getUsing(key, usingValue) call, passed the same key and usingValue as into this method call. This means, as in getUsing(K, V), usingValue could safely be null, in this case a new value instance is created to deserialize the data.

In code, acquireUsing is specified as :

V acquireUsing(K key, V usingValue) {
     if (!containsKey(key))
         put(key, defaultValue(key));
     return getUsing(key, usingValue);
 }

Where defaultValue(key) returns either default value or defaultValueProvider.

If the ChronicleMap is off-heap updatable, i. e. created via ChronicleMapBuilder builder (values are Byteable), there is one more option of what to do if the key is absent in the map. By default, value bytes are just zeroed out, no default value, either provided for key or constant, is put for the absent key.

Parameters:

key - the key whose associated value is to be returned

usingValue - the object to read value data in, if present. Can not be null

Returns:

value to which the given key is mapping after this call, either found or created

See Also:

getUsing(Object, Object)

acquireUsingLocked

@NotNull
WriteContext<K,V> acquireUsingLocked(@NotNull
                                           K key,
                                           @NotNull
                                           V usingValue)

getMapped

<R> R getMapped(K key,
              @NotNull
              Function<? super V,R> function)

Apply a mapping to the value returned by a key and return a result. A read lock is assumed.

Type Parameters:

R - return type.

Parameters:

key - to apply the mapping to

function - to calculate a result

Returns:

the result of the function, or null if there is no entry for the key.

putMapped

V putMapped(K key,
          @NotNull
          UnaryOperator<V> unaryOperator)

Apply a unaryOperator to the value for a key and return a result. A write lock is assumed.

If there is no entry for this key null will be returned

Parameters:

key - to apply the mapping to

unaryOperator - to alter the value and calculate a result

Returns:

the result of the function.

update

UpdateResult update(K key,
                  V value)

A special operation, similar to replace(key, value, value), but puts the entry even if it was absent in the map.

getAll

void getAll(File toFile)
            throws IOException

Exports all the entries to a File storing them in JSON format, an attempt is made where possible to use standard java serialisation and keep the data human readable, data serialized using the custom serialises are converted to a binary format which is not human readable but this is only done if the Keys or Values are not Serializable. This method can be used in conjunction with putAll(java.io.File) and is especially useful if you wish to import/export entries from one chronicle map into another. This import and export of the entries can be performed even when the versions of ChronicleMap differ. This method is not performant and as such we recommend it is not used in performance sensitive code.

Parameters:

toFile - the file to store all the entries to, the entries will be stored in JSON format

Throws:

IOException - its not possible store the data to toFile

See Also:

putAll(java.io.File)

putAll

void putAll(File fromFile)
            throws IOException

Imports all the entries from a File, the fromFile must be created using or the same format as get(java.lang.Object), this method behaves similar to Map.put(java.lang.Object, java.lang.Object) where existing entries are overwritten. A write lock is only held while each individual entry is inserted into the map, not over all the entries in the File

Parameters:

fromFile - the file containing entries ( in JSON format ) which will be deserialized and Map.put(java.lang.Object, java.lang.Object) into the map

Throws:

IOException - its not possible read the fromFile

See Also:

getAll(java.io.File)

newValueInstance

V newValueInstance()

Creates an empty value instance, which can be used with the following methods :

getUsing(java.lang.Object, java.lang.Object) getUsingLocked(java.lang.Object, java.lang.Object) acquireUsing(java.lang.Object, java.lang.Object) acquireUsingLocked(java.lang.Object, java.lang.Object)

for example like this :

V value = map.newValueInstance();
 try (ReadContext rc = map.getUsingLocked(key, value)) {
  // add your logic here
 } // the read lock is released here
 

Returns:

a new empty instance based on the Value type

See Also:

getUsing(java.lang.Object, java.lang.Object), getUsingLocked(java.lang.Object, java.lang.Object), acquireUsing(java.lang.Object, java.lang.Object), acquireUsingLocked(java.lang.Object, java.lang.Object)

newKeyInstance

K newKeyInstance()

Creates an empty value instance, which can be used with the following methods :

getUsing(java.lang.Object, java.lang.Object) getUsingLocked(java.lang.Object, java.lang.Object) acquireUsing(java.lang.Object, java.lang.Object) acquireUsingLocked(java.lang.Object, java.lang.Object)

for example like this :

K key = map.newKeyInstance();
 key.setMyStringField("some key");

 try (ReadContext rc = map.getUsingLocked(key, value)) {
  // add your logic here
 } // the read lock is released here
 

Returns:

a new empty instance based on the Key type

See Also:

getUsing(java.lang.Object, java.lang.Object), getUsingLocked(java.lang.Object, java.lang.Object), acquireUsing(java.lang.Object, java.lang.Object), acquireUsingLocked(java.lang.Object, java.lang.Object)

readKey

K readKey(Bytes entry,
        long keyPos)

readValue

V readValue(Bytes entry,
          long valuePos)

keyClass

Class<K> keyClass()

Returns:

the class of <K>

valueClass

Class<V> valueClass()

Returns:

the class of <V>

name

String name()

the name of the map