Package com.helger.commons.collection.impl

Interface ICommonsMap<KEYTYPE,VALUETYPE>

Type Parameters:

KEYTYPE - Map key type

VALUETYPE - Map value type

All Superinterfaces:

ICloneable<ICommonsMap<KEYTYPE,VALUETYPE>>, Map<KEYTYPE,VALUETYPE>

All Known Subinterfaces:

IAttributeContainer<KEYTYPE,VALUETYPE>, IAttributeContainerAny<KEYTYPE>, ICommonsNavigableMap<KEYTYPE,VALUETYPE>, ICommonsOrderedMap<KEYTYPE,VALUETYPE>, ICommonsSortedMap<KEYTYPE,VALUETYPE>, IStringMap

All Known Implementing Classes:

AbstractSoftMap, AttributeContainer, AttributeContainerAny, AttributeContainerAnyConcurrent, AttributeContainerConcurrent, CommonsConcurrentHashMap, CommonsEnumMap, CommonsHashMap, CommonsLinkedHashMap, CommonsTreeMap, CommonsWeakHashMap, LoggingLRUMap, LRUMap, NonBlockingProperties, SoftHashMap, SoftLinkedHashMap, StringMap

public interface ICommonsMap<KEYTYPE,VALUETYPE>
extends Map<KEYTYPE,VALUETYPE>, ICloneable<ICommonsMap<KEYTYPE,VALUETYPE>>

A special Map interface with extended functionality

Author:

Philip Helger

Nested Class Summary

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

Map.Entry<K,V>

Method Summary

