Scylla Documentation Logo Documentation
  • Server
    • Scylla Open Source
    • Scylla Enterprise
    • Scylla Alternator
  • Cloud
    • Scylla Cloud
    • Scylla Cloud Docs
  • Tools
    • Scylla Manager
    • Scylla Monitoring Stack
    • Scylla Operator
  • Drivers
    • CQL Drivers
    • DynamoDB Drivers
Download
Menu
Scylla Java Driver Manual Core driver Metadata Node metadata

Node metadata¶

Quick overview¶

session.getMetadata().getNodes(): all nodes known to the driver (even if not actively connected).

  • Node instances are mutable, the fields will update in real time.

  • getting notifications: CqlSession.builder().addNodeStateListener.


Metadata#getNodes returns all the nodes known to the driver when the metadata was retrieved; this includes down and ignored nodes (see below), so the fact that a node is in this list does not necessarily mean that the driver is connected to it.

Map<InetSocketAddress, Node> nodes = session.getMetadata().getNodes();
System.out.println("Nodes in the cluster:");
for (Node node : nodes.values()) {
  System.out.printf(
      "  %s is %s and %s (%d connections)%n",
      node.getConnectAddress().getAddress(),
      node.getState(),
      node.getDistance(),
      node.getOpenConnections());
}

The returned map is immutable: it does not reflect additions or removals since the metadata was retrieved. On the other hand, the Node object is mutable; you can hold onto an instance across metadata refreshes and see updates to the fields.

A few notable fields are explained below; for the full details, refer to the Javadocs.

Node#getState() indicates how the driver sees the node (see the Javadocs of NodeState for the list of possible states with detailed explanations). In general, the driver tries to be resilient to spurious DOWN notifications, and will try to use a node as long as it seems up, even if some events seem to indicate otherwise: for example, if the Cassandra gossip detects a node as down because of cross-node connectivity issues, but the driver still has active connections to that node, the node will stay up. Two related properties are Node#getOpenConnections() and Node#isReconnecting().

Node#getDatacenter() and Node#getRack() represent the location of the node. This information is used by some load balancing policies to prioritize coordinators that are physically close to the client.

Node#getDistance() is set by the load balancing policy. The driver does not connect to IGNORED nodes. The exact definition of LOCAL and REMOTE is left to the interpretation of each policy, but in general it represents the proximity to the client, and LOCAL nodes will be prioritized as coordinators. They also influence pooling options.

Node#getExtras() contains additional free-form properties. This is intended for future evolution or custom driver extensions. In particular, if the driver is connected to Datastax Enterprise, the map will contain additional information under the keys defined in DseNodeProperties:

Object rawDseVersion = node.getExtras().get(DseNodeProperties.DSE_VERSION);
Version dseVersion = (rawDseVersion == null) ? null : (Version) rawDseVersion;

Notifications¶

If you need to follow node state changes, you don’t need to poll the metadata manually; instead, you can register one or more listeners to get notified when changes occur:

NodeStateListener listener =
    new NodeStateListenerBase() {
      @Override
      public void onUp(@NonNull Node node) {
        System.out.printf("%s went UP%n", node);
      }
    };
CqlSession session = CqlSession.builder()
    .addNodeStateListener(listener)
    .build();

See NodeStateListener for the list of available methods. NodeStateListenerBase is a convenience implementation with empty methods, for when you only need to override a few of them.

It is also possible to register one or more listeners via the configuration:

datastax-java-driver {
  advanced {
    node-state-listener.classes = [com.example.app.MyNodeStateListener1,com.example.app.MyNodeStateListener2]
  }
}

Listeners registered via configuration will be instantiated with reflection; they must have a public constructor taking a DriverContext argument.

The two registration methods (programmatic and via the configuration) can be used simultaneously.

Advanced topics¶

Forcing a node down¶

It is possible to temporarily or permanently close all connections to a node and disable reconnection. The driver does that internally for certain unrecoverable errors (such as a protocol version mismatch), but this could also be useful for maintenance, or for a custom component (load balancing policy, etc).

