de.ipcon.db.core

Class TransactionMessageBus

java.lang.Object

de.ipcon.db.core.TransactionMessageBus

public class TransactionMessageBus
extends java.lang.Object

Manages the registration of TransactionListenerI instances and orchestrates the dispatch of transaction-related events.

This class serves as a central message bus with two primary responsibilities:

• Transaction Monitoring: It acts as a handler for registering listeners to receive notifications when changes are recorded in the transaction.
• Virtual Event Bridging: It provides a mechanism for non-persistent Business Objects (BOs) or virtual attributes to trigger events manually. This allows virtual changes to be processed downstream using the same event pipeline as physical persistence changes.

See Also:

TransactionListenerI

Constructor Summary

Constructors

Constructor and Description
TransactionMessageBus() Constructor.

Method Summary

Modifier and Type	Method and Description
void	close() Closes the message bus and releases resources.
void	consumeAfterSetMessage(SetValueEventI changeEvent) Consumes a change event and queues a corresponding virtual message for listeners.
static void	consumeScriptedAttributeChange(SetValueEventI changeEvent) Static helper to bridge scripted attribute changes into the message bus.
boolean	createAfterAddMessage(BO bo, AttributeI attribute, BO addedBO) Creates and queues a virtual event indicating an element has been added to a many-relation attribute.
boolean	createAfterRemoveMessage(BO bo, AttributeI attribute, BO removedBO) Creates and queues a virtual event indicating an element has been removed from a many-relation attribute.
boolean	createAfterSetMessage(BO bo, AttributeI attribute, java.lang.Object newValue) Creates and queues a new change message for setting a scalar or n-1 relation.
boolean	createAfterSetMessage(BO bo, AttributeI attribute, java.lang.Object newValue, java.lang.Object oldValue)
void	disableSynchronousEventsForUnittests() Disables synchronous event dispatching.
void	enableSynchronousEventsForUnittests() Enables synchronous event dispatching (for Unit Tests).
boolean	enqueueProc(BOProc proc) Enqueues a single BOProc and triggers processing.
boolean	enqueueProcs(java.util.List<BOProc> procs) Enqueues a list of BOProcs.
void	fireCheckPoint() Triggers the checkpoint event on all registered listeners.
void	forceResumeFiringNewProcs() Forcefully ignores previous pause requests from any source and re-enables event firing.
boolean	isAcceptingMessages() Determines if the bus is currently operational.
boolean	isEventFiringPaused() Checks if the notification system is currently paused.
static void	killNewProcsRunner() Stops the background thread responsible for processing events.
void	newProcSync() Blocks until the event backlog is cleared and all listeners have been informed.
void	notifyFiredProcWaits() Notifies threads waiting on the backlog lock.
void	notifyTransactionListeners() Notifies listeners of pending changes.
void	pauseFiringNewProcs() Pauses notifications for all consumers.
void	registerListener(de.ipcon.db.core.TransactionListenerI l) Registers a listener to receive notification on new changes from this point forward.
void	removeAllListeners() Removes all registered listeners.
void	resumeFiringNewProcs() Decrements the pause counter and resumes firing of new procs if the counter reaches zero.
void	unregisterListener(de.ipcon.db.core.TransactionListenerI l) Unregisters a listener, preventing it from receiving further notifications.

Methods inherited from class java.lang.Object

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

Constructor Detail

TransactionMessageBus

public TransactionMessageBus()

Constructor.

Method Detail

close

public void close()

Closes the message bus and releases resources.

This method clears the listeners map and the event queue, effectively stopping any further event processing or notifications.

isEventFiringPaused

public boolean isEventFiringPaused()

Checks if the notification system is currently paused.

If this returns true but isAcceptingMessages() is also true, messages will be queued and delayed until messaging resumes.

Returns:

true if notification of listeners has been explicitly paused; false otherwise.

pauseFiringNewProcs

public void pauseFiringNewProcs()

Pauses notifications for all consumers.

This supports re-entrancy: multiple calls to this method require an equal number of resumeFiringNewProcs() calls to re-enable firing.

resumeFiringNewProcs

public void resumeFiringNewProcs()

Decrements the pause counter and resumes firing of new procs if the counter reaches zero.

Will directly trigger a notification flush if firing is successfully resumed and listeners are available.

forceResumeFiringNewProcs

public void forceResumeFiringNewProcs()

Forcefully ignores previous pause requests from any source and re-enables event firing.

Use with caution: This overrides nested pause locks.

killNewProcsRunner

public static void killNewProcsRunner()

Stops the background thread responsible for processing events.

This should only be called if a classloader is disposed of or during application shutdown.

registerListener

public void registerListener(de.ipcon.db.core.TransactionListenerI l)

Registers a listener to receive notification on new changes from this point forward.

Parameters:

l - The listener to register (must be non-null).

unregisterListener

public void unregisterListener(de.ipcon.db.core.TransactionListenerI l)