Modifier and Type	Method	Description
default void	addAll(Map<? extends KEYTYPE,? extends VALUETYPE> aValues)	Add all provided values.
default boolean	containsAnyEntry(Predicate<? super Map.Entry<KEYTYPE,VALUETYPE>> aFilter)	Check if at least one entry matches the passed filter.
default boolean	containsAnyKey(Predicate<? super KEYTYPE> aFilter)	Check if at least one key matches the passed filter.
default boolean	containsAnyValue(Predicate<? super VALUETYPE> aFilter)	Check if at least one value matches the passed filter.
default ICommonsSet<Map.Entry<KEYTYPE,VALUETYPE>>	copyOfEntrySet()
default ICommonsSet<KEYTYPE>	copyOfKeySet()
default ICommonsSet<KEYTYPE>	copyOfKeySet(Predicate<? super KEYTYPE> aFilter)	Create a copy of all values matching the passed filter.
default ICommonsList<VALUETYPE>	copyOfValues()
default ICommonsList<VALUETYPE>	copyOfValues(Predicate<? super VALUETYPE> aFilter)	Create a copy of all values matching the passed filter.
default <DSTTYPE> ICommonsList<DSTTYPE>	copyOfValuesMapped(Function<? super VALUETYPE,? extends DSTTYPE> aMapper)	Create a copy of all values after applying the passed mapping function.
default <DSTTYPE> ICommonsList<DSTTYPE>	copyOfValuesMapped(Predicate<? super VALUETYPE> aFilter, Function<? super VALUETYPE,? extends DSTTYPE> aMapper)	Create a copy of all values matching the passed filter which are then converted using the provided function.
default <K, V> ICommonsMap<K,V>	createInstance()	Create a new empty map.
default Map.Entry<KEYTYPE,VALUETYPE>	findFirstEntry(Predicate<? super Map.Entry<KEYTYPE,VALUETYPE>> aFilter)	Find the first entry that matches the passed filter.
default KEYTYPE	findFirstKey(Predicate<? super Map.Entry<KEYTYPE,VALUETYPE>> aFilter)	Find the first key that matches the passed filter.
default VALUETYPE	findFirstValue(Predicate<? super Map.Entry<KEYTYPE,VALUETYPE>> aFilter)	Find the first value that matches the passed filter.
default void	forEach(BiPredicate<? super KEYTYPE,? super VALUETYPE> aFilter, BiConsumer<? super KEYTYPE,? super VALUETYPE> aConsumer)	Invoke the provided consumer on each entry (pair of key and value) that matches the provided filter.
default void	forEachKey(Consumer<? super KEYTYPE> aConsumer)	Invoke the provided consumer on each key.
default void	forEachKey(Predicate<? super KEYTYPE> aFilter, Consumer<? super KEYTYPE> aConsumer)	Invoke the provided consumer on each key that matches the provided filter.
default void	forEachValue(Consumer<? super VALUETYPE> aConsumer)	Invoke the provided consumer on each value.
default void	forEachValue(Predicate<? super VALUETYPE> aFilter, Consumer<? super VALUETYPE> aConsumer)	Invoke the provided consumer on each value that matches the provided filter.
default Map<KEYTYPE,VALUETYPE>	getAsUnmodifiable()
default Map.Entry<KEYTYPE,VALUETYPE>	getFirstEntry()	Get the first element of this map or null.
default Map.Entry<KEYTYPE,VALUETYPE>	getFirstEntry(Map.Entry<KEYTYPE,VALUETYPE> aDefault)	Get the first element of this map or the provided default value.
default KEYTYPE	getFirstKey()	Get the first key of this map or null.
default KEYTYPE	getFirstKey(KEYTYPE aDefault)	Get the first key of this map or the provided default value.
default VALUETYPE	getFirstValue()	Get the first value of this map or null.
default VALUETYPE	getFirstValue(VALUETYPE aDefault)	Get the first value of this map or the provided default value.
default ICommonsOrderedMap<KEYTYPE,VALUETYPE>	getSortedByKey(Comparator<? super KEYTYPE> aKeyComparator)	Get the map sorted by its keys.
default ICommonsOrderedMap<KEYTYPE,VALUETYPE>	getSortedByValue(Comparator<? super VALUETYPE> aValueComparator)	Get the map sorted by its values.
default ICommonsMap<VALUETYPE,KEYTYPE>	getSwappedKeyValues()	Get a map where keys and values are exchanged.
default boolean	isNotEmpty()
default VALUETYPE	put(Map.Entry<? extends KEYTYPE,? extends VALUETYPE> aEntry)	Special put overload that takes an entry and should simplify copying from other maps.
default void	putAll(Iterable<? extends Map.Entry<KEYTYPE,VALUETYPE>> aIterable)	Add all passed entries to this map.
default void	putAll(Map<KEYTYPE,VALUETYPE> aMap, Predicate<? super Map.Entry<? extends KEYTYPE,? extends VALUETYPE>> aFilter)	Add all items from the passed map that match the filter to this map.
default <ELEMENTTYPE> void	putAllMapped(ELEMENTTYPE[] aElements, Function<? super ELEMENTTYPE,? extends KEYTYPE> aKeyMapper, Function<? super ELEMENTTYPE,? extends VALUETYPE> aValueMapper)	Add all items from the passed array to this map using the provided key and value mapper.
default <ELEMENTTYPE> void	putAllMapped(Iterable<? extends ELEMENTTYPE> aElements, Function<? super ELEMENTTYPE,? extends KEYTYPE> aKeyMapper, Function<? super ELEMENTTYPE,? extends VALUETYPE> aValueMapper)	Add all items from the passed iterable to this map using the provided key and value mapper.
default <SRCKEYTYPE, SRCVALUETYPE> void	putAllMapped(Map<? extends SRCKEYTYPE,? extends SRCVALUETYPE> aMap, Function<? super SRCKEYTYPE,? extends KEYTYPE> aKeyMapper, Function<? super SRCVALUETYPE,? extends VALUETYPE> aValueMapper)	Add all items from the passed map to this map using the provided key and value mapper.
default void	putIf(KEYTYPE aKey, VALUETYPE aValue, Predicate<? super VALUETYPE> aFilter)	Put the passed value into the map if the provided predicate is fulfilled.
default void	putIfNotNull(KEYTYPE aKey, VALUETYPE aValue)	Put the passed value into the map if it is not null.
default EChange	removeAll()	Remove all elements from this collection.
default EChange	removeIf(Predicate<? super Map.Entry<? extends KEYTYPE,? extends VALUETYPE>> aFilter)
default EChange	removeIfKey(Predicate<? super KEYTYPE> aFilter)
default EChange	removeIfValue(Predicate<? super VALUETYPE> aFilter)
default EChange	removeObject(KEYTYPE aKey)	Remove the object with the passed key from this map.
default EChange	setAll(Map<? extends KEYTYPE,? extends VALUETYPE> aValues)	Clear and add all provided values.