import com.datastax.oss.driver.internal.core.context.InternalDriverContext;
import com.datastax.oss.driver.internal.core.metadata.TopologyEvent;

InternalDriverContext context = (InternalDriverContext) session.getContext();
context.getEventBus().fire(TopologyEvent.forceDown(node1.getConnectAddress()));
context.getEventBus().fire(TopologyEvent.forceUp(node1.getConnectAddress()));

As shown by the imports above, forcing a node down requires the internal driver API, which is reserved for expert usage and subject to the disclaimers in API conventions.

Using a custom topology monitor¶

By default, the driver relies on Cassandra’s gossip protocol to receive notifications about the node states. It opens a control connection to one of the nodes, and registers for server-sent state events.

Some organizations have their own way of monitoring Cassandra nodes, and prefer to use it instead. It is possible to completely override the default behavior to bypass gossip. The full details are beyond the scope of this document; if you’re interested, study the TopologyMonitor interface in the source code.

PREVIOUS
Metadata
NEXT
Schema metadata
  • 4.13.0.x
    • 4.13.0.x
    • 4.12.0.x
    • 4.11.1.x
    • 4.10.0.x
    • 4.7.2.x
    • 3.11.2.x
    • 3.11.0.x
    • 3.10.2.x
    • 3.7.2.x
  • Java Driver for Scylla and Apache Cassandra®
  • API Documentation
  • Manual
    • API conventions
    • Case sensitivity
    • Core driver
      • Address resolution
      • Asynchronous programming
      • Authentication
      • Bill of Materials (BOM)
      • Compression
      • Configuration
        • Reference configuration
      • Control connection
      • Custom codecs
      • Detachable types
      • Using the driver in GraalVM native images
      • Query idempotence
      • Integration
      • Load balancing
      • Logging
      • Metadata
        • Node metadata
        • Schema metadata
        • Token metadata
      • Metrics
      • Native protocol
      • Non-blocking programming
      • Paging
      • Performance
      • Connection pooling
      • Query timestamps
      • Reactive Style Programming
      • Reconnection
      • Request tracker
      • Retries
      • Using the shaded JAR
      • Speculative query execution
      • SSL
      • Statements
        • Batch statements
        • Per-query keyspace
        • Prepared statements
        • Simple statements
      • Temporal types
      • Request throttling
      • Query tracing
      • Tuples
      • User-defined types
    • Developer docs
      • Administrative tasks
      • Common infrastructure
        • Concurrency
        • Driver context
        • Event bus
      • Native protocol layer
      • Netty pipeline
      • Request execution
    • Mapper
      • Integration
        • Kotlin
        • Lombok
        • Java 14 Records
        • Scala
      • DAOs
        • Custom result types
        • Delete methods
        • GetEntity methods
        • Increment methods
        • Insert methods
        • Null saving strategy
        • Query methods
        • Query provider methods
        • Select methods
        • SetEntity methods
        • Statement attributes
        • Update methods
      • Entities
      • Mapper interface
    • OSGi
    • Query builder
      • Conditions
      • DELETE
      • Idempotence in the query builder
      • INSERT
      • Relations
      • Schema builder
        • Aggregate
        • Function
        • Index
        • Keyspace
        • Materialized View
        • Table
        • Type
      • SELECT
      • Terms
      • TRUNCATE
      • UPDATE
  • Upgrade guide
  • Frequently asked questions
  • Changelog
  • Create an issue
  • Edit this page

On this page

  • Node metadata
    • Quick overview
    • Notifications
    • Advanced topics
      • Forcing a node down
      • Using a custom topology monitor
Logo
Docs Contact Us About Us
Mail List Icon Slack Icon
© 2022, ScyllaDB. All rights reserved.
Last updated on 25 May 2022.
Powered by Sphinx 4.3.2 & ScyllaDB Theme 1.2.2