JAVA-2505: Annotate Node.getHostId() as nullable (apache#1350)

olim7t · adutra · commit beaad5f4bc66 · 2019-10-21T10:57:12.000+03:00
diff --git a/changelog/README.md b/changelog/README.md
@@ -4,6 +4,7 @@
 
 ### 4.3.0 (in progress)
 
+- [documentation] JAVA-2505: Annotate Node.getHostId() as nullable
 - [improvement] JAVA-1708: Support DSE "everywhere" replication strategy
 - [improvement] JAVA-2471: Consider DSE version when parsing the schema
 - [improvement] JAVA-2444: Add method setRoutingKey(ByteBuffer...) to StatementBuilder
diff --git a/core/revapi.json b/core/revapi.json
@@ -4816,6 +4816,20 @@
         "old": "field com\\.datastax\\.oss\\.driver\\.api\\.core\\.Version.V.*",
         "annotation": "@edu.umd.cs.findbugs.annotations.NonNull",
         "justification": "Marking constants as non-null doesn't break existing code"
+      },
+      {
+        "code": "java.annotation.removed",
+        "old": "method java.util.UUID com.datastax.oss.driver.api.core.metadata.Node::getHostId()",
+        "new": "method java.util.UUID com.datastax.oss.driver.api.core.metadata.Node::getHostId()",
+        "annotation": "@edu.umd.cs.findbugs.annotations.NonNull",
+        "justification": "JAVA-2505: Annotate Node.getHostId() as nullable"
+      },
+      {
+        "code": "java.annotation.added",
+        "old": "method java.util.UUID com.datastax.oss.driver.api.core.metadata.Node::getHostId()",
+        "new": "method java.util.UUID com.datastax.oss.driver.api.core.metadata.Node::getHostId()",
+        "annotation": "@edu.umd.cs.findbugs.annotations.Nullable",
+        "justification": "JAVA-2505: Annotate Node.getHostId() as nullable"
       }
     ]
   }
diff --git a/core/src/main/java/com/datastax/oss/driver/api/core/metadata/Node.java b/core/src/main/java/com/datastax/oss/driver/api/core/metadata/Node.java
@@ -184,9 +184,26 @@ public interface Node {
    * The host ID that is assigned to this node by Cassandra. This value can be used to uniquely
    * identify a node even when the underling IP address changes.
    *
-   * <p>This information is always present.
+   * <p>This information is always present once the session has initialized. However, there is a
+   * narrow corner case where a driver client can observe a null value: if a {@link
+   * NodeStateListener} is registered, the <b>very first</b> {@code onUp} call will reference a node
+   * that has a null id (that node is the initial contact point, and the driver hasn't read host ids
+   * from {@code system.local} and {@code system.peers} yet). Beyond that point &mdash; including
+   * any other {@code onUp} call &mdash; the host id will always be present.
+   *
+   * <pre>
+   * CqlSession session = CqlSession.builder()
+   *     .withNodeStateListener(
+   *         new NodeStateListenerBase() {
+   *           &#64;Override
+   *           public void onUp(@NonNull Node node) {
+   *             // node.getHostId() == null for the first invocation only
+   *           }
+   *         })
+   *     .build();
+   * </pre>
    */
-  @NonNull
+  @Nullable
   UUID getHostId();
 
   /**
diff --git a/core/src/main/java/com/datastax/oss/driver/internal/core/metadata/DefaultNode.java b/core/src/main/java/com/datastax/oss/driver/internal/core/metadata/DefaultNode.java
@@ -129,7 +129,7 @@ public Version getCassandraVersion() {
     return cassandraVersion;
   }
 
-  @NonNull
+  @Nullable
   @Override
   public UUID getHostId() {
     return hostId;

Original file line number	Diff line number	Diff line change
`@@ -129,7 +129,7 @@ public Version getCassandraVersion() {`
`129`	`129`	`return cassandraVersion;`
`130`	`130`	`}`
`131`	`131`
`132`		`- @NonNull`
	`132`	`+ @Nullable`
`133`	`133`	`@Override`
`134`	`134`	`public UUID getHostId() {`
`135`	`135`	`return hostId;`