Interface IMultiLookup<Key,Value>
-
- All Known Subinterfaces:
IMultiLookupAbstract<Key,Value,Bucket>,IMultiLookupAbstract.ToMultisetsAbstract<Key,Value>,IMultiLookupAbstract.ToSetsAbstract<Key,Value>
public interface IMultiLookup<Key,Value>A multi-map that associates sets / multisets / delta sets of values to each key.Implementors must provide semantic (not identity-based) hashCode() and equals() using the static helpers
hashCode(IMultiLookup)andequals(IMultiLookup, Object)here.- Since:
- 2.0
- No Implement:
- This interface is not intended to be implemented by clients.
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static classIMultiLookup.ChangeGranularityHow significant was the change? *
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description IMultiLookup.ChangeGranularityaddPair(Key key, Value value)Adds key-value pair to the lookup structure, or fails if not possible.IMultiLookup.ChangeGranularityaddPairOrNop(Key key, Value value)Adds key-value pair to the lookup structure.IMultiLookup.ChangeGranularityaddPairPositiveMultiplicity(Key key, Value value, int count)Updates multiplicity of key-value pair by a positive amount.voidclear()Empties out the lookup structure.intcountKeys()java.lang.Iterable<Key>distinctKeys()java.util.stream.Stream<Key>distinctKeysStream()java.lang.Iterable<Value>distinctValues()Iterates once over each distinct value.java.util.stream.Stream<Value>distinctValuesStream()Iterates once over each distinct value.static <Key,Value>
booleanequals(IMultiLookup<Key,Value> self, java.lang.Object obj)Provides semantic equality comparison.static <Key,Value>
inthashCode(IMultiLookup<Key,Value> memory)Provides semantic hashCode() comparison.booleanisEmpty()Returns true if this collection is empty, false otherwise.IMemoryView<Value>lookup(Key key)Returns a (read-only) bucket of values associated with the given key.IMemoryView<Value>lookupAndRemoveAll(Key key)Returns a (read-only) bucket of values associated with the given key, while simultaneously removing them.booleanlookupExists(Key key)Returns true if there are any values associated with the given key.default IMemoryView<Value>lookupOrEmpty(Key key)Returns a (read-only) bucket of values associated with the given key.IMemoryView<Value>lookupUnsafe(java.lang.Object key)Returns a (read-only) bucket of values associated with the given key, which can be of any type.default IMemoryView<Value>lookupUnsafeOrEmpty(java.lang.Object key)Returns a (read-only) bucket of values associated with the given key.IMultiLookup.ChangeGranularityremovePair(Key key, Value value)Removes key-value pair from the lookup structure, or fails if not possible.IMultiLookup.ChangeGranularityremovePairOrNop(Key key, Value value)Removes key-value pair from the lookup structure.
-
-
-
Method Detail
-
isEmpty
boolean isEmpty()
Returns true if this collection is empty, false otherwise.- Since:
- 2.2
-
lookupExists
boolean lookupExists(Key key)
Returns true if there are any values associated with the given key.- Parameters:
key- a key for which associated values are sought- Since:
- 2.3
-
lookup
IMemoryView<Value> lookup(Key key)
Returns a (read-only) bucket of values associated with the given key. Clients must not modify the returned bucket.- Parameters:
key- a key for which associated values are sought- Returns:
- null if key not found, a bucket of values otherwise
-
lookupOrEmpty
default IMemoryView<Value> lookupOrEmpty(Key key)
Returns a (read-only) bucket of values associated with the given key. Clients must not modify the returned bucket.- Parameters:
key- a key for which associated values are sought- Returns:
- a bucket of values, never null
-
lookupAndRemoveAll
IMemoryView<Value> lookupAndRemoveAll(Key key)
Returns a (read-only) bucket of values associated with the given key, while simultaneously removing them. Clients must not modify the returned bucket.- Parameters:
key- a key for which associated values are sought- Returns:
- a bucket of values, never null
- Since:
- 2.3
-
lookupUnsafe
IMemoryView<Value> lookupUnsafe(java.lang.Object key)
Returns a (read-only) bucket of values associated with the given key, which can be of any type. Clients must not modify the returned bucket.- Parameters:
key- a key for which associated values are sought (may or may not be of Key type)- Returns:
- null if key not found, a bucket of values otherwise
-
lookupUnsafeOrEmpty
default IMemoryView<Value> lookupUnsafeOrEmpty(java.lang.Object key)
Returns a (read-only) bucket of values associated with the given key. Clients must not modify the returned bucket.- Parameters:
key- a key for which associated values are sought (may or may not be of Key type)- Returns:
- a bucket of values, never null
-
distinctKeys
java.lang.Iterable<Key> distinctKeys()
- Returns:
- the set of distinct keys that have values associated.
-
distinctKeysStream
java.util.stream.Stream<Key> distinctKeysStream()
- Returns:
- the set of distinct keys that have values associated.
- Since:
- 2.3
-
countKeys
int countKeys()
- Returns:
- the number of distinct keys that have values associated.
-
distinctValues
java.lang.Iterable<Value> distinctValues()
Iterates once over each distinct value.
-
distinctValuesStream
java.util.stream.Stream<Value> distinctValuesStream()
Iterates once over each distinct value.- Since:
- 2.3
-
addPair
IMultiLookup.ChangeGranularity addPair(Key key, Value value)
Adds key-value pair to the lookup structure, or fails if not possible.If the addition would cause duplicates but the bucket type does not allow it (
CollectionsFactory.MemoryType.SETS), the operation throws anIllegalStateException.- Returns:
- the granularity of the change
- Throws:
java.lang.IllegalStateException- if addition would cause duplication that is not permitted
-
addPairOrNop
IMultiLookup.ChangeGranularity addPairOrNop(Key key, Value value)
Adds key-value pair to the lookup structure.If the addition would cause duplicates but the bucket type does not allow it (
CollectionsFactory.MemoryType.SETS), the operation is silently ignored andIMultiLookup.ChangeGranularity.DUPLICATEis returned.- Returns:
- the granularity of the change, or
IMultiLookup.ChangeGranularity.DUPLICATEif addition would result in a duplicate and therefore ignored - Since:
- 2.3
-
removePair
IMultiLookup.ChangeGranularity removePair(Key key, Value value)
Removes key-value pair from the lookup structure, or fails if not possible.When attempting to remove a key-value pair with zero multiplicity from a non-delta bucket type (
CollectionsFactory.MemoryType.SETSorCollectionsFactory.MemoryType.MULTISETS}), anIllegalStateExceptionis thrown.- Returns:
- the granularity of the change
- Throws:
java.lang.IllegalStateException- if removing non-existing element that is not permitted
-
removePairOrNop
IMultiLookup.ChangeGranularity removePairOrNop(Key key, Value value)
Removes key-value pair from the lookup structure.When attempting to remove a key-value pair with zero multiplicity from a non-delta bucket type (
CollectionsFactory.MemoryType.SETSorCollectionsFactory.MemoryType.MULTISETS}), the operation is silently ignored andIMultiLookup.ChangeGranularity.DUPLICATEis returned.- Returns:
- the granularity of the change
- Throws:
java.lang.IllegalStateException- if removing non-existing element that is not permitted- Since:
- 2.3
-
addPairPositiveMultiplicity
IMultiLookup.ChangeGranularity addPairPositiveMultiplicity(Key key, Value value, int count)
Updates multiplicity of key-value pair by a positive amount.PRE: count > 0
- Returns:
- the granularity of the change
- Throws:
java.lang.IllegalStateException- if addition would cause duplication that is not permitted
-
clear
void clear()
Empties out the lookup structure.
-
equals
static <Key,Value> boolean equals(IMultiLookup<Key,Value> self, java.lang.Object obj)
Provides semantic equality comparison.
-
hashCode
static <Key,Value> int hashCode(IMultiLookup<Key,Value> memory)
Provides semantic hashCode() comparison.
-
-