Callout external docs and examples (#1224)

* Callout external docs and examples * Fixed tests for 2.11 vs stream and consumer metadata * Fixed tests for 2.11 vs stream and consumer metadata
nats-io · Sep 11, 2024 · 4d51fa1 · 4d51fa1
1 parent 346cc29
commit 4d51fa1
Show file tree

Hide file tree

Showing 10 changed files with 61 additions and 47 deletions.
diff --git a/README.md b/README.md
@@ -13,12 +13,13 @@
 [![Build Main Badge](https://github.com/nats-io/nats.java/actions/workflows/build-main.yml/badge.svg?event=push)](https://github.com/nats-io/nats.java/actions/workflows/build-main.yml)
 [![Release Badge](https://github.com/nats-io/nats.java/actions/workflows/build-release.yml/badge.svg?event=release)](https://github.com/nats-io/nats.java/actions/workflows/build-release.yml)
 
-The [**API**](https://javadoc.io/doc/io.nats/jnats/latest/index.html) is simple to use and highly performant.
 
-**Check out [NATS by Example](https://natsbyexample.com) - An evolving collection of runnable, cross-client reference examples for NATS.**
+### Examples and other documentation...
 
-There are also many basic examples in the [examples](https://github.com/nats-io/nats.java/tree/main/src/examples/java/io/nats/examples) directory of this repo
-and more simple application examples in the [Java Nats Examples](https://github.com/nats-io/java-nats-examples) repo.
+1. [**Java API Docs**](https://javadoc.io/doc/io.nats/jnats/latest/index.html) - the latest Java API docs.
+1. [**NATS by Example**](https://natsbyexample.com) - An evolving collection of runnable, cross-client reference examples for NATS.
+1. The [**examples directory**](https://github.com/nats-io/nats.java/tree/main/src/examples/java/io/nats/examples) covers basic api use.
+1. The [**Java Nats Examples**](https://github.com/nats-io/java-nats-examples) github repo, a collection of simple use case examples.
 
 ## Table of Contents
 * [Simplification](#simplification)

diff --git a/src/test/java/io/nats/client/api/ConsumerConfigurationTests.java b/src/test/java/io/nats/client/api/ConsumerConfigurationTests.java
@@ -38,7 +38,7 @@ public class ConsumerConfigurationTests extends TestBase {
     public void testBuilder() throws Exception {
         ZonedDateTime zdt = ZonedDateTime.of(2012, 1, 12, 6, 30, 1, 500, DateTimeUtils.ZONE_ID_GMT);
         Map<String, String> metadata = new HashMap<>();
-        metadata.put("meta-foo", "meta-bar");
+        metadata.put(META_KEY, META_VALUE);
 
         ConsumerConfiguration.Builder builder = ConsumerConfiguration.builder()
             .ackPolicy(AckPolicy.Explicit)
@@ -272,7 +272,7 @@ private void assertAsBuilt(ConsumerConfiguration c, ZonedDateTime zdt) {
         assertEquals(Duration.ofSeconds(2), c.getBackoff().get(1));
         assertEquals(Duration.ofSeconds(3), c.getBackoff().get(2));
         assertEquals(1, c.getMetadata().size());
-        assertEquals("meta-bar", c.getMetadata().get("meta-foo"));
+        assertEquals(META_VALUE, c.getMetadata().get(META_KEY));
     }
 
     @Test
@@ -311,7 +311,7 @@ public void testParsingAndSetters() {
         assertEquals(Duration.ofSeconds(2), c.getBackoff().get(1));
         assertEquals(Duration.ofSeconds(3), c.getBackoff().get(2));
         assertEquals(1, c.getMetadata().size());
-        assertEquals("meta-bar", c.getMetadata().get("meta-foo"));
+        assertEquals(META_VALUE, c.getMetadata().get(META_KEY));
 
         assertDefaultCc(new ConsumerConfiguration(ConsumerConfiguration.builder().jsonValue(JsonValue.EMPTY_MAP).build()));
     }

diff --git a/src/test/java/io/nats/client/api/StreamConfigurationTests.java b/src/test/java/io/nats/client/api/StreamConfigurationTests.java
@@ -150,7 +150,7 @@ public void testConstruction() {
         // copy constructor
         validate(StreamConfiguration.builder(testSc).build(), false);
 
-        Map<String, String> metaData = new HashMap<>(); metaData.put("meta-foo", "meta-bar");
+        Map<String, String> metaData = new HashMap<>(); metaData.put(META_KEY, META_VALUE);
 
         // builder
         StreamConfiguration.Builder builder = StreamConfiguration.builder()
@@ -543,7 +543,7 @@ private void validate(StreamConfiguration sc, boolean serverTest) {
             validateSource(sc.getSources().get(1), 1, zdt);
 
             assertEquals(1, sc.getMetadata().size());
-            assertEquals("meta-bar", sc.getMetadata().get("meta-foo"));
+            assertEquals(META_VALUE, sc.getMetadata().get(META_KEY));
             assertEquals(82942, sc.getFirstSequence());
 
             assertSame(S2, sc.getCompressionOption());

diff --git a/src/test/java/io/nats/client/impl/JetStreamGeneralTests.java b/src/test/java/io/nats/client/impl/JetStreamGeneralTests.java
@@ -806,7 +806,6 @@ public void testConsumerIsNotModified() throws Exception {
     public void testSubscribeDurableConsumerMustMatch() throws Exception {
         jsServer.run(nc -> {
             JetStream js = nc.jetStream();
-            JetStreamManagement jsm = nc.jetStreamManagement();
 
             String stream = stream();
             String subject = subject();
@@ -879,7 +878,7 @@ public void testSubscribeDurableConsumerMustMatch() throws Exception {
             Map<String, String> metadataA = new HashMap<>(); metadataA.put("a", "A");
             Map<String, String> metadataB = new HashMap<>(); metadataB.put("b", "B");
 
-            if (nc.getServerInfo().isNewerVersionThan("2.9.99")) {
+            if (atLeast2_10()) {
                 // metadata server null versus new not null
                 nc.jetStreamManagement().addOrUpdateConsumer(stream, pushDurableBuilder(subject, uname, deliver).build());
                 changeExPush(js, subject, pushDurableBuilder(subject, uname, deliver).metadata(metadataA), "metadata");
@@ -891,8 +890,10 @@ public void testSubscribeDurableConsumerMustMatch() throws Exception {
                 // metadata server not null versus new not null but different
                 changeExPush(js, subject, pushDurableBuilder(subject, uname, deliver).metadata(metadataB), "metadata");
 
-                // metadata server not null versus new not null and same
-                changeOkPush(js, subject, pushDurableBuilder(subject, uname, deliver).metadata(metadataA));
+                if (before2_11()) {
+                    // metadata server not null versus new not null and same
+                    changeOkPush(js, subject, pushDurableBuilder(subject, uname, deliver).metadata(metadataA));
+                }
             }
         });
     }

diff --git a/src/test/java/io/nats/client/impl/JetStreamManagementTests.java b/src/test/java/io/nats/client/impl/JetStreamManagementTests.java
@@ -107,7 +107,7 @@ public void testStreamCreate() throws Exception {
     @Test
     public void testStreamMetadata() throws Exception {
         jsServer.run(nc -> {
-            Map<String, String> metaData = new HashMap<>(); metaData.put("meta-foo", "meta-bar");
+            Map<String, String> metaData = new HashMap<>(); metaData.put(META_KEY, META_VALUE);
             JetStreamManagement jsm = nc.jetStreamManagement();
 
             StreamConfiguration sc = StreamConfiguration.builder()
@@ -119,14 +119,7 @@ public void testStreamMetadata() throws Exception {
 
             StreamInfo si = jsm.addStream(sc);
             assertNotNull(si.getConfiguration());
-            sc = si.getConfiguration();
-            if (nc.getServerInfo().isSameOrNewerThanVersion("2.10")) {
-                assertEquals(1, sc.getMetadata().size());
-                assertEquals("meta-bar", sc.getMetadata().get("meta-foo"));
-            }
-            else {
-                assertNull(sc.getMetadata());
-            }
+            assertMetaData(si.getConfiguration().getMetadata());
         });
     }
 
@@ -1009,7 +1002,7 @@ private void assertValidAddOrUpdate(JetStreamManagement jsm, ConsumerConfigurati
     @Test
     public void testConsumerMetadata() throws Exception {
         jsServer.run(nc -> {
-            Map<String, String> metaData = new HashMap<>(); metaData.put("meta-foo", "meta-bar");
+            Map<String, String> metaData = new HashMap<>(); metaData.put(META_KEY, META_VALUE);
             JetStreamManagement jsm = nc.jetStreamManagement();
             TestingStreamContainer tsc = new TestingStreamContainer(jsm);
 
@@ -1019,14 +1012,7 @@ public void testConsumerMetadata() throws Exception {
                 .build();
 
             ConsumerInfo ci = jsm.addOrUpdateConsumer(tsc.stream, cc);
-            if (nc.getServerInfo().isSameOrNewerThanVersion("2.10")) {
-                assertEquals(1, ci.getConsumerConfiguration().getMetadata().size());
-                assertEquals("meta-bar", ci.getConsumerConfiguration().getMetadata().get("meta-foo"));
-            }
-            else {
-                assertNotNull(ci.getConsumerConfiguration().getMetadata());
-                assertEquals(0, ci.getConsumerConfiguration().getMetadata().size());
-            }
+            assertMetaData(ci.getConsumerConfiguration().getMetadata());
         });
     }
 

diff --git a/src/test/java/io/nats/client/impl/KeyValueTests.java b/src/test/java/io/nats/client/impl/KeyValueTests.java
@@ -53,7 +53,7 @@ public void testWorkflow() throws Exception {
             nc.keyValueManagement(KeyValueOptions.builder(DEFAULT_JS_OPTIONS).build()); // coverage
 
             Map<String, String> metadata = new HashMap<>();
-            metadata.put("meta-foo", "meta-bar");
+            metadata.put(META_KEY, META_VALUE);
 
             // create the bucket
             String bucket = bucket();
@@ -338,10 +338,7 @@ private void assertInitialStatus(KeyValueStatus status, String bucket, String de
         assertTrue(status.toString().contains(bucket));
         assertTrue(status.toString().contains(desc));
 
-        if (atLeast2_10()) {
-            assertEquals(1, status.getMetadata().size());
-            assertEquals("meta-bar", status.getMetadata().get("meta-foo"));
-        }
+        assertMetaData(status.getMetadata());
     }
 
     @Test

diff --git a/src/test/java/io/nats/client/impl/ObjectStoreTests.java b/src/test/java/io/nats/client/impl/ObjectStoreTests.java
@@ -41,7 +41,7 @@ public void testWorkflow() throws Exception {
             nc.objectStoreManagement(ObjectStoreOptions.builder(DEFAULT_JS_OPTIONS).build()); // coverage
 
             Map<String, String> metadata = new HashMap<>();
-            metadata.put("meta-foo", "meta-bar");
+            metadata.put(META_KEY, META_VALUE);
 
             String bucket = bucket();
             String desc = variant();
@@ -174,10 +174,7 @@ private static void validateStatus(ObjectStoreStatus status, String bucket, Stri
         assertEquals("JetStream", status.getBackingStore());
         assertNotNull(status.toString()); // coverage
 
-        if (atLeast2_10()) {
-            assertEquals(1, status.getMetadata().size());
-            assertEquals("meta-bar", status.getMetadata().get("meta-foo"));
-        }
+        assertMetaData(status.getMetadata());
     }
 
     @SuppressWarnings("SameParameterValue")

diff --git a/src/test/java/io/nats/client/utils/TestBase.java b/src/test/java/io/nats/client/utils/TestBase.java
@@ -26,6 +26,7 @@
 import java.nio.file.Files;
 import java.time.Duration;
 import java.util.List;
+import java.util.Map;
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.locks.LockSupport;
 import java.util.function.Supplier;
@@ -44,9 +45,9 @@ public class TestBase {
     public static final String STARTS_WITH_DOT     = ".starts-with-dot";
     public static final String ENDS_WITH_DOT       = "ends-with-dot.";
     public static final String ENDS_WITH_DOT_SPACE = "ends-with-space. ";
-    public static final String ENDS_WITH_CR       = "ends-with-space.\r";
-    public static final String ENDS_WITH_LF       = "ends-with-space.\n";
-    public static final String ENDS_WITH_TAB      = "ends-with-space.\t";
+    public static final String ENDS_WITH_CR        = "ends-with-space.\r";
+    public static final String ENDS_WITH_LF        = "ends-with-space.\n";
+    public static final String ENDS_WITH_TAB       = "ends-with-space.\t";
     public static final String STAR_NOT_SEGMENT    = "star*not*segment";
     public static final String GT_NOT_SEGMENT      = "gt>not>segment";
     public static final String EMPTY_SEGMENT       = "blah..blah";
@@ -70,6 +71,9 @@ public class TestBase {
     public static final String HAS_EQUALS     = "has=equals";
     public static final String HAS_TIC        = "has`tic";
 
+    public static final String META_KEY   = "meta-test-key";
+    public static final String META_VALUE = "meta-test-value";
+
     public static final long STANDARD_CONNECTION_WAIT_MS = 5000;
     public static final long LONG_CONNECTION_WAIT_MS = 7500;
     public static final long STANDARD_FLUSH_TIMEOUT_MS = 2000;
@@ -122,7 +126,7 @@ public static boolean atLeast2_9_1(ServerInfo si) {
     }
 
     public static boolean atLeast2_10() {
-        return RUN_SERVER_INFO.isNewerVersionThan("2.9.99");
+        return atLeast2_10(RUN_SERVER_INFO);
     }
 
     public static boolean atLeast2_10(ServerInfo si) {
@@ -133,10 +137,22 @@ public static boolean atLeast2_10_3(ServerInfo si) {
         return si.isSameOrNewerThanVersion("2.10.3");
     }
 
+    public static boolean atLeast2_11() {
+        return atLeast2_11(RUN_SERVER_INFO);
+    }
+
     public static boolean atLeast2_11(ServerInfo si) {
         return si.isNewerVersionThan("2.10.99");
     }
 
+    public static boolean before2_11() {
+        return before2_11(RUN_SERVER_INFO);
+    }
+
+    public static boolean before2_11(ServerInfo si) {
+        return si.isOlderThanVersion("2.11");
+    }
+
     public static void runInServer(InServerTest inServerTest) throws Exception {
         runInServer(false, false, null, null, inServerTest);
     }
@@ -815,4 +831,20 @@ else if (error.getKind() == KIND_ILLEGAL_STATE) {
             assertInstanceOf(IllegalStateException.class, e);
         }
     }
+
+    public static void assertMetaData(Map<String, String> metadata) {
+        if (atLeast2_10()) {
+            if (before2_11()) {
+                assertEquals(1, metadata.size());
+            }
+            else {
+                assertTrue(metadata.size() > 1);
+            }
+            assertEquals(META_VALUE, metadata.get(META_KEY));
+        }
+        else {
+            assertNotNull(metadata);
+            assertEquals(0, metadata.size());
+        }
+    }
 }
diff --git a/src/test/resources/data/ConsumerConfiguration.json b/src/test/resources/data/ConsumerConfiguration.json
@@ -26,5 +26,5 @@
   "backoff": [1000000000, 2000000000, 3000000000],
   "num_replicas": 5,
   "mem_storage": true,
-  "metadata":{"meta-foo":"meta-bar"}
+  "metadata":{"meta-test-key":"meta-test-value"}
 }
diff --git a/src/test/resources/data/StreamConfiguration.json b/src/test/resources/data/StreamConfiguration.json
@@ -23,7 +23,7 @@
   "allow_rollup_hdrs": true,
   "allow_direct": true,
   "mirror_direct": true,
-  "metadata":{"meta-foo":"meta-bar"},
+  "metadata":{"meta-test-key":"meta-test-value"},
   "first_seq": 82942,
   "placement": {
     "cluster": "clstr",