Methods inherited from interface com.helger.commons.lang.ICloneable

getClone

Methods inherited from interface java.util.Map

clear, compute, computeIfAbsent, computeIfPresent, containsKey, containsValue, entrySet, equals, forEach, get, getOrDefault, hashCode, isEmpty, keySet, merge, put, putAll, putIfAbsent, remove, remove, replace, replace, replaceAll, size, values

Method Details

createInstance

@Nonnull
@ReturnsMutableCopy
default <K,
V> ICommonsMap<K,V> createInstance()

Create a new empty map. Overwrite this if you don't want to use CommonsHashMap.

Type Parameters:

K - Map key type

V - Map value type

Returns:

A new empty map. Never null.

copyOfKeySet

@Nonnull
@ReturnsMutableCopy
default ICommonsSet<KEYTYPE> copyOfKeySet()

Returns:

A new non-null set with all keys.

See Also:

• Map.keySet()
• copyOfKeySet(Predicate)

copyOfKeySet

@Nonnull
@ReturnsMutableCopy
default ICommonsSet<KEYTYPE> copyOfKeySet(@Nullable
 Predicate<? super KEYTYPE> aFilter)

Create a copy of all values matching the passed filter.

Parameters:

aFilter - The filter to be applied. May be null.

Returns:

A new non-null set with all matching keys.

See Also:

• Map.keySet()
• copyOfKeySet()

copyOfValues

@Nonnull
@ReturnsMutableCopy
default ICommonsList<VALUETYPE> copyOfValues()

Returns:

A new non-null set with all values.

See Also:

• Map.values()
• copyOfValues(Predicate)
• copyOfValuesMapped(Function)
• copyOfValuesMapped(Predicate, Function)

copyOfValues

@Nonnull
@ReturnsMutableCopy
default ICommonsList<VALUETYPE> copyOfValues(@Nullable
 Predicate<? super VALUETYPE> aFilter)

Create a copy of all values matching the passed filter.

Parameters:

aFilter - The filter to be applied. May be null.

Returns:

A new list with all matching values. If no filter is provided the returned value is identical as of copyOfValues()

See Also:

• Map.values()
• copyOfValues()
• copyOfValuesMapped(Function)
• copyOfValuesMapped(Predicate, Function)

copyOfValuesMapped

@Nonnull
@ReturnsMutableCopy
default <DSTTYPE> ICommonsList<DSTTYPE> copyOfValuesMapped(@Nonnull
 Function<? super VALUETYPE,? extends DSTTYPE> aMapper)

Create a copy of all values after applying the passed mapping function.

Type Parameters:

DSTTYPE - The destination type to be mapped to

Parameters:

aMapper - The mapping function to be applied. May not be null.

Returns:

A new list with all mapped values.

See Also:

• Map.values()
• copyOfValues()
• copyOfValuesMapped(Function)
• copyOfValuesMapped(Predicate, Function)

copyOfValuesMapped

@Nonnull
@ReturnsMutableCopy
default <DSTTYPE> ICommonsList<DSTTYPE> copyOfValuesMapped(@Nullable
 Predicate<? super VALUETYPE> aFilter,
 @Nonnull
 Function<? super VALUETYPE,? extends DSTTYPE> aMapper)

Create a copy of all values matching the passed filter which are then converted using the provided function.

Type Parameters:

DSTTYPE - The destination type to be mapped to

Parameters:

aFilter - The filter to be applied. May be null.

aMapper - The mapping function to be applied. May not be null.

Returns:

A new list with all matching converted values. If no filter is provided the returned value is identical as of copyOfValuesMapped(Function)

See Also:

• Map.values()
• copyOfValues()
• copyOfValues(Predicate)
• copyOfValuesMapped(Predicate, Function)

copyOfEntrySet

@Nonnull
@ReturnsMutableCopy
default ICommonsSet<Map.Entry<KEYTYPE,VALUETYPE>> copyOfEntrySet()

Returns:

A new non-null copy of the entry set.

isNotEmpty

default boolean isNotEmpty()

Returns:

true if the map is not empty, false otherwise.

getFirstEntry

