KAFKA-9663: Update JavaDocs to indicate null return values in Kafka…

…Streams (#8228) Reviewer: Matthias J. Sax <[email protected]>
apache · Mar 7, 2020 · 2775572 · 2775572
1 parent e7f6c1e
commit 2775572
Show file tree

Hide file tree

Showing 2 changed files with 12 additions and 8 deletions.
diff --git a/streams/src/main/java/org/apache/kafka/streams/KafkaStreams.java b/streams/src/main/java/org/apache/kafka/streams/KafkaStreams.java
@@ -1083,7 +1083,8 @@ public Collection<StreamsMetadata> allMetadataForStore(final String storeName) {
      * @param keySerializer serializer for the key
      * @param <K>           key type
      * @return {@link StreamsMetadata} for the {@code KafkaStreams} instance with the provided {@code storeName} and
-     * {@code key} of this application or {@link StreamsMetadata#NOT_AVAILABLE} if Kafka Streams is (re-)initializing
+     * {@code key} of this application or {@link StreamsMetadata#NOT_AVAILABLE} if Kafka Streams is (re-)initializing,
+     * or {@code null} if no matching metadata could be found.
      * @deprecated Since 2.5. Use {@link #queryMetadataForKey(String, Object, Serializer)} instead.
      */
     @Deprecated
@@ -1116,7 +1117,8 @@ public <K> StreamsMetadata metadataForKey(final String storeName,
      * @param partitioner the partitioner to be use to locate the host for the key
      * @param <K>         key type
      * @return {@link StreamsMetadata} for the {@code KafkaStreams} instance with the provided {@code storeName} and
-     * {@code key} of this application or {@link StreamsMetadata#NOT_AVAILABLE} if Kafka Streams is (re-)initializing
+     * {@code key} of this application or {@link StreamsMetadata#NOT_AVAILABLE} if Kafka Streams is (re-)initializing,
+     * or {@code null} if no matching metadata could be found.
      * @deprecated Since 2.5. Use {@link #queryMetadataForKey(String, Object, StreamPartitioner)} instead.
      */
     @Deprecated
@@ -1134,7 +1136,8 @@ public <K> StreamsMetadata metadataForKey(final String storeName,
      * @param key           the key to find metadata for
      * @param keySerializer serializer for the key
      * @param <K>           key type
-     * Returns {@link KeyQueryMetadata} containing all metadata about hosting the given key for the given store.
+     * Returns {@link KeyQueryMetadata} containing all metadata about hosting the given key for the given store,
+     * or {@code null} if no matching metadata could be found.
      */
     public <K> KeyQueryMetadata queryMetadataForKey(final String storeName,
                                                     final K key,
@@ -1151,7 +1154,7 @@ public <K> KeyQueryMetadata queryMetadataForKey(final String storeName,
      * @param partitioner the partitioner to be use to locate the host for the key
      * @param <K>           key type
      * Returns {@link KeyQueryMetadata} containing all metadata about hosting the given key for the given store, using the
-     * the supplied partitioner
+     * the supplied partitioner, or {@code null} if no matching metadata could be found.
      */
     public <K> KeyQueryMetadata queryMetadataForKey(final String storeName,
                                                     final K key,

diff --git a/streams/src/main/java/org/apache/kafka/streams/processor/internals/StreamsMetadataState.java b/streams/src/main/java/org/apache/kafka/streams/processor/internals/StreamsMetadataState.java
@@ -136,7 +136,7 @@ public synchronized Collection<StreamsMetadata> getAllMetadataForStore(final Str
      * @param keySerializer Serializer for the key
      * @param <K>           key type
      * @return The {@link StreamsMetadata} for the storeName and key or {@link StreamsMetadata#NOT_AVAILABLE}
-     * if streams is (re-)initializing
+     * if streams is (re-)initializing, or {@code null} if no matching metadata could be found.
      * @deprecated Use {@link #getKeyQueryMetadataForKey(String, Object, Serializer)} instead.
      */
     @Deprecated
@@ -184,7 +184,8 @@ public synchronized <K> StreamsMetadata getMetadataWithKey(final String storeNam
      * @param keySerializer Serializer for the key
      * @param <K>           key type
      * @return The {@link KeyQueryMetadata} for the storeName and key or {@link KeyQueryMetadata#NOT_AVAILABLE}
-     * if streams is (re-)initializing or null if the corresponding topic cannot be found
+     * if streams is (re-)initializing or {@code null} if the corresponding topic cannot be found,
+     * or null if no matching metadata could be found.
      */
     public synchronized <K> KeyQueryMetadata getKeyQueryMetadataForKey(final String storeName,
                                                                        final K key,
@@ -206,7 +207,7 @@ public synchronized <K> KeyQueryMetadata getKeyQueryMetadataForKey(final String
      * @param partitioner partitioner to use to find correct partition for key
      * @param <K>         key type
      * @return The {@link KeyQueryMetadata} for the storeName and key or {@link KeyQueryMetadata#NOT_AVAILABLE}
-     * if streams is (re-)initializing
+     * if streams is (re-)initializing, or {@code null} if no matching metadata could be found.
      */
     public synchronized <K> KeyQueryMetadata getKeyQueryMetadataForKey(final String storeName,
                                                                        final K key,
@@ -246,7 +247,7 @@ public synchronized <K> KeyQueryMetadata getKeyQueryMetadataForKey(final String
      * @param partitioner partitioner to use to find correct partition for key
      * @param <K>         key type
      * @return The {@link StreamsMetadata} for the storeName and key or {@link StreamsMetadata#NOT_AVAILABLE}
-     * if streams is (re-)initializing
+     * if streams is (re-)initializing, or {@code null} if no matching metadata could be found.
      * @deprecated Use {@link #getKeyQueryMetadataForKey(String, Object, StreamPartitioner)} instead.
      */
     @Deprecated