Package org.axonframework.axonserver.connector

Interface TopologyChangeListener

All Superinterfaces:

Consumer<io.axoniq.axonserver.grpc.control.TopologyChange>

Functional Interface:

This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

@FunctionalInterface
public interface TopologyChangeListener
extends Consumer<io.axoniq.axonserver.grpc.control.TopologyChange>

A functional interface representing a listener that is notified when a TopologyChange occurs to a specific context.

A TopologyChange can reflect any of the following update:

1. TopologyChange.Type.COMMAND_HANDLER_ADDED - A command handler was added by a specific instance to the context the listener is attached to.
2. TopologyChange.Type.COMMAND_HANDLER_REMOVED - A command handler was removed from a specific instance for the context the listener is attached to.
3. TopologyChange.Type.QUERY_HANDLER_ADDED - A query handler was added by a specific instance to the context the listener is attached to.
4. TopologyChange.Type.QUERY_HANDLER_REMOVED - A query handler was removed from a specific instance for the context the listener is attached to.
5. TopologyChange.Type.RESET - This signals the connection broke down of a specific instance for the context the listener is attached to.

A TopologyChange includes more information to better comprehend the actual change, being:

• The type - The type of update.
• The context - The context from which the change originates.
• The client id - The identifier of the client for which a topology change occurred.
• The client stream id - The identifier of the stream/connection for a client (e.g., the Axon Framework node) for which a topology change occurred, defined by Axon Server.
• The component name - The name of the component for which a topology change occurred.
• The handler subscription - The handler subscription containing the TopologyChange.HandlerSubscription.name() and an optional TopologyChange.HandlerSubscription.loadFactor() that is only present for command handler subscriptions.

Here is an example TopologyChange.toString() for a TopologyChange.Type.COMMAND_HANDLER_ADDED:

 TopologyChange{
     type=COMMAND_HANDLER_ADDED,
     context='axoniq-university',
     clientId='149466@axoniq-uni',
     clientStreamId='149466@axoniq-uni.2bb5c0b4-59d9-4396-ad14-a32059f71d9a',
     componentName='AxonIQ University',
     handlerSubscription=HandlerSubscription{
         name='io.axoniq.demo.university.faculty.write.createcourse.CreateCourse',
         loadFactor=100
     }
 }
 

An example use case of this functional interface, is to get notified when a new instance connects or disconnects. A newly connecting instance would mean a new TopologyChange.clientStreamId() entered, while a disconnect is signaled by the TopologyChange.Type.RESET TopologyChange.type(). Such a coarse topology change means the routing of commands will change, which impacts Cache hits for your aggregates or sagas, for example.

Registering this interface with the

invalid reference

org.axonframework.config.Configurer

will ensure it is registered with the default context only! If you need to register several change listeners, either with the same context or with different contexts, you are required to retrieve the ControlChannel from the AxonServerConnectionManager manually, and invoke ControlChannel.registerTopologyChangeHandler(Consumer) for each change listener separately.

Note that Axon Server 2025.1.2 or up is required to use this feature!

Since:

4.12.0

Author:

Steven van Beelen

Method Summary

Modifier and Type	Method	Description
default void	accept(io.axoniq.axonserver.grpc.control.TopologyChange change)
void	onChange(TopologyChange change)	A handler towards a TopologyChange from the context this listener was registered to.

Methods inherited from interface java.util.function.Consumer

andThen

Method Details

accept

default void accept(io.axoniq.axonserver.grpc.control.TopologyChange change)

Specified by:

accept in interface Consumer<io.axoniq.axonserver.grpc.control.TopologyChange>

onChange

void onChange(TopologyChange change)

A handler towards a TopologyChange from the context this listener was registered to.

Parameters:

change - The TopologyChange that transpired for the context this listener was registered to.