@Nullable
default Map.Entry<KEYTYPE,VALUETYPE> getFirstEntry()

Get the first element of this map or null.

Returns:

null if the map is empty, the first element otherwise.

See Also:

• getFirstEntry(java.util.Map.Entry)

getFirstEntry

@Nullable
default Map.Entry<KEYTYPE,VALUETYPE> getFirstEntry(@Nullable
 Map.Entry<KEYTYPE,VALUETYPE> aDefault)

Get the first element of this map or the provided default value.

Parameters:

aDefault - The default value to be returned if this map is empty. May be null.

Returns:

The provided default value if the map is empty, the first entry otherwise.

See Also:

• getFirstEntry()

getFirstKey

@Nullable
default KEYTYPE getFirstKey()

Get the first key of this map or null.

Returns:

null if the map is empty, the first key otherwise.

See Also:

• getFirstKey(Object)

getFirstKey

@Nullable
default KEYTYPE getFirstKey(@Nullable
 KEYTYPE aDefault)

Get the first key of this map or the provided default value.

Parameters:

aDefault - The default value to be returned if this map is empty. May be null.

Returns:

The provided default value if the map is empty, the first key otherwise.

See Also:

• getFirstKey()

getFirstValue

@Nullable
default VALUETYPE getFirstValue()

Get the first value of this map or null.

Returns:

null if the map is empty, the first value otherwise.

See Also:

• getFirstValue(Object)

getFirstValue

@Nullable
default VALUETYPE getFirstValue(@Nullable
 VALUETYPE aDefault)

Get the first value of this map or the provided default value.

Parameters:

aDefault - The default value to be returned if this map is empty. May be null.

Returns:

The provided default value if the map is empty, the first value otherwise.

See Also:

• getFirstValue()

findFirstEntry

@Nullable
default Map.Entry<KEYTYPE,VALUETYPE> findFirstEntry(@Nullable
 Predicate<? super Map.Entry<KEYTYPE,VALUETYPE>> aFilter)

Find the first entry that matches the passed filter.

Parameters:

aFilter - The filter to be applied. May be null.

Returns:

null if no matching element was found. I no filter was provided, the result is the same as getFirstEntry().

findFirstKey

@Nullable
default KEYTYPE findFirstKey(@Nullable
 Predicate<? super Map.Entry<KEYTYPE,VALUETYPE>> aFilter)

Find the first key that matches the passed filter.

Parameters:

aFilter - The filter to be applied. May be null.

Returns:

null if no matching element was found. I no filter was provided, the result is the same as getFirstKey().

findFirstValue

@Nullable
default VALUETYPE findFirstValue(@Nullable
 Predicate<? super Map.Entry<KEYTYPE,VALUETYPE>> aFilter)

Find the first value that matches the passed filter.

Parameters:

aFilter - The filter to be applied. May be null.

Returns:

null if no matching element was found. I no filter was provided, the result is the same as getFirstValue().

containsAnyEntry

default boolean containsAnyEntry(@Nullable
 Predicate<? super Map.Entry<KEYTYPE,VALUETYPE>> aFilter)

Check if at least one entry matches the passed filter.

Parameters:

aFilter - The filter to be applied. May be null.

Returns:

true if the map is not empty and contains at least one element matching the filter, false otherwise. If no filter is provided the return value is identical to isNotEmpty().

containsAnyKey

default boolean containsAnyKey(@Nullable
 Predicate<? super KEYTYPE> aFilter)

Check if at least one key matches the passed filter.

Parameters:

aFilter - The filter to be applied. May be null.

Returns:

true if the map is not empty and contains at least one key matching the filter, false otherwise. If no filter is provided the return value is identical to isNotEmpty().

containsAnyValue

default boolean containsAnyValue(@Nullable
 Predicate<? super VALUETYPE> aFilter)

Check if at least one value matches the passed filter.

Parameters:

aFilter - The filter to be applied. May be null.

Returns:

true if the map is not empty and contains at least one value matching the filter, false otherwise. If no filter is provided the return value is identical to isNotEmpty().

forEachKey

default void forEachKey(@Nonnull
 Consumer<? super KEYTYPE> aConsumer)

Invoke the provided consumer on each key.

Parameters:

aConsumer - The consumer to be invoked. May not be null.

