Apply connection timeout for each connect attempt

Relax a socket provider contract. Now socket provider can throw a
transient error and the client will try to obtain a socket again instead
of being closed.

Make built-in socket providers configurable. Now the client can set
retries count and connection timeout for providers.

Update README doc im scope of new socket provider contract.

Closes: #167
Follows on: #144

Author: nicktorwald

Diff for: README.md

@@ -22,7 +22,7 @@ To get the Java connector for Tarantool 1.6.9, visit
 
 ## Getting started
 
-1. Add a dependency to your `pom.xml` file.
+1. Add a dependency to your `pom.xml` file:
 
 ```xml
 <dependency>
@@ -32,75 +32,81 @@ To get the Java connector for Tarantool 1.6.9, visit
 </dependency>
 ```
 
-2. Configure `TarantoolClientConfig`.
+2. Configure `TarantoolClientConfig`:
 
 ```java
 TarantoolClientConfig config = new TarantoolClientConfig();
 config.username = "test";
 config.password = "test";
 ```
 
-3. Implement your `SocketChannelProvider`.
-   It should return a connected `SocketChannel`.
+3. Create a client:
 
 ```java
-SocketChannelProvider socketChannelProvider = new SocketChannelProvider() {
-           @Override
-           public SocketChannel get(int retryNumber, Throwable lastError) {
-               if (lastError != null) {
-                   lastError.printStackTrace(System.out);
-               }
-               try {
-                   return SocketChannel.open(new InetSocketAddress("localhost", 3301));
-               } catch (IOException e) {
-                   throw new IllegalStateException(e);
-               }
-           }
-       };
+TarantoolClient client = new TarantoolClientImpl("host:3301", config);
+```
+
+using `TarantoolClientImpl(String, TarantoolClientConfig)` is equivalent to:
+
+```java
+SocketChannelProvider socketChannelProvider = new SingleSocketChannelProviderImpl("host:3301")
+TarantoolClient client = new TarantoolClientImpl(socketChannelProvider, config);
 ```
 
