Server Pool Update

server-pool/README.md

@@ -1,12 +1,17 @@
 ![NATS](../images/large-logo.png)
 
-# Server List Provider
+# Example Server Pool
 
-Example how the developer can provide the connection/reconnection info themselves / dynamically.
+This example is a template example for implementing a server pool.
 
-__TODO: FIX!!!__
+The ExampleServerPool class extends the internal implementation, NatsServerPool.
 
-CURRENTLY NON-FUNCTIONAL AGAINST LATEST VERSION AS INITIAL IMPLEMENTATION WAS EXPERIMENTAL
+There are comments in the example code to explain the intention of each method in the interface and custom methods in the implementation.
+
+## Source Code
+[ServerPool](https://github.com/nats-io/nats.java/blob/main/src/main/java/io/nats/client/ServerPool.java) interface.
+
+[NatsServerPool](https://github.com/nats-io/nats.java/blob/main/src/main/java/io/nats/client/impl/NatsServerPool.java) implementation.
 
 ## License
 

server-pool/gradle/wrapper/gradle-wrapper.properties

@@ -3,3 +3,4 @@ distributionPath=wrapper/dists
 distributionUrl=https\://services.gradle.org/distributions/gradle-6.3-bin.zip
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
+

server-pool/gradlew

@@ -1,5 +1,4 @@
 #!/usr/bin/env sh
-
 #
 # Copyright 2015 the original author or authors.
 #

server-pool/gradlew.bat

@@ -15,11 +15,11 @@
 @rem
 
 @if "%DEBUG%" == "" @echo off
-@rem ##########################################################################
+@rem #########################################################################
 @rem
 @rem  Gradle startup script for Windows
 @rem
-@rem ##########################################################################
+@rem #########################################################################
 
 @rem Set local scope for the variables with windows NT shell
 if "%OS%"=="Windows_NT" setlocal

server-pool/src/main/java/io/nats/slp/ExampleServerPool.java

@@ -0,0 +1,94 @@
+package io.nats.slp;
+
+import io.nats.client.Options;
+import io.nats.client.impl.NatsServerPool;
+import io.nats.client.support.NatsUri;
+
+import java.util.List;
+
+// By extending NatsServerPool you get a jump start on
+// the implementation for ServerPool
+class ExampleServerPool extends NatsServerPool {
+
+    @Override
+    public void initialize(Options opts) {
+        // here is the opportunity to inspect any Options
+        // you are already using in your connection
+        super.initialize(opts);
+    }
+
+    @Override
+    public boolean acceptDiscoveredUrls(List<String> discoveredServers) {
+        // Whenever the client receives ServerInfo from the server
+        // it provides a list of available servers to the pool
+        // -----
+        // If you are implementing custom behavior, for instance
+        // you already know about all the servers you want,
+        // so you might not care about these.
+        return super.acceptDiscoveredUrls(discoveredServers);
+    }
+
+    @Override
+    protected void afterListChanged() {
+        // This method is part of NatsServerPool, not the ServerPool interface
+        // This is called in NatsServerPool at the end of the initialize() method
+        // and at the end of the acceptDiscoveredUrls() method
+        super.afterListChanged();
+    }
+
+    @Override
+    public NatsUri peekNextServer() {
+        // this allows the connection handle to peek at the next server
+        // you will give it via the nextServer() method
+        return super.peekNextServer();
+    }
+
+    @Override
+    public NatsUri nextServer() {
+        // give the connection the next server to try to connect to
+        // from your pool
+        return super.nextServer();
+    }
+
+    @Override
+    public List<String> resolveHostToIps(String host) {
+        // the connection will try to resolve hosts to ip addresses
+        // if Options.isNoResolveHostnames is not set (default is to resolve)
+        return super.resolveHostToIps(host);
+    }
+
+    @Override
+    public void connectSucceeded(NatsUri nuri) {
+        // The connection lets you know if it was able to
+        // connect to the nextServer() you gave it
+        super.connectSucceeded(nuri);
+    }
+
+    @Override
+    public void connectFailed(NatsUri nuri) {
+        // The connection lets you know if it could not
+        // connect to the nextServer() you gave it
+        super.connectFailed(nuri);
+    }
+
+    @Override
+    public List<String> getServerList() {
+        // This method is not used by the connection other than to pass on
+        // information to the user
+        return super.getServerList();
+    }
+
+    @Override
+    public boolean hasSecureServer() {
+        // This asks your pool if any of your connection are secure
+        // so it knows whether to upgrade the connection
+        return super.hasSecureServer();
+    }
+
+    @Override
+    protected int findEquivalent(List<NatsUri> list, NatsUri toFind) {
+        // This method is part of NatsServerPool, not the ServerPool interface
+        // It's used to keep its own server list unique
+        return super.findEquivalent(list, toFind);
+    }
+}

server-pool/src/main/java/io/nats/slp/Main.java

@@ -0,0 +1,25 @@
+package io.nats.slp;
+
+import io.nats.client.Connection;
+import io.nats.client.Nats;
+import io.nats.client.Options;
+
+public class Main {
+    static String[] BOOTSTRAP = new String[] {"nats://host1:4222","nats://host2:4222","nats://host3:4222"};
+
+    public static void main(String[] args) {
+        // provide a custom implementation of the ServerPool
+        // There also is a property for a no-op constructor ServerPool instance: servers_pool_implementation_class
+        Options options = new Options.Builder()
+            .servers(BOOTSTRAP)
+            .serverPool(new ExampleServerPool())
+            .build();
+
+        try (Connection nc = Nats.connect(options)) {
+            // During connects or reconnects, the server pool implementation is called
+        }
+        catch (Exception e) {
+            e.printStackTrace();
+        }
+    }
+}