Interface IMultiLookupAbstract<Key,Value,Bucket extends MarkedMemory<Value>>
-
- All Superinterfaces:
IMultiLookup<Key,Value>
- All Known Subinterfaces:
IMultiLookupAbstract.ToMultisetsAbstract<Key,Value>,IMultiLookupAbstract.ToSetsAbstract<Key,Value>
public interface IMultiLookupAbstract<Key,Value,Bucket extends MarkedMemory<Value>> extends IMultiLookup<Key,Value>
Specialized multimap implementation that saves memory by storing singleton value objects (multiplicity 1) instead of multiset buckets whenever there is only one value associated with a key.See specialized
IMultiLookupAbstract.ToSetsAbstract,IMultiLookupAbstract.ToMultisetsAbstractfor various bucket types.Implemented as a Key->Object map with invariant:
- key maps to null if associated with no values;
- key maps to a single Value iff it is associated with a single value of multiplicity +1;
- key maps to Bucket otherwise
Not intended as an API, but rather as a 'base class' for implementors. Realized as an interface with default implementations, instead of an abstract class, to ensure that implementors can easily choose a base class such as UnifiedMap to augment.
Implementor should inherit from a Map
-like class (primitive map possible) and bind the lowLevel* methods accordingly. - Since:
- 2.0
- No Implement:
- This interface is not intended to be implemented by clients.
- No Reference:
- This interface is not intended to be referenced by clients.
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static interfaceIMultiLookupAbstract.ToMultisetsAbstract<Key,Value>A multi-lookup whose buckets are multisets.static interfaceIMultiLookupAbstract.ToSetsAbstract<Key,Value>A multi-lookup whose buckets are sets.-
Nested classes/interfaces inherited from interface org.eclipse.viatra.query.runtime.matchers.util.IMultiLookup
IMultiLookup.ChangeGranularity
-
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description default IMultiLookup.ChangeGranularityaddPair(Key key, Value value)Adds key-value pair to the lookup structure, or fails if not possible.default IMultiLookup.ChangeGranularityaddPairInternal(Key key, Value value, boolean throwIfImpossible)default IMultiLookup.ChangeGranularityaddPairOrNop(Key key, Value value)Adds key-value pair to the lookup structure.default IMultiLookup.ChangeGranularityaddPairPositiveMultiplicity(Key key, Value value, int count)Updates multiplicity of key-value pair by a positive amount.booleanaddToBucket(Bucket bucket, Value value, boolean throwIfImpossible)Increases the multiplicity of the value in the bucket.ValueasSingleton(Bucket bucket)Checks whether the bucket is a singleton, i.e.default intcountKeys()BucketcreateDeltaBucket(Value positive, Value negative)BucketcreateSingletonBucket(Value value)default java.lang.Iterable<Key>distinctKeys()default java.util.stream.Stream<Key>distinctKeysStream()default java.lang.Iterable<Value>distinctValues()Iterates once over each distinct value.default java.util.stream.Stream<Value>distinctValuesStream()Iterates once over each distinct value.booleanduplicatesAllowed()default voidhandleSingleton(Key key, Bucket bucket)default IMemoryView<Value>lookup(Key key)Returns a (read-only) bucket of values associated with the given key.default IMemoryView<Value>lookupAndRemoveAll(Key key)Returns a (read-only) bucket of values associated with the given key, while simultaneously removing them.default booleanlookupExists(Key key)Returns true if there are any values associated with the given key.default 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.java.lang.ObjectlowLevelGet(Key key)Implementor shall bind to the low-level get() or equivalent of the underlying Key-to-Object mapjava.lang.ObjectlowLevelGetUnsafe(java.lang.Object key)Implementor shall bind to the low-level get() or equivalent of the underlying Key-to-Object mapjava.lang.Iterable<Key>lowLevelKeySet()Implementor shall bind to the low-level keySet() or equivalent of the underlying Key-to-Object mapvoidlowLevelPut(Key key, java.lang.Object valueOrBucket)Implementor shall bind to the low-level put() or equivalent of the underlying Key-to-Object mapjava.lang.ObjectlowLevelPutIfAbsent(Key key, Value value)Implementor shall bind to the low-level putIfAbsent() or equivalent of the underlying Key-to-Object mapjava.lang.ObjectlowLevelRemove(Key key)Implementor shall bind to the low-level remove() or equivalent of the underlying Key-to-Object mapintlowLevelSize()Implementor shall bind to the low-level size() or equivalent of the underlying Key-to-Object mapjava.lang.Iterable<java.lang.Object>lowLevelValues()Implementor shall bind to the low-level values() or equivalent of the underlying Key-to-Object mapbooleannegativesAllowed()booleanremoveFromBucket(Bucket bucket, Value value, boolean throwIfImpossible)Decreases the multiplicity of the value in the bucket.default IMultiLookup.ChangeGranularityremovePair(Key key, Value value)Removes key-value pair from the lookup structure, or fails if not possible.default IMultiLookup.ChangeGranularityremovePairInternal(Key key, Value value, boolean throwIfImpossible)default IMultiLookup.ChangeGranularityremovePairOrNop(Key key, Value value)Removes key-value pair from the lookup structure.default IMemoryView<Value>yieldSingleton(Value value)-
Methods inherited from interface org.eclipse.viatra.query.runtime.matchers.util.IMultiLookup
clear, isEmpty, lookupOrEmpty, lookupUnsafeOrEmpty
-
-
-
-
Method Detail
-
lowLevelGet
java.lang.Object lowLevelGet(Key key)
Implementor shall bind to the low-level get() or equivalent of the underlying Key-to-Object map
-
lowLevelGetUnsafe
java.lang.Object lowLevelGetUnsafe(java.lang.Object key)
Implementor shall bind to the low-level get() or equivalent of the underlying Key-to-Object map
-
lowLevelRemove
java.lang.Object lowLevelRemove(Key key)
Implementor shall bind to the low-level remove() or equivalent of the underlying Key-to-Object map
-
lowLevelPutIfAbsent
java.lang.Object lowLevelPutIfAbsent(Key key, Value value)
Implementor shall bind to the low-level putIfAbsent() or equivalent of the underlying Key-to-Object map
-
lowLevelPut
void lowLevelPut(Key key, java.lang.Object valueOrBucket)
Implementor shall bind to the low-level put() or equivalent of the underlying Key-to-Object map
-
lowLevelValues
java.lang.Iterable<java.lang.Object> lowLevelValues()
Implementor shall bind to the low-level values() or equivalent of the underlying Key-to-Object map
-
lowLevelKeySet
java.lang.Iterable<Key> lowLevelKeySet()
Implementor shall bind to the low-level keySet() or equivalent of the underlying Key-to-Object map
-
lowLevelSize
int lowLevelSize()
Implementor shall bind to the low-level size() or equivalent of the underlying Key-to-Object map
-
lookupExists
default boolean lookupExists(Key key)
Description copied from interface:IMultiLookupReturns true if there are any values associated with the given key.- Specified by:
lookupExistsin interfaceIMultiLookup<Key,Value>- Parameters:
key- a key for which associated values are sought
-
lookup
default IMemoryView<Value> lookup(Key key)
Description copied from interface:IMultiLookupReturns a (read-only) bucket of values associated with the given key. Clients must not modify the returned bucket.- Specified by:
lookupin interfaceIMultiLookup<Key,Value>- Parameters:
key- a key for which associated values are sought- Returns:
- null if key not found, a bucket of values otherwise
-
lookupAndRemoveAll
default IMemoryView<Value> lookupAndRemoveAll(Key key)
Description copied from interface:IMultiLookupReturns a (read-only) bucket of values associated with the given key, while simultaneously removing them. Clients must not modify the returned bucket.- Specified by:
lookupAndRemoveAllin interfaceIMultiLookup<Key,Value>- Parameters:
key- a key for which associated values are sought- Returns:
- a bucket of values, never null
-
lookupUnsafe
default IMemoryView<Value> lookupUnsafe(java.lang.Object key)
Description copied from interface:IMultiLookupReturns a (read-only) bucket of values associated with the given key, which can be of any type. Clients must not modify the returned bucket.- Specified by:
lookupUnsafein interfaceIMultiLookup<Key,Value>- 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
-
addPair
default IMultiLookup.ChangeGranularity addPair(Key key, Value value)
Description copied from interface:IMultiLookupAdds 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.- Specified by:
addPairin interfaceIMultiLookup<Key,Value>- Returns:
- the granularity of the change
-
addPairOrNop
default IMultiLookup.ChangeGranularity addPairOrNop(Key key, Value value)
Description copied from interface:IMultiLookupAdds 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.- Specified by:
addPairOrNopin interfaceIMultiLookup<Key,Value>- Returns:
- the granularity of the change, or
IMultiLookup.ChangeGranularity.DUPLICATEif addition would result in a duplicate and therefore ignored
-
addPairInternal
default IMultiLookup.ChangeGranularity addPairInternal(Key key, Value value, boolean throwIfImpossible)
-
addPairPositiveMultiplicity
default IMultiLookup.ChangeGranularity addPairPositiveMultiplicity(Key key, Value value, int count)
Description copied from interface:IMultiLookupUpdates multiplicity of key-value pair by a positive amount.PRE: count > 0
- Specified by:
addPairPositiveMultiplicityin interfaceIMultiLookup<Key,Value>- Returns:
- the granularity of the change
-
removePair
default IMultiLookup.ChangeGranularity removePair(Key key, Value value)
Description copied from interface:IMultiLookupRemoves 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.- Specified by:
removePairin interfaceIMultiLookup<Key,Value>- Returns:
- the granularity of the change
-
removePairOrNop
default IMultiLookup.ChangeGranularity removePairOrNop(Key key, Value value)
Description copied from interface:IMultiLookupRemoves 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.- Specified by:
removePairOrNopin interfaceIMultiLookup<Key,Value>- Returns:
- the granularity of the change
-
removePairInternal
default IMultiLookup.ChangeGranularity removePairInternal(Key key, Value value, boolean throwIfImpossible)
-
distinctValues
default java.lang.Iterable<Value> distinctValues()
Description copied from interface:IMultiLookupIterates once over each distinct value.- Specified by:
distinctValuesin interfaceIMultiLookup<Key,Value>
-
distinctValuesStream
default java.util.stream.Stream<Value> distinctValuesStream()
Description copied from interface:IMultiLookupIterates once over each distinct value.- Specified by:
distinctValuesStreamin interfaceIMultiLookup<Key,Value>
-
distinctKeys
default java.lang.Iterable<Key> distinctKeys()
- Specified by:
distinctKeysin interfaceIMultiLookup<Key,Value>- Returns:
- the set of distinct keys that have values associated.
-
distinctKeysStream
default java.util.stream.Stream<Key> distinctKeysStream()
- Specified by:
distinctKeysStreamin interfaceIMultiLookup<Key,Value>- Returns:
- the set of distinct keys that have values associated.
-
countKeys
default int countKeys()
- Specified by:
countKeysin interfaceIMultiLookup<Key,Value>- Returns:
- the number of distinct keys that have values associated.
-
negativesAllowed
boolean negativesAllowed()
- Returns:
- iff negative multiplicites are allowed
-
duplicatesAllowed
boolean duplicatesAllowed()
- Returns:
- iff larger-than-1 multiplicites are allowed
- Since:
- 2.3
-
addToBucket
boolean addToBucket(Bucket bucket, Value value, boolean throwIfImpossible)
Increases the multiplicity of the value in the bucket.- Returns:
- true iff non-duplicate
- Throws:
java.lang.IllegalStateException- if disallowed duplication and throwIfImpossible is specified
-
removeFromBucket
boolean removeFromBucket(Bucket bucket, Value value, boolean throwIfImpossible)
Decreases the multiplicity of the value in the bucket.- Returns:
- false if removing duplicate value
- Throws:
java.lang.IllegalStateException- if removing non-existing value (unless delta map) and throwIfImpossible is specified
-
asSingleton
Value asSingleton(Bucket bucket)
Checks whether the bucket is a singleton, i.e. it contains a single value with multiplicity +1- Returns:
- the singleton value, or null if the bucket is not singleton
-
createSingletonBucket
Bucket createSingletonBucket(Value value)
- Returns:
- a new bucket consisting of a sole value
-
yieldSingleton
default IMemoryView<Value> yieldSingleton(Value value)
- Returns:
- a read-only bucket consisting of a sole value, to be returned to the user
-
createDeltaBucket
Bucket createDeltaBucket(Value positive, Value negative)
- Parameters:
positive- the previously existing value, or null if the delta is to contain a single negative tuple- Returns:
- a new bucket consisting of a delta of two values
- Throws:
java.lang.IllegalStateException- if deltas not supported
-
-