Merge pull request #256 from nats-io/2.6.0

2.6.0

Author: sasbury

.travis.yml

@@ -7,6 +7,7 @@ jdk:
 - openjdk8
 - openjdk9
 - openjdk10
+- openjdk11
 before_script:
 - wget "https://github.com/nats-io/nats-server/releases/download/$nats_server_version/gnatsd-$nats_server_version-linux-amd64.zip"
   -O tmp.zip

CHANGELOG.md

@@ -1,6 +1,15 @@
 
 # Change Log
 
+## Version 2.6.0
+
+* [FIXED] - cleaned up use of "chain" instead of "creds"
+* [FIXED] - #255 - added special ioexception when possible to indicate an authentication problem on connect
+* [FIXED] - #252 - deprecated strings for username/pass/token and use char arrays instead, required changing some other code to CharBuffer
+* [ADDED] - Openjdk11 to travis build and updated gradle wrapper to 5.5
+* [ADDED] - an option to trace connect timing, including a test and example
+* [FIXED/ADDED] - #197 - the ability to use a single dispatcher for multiple message handlers, including multiple subscriptions on a single subject
+
 ## Version 2.5.2
 
 * [FIXED] - #244 - fixed an issue with parsing ipv6 addresses in the info JSON, added unit test for parser

README.md

@@ -52,9 +52,9 @@ The java-nats client is provided in a single jar file, with a single external de
 
 ### Downloading the Jar
 
