K
- the map key typeV
- the map value typepublic interface ChronicleMap<K,V> extends ConcurrentMap<K,V>, ChronicleHash
ConcurrentMap
interface, stores the data off-heap.
For information on
ChronicleMap
ChronicleMap
flavors and propertiesChronicleMapBuilder
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.
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.
|
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 : |
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 : |
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.
|
Class<V> |
valueClass() |
putIfAbsent, remove, replace, replace
clear, containsKey, containsValue, entrySet, equals, hashCode, isEmpty, keySet, put, putAll, remove, size, values
close, file
long longSize()
Map.size()
V get(Object key)
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.
get
in interface Map<K,V>
key
- the key whose associated value is to be returnednull
if no value is mappedgetUsing(Object, Object)
V getUsing(K key, V usingValue)
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.
key
- the key whose associated value is to be returnedusingValue
- the object to read value data in, if possiblenull
if this map contains
no mapping for the keyget(Object)
,
acquireUsing(Object, Object)
,
ChronicleMapBuilder.valueMarshaller(BytesMarshaller)
@NotNull ReadContext<K,V> getUsingLocked(@NotNull K key, @NotNull V usingValue)
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
key
- the key whose associated value is to be returnedusingValue
- the object to read value data in, if possibleget(Object)
,
getUsing(Object, Object)
,
ChronicleMapBuilder.valueMarshaller(BytesMarshaller)
V acquireUsing(@NotNull K key, V usingValue)
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.
key
- the key whose associated value is to be returnedusingValue
- the object to read value data in, if present. Can not be nullgetUsing(Object, Object)
@NotNull WriteContext<K,V> acquireUsingLocked(@NotNull K key, @NotNull V usingValue)
<R> R getMapped(K key, @NotNull Function<? super V,R> function)
R
- return type.key
- to apply the mapping tofunction
- to calculate a resultV putMapped(K key, @NotNull UnaryOperator<V> unaryOperator)
If there is no entry for this key null will be returned
key
- to apply the mapping tounaryOperator
- to alter the value and calculate a resultvoid getAll(File toFile) throws IOException
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.toFile
- the file to store all the entries to, the entries will be stored in JSON
formatIOException
- its not possible store the data to toFile
putAll(java.io.File)
void putAll(File fromFile) throws IOException
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
fromFile
- the file containing entries ( in JSON format ) which will be deserialized and
Map.put(java.lang.Object, java.lang.Object)
into the mapIOException
- its not possible read the fromFile
getAll(java.io.File)
V newValueInstance()
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
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)
K newKeyInstance()
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
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)
Copyright © 2015. All rights reserved.