-Here you could also implement some reconnection or fallback policy.
-Remember that `TarantoolClient` adopts a
-[fail-fast](https://en.wikipedia.org/wiki/Fail-fast) policy
-when a client is not connected.
+You could implement your own `SocketChannelProvider`. It should return 
+a connected `SocketChannel`. Feel free to implement `get(int retryNumber, Throwable lastError)`
+using your appropriate strategy to obtain the channel. The strategy can take into
+account current attempt number (retryNumber) and the last transient error occurred on
+the previous attempt.
 
-The `TarantoolClient` will stop functioning if your implementation of a socket
-channel provider raises an exception or returns a null. You will need a new
-instance of client to recover. Hence, you should only throw in case you have
-met unrecoverable error.
+The `TarantoolClient` will be closed if your implementation of a socket
+channel provider raises any exceptions but not a `SocketProviderTransientException`.
+Latter is handled by the client as a recoverable error. Otherwise, you will
+need a new instance of client to recover. Hence, you should only throw an
+error different to `SocketProviderTransientException` in case you have met
+unrecoverable error.
 
-Below is an example of `SocketChannelProvider` implementation that handles short
-tarantool restarts.
+Below is an example of `SocketChannelProvider` implementation that tries
+to connect no more than 3 times, two seconds for each attempt at max.
 
 ```java
 SocketChannelProvider socketChannelProvider = new SocketChannelProvider() {
     @Override
     public SocketChannel get(int retryNumber, Throwable lastError) {
-        long deadline = System.currentTimeMillis() + RESTART_TIMEOUT;
-        while (!Thread.currentThread().isInterrupted()) {
-            try {
-                return SocketChannel.open(new InetSocketAddress("localhost", 3301));
-            } catch (IOException e) {
-                if (deadline < System.currentTimeMillis())
-                    throw new RuntimeException(e);
-                try {
-                    Thread.sleep(100);
-                } catch (InterruptedException ignored) {
-                    Thread.currentThread().interrupt();
-                }
+        if (retryNumber > 3) {
+            throw new RuntimeException("Too many attempts");
+        }
+        SocketChannel channel = null;
+        try {
+            channel = SocketChannel.open();
+            channel.socket().connect(new InetSocketAddress("localhost", 3301), 2000);
+            return channel;
+        } catch (IOException e) {
+            if (channel != null) {
+                 try {
+                     channel.close();
+                 } catch (IOException ignored) { }
             }
+            throw new SocketProviderTransientException("Couldn't connect to server", e);
         }
-        throw new RuntimeException(new TimeoutException("Connect timed out."));
     }
 };
 ```
 
-4. Create a client.
+Same behaviour can be achieved using built-in `SingleSocketChannelProviderImpl`:
 
 ```java
+TarantoolClientConfig config = new TarantoolClientConfig();
+config.connectionTimeout = 2_000; // two seconds timeout per attempt
+config.retryCount = 3;            // three attempts at max
+
+SocketChannelProvider socketChannelProvider = new SingleSocketChannelProviderImpl("localhost:3301")
 TarantoolClient client = new TarantoolClientImpl(socketChannelProvider, config);
 ```
 
+`SingleSocketChannelProviderImpl` implements `ConfigurableSocketChannelProvider` that
+makes possible for the client to configure a socket provider.
+
 > **Notes:**
 > * `TarantoolClient` is thread-safe and asynchronous, so you should use one
 >   client inside the whole application.
@@ -198,7 +204,7 @@ client.syncOps().insert(23, Arrays.asList(1, 1));
 Auto-discovery feature allows a cluster client to fetch addresses of 
 cluster nodes to reflect changes related to the cluster topology. To achieve
 this you have to create a Lua function on the server side which returns 
-a single array result. Client periodically pools the server to obtain a 
+a single array result. Client periodically polls the server to obtain a 
 fresh list and apply it if its content changes.
 
 1. On the server side create a function which returns nodes:

Diff for: src/main/java/org/tarantool/BaseSocketChannelProvider.java

@@ -4,7 +4,7 @@
 import java.net.InetSocketAddress;
 import java.nio.channels.SocketChannel;
 
-public abstract class BaseSocketChannelProvider implements SocketChannelProvider {
+public abstract class BaseSocketChannelProvider implements ConfigurableSocketChannelProvider {
 
     /**
      * Limit of retries.
@@ -14,46 +14,30 @@ public abstract class BaseSocketChannelProvider implements SocketChannelProvider
     /**
      * Timeout to establish socket connection with an individual server.
      */
-    private int timeout = NO_TIMEOUT;
+    private int connectionTimeout = NO_TIMEOUT;
 
     /**
      * Tries to establish a new connection to the Tarantool instances.
      *
-     * @param retryNumber number of current retry. Reset after successful connect.
+     * @param retryNumber number of current retry
      * @param lastError   the last error occurs when reconnecting
      *
      * @return connected socket channel
      *
-     * @throws CommunicationException if any I/O errors happen or there are
-     *                                no addresses available
+     * @throws CommunicationException           if number of retries or socket timeout are exceeded
+     * @throws SocketProviderTransientException if any I/O errors happen
      */
     @Override
     public final SocketChannel get(int retryNumber, Throwable lastError) {
         if (areRetriesExhausted(retryNumber)) {
             throw new CommunicationException("Connection retries exceeded.", lastError);
         }
 
-        long deadline = System.currentTimeMillis() + timeout;
-        while (!Thread.currentThread().isInterrupted()) {
-            try {
-                InetSocketAddress address = getAddress(retryNumber, lastError);
-                return openChannel(address);
-            } catch (IOException e) {
-                checkTimeout(deadline, e);
-            }
-        }
-        throw new CommunicationException("Thread interrupted.", new InterruptedException());
-    }
-
-    private void checkTimeout(long deadline, Exception e) {
-        long timeLeft = deadline - System.currentTimeMillis();
-        if (timeLeft <= 0) {
-            throw new CommunicationException("Connection time out.", e);
-        }
         try {
-            Thread.sleep(timeLeft / 10);
-        } catch (InterruptedException ignored) {
-            Thread.currentThread().interrupt();
+            InetSocketAddress address = getAddress(retryNumber, lastError);
+            return openChannel(address);
+        } catch (IOException e) {
+            throw new SocketProviderTransientException("Couldn't connect to the server", e);
         }
     }
 
@@ -79,6 +63,7 @@ private void checkTimeout(long deadline, Exception e) {
      *
      * @param retriesLimit Limit of retries to use.
      */
+    @Override
     public void setRetriesLimit(int retriesLimit) {
         this.retriesLimit = retriesLimit;
     }
@@ -111,7 +96,7 @@ protected SocketChannel openChannel(InetSocketAddress socketAddress) throws IOEx
         SocketChannel channel = null;
         try {
             channel = SocketChannel.open();
-            channel.socket().connect(socketAddress, timeout);
+            channel.socket().connect(socketAddress, connectionTimeout);
             return channel;
         } catch (IOException e) {
             if (channel != null) {
@@ -126,36 +111,37 @@ protected SocketChannel openChannel(InetSocketAddress socketAddress) throws IOEx
     }
 
     /**
-     * Sets maximum amount of time to wait for a socket connection establishment
-     * with an individual server.
-     * <p>
-     * Zero means infinite timeout.
-     *
-     * @param timeout timeout value, ms.
+     * Gets maximum amount of time to wait for a socket
+     * connection establishment with an individual server.
      *
-     * @throws IllegalArgumentException if timeout is negative.
+     * @return timeout
      */
-    public void setTimeout(int timeout) {
-        if (timeout < 0) {
-            throw new IllegalArgumentException("timeout is negative.");
-        }
-        this.timeout = timeout;
+    public int getConnectionTimeout() {
+        return connectionTimeout;
     }
 
     /**
-     * Gest maximum amount of time to wait for a socket
-     * connection establishment with an individual server.
+     * Sets maximum amount of time to wait for a socket connection establishment
+     * with an individual server.
+     * <p>
+     * Zero means infinite connectionTimeout.
      *
-     * @return timeout
+     * @param connectionTimeout connectionTimeout value, ms.
+     *
+     * @throws IllegalArgumentException if connectionTimeout is negative.
      */
-    public int getTimeout() {
-        return timeout;
+    @Override
+    public void setConnectionTimeout(int connectionTimeout) {
+        if (connectionTimeout < 0) {
+            throw new IllegalArgumentException("connectionTimeout is negative.");
+        }
+        this.connectionTimeout = connectionTimeout;
     }
 
     /**
      * Provides a decision on whether retries limit is hit.
      *
-     * @param retries Current count of retries.
+     * @param retries current count of retries.
      *
      * @return {@code true} if retries are exhausted.
      */
@@ -166,4 +152,5 @@ private boolean areRetriesExhausted(int retries) {
         }
         return retries >= limit;
     }
+
 }

Diff for: src/main/java/org/tarantool/ConfigurableSocketChannelProvider.java

@@ -0,0 +1,23 @@
+package org.tarantool;
+
+public interface ConfigurableSocketChannelProvider extends SocketChannelProvider {
+
+    int RETRY_NO_LIMIT = -1;
+    int NO_TIMEOUT = 0;
+
+    /**
+     * Configures max count of retries.
+     *
+     * @param limit max attempts count
+     */
+    void setRetriesLimit(int limit);
+
+    /**
+     * Configures max time to establish
+     * a connection per attempt.
+     *
+     * @param timeout connection timeout in millis
+     */
+    void setConnectionTimeout(int timeout);
+
+}

Diff for: src/main/java/org/tarantool/SocketChannelProvider.java

@@ -1,18 +1,22 @@
 package org.tarantool;
 
+import java.net.SocketAddress;
 import java.nio.channels.SocketChannel;
 
 public interface SocketChannelProvider {
 
-    int RETRY_NO_LIMIT = -1;
-    int NO_TIMEOUT = 0;
-
     /**
      * Provides socket channel to init restore connection.
-     * You could change hosts on fail and sleep between retries in this method
-     * @param retryNumber number of current retry. Reset after successful connect.
+     * You could change hosts between retries in this method.
+     *
+     * @param retryNumber number of current retry.
      * @param lastError   the last error occurs when reconnecting
-     * @return the result of SocketChannel open(SocketAddress remote) call
+     *
+     * @return the result of {@link SocketChannel#open(SocketAddress)} call
+     *
+     * @throws SocketProviderTransientException if recoverable error occurred
+     * @throws RuntimeException                 if any other reasons occurred
      */
     SocketChannel get(int retryNumber, Throwable lastError);
+
 }

Diff for: src/main/java/org/tarantool/SocketProviderTransientException.java

@@ -0,0 +1,9 @@
+package org.tarantool;
+
+public class SocketProviderTransientException extends RuntimeException {
+
+    public SocketProviderTransientException(String message, Throwable cause) {
+        super(message, cause);
+    }
+
+}

Diff for: src/main/java/org/tarantool/TarantoolClientConfig.java

@@ -36,16 +36,35 @@ public class TarantoolClientConfig {
      */
     public double directWriteFactor = 0.5d;
 
+    /**
+     * Write operation timeout.
+     */
+    public long writeTimeoutMillis = 60 * 1000L;
+
     /**
      * Use old call command https://github.com/tarantool/doc/issues/54,
      * please ensure that you server supports new call command.
      */
     public boolean useNewCall = false;
 
     /**
-     * Limits for synchronous operations.
+     *  Max time to establish connection to the server
+     *  and be completely configured (to have an {@code ALIVE} status).
+     *
+     * @see TarantoolClient#isAlive()
      */
     public long initTimeoutMillis = 60 * 1000L;
-    public long writeTimeoutMillis = 60 * 1000L;
+
+    /**
+     * Connection timeout per attempt.
+     * {@code 0} means no timeout.
+     */
+    public int connectionTimeout = 2 * 1000;
+
+    /**
+     * Total attempts number to connect to DB.
+     * {@code -1} means unlimited attempts.
+     */
+    public int retryCount = 3;
 
 }