forEachValue

default void forEachValue(@Nonnull
 Consumer<? super VALUETYPE> aConsumer)

Invoke the provided consumer on each value.

Parameters:

aConsumer - The consumer to be invoked. May not be null.

forEach

default void forEach(@Nullable
 BiPredicate<? super KEYTYPE,? super VALUETYPE> aFilter,
 @Nonnull
 BiConsumer<? super KEYTYPE,? super VALUETYPE> aConsumer)

Invoke the provided consumer on each entry (pair of key and value) that matches the provided filter.

Parameters:

aFilter - The filter to be applied. May be null.

aConsumer - The consumer to be invoked. May not be null.

See Also:

• Map.forEach(BiConsumer)

forEachKey

default void forEachKey(@Nullable
 Predicate<? super KEYTYPE> aFilter,
 @Nonnull
 Consumer<? super KEYTYPE> aConsumer)

Invoke the provided consumer on each key that matches the provided filter.

Parameters:

aFilter - The filter to be applied. May be null.

aConsumer - The consumer to be invoked. May not be null.

See Also:

• forEachKey(Consumer)
• forEach(BiPredicate, BiConsumer)

forEachValue

default void forEachValue(@Nullable
 Predicate<? super VALUETYPE> aFilter,
 @Nonnull
 Consumer<? super VALUETYPE> aConsumer)

Invoke the provided consumer on each value that matches the provided filter.

Parameters:

aFilter - The filter to be applied. May be null.

aConsumer - The consumer to be invoked. May not be null.

See Also:

• forEachValue(Consumer)
• forEach(BiPredicate, BiConsumer)

getSortedByKey

@Nonnull
@ReturnsMutableCopy
default ICommonsOrderedMap<KEYTYPE,VALUETYPE> getSortedByKey(@Nonnull
 Comparator<? super KEYTYPE> aKeyComparator)

Get the map sorted by its keys. The comparison order is defined by the passed comparator object.

Parameters:

aKeyComparator - The comparator to be used. May not be null.

Returns:

the sorted map and never null.

getSortedByValue

@Nonnull
@ReturnsMutableCopy
default ICommonsOrderedMap<KEYTYPE,VALUETYPE> getSortedByValue(@Nonnull
 Comparator<? super VALUETYPE> aValueComparator)

Get the map sorted by its values. The comparison order is defined by the passed comparator object.

Parameters:

aValueComparator - The comparator to be used. May not be null.

Returns:

the sorted map and never null.

getSwappedKeyValues

@Nullable
@ReturnsMutableCopy
default ICommonsMap<VALUETYPE,KEYTYPE> getSwappedKeyValues()

Get a map where keys and values are exchanged.

Returns:

The swapped hash map based on the type returned by createInstance().

put

@Nullable
default VALUETYPE put(@Nonnull
 Map.Entry<? extends KEYTYPE,? extends VALUETYPE> aEntry)

Special put overload that takes an entry and should simplify copying from other maps.

Parameters:

aEntry - Entry to be added. May not be null.

Returns:

the return value of Map.put(Object, Object). May be null.

Since:

9.0.0

putIf

default void putIf(@Nonnull
 KEYTYPE aKey,
 @Nullable
 VALUETYPE aValue,
 @Nonnull
 Predicate<? super VALUETYPE> aFilter)

Put the passed value into the map if the provided predicate is fulfilled.

Parameters:

aKey - Key to use. May not be null for certain map types.

aValue - The value to be added. May be null in which case nothing happens.

aFilter - The value predicate to be checked before insertion. May not be null.

putIfNotNull

default void putIfNotNull(@Nonnull
 KEYTYPE aKey,
 @Nullable
 VALUETYPE aValue)

Put the passed value into the map if it is not null.

Parameters:

aKey - Key to use. May not be null for certain map types.

aValue - The value to be added. May be null in which case nothing happens.

putAll

default void putAll(@Nullable
 Iterable<? extends Map.Entry<KEYTYPE,VALUETYPE>> aIterable)

Add all passed entries to this map.

Parameters:

aIterable - Source map entries. May be null.

Since:

8.5.5

putAll