Unregisters a listener, preventing it from receiving further notifications.

Parameters:

l - The listener to remove (must be non-null).

removeAllListeners

public void removeAllListeners()

Removes all registered listeners.

notifyTransactionListeners

public void notifyTransactionListeners()

Notifies listeners of pending changes. This method is usually called by the NewProcsRunner thread.

fireCheckPoint

public void fireCheckPoint()

Triggers the checkpoint event on all registered listeners.

Iterates through all listeners and calls their TransactionListenerI.checkPoint() method. Exceptions thrown by individual listeners are caught and logged to ensure that notification continues for other listeners.

newProcSync

public void newProcSync()

Blocks until the event backlog is cleared and all listeners have been informed.

Throws:

java.lang.IllegalStateException - if firing new procs is currently paused.

notifyFiredProcWaits

public void notifyFiredProcWaits()

Notifies threads waiting on the backlog lock.

This is used to signal methods like newProcSync() that the event queue processing cycle has completed or the queue state has changed.

isAcceptingMessages

public boolean isAcceptingMessages()

Determines if the bus is currently operational.

Returns:

true if this message bus can consume and notify listeners.

enableSynchronousEventsForUnittests

public void enableSynchronousEventsForUnittests()

Enables synchronous event dispatching (for Unit Tests).

disableSynchronousEventsForUnittests

public void disableSynchronousEventsForUnittests()

Disables synchronous event dispatching.

consumeScriptedAttributeChange

public static void consumeScriptedAttributeChange(SetValueEventI changeEvent)

Static helper to bridge scripted attribute changes into the message bus.

This method calls consumeAfterSetMessage(SetValueEventI) on the MessageBus associated with the BO's loading transaction. It is the default callback for ScriptedAttribute changes, capable of handling BOs from cascaded InstrumentedSchemas.

Parameters:

changeEvent - The event detailing the attribute change.

consumeAfterSetMessage

public void consumeAfterSetMessage(SetValueEventI changeEvent)

Consumes a change event and queues a corresponding virtual message for listeners.

This method determines whether the event represents a value set, an addition, or a removal, and delegates to the appropriate creation method.

Parameters:

changeEvent - The event containing details about the change (BO, attribute, value). Must not be null.

createAfterSetMessage

public boolean createAfterSetMessage(BO bo,
                                     AttributeI attribute,
                                     java.lang.Object newValue)

Creates and queues a new change message for setting a scalar or n-1 relation.

Contract: If newValue is provided, attribute is mandatory. Otherwise, both are currently optional (though providing them is best practice).

Parameters:

bo - The BO which was changed virtually. Must be non-null.

attribute - The nullable attribute that was changed. While this method doesn't validate if the attribute is truly virtual, it is intended for virtual attributes. (Persistent attributes generate procs automatically via the transaction).

newValue - The new value to put into the notification. Can be null if the value isn't available directly and the up-to-date value must be fetched by the view.

oldValue - A nullable and optional old value to include in the event. Provide this only if readily available, as it is often ignored by listeners.

Returns:

true if the message has been queued; false if queuing failed.

createAfterSetMessage

public boolean createAfterSetMessage(BO bo,
                                     AttributeI attribute,
                                     java.lang.Object newValue,
                                     java.lang.Object oldValue)

createAfterAddMessage

public boolean createAfterAddMessage(BO bo,
                                     AttributeI attribute,
                                     BO addedBO)

Creates and queues a virtual event indicating an element has been added to a many-relation attribute.

This method is a convenience wrapper that delegates to createAfterManyChangeMessage(BO, AttributeI, BO, boolean) with the isAdded flag set to true.

Parameters:

bo - The owner BO.

attribute - The relation attribute.

addedBO - The business object that was added to the relation.

Returns:

true if the message was successfully created and queued; false otherwise.

createAfterRemoveMessage

public boolean createAfterRemoveMessage(BO bo,
                                        AttributeI attribute,
                                        BO removedBO)

Creates and queues a virtual event indicating an element has been removed from a many-relation attribute.

This method is a convenience wrapper that delegates to createAfterManyChangeMessage(BO, AttributeI, BO, boolean) with the isAdded flag set to false.

Parameters:

bo - The owner BO.

attribute - The relation attribute.

removedBO - The business object that was removed from the relation.

Returns:

true if the message was successfully created and queued; false otherwise.

enqueueProc

public boolean enqueueProc(BOProc proc)

Enqueues a single BOProc and triggers processing.

Note: This will not fill the queue if there are no listeners, or if the proc trigger is not running (e.g. in a headless environment).

Parameters:

proc - The proc to put into the virtual queue. Must be non-null.

Returns:

true if the proc has been queued, false otherwise.

enqueueProcs

public boolean enqueueProcs(java.util.List<BOProc> procs)

Enqueues a list of BOProcs.

Parameters:

procs - The list of procs to queue.

Returns:

true if successful.