de.ipcon.db.core

Class LazyRelationMap

java.lang.Object

de.ipcon.db.core.LazyRelationMap

All Implemented Interfaces:

LazyMapI, java.io.Serializable, java.util.Map

public class LazyRelationMap
extends java.lang.Object
implements java.io.Serializable, LazyMapI

This class serves as a stub for a TreeMap whose values do not exist at all. The trick is to provide a constructor on top of Castor's lazy classes that fills an internal ArrayList, which in lazy mode can answer simple questions and when accessing values, the list is filled.

Generally the collection can work on both sides of the connection (i.e. in the access area of Castor and on the client). The transport mechanism just has to provide an instance of a loading mechanism for the incoming value, which allows the collection to load the missing values.

The collection has three states:

• Freshly loaded from Castor: we know the ID's and have an active and real-life instance of a RelationCollection from Castor.
• After the first transport to the client (and any number of transports later on): the transport mechanism provides them with a BOLoaderI instance, which necessarily provides them with objects.
• Put back to the server, but this may correspond to the first state described above.

See Also:

Serialized Form

Nested Class Summary

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

java.util.Map.Entry<K,V>

Constructor Summary

Constructors

Constructor and Description
LazyRelationMap(BO _parentBO, java.lang.String _attributeName)
LazyRelationMap(java.util.Collection r, BO _parentBO, java.lang.String _attributeName)
LazyRelationMap(java.util.TreeMap t, BO _parentBO, java.lang.String _attributeName)

Method Summary

Modifier and Type	Method and Description
void	__unlazy(java.util.concurrent.CompletableFuture future, java.util.TreeMap resultMap)
void	addRelationObject(BO value)
void	clear() Removes all mappings from this map (optional operation, currently unsupported).
boolean	clearLazyChanges() Clears out any lazy changes persisted in this, still lazy, map.
java.util.SortedMap	cloneInternalMap() Forces the lazy loading of this lazy map, if it hasn't occurred already, and returns a shallow copy of the internal map that backs this lazy map.
boolean	containsKey(java.lang.Object key) Returns true if this map contains a mapping for the specified key.
boolean	containsValue(java.lang.Object value) Returns true if this map maps one or more keys to the specified value.
java.lang.String	debugCtx()
java.util.Set	entrySet() Returns a set view of the mappings contained in this map.
java.lang.Object	get(java.lang.Object key) Returns the value to which this map maps the specified key.
java.lang.String	getAttributeName() The attribute name this LazyRelationMap is accessible from its parent BO
java.util.Collection	getCollection()
RetainedChanges	getLazyChanges()
BO	getParentBO() The parent BO for this LazyRelationMap
boolean	hasEssentialInfos()
boolean	hasLazyChanges()
boolean	isEmpty() Returns true if this map contains no key-value mappings.
boolean	isLazy() Returns true if the map has not yet been populated with values, or if an asynchronous loading task is pending, cancelled or failed.
boolean	isUnLazyBeforeTransport()
boolean	isUnlazyFailed() Returns true if an asynchronous unlazy attempt terminated abnormally.
java.util.Set	keySet() Returns a set view of the keys contained in this map.
int	lazySize() Returns the number of key-value mappings in this map without necessarily unlazying it.
java.util.Collection	pgetCollection() this method is exclusively used in Castor context
java.lang.Object	probabilityContainer(java.lang.String reason, boolean readonly) This routine is similar to the containsKey method, but it is "probably", i.e. not 100% sure.
boolean	probablyContainsKey(java.lang.Object key, boolean ifLazy) The difficult thing about this routine is that it is ALWAYS called by the BOs to fill the dilateral Collections and to manage them mutually.
boolean	probablyContainsValue(java.lang.Object value, boolean ifLazy)
java.lang.Object	probablyGet(java.lang.Object key) Here we are not really interested in the LazyColl.
void	probablyPut(java.lang.Object key, java.lang.Object value) For put and get we must always inform a lazyColl, if it is usable.
void	probablyRemove(java.lang.Object key, java.lang.Object value)
java.lang.Object	put(java.lang.Object key, java.lang.Object value) Associates the specified value with the specified key in this map (optional operation).
void	putAll(java.util.Map t) Copies all of the mappings from the specified map to this map (optional operation).
java.lang.Object	remove(java.lang.Object key) Removes the mapping for this key from this map if it is present (optional operation).
void	removeRelationObject(BO value)
boolean	resetFailedUnlazy() Resets an exceptionally terminated or cancelled unlazy task back to an unpopulated (lazy) state.
void	setUnLazyBeforeTransport(boolean $18)
int	size() Returns the number of key-value mappings in this map.
int	sizeFast() Deprecated. replaced by lazySize()
java.lang.String	toString()
java.lang.String	toString(boolean novalues)
java.util.Map	unLazy() Materializes the relation map synchronously or awaits an in-flight unlazy operation.
java.util.Map	unLazy(java.lang.String reason)
java.util.Collection	values() Returns a collection view of the values contained in this map.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface de.ipcon.tools.LazyMapI