default void putAll(@Nullable
 Map<KEYTYPE,VALUETYPE> aMap,
 @Nullable
 Predicate<? super Map.Entry<? extends KEYTYPE,? extends VALUETYPE>> aFilter)

Add all items from the passed map that match the filter to this map.

Parameters:

aMap - Source Map. May be null.

aFilter - The filter to use. May be null.

Since:

8.5.5

putAllMapped

default <ELEMENTTYPE> void putAllMapped(@Nullable
 ELEMENTTYPE[] aElements,
 @Nonnull
 Function<? super ELEMENTTYPE,? extends KEYTYPE> aKeyMapper,
 @Nonnull
 Function<? super ELEMENTTYPE,? extends VALUETYPE> aValueMapper)

Add all items from the passed array to this map using the provided key and value mapper.

Type Parameters:

ELEMENTTYPE - Array element type

Parameters:

aElements - Source collection. May be null.

aKeyMapper - The key mapper. May not be null.

aValueMapper - The value mapper. May not be null.

Since:

8.5.5

putAllMapped

default <ELEMENTTYPE> void putAllMapped(@Nullable
 Iterable<? extends ELEMENTTYPE> aElements,
 @Nonnull
 Function<? super ELEMENTTYPE,? extends KEYTYPE> aKeyMapper,
 @Nonnull
 Function<? super ELEMENTTYPE,? extends VALUETYPE> aValueMapper)

Add all items from the passed iterable to this map using the provided key and value mapper.

Type Parameters:

ELEMENTTYPE - Collection element type

Parameters:

aElements - Source collection. May be null.

aKeyMapper - The key mapper. May not be null.

aValueMapper - The value mapper. May not be null.

Since:

8.5.5

putAllMapped

default <SRCKEYTYPE,
SRCVALUETYPE> void putAllMapped(@Nullable
 Map<? extends SRCKEYTYPE,? extends SRCVALUETYPE> aMap,
 @Nonnull
 Function<? super SRCKEYTYPE,? extends KEYTYPE> aKeyMapper,
 @Nonnull
 Function<? super SRCVALUETYPE,? extends VALUETYPE> aValueMapper)

Add all items from the passed map to this map using the provided key and value mapper.

Type Parameters:

SRCKEYTYPE - Source map key type

SRCVALUETYPE - Source map value type

Parameters:

aMap - Source map. May be null.

aKeyMapper - The key mapper. May not be null.

aValueMapper - The value mapper. May not be null.

Since:

8.5.5

addAll

default void addAll(@Nullable
 Map<? extends KEYTYPE,? extends VALUETYPE> aValues)

Add all provided values.

Parameters:

aValues - The values to be added. May be null.

setAll

@Nonnull
default EChange setAll(@Nullable
 Map<? extends KEYTYPE,? extends VALUETYPE> aValues)

Clear and add all provided values.

Parameters:

aValues - The values to be added. May be null.

Returns:

EChange

removeAll

@Nonnull
default EChange removeAll()

Remove all elements from this collection. This is similar to Map.clear() but it returns a different value whether something was cleared or not.

Returns:

EChange.CHANGED if the collection was not empty and something was removed, EChange.UNCHANGED otherwise.

See Also:

• Map.clear()

removeObject

@Nonnull
default EChange removeObject(@Nullable
 KEYTYPE aKey)

Remove the object with the passed key from this map.
Note: this method returns EChange.UNCHANGED even if removal was successful if the value was null.

Parameters:

aKey - The key to be removed. May be null.

Returns:

EChange.CHANGED if the removal was successful, EChange.UNCHANGED if removal fails.

See Also:

• Map.remove(Object)

removeIf

@Nonnull
default EChange removeIf(@Nonnull
 Predicate<? super Map.Entry<? extends KEYTYPE,? extends VALUETYPE>> aFilter)

removeIfKey

@Nonnull
default EChange removeIfKey(@Nonnull
 Predicate<? super KEYTYPE> aFilter)

removeIfValue

@Nonnull
default EChange removeIfValue(@Nonnull
 Predicate<? super VALUETYPE> aFilter)

getAsUnmodifiable

@Nonnull
@CodingStyleguideUnaware
default Map<KEYTYPE,VALUETYPE> getAsUnmodifiable()

Returns:

An unmodifiable version of this map. Never null.

See Also:

• Collections