Class TopologyAwareRouter

java.lang.Object

com.loomcache.server.cluster.TopologyAwareRouter

public class TopologyAwareRouter
extends Object

Routes read and write requests based on topology awareness.

Routing strategy:

• Reads: Prefers closest node (same rack > same zone > same region > any) respecting consistency level requirements
• Writes: Always routes to the partition leader regardless of topology
• Fallback: If preferred node is unavailable, tries next closest node

Thread safety: uses ReentrantLock for topology map updates and atomic counters for stats.

Since:

1.0

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final record	TopologyAwareRouter.NodeEndpoint	Represents a network endpoint for a cache node.
static final record	TopologyAwareRouter.TopologyRouterStats	Statistics for topology-aware routing.

Constructor Summary

Constructors

Constructor	Description
TopologyAwareRouter(TopologyConfig config)	Create a new TopologyAwareRouter.

Method Summary

Modifier and Type	Method	Description
Map<String, TopologyInfo>	getNodeTopologies()	Get all topology information registered in this router.
TopologyAwareRouter.TopologyRouterStats	getStats()	Get routing statistics.
void	registerNodeTopology(String nodeId, TopologyInfo topology)	Register a node's topology information.
void	resetStats()	Reset statistics counters.
TopologyAwareRouter.NodeEndpoint	routeRead(String key, ConsistencyLevel consistencyLevel, List<TopologyAwareRouter.NodeEndpoint> availableNodes, String leaderId)	Route a read request based on topology and consistency level.
TopologyAwareRouter.NodeEndpoint	routeWrite(List<TopologyAwareRouter.NodeEndpoint> availableNodes, String leaderId)	Route a write request (always to leader regardless of topology).

Methods inherited from class Object

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

Constructor Details

TopologyAwareRouter

public TopologyAwareRouter(TopologyConfig config)

Create a new TopologyAwareRouter.

Parameters:

config - TopologyConfig with local node topology

Method Details

registerNodeTopology

public void registerNodeTopology(String nodeId,
 TopologyInfo topology)

Register a node's topology information.

Parameters:

nodeId - the node identifier

topology - the TopologyInfo for the node

routeRead

public TopologyAwareRouter.NodeEndpoint routeRead(String key,
 ConsistencyLevel consistencyLevel,
 List<TopologyAwareRouter.NodeEndpoint> availableNodes,
 String leaderId)

Route a read request based on topology and consistency level.

Preference order:

1. STRONG: leader only
2. BOUNDED_STALENESS/EVENTUAL: same rack > same zone > same region > any available
3. SESSION: try to return to same node if possible

Parameters:

key - the cache key

consistencyLevel - the required consistency level

availableNodes - list of available nodes (with endpoints)

leaderId - the current leader node ID

Returns:

the NodeEndpoint to route the read to

Throws:

IllegalArgumentException - if parameters are invalid or no available nodes

routeWrite

public TopologyAwareRouter.NodeEndpoint routeWrite(List<TopologyAwareRouter.NodeEndpoint> availableNodes,
 String leaderId)

Route a write request (always to leader regardless of topology).

Parameters:

availableNodes - list of available nodes

leaderId - the current leader node ID

Returns:

the NodeEndpoint of the leader

Throws:

IllegalArgumentException - if parameters are invalid or leader not found

getNodeTopologies

public Map<String, TopologyInfo> getNodeTopologies()

Get all topology information registered in this router.

Returns:

map of nodeId → TopologyInfo (copy)

getStats

public TopologyAwareRouter.TopologyRouterStats getStats()

Get routing statistics.

Returns:

TopologyRouterStats with current counters

resetStats

public void resetStats()

Reset statistics counters.