isLazy, lazyIsEmpty

Methods inherited from interface java.util.Map

compute, computeIfAbsent, computeIfPresent, equals, forEach, getOrDefault, hashCode, merge, putIfAbsent, remove, replace, replace, replaceAll

Constructor Detail

LazyRelationMap

public LazyRelationMap(BO _parentBO,
                       java.lang.String _attributeName)

LazyRelationMap

public LazyRelationMap(java.util.TreeMap t,
                       BO _parentBO,
                       java.lang.String _attributeName)

LazyRelationMap

public LazyRelationMap(java.util.Collection r,
                       BO _parentBO,
                       java.lang.String _attributeName)

Method Detail

getAttributeName

public java.lang.String getAttributeName()

The attribute name this LazyRelationMap is accessible from its parent BO

getParentBO

public BO getParentBO()

The parent BO for this LazyRelationMap

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

toString

public java.lang.String toString(boolean novalues)

debugCtx

public java.lang.String debugCtx()

hasEssentialInfos

public boolean hasEssentialInfos()

isLazy

public boolean isLazy()

Returns true if the map has not yet been populated with values, or if an asynchronous loading task is pending, cancelled or failed.

A return value of true indicates either that population has not yet completed (unpopulated state or pending CompletableFuture) or that an in-flight future terminated abnormally via cancellation or an uncaught exception, meaning no resolved map data is available.

Specified by:

isLazy in interface LazyMapI

Returns:

true if populated map data is not available; false once values are fully resolved

isUnlazyFailed

public boolean isUnlazyFailed()

Returns true if an asynchronous unlazy attempt terminated abnormally.

Evaluates to true solely when the backing CompletableFuture failed due to an uncaught exception or explicit cancellation. Returns false while loading is pending, if the map remains lazy or if materialization completed successfully.

Returns:

true if unlazying failed or was cancelled; false otherwise

resetFailedUnlazy

public boolean resetFailedUnlazy()

Resets an exceptionally terminated or cancelled unlazy task back to an unpopulated (lazy) state.

Performs an atomic compare-and-set to replace a failed CompletableFuture with null, clearing internalMap to allow a subsequent unlazy attempt. Does nothing if the current value is not a failed future (e.g. if still pending, already completed successfully or already reset).

Callers should manage retry policies explicitly to avoid repeated reset cycles on persistent failures.

Returns:

true if the map was atomically reset to an unpopulated state; false if no failed future was present or another thread updated the state first

hasLazyChanges

public boolean hasLazyChanges()

getLazyChanges

public RetainedChanges getLazyChanges()

clearLazyChanges

public boolean clearLazyChanges()

Clears out any lazy changes persisted in this, still lazy, map. For use in caching and caching gc situations.

Returns:

true if this map had Retained-/LazyChanges which have been cleared. false if this map is either lazy, completed exceptionally or fully unlazy.

unLazy

public java.util.Map unLazy()

Materializes the relation map synchronously or awaits an in-flight unlazy operation.

If the relation has already materialized, this method returns the populated Map immediately. If another thread is actively resolving the collection, this thread awaits that Future via awaitFutureUnchecked(Future, String).

When this thread initiates the unlazy process, it registers an UnlazyingCompletableFuture in VALUE via compare-and-set and executes _unlazy(UnlazyingCompletableFuture) synchronously on the current thread. Synchronous execution is mandatory to prevent Castor's LockEngine from detecting cross-thread transaction lock dependencies, which otherwise trigger false-positive deadlock aborts (locks are associated with threads in Castor).

Parameters:

reason - descriptive caller context for tracing and diagnostics (e.g. "beforeTransport")

Returns:

the populated, synchronized relation map

Throws:

java.lang.IllegalStateException - if an unrecoverable data integrity error or incomplete hydration occurs

IRuntimeException - if the thread was interrupted or the operation failed unexpectedly

unLazy

public java.util.Map unLazy(java.lang.String reason)

__unlazy

public void __unlazy(java.util.concurrent.CompletableFuture future,
                     java.util.TreeMap resultMap)

