JAVA-1801: Revisit NodeStateListener and SchemaChangeListener APIs

changelog/README.md

@@ -4,6 +4,7 @@
 
 ### 4.0.0-alpha4 (in progress)
 
+- [improvement] JAVA-1801: Revisit NodeStateListener and SchemaChangeListener APIs
 - [improvement] JAVA-1759: Revisit metrics API
 - [improvement] JAVA-1776: Use concurrency annotations
 - [improvement] JAVA-1799: Use CqlIdentifier for simple statement named values

core/src/main/java/com/datastax/oss/driver/api/core/config/DefaultDriverOption.java

@@ -113,6 +113,8 @@ public enum DefaultDriverOption implements DriverOption {
   METADATA_SCHEMA_WINDOW("metadata.schema.debouncer.window", true),
   METADATA_SCHEMA_MAX_EVENTS("metadata.schema.debouncer.max-events", true),
   METADATA_TOKEN_MAP_ENABLED("metadata.token-map.enabled", true),
+  METADATA_NODE_STATE_LISTENER_CLASS("metadata.node-state-listener.class", false),
+  METADATA_SCHEMA_CHANGE_LISTENER_CLASS("metadata.schema-change-listener.class", false),
 
   TIMESTAMP_GENERATOR_CLASS("request.timestamp-generator.class", true),
   TIMESTAMP_GENERATOR_FORCE_JAVA_CLOCK("request.timestamp-generator.force-java-clock", false),

core/src/main/java/com/datastax/oss/driver/api/core/metadata/NodeStateListener.java

@@ -16,22 +16,23 @@
 package com.datastax.oss.driver.api.core.metadata;
 
 import com.datastax.oss.driver.api.core.loadbalancing.NodeDistance;
-import com.datastax.oss.driver.api.core.session.Session;
 import com.datastax.oss.driver.api.core.session.SessionBuilder;
 
 /**
  * A listener that gets notified when nodes states change.
  *
- * <p>An implementation of this interface can be registered with {@link
- * SessionBuilder#addNodeStateListeners(NodeStateListener...)} or at runtime with {@link
- * Session#register(NodeStateListener)}.
+ * <p>An implementation of this interface can be registered in the configuration, or with {@link
+ * SessionBuilder#withNodeStateListener(NodeStateListener)}.
  *
  * <p>Note that the methods defined by this interface will be executed by internal driver threads,
  * and are therefore expected to have short execution times. If you need to perform long
  * computations or blocking calls in response to schema change events, it is strongly recommended to
  * schedule them asynchronously on a separate thread provided by your application code.
+ *
+ * <p>If you implement this interface but don't need to implement all the methods, extend {@link
+ * NodeStateListenerBase}.
  */
-public interface NodeStateListener {
+public interface NodeStateListener extends AutoCloseable {
 
   /**
    * Invoked when a node is first added to the cluster.
@@ -61,13 +62,4 @@ public interface NodeStateListener {
    * absent from the new list.
    */
   void onRemove(Node node);
-
-  /** Invoked when the listener is registered with a session. */
-  void onRegister(Session session);
-
-  /**
-   * Invoked when the listener is unregistered from a session, or at session shutdown, whichever
-   * comes first.
-   */
-  void onUnregister(Session session);
 }

core/src/main/java/com/datastax/oss/driver/api/core/metadata/NodeStateListenerBase.java

@@ -0,0 +1,48 @@
+/*
+ * Copyright DataStax, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.datastax.oss.driver.api.core.metadata;
+
+/**
+ * Convenience class for listener implementations that that don't need to override all methods (all
+ * methods in this class are empty).
+ */
+public class NodeStateListenerBase implements NodeStateListener {
+
+  @Override
+  public void onAdd(Node node) {
+    // nothing to do
+  }
+
+  @Override
+  public void onUp(Node node) {
+    // nothing to do
+  }
+
+  @Override
+  public void onDown(Node node) {
+    // nothing to do
+  }
+
+  @Override
+  public void onRemove(Node node) {
+    // nothing to do
+  }
+
+  @Override
+  public void close() throws Exception {
+    // nothing to do
+  }
+}

core/src/main/java/com/datastax/oss/driver/api/core/metadata/schema/SchemaChangeListener.java

@@ -15,21 +15,24 @@
  */
 package com.datastax.oss.driver.api.core.metadata.schema;
 
-import com.datastax.oss.driver.api.core.session.Session;
+import com.datastax.oss.driver.api.core.session.SessionBuilder;
 import com.datastax.oss.driver.api.core.type.UserDefinedType;
 
 /**
  * Tracks schema changes.
  *
- * <p>An implementation of this interface can be registered with {@link
- * Session#register(SchemaChangeListener)}.
+ * <p>An implementation of this interface can be registered in the configuration, or with {@link
+ * SessionBuilder#withSchemaChangeListener(SchemaChangeListener)}.
  *
  * <p>Note that the methods defined by this interface will be executed by internal driver threads,
  * and are therefore expected to have short execution times. If you need to perform long
  * computations or blocking calls in response to schema change events, it is strongly recommended to
  * schedule them asynchronously on a separate thread provided by your application code.
+ *
+ * <p>If you implement this interface but don't need to implement all the methods, extend {@link
+ * SchemaChangeListenerBase}.
  */
-public interface SchemaChangeListener {
+public interface SchemaChangeListener extends AutoCloseable {
 
   void onKeyspaceCreated(KeyspaceMetadata keyspace);
 
@@ -66,13 +69,4 @@ public interface SchemaChangeListener {
   void onViewDropped(ViewMetadata view);
 
   void onViewUpdated(ViewMetadata current, ViewMetadata previous);
-
-  /** Invoked when the listener is registered with a session. */
-  void onRegister(Session session);
-
-  /**
-   * Invoked when the listener is unregistered from a session, or at session shutdown, whichever
-   * comes first.
-   */
-  void onUnregister(Session session);
 }

core/src/main/java/com/datastax/oss/driver/api/core/metadata/schema/SchemaChangeListenerBase.java

@@ -15,74 +15,106 @@
  */
 package com.datastax.oss.driver.api.core.metadata.schema;
 
-import com.datastax.oss.driver.api.core.session.Session;
 import com.datastax.oss.driver.api.core.type.UserDefinedType;
 
 /**
- * Convenience schema change listener implementation that defines all methods as no-ops.
- *
- * <p>Implementors that are only interested in a subset of events can extend this class and override
- * the relevant methods.
+ * Convenience class for listener implementations that that don't need to override all methods (all
+ * methods in this class are empty).
  */
 public class SchemaChangeListenerBase implements SchemaChangeListener {
 
   @Override
-  public void onKeyspaceCreated(KeyspaceMetadata keyspace) {}
-
-  @Override
-  public void onKeyspaceDropped(KeyspaceMetadata keyspace) {}
+  public void onKeyspaceCreated(KeyspaceMetadata keyspace) {
+    // nothing to do
+  }
 
   @Override
-  public void onKeyspaceUpdated(KeyspaceMetadata current, KeyspaceMetadata previous) {}
+  public void onKeyspaceDropped(KeyspaceMetadata keyspace) {
+    // nothing to do
+  }
 
   @Override
-  public void onTableCreated(TableMetadata table) {}
+  public void onKeyspaceUpdated(KeyspaceMetadata current, KeyspaceMetadata previous) {
+    // nothing to do
+  }
 
   @Override
-  public void onTableDropped(TableMetadata table) {}
+  public void onTableCreated(TableMetadata table) {
+    // nothing to do
+  }
 
   @Override
-  public void onTableUpdated(TableMetadata current, TableMetadata previous) {}
+  public void onTableDropped(TableMetadata table) {
+    // nothing to do
+  }
 
   @Override
-  public void onUserDefinedTypeCreated(UserDefinedType type) {}
+  public void onTableUpdated(TableMetadata current, TableMetadata previous) {
+    // nothing to do
+  }
 
   @Override
-  public void onUserDefinedTypeDropped(UserDefinedType type) {}
+  public void onUserDefinedTypeCreated(UserDefinedType type) {
+    // nothing to do
+  }
 
   @Override
-  public void onUserDefinedTypeUpdated(UserDefinedType current, UserDefinedType previous) {}
+  public void onUserDefinedTypeDropped(UserDefinedType type) {
+    // nothing to do
+  }
 
   @Override
-  public void onFunctionCreated(FunctionMetadata function) {}
+  public void onUserDefinedTypeUpdated(UserDefinedType current, UserDefinedType previous) {
+    // nothing to do
+  }
 
   @Override
-  public void onFunctionDropped(FunctionMetadata function) {}
+  public void onFunctionCreated(FunctionMetadata function) {
+    // nothing to do
+  }
 
   @Override
-  public void onFunctionUpdated(FunctionMetadata current, FunctionMetadata previous) {}
+  public void onFunctionDropped(FunctionMetadata function) {
+    // nothing to do
+  }
 
   @Override
-  public void onAggregateCreated(AggregateMetadata aggregate) {}
+  public void onFunctionUpdated(FunctionMetadata current, FunctionMetadata previous) {
+    // nothing to do
+  }
 
   @Override
-  public void onAggregateDropped(AggregateMetadata aggregate) {}
+  public void onAggregateCreated(AggregateMetadata aggregate) {
+    // nothing to do
+  }
 
   @Override
-  public void onAggregateUpdated(AggregateMetadata current, AggregateMetadata previous) {}
+  public void onAggregateDropped(AggregateMetadata aggregate) {
+    // nothing to do
+  }
 
   @Override
-  public void onViewCreated(ViewMetadata view) {}
+  public void onAggregateUpdated(AggregateMetadata current, AggregateMetadata previous) {
+    // nothing to do
+  }
 
   @Override
-  public void onViewDropped(ViewMetadata view) {}
+  public void onViewCreated(ViewMetadata view) {
+    // nothing to do
+  }
 
   @Override
-  public void onViewUpdated(ViewMetadata current, ViewMetadata previous) {}
+  public void onViewDropped(ViewMetadata view) {
+    // nothing to do
+  }
 
   @Override
-  public void onRegister(Session session) {}
+  public void onViewUpdated(ViewMetadata current, ViewMetadata previous) {
+    // nothing to do
+  }
 
   @Override
-  public void onUnregister(Session session) {}
+  public void close() throws Exception {
+    // nothing to do
+  }
 }

core/src/main/java/com/datastax/oss/driver/api/core/session/Session.java

@@ -24,8 +24,6 @@
 import com.datastax.oss.driver.api.core.metadata.Metadata;
 import com.datastax.oss.driver.api.core.metadata.Node;
 import com.datastax.oss.driver.api.core.metadata.NodeState;
-import com.datastax.oss.driver.api.core.metadata.NodeStateListener;
-import com.datastax.oss.driver.api.core.metadata.schema.SchemaChangeListener;
 import com.datastax.oss.driver.api.core.metrics.Metrics;
 import com.datastax.oss.driver.api.core.type.reflect.GenericType;
 import com.datastax.oss.driver.internal.core.util.concurrent.BlockingOperation;
@@ -195,32 +193,4 @@ default boolean checkSchemaAgreement() {
    */
   <RequestT extends Request, ResultT> ResultT execute(
       RequestT request, GenericType<ResultT> resultType);
-
-  /**
-   * Registers the provided schema change listener.
-   *
-   * <p>This is a no-op if the listener was registered already.
-   */
-  void register(SchemaChangeListener listener);
-
-  /**
-   * Unregisters the provided schema change listener.
-   *
-   * <p>This is a no-op if the listener was not registered.
-   */
-  void unregister(SchemaChangeListener listener);
-
-  /**
-   * Registers the provided node state listener.
-   *
-   * <p>This is a no-op if the listener was registered already.
-   */
-  void register(NodeStateListener listener);
-
-  /**
-   * Unregisters the provided node state listener.
-   *
-   * <p>This is a no-op if the listener was not registered.
-   */
-  void unregister(NodeStateListener listener);
 }