From 4d51fa1b29b3da12459801c330e825b4b630df55 Mon Sep 17 00:00:00 2001 From: Scott Fauerbach Date: Wed, 11 Sep 2024 05:40:03 -0400 Subject: [PATCH] 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 --- README.md | 9 +++-- .../api/ConsumerConfigurationTests.java | 6 +-- .../client/api/StreamConfigurationTests.java | 4 +- .../client/impl/JetStreamGeneralTests.java | 9 +++-- .../client/impl/JetStreamManagementTests.java | 22 ++-------- .../io/nats/client/impl/KeyValueTests.java | 7 +--- .../io/nats/client/impl/ObjectStoreTests.java | 7 +--- .../java/io/nats/client/utils/TestBase.java | 40 +++++++++++++++++-- .../resources/data/ConsumerConfiguration.json | 2 +- .../resources/data/StreamConfiguration.json | 2 +- 10 files changed, 61 insertions(+), 47 deletions(-) diff --git a/README.md b/README.md index fb11f65e8..192b2782b 100644 --- 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 index 0f4a94a7d..7d843661d 100644 --- 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 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 index bc7734c5a..71ed2a36d 100644 --- 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 metaData = new HashMap<>(); metaData.put("meta-foo", "meta-bar"); + Map 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 index 1d84a827f..138cf238c 100644 --- 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 metadataA = new HashMap<>(); metadataA.put("a", "A"); Map 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 index b929a6bc0..9a468f8f0 100644 --- 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 metaData = new HashMap<>(); metaData.put("meta-foo", "meta-bar"); + Map 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 metaData = new HashMap<>(); metaData.put("meta-foo", "meta-bar"); + Map 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 index 2c7748182..c67f783a5 100644 --- 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 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 index 6e0f20985..bbfa1db96 100644 --- 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 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 index 53c2b7e95..7ff1fa2cd 100644 --- 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 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 index 43d9ec2f7..5a8737392 100644 --- 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 index d84cdcb79..f500f77a2 100644 --- 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",