-You can download the latest jar at [https://search.maven.org/remotecontent?filepath=io/nats/jnats/2.5.2/jnats-2.5.2.jar](https://search.maven.org/remotecontent?filepath=io/nats/jnats/2.5.2/jnats-2.5.2.jar).
+You can download the latest jar at [https://search.maven.org/remotecontent?filepath=io/nats/jnats/2.6.0/jnats-2.6.0.jar](https://search.maven.org/remotecontent?filepath=io/nats/jnats/2.6.0/jnats-2.6.0.jar).
 
-The examples are available at [https://search.maven.org/remotecontent?filepath=io/nats/jnats/2.5.2/jnats-2.5.2-examples.jar](https://search.maven.org/remotecontent?filepath=io/nats/jnats/2.5.2/jnats-2.5.2-examples.jar).
+The examples are available at [https://search.maven.org/remotecontent?filepath=io/nats/jnats/2.6.0/jnats-2.6.0-examples.jar](https://search.maven.org/remotecontent?filepath=io/nats/jnats/2.6.0/jnats-2.6.0-examples.jar).
 
 To use NKeys, you will need the ed25519 library, which can be downloaded at [https://repo1.maven.org/maven2/net/i2p/crypto/eddsa/0.3.0/eddsa-0.3.0.jar](https://repo1.maven.org/maven2/net/i2p/crypto/eddsa/0.3.0/eddsa-0.3.0.jar).
 
@@ -64,7 +64,7 @@ The NATS client is available in the Maven central repository, and can be importe
 
 ```groovy
 dependencies {
-    implementation 'io.nats:jnats:2.5.2'
+    implementation 'io.nats:jnats:2.6.0'
 }
 ```
 
@@ -90,7 +90,7 @@ The NATS client is available on the Maven central repository, and can be importe
 <dependency>
     <groupId>io.nats</groupId>
     <artifactId>jnats</artifactId>
-    <version>2.5.2</version>
+    <version>2.6.0</version>
 </dependency>
 ```
 
@@ -194,7 +194,7 @@ The Java NATS library provides two mechanisms to listen for messages, three if y
     String response = new String(msg.getData(), StandardCharsets.UTF_8);
     ```
 
-2. A Dispatcher that will call application code in a background thread. Dispatchers can manage multiple subjects with a single thread and single callback.
+2. A Dispatcher that will call application code in a background thread. Dispatchers can manage multiple subjects with a single thread and shared callback.
 
     ```java
     Dispatcher d = nc.createDispatcher((msg) -> {
@@ -205,6 +205,18 @@ The Java NATS library provides two mechanisms to listen for messages, three if y
     d.subscribe("subject");
     ```
 
+    A dispatcher can also accept individual callbacks for any given subscription.
+
+    ```java
+    Dispatcher d = nc.createDispatcher((msg) -> {});
+
+    Subscription s = d.subscribe("some.subject", (msg) -> {
+        String response = new String(msg.getData(), StandardCharsets.UTF_8);
+        System.out.println("Message received (up to 100 times): " + response);
+    });
+    d.unsubscribe(s, 100);
+    ```
+
 ## Advanced Usage
 
 ### TLS

build.gradle

@@ -13,10 +13,10 @@ plugins {
 // Update version here, repeated check-ins not into master will have snapshot on them
 // Be sure to update Nats.java with the latest version, the change log and the package-info.java
 def versionMajor = 2
-def versionMinor = 5
-def versionPatch = 2
+def versionMinor = 6
+def versionPatch = 0
 def versionModifier = ""
-def jarVersion = "2.5.2"
+def jarVersion = "2.6.0"
 def branch = System.getenv("TRAVIS_BRANCH");
 
 def getVersionName = { ->

gradle/wrapper/gradle-wrapper.properties

@@ -1,5 +1,5 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-4.8-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-5.5.1-bin.zip
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists

src/examples/java/io/nats/examples/ConnectTime.java

@@ -0,0 +1,107 @@
+// Copyright 2015-2018 The NATS Authors
+// 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 io.nats.examples;
+
+import java.time.Duration;
+
+import io.nats.client.AuthHandler;
+import io.nats.client.Connection;
+import io.nats.client.Consumer;
+import io.nats.client.ErrorListener;
+import io.nats.client.Nats;
+import io.nats.client.Options;
+
+public class ConnectTime {
+    static final String usageString =
+            "\nUsage: java ConnectTime server\n"
+            + "\nUse tls:// or opentls:// to require tls, via the Default SSLContext\n"
+            + "\nSet the environment variable NATS_NKEY to use challenge response authentication by setting a file containing your private key.\n"
+            + "\nSet the environment variable NATS_CREDS to use JWT/NKey authentication by setting a file containing your user creds.\n"
+            + "\nUse the URL for user/pass/token authentication.\n";
+    
+    public static Options createOptions(String server) throws Exception {
+        Options.Builder builder = new Options.Builder().
+                        server(server).
+                        connectionTimeout(Duration.ofSeconds(5)).
+                        pingInterval(Duration.ofSeconds(10)).
+                        reconnectWait(Duration.ofSeconds(1)).
+                        maxReconnects(-1).
+                        traceConnection();
+
+
+        builder = builder.connectionListener((conn, type) -> System.out.println("Status change "+type));
+
+        builder = builder.errorListener(new ErrorListener() {
+            @Override
+            public void slowConsumerDetected(Connection conn, Consumer consumer) {
+                System.out.println("NATS connection slow consumer detected");
+            }
+
+            @Override
+            public void exceptionOccurred(Connection conn, Exception exp) {
+                System.out.println("NATS connection exception occurred");
+                exp.printStackTrace();
+            }
+
+            @Override
+            public void errorOccurred(Connection conn, String error) {
+                System.out.println("NATS connection error occurred " + error);
+            }
+        });
+
+        if (System.getenv("NATS_NKEY") != null && System.getenv("NATS_NKEY") != "") {
+            AuthHandler handler = new ExampleAuthHandler(System.getenv("NATS_NKEY"));
+            builder.authHandler(handler);
+        } else if (System.getenv("NATS_CREDS") != null && System.getenv("NATS_CREDS") != "") {
+            builder.authHandler(Nats.credentials(System.getenv("NATS_CREDS")));
+        }
+
+        return builder.build();
+    }
+
+    public static void main(String args[]) {
+        String server;
+
+        if (args.length == 1) {
+            server = args[0];
+        } else {
+            usage();
+            return;
+        }
+
+        try {
+            System.out.println();
+            System.out.printf("Timing connect time to %s.\n", server);
+            System.out.println();
+
+            Options options = createOptions(server);
+
+            long start = System.nanoTime();
+            Connection nc = Nats.connect(options);
+            long end = System.nanoTime();
+            double seconds = ((double)(end - start)) / 1_000_000_000.0;
+            System.out.printf("Connect time to %s was %.3f seconds\n", server, seconds);
+
+            nc.close();
+            
+        } catch (Exception exp) {
+            exp.printStackTrace();
+        }
+    }
+
+    static void usage() {
+        System.err.println(usageString);
+        System.exit(-1);
+    }
+}

src/examples/java/io/nats/examples/ExampleUtils.java

@@ -18,6 +18,8 @@
 import io.nats.client.AuthHandler;
 import io.nats.client.Connection;
 import io.nats.client.ConnectionListener;
+import io.nats.client.Consumer;
+import io.nats.client.ErrorListener;
 import io.nats.client.Nats;
 import io.nats.client.Options;
 
@@ -28,6 +30,19 @@ public static Options createExampleOptions(String server, boolean allowReconnect
                         connectionTimeout(Duration.ofSeconds(5)).
                         pingInterval(Duration.ofSeconds(10)).
                         reconnectWait(Duration.ofSeconds(1)).
+                        errorListener(new ErrorListener(){
+                            public void exceptionOccurred(Connection conn, Exception exp) {
+                                System.out.println("Exception " + exp.getMessage());
+                            }
+
+                            public void errorOccurred(Connection conn, String type) {
+                                System.out.println("Error " + type);
+                            }
+                            
+                            public void slowConsumerDetected(Connection conn, Consumer consumer) {
+                                System.out.println("Slow consumer");
+                            }
+                        }).
                         connectionListener(new ConnectionListener(){
                             public void connectionEvent(Connection conn, Events type) {
                                     System.out.println("Status change "+type);

src/main/java/io/nats/client/AuthenticationException.java

@@ -0,0 +1,38 @@
+// Copyright 2018 The NATS Authors
+// 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 io.nats.client;
+
+import java.io.IOException;
+
+/**
+ * AuthenticationException is used when the connect process fails due to an authentication
+ * problem.
+ * 
+ * The exception will not include the authentication tokens, but as a subclass
+ * of IOException allows the client to distinguish an IO problem from an
+ * authentication problem.
+ */
+public class AuthenticationException extends IOException {
+
+    private static final long serialVersionUID = 1L;
+
+    /**
+     * Create a new AuthenticationException.
+     * 
+     * @param errorMessage the error message, see Exception for details
+     */
+    public AuthenticationException(String errorMessage) {
+        super(errorMessage);
+    }
+}