pgetCollection

public java.util.Collection pgetCollection()

this method is exclusively used in Castor context

getCollection

public java.util.Collection getCollection()

cloneInternalMap

public java.util.SortedMap cloneInternalMap()

Description copied from interface: LazyMapI

Forces the lazy loading of this lazy map, if it hasn't occurred already, and returns a shallow copy of the internal map that backs this lazy map. This method provides a way to obtain a materialized view, i.e., a shallow copy of this lazy map's data.

Specified by:

cloneInternalMap in interface LazyMapI

Returns:

A new SortedMap containing the key-value mappings of this lazy map.

clear

public void clear()

Removes all mappings from this map (optional operation, currently unsupported).

Specified by:

clear in interface java.util.Map

containsKey

public boolean containsKey(java.lang.Object key)

Returns true if this map contains a mapping for the specified key.

Specified by:

containsKey in interface java.util.Map

containsValue

public boolean containsValue(java.lang.Object value)

Returns true if this map maps one or more keys to the specified value.

Specified by:

containsValue in interface java.util.Map

entrySet

public java.util.Set entrySet()

Returns a set view of the mappings contained in this map.

Specified by:

entrySet in interface java.util.Map

get

public java.lang.Object get(java.lang.Object key)

Returns the value to which this map maps the specified key.

Specified by:

get in interface java.util.Map

isEmpty

public boolean isEmpty()

Returns true if this map contains no key-value mappings.

Specified by:

isEmpty in interface java.util.Map

keySet

public java.util.Set keySet()

Returns a set view of the keys contained in this map.

Specified by:

keySet in interface java.util.Map

put

public java.lang.Object put(java.lang.Object key,
                            java.lang.Object value)

Associates the specified value with the specified key in this map (optional operation).

Specified by:

put in interface java.util.Map

putAll

public void putAll(java.util.Map t)

Copies all of the mappings from the specified map to this map (optional operation).

Specified by:

putAll in interface java.util.Map

remove

public java.lang.Object remove(java.lang.Object key)

Removes the mapping for this key from this map if it is present (optional operation).

Specified by:

remove in interface java.util.Map

size

public int size()

Returns the number of key-value mappings in this map.

Specified by:

size in interface java.util.Map

values

public java.util.Collection values()

Returns a collection view of the values contained in this map.

Specified by:

values in interface java.util.Map

probabilityContainer

public java.lang.Object probabilityContainer(java.lang.String reason,
                                             boolean readonly)

This routine is similar to the containsKey method, but it is "probably", i.e. not 100% sure. However, it is sufficient in normal operation on the client to ensure the recording of the transaction and not to trigger unlazy events unnecessarily.

probablyContainsKey

public boolean probablyContainsKey(java.lang.Object key,
                                   boolean ifLazy)

The difficult thing about this routine is that it is ALWAYS called by the BOs to fill the dilateral Collections and to manage them mutually. However, this should not lead to the backend constantly having to do unlazying and thus hurting performance severely. Thus the priority is as follows: Information about the collection (probablyContainsXXX) - if we are not lazy anymore, then this is 1st choice in any case. - Otherwise we rely on the removed/added hashes.

probablyContainsValue

public boolean probablyContainsValue(java.lang.Object value,
                                     boolean ifLazy)

probablyGet

public java.lang.Object probablyGet(java.lang.Object key)

Here we are not really interested in the LazyColl. Either we are lazy or not; in the first case we can just use our relationMap, otherwise the added/removed hashes.

probablyPut

public void probablyPut(java.lang.Object key,
                        java.lang.Object value)

For put and get we must always inform a lazyColl, if it is usable. Otherwise Castor wouldn't know, how to proceed... Apart from that we again do the game of lazy/non-lazy like in the other "probably*" methods in this class.

probablyRemove

public void probablyRemove(java.lang.Object key,
                           java.lang.Object value)

lazySize

public int lazySize()

Returns the number of key-value mappings in this map without necessarily unlazying it.

Specified by:

lazySize in interface LazyMapI

Returns:

The anticipated number of key-value mappings in the fully loaded map.

sizeFast

@Deprecated
public int sizeFast()

Deprecated. replaced by lazySize()

Returns the number of key-value mappings in this map without necessarily unlazying it.

addRelationObject

public void addRelationObject(BO value)

removeRelationObject

public void removeRelationObject(BO value)

isUnLazyBeforeTransport

public boolean isUnLazyBeforeTransport()

setUnLazyBeforeTransport

public void setUnLazyBeforeTransport(boolean $18)