DefaultConnectionPolicy
Date: 2016-02-29

de.zib.scalaris

## Class DefaultConnectionPolicy

- java.lang.Object
- - de.zib.scalaris.ConnectionPolicy
  - - de.zib.scalaris.DefaultConnectionPolicy

- Direct Known Subclasses:
    RoundRobinConnectionPolicy

      public class DefaultConnectionPolicy
      extends ConnectionPolicy

  Implements a `ConnectionPolicy` by choosing nodes randomly. Sorts nodes into two lists:
  - good nodes
  - bad nodes
  Nodes that failed during a connection or in an attempt to connect will be transferred to the bad nodes list `badNodes`. When a connection attempt to a node is successful, it will be removed from this list and put into the good nodes list `goodNodes` and the node's connection failure statistics will be reset using `PeerNode.resetFailureCount()`. Whenever a node is being selected for a new connection (or reconnect), it will select one randomly from the `goodNodes` list. If this list is empty, it will select the least recently failed node from `badNodes`. At most `maxRetries` retries are attempted per operation (see `Connection.connect()`, `Connection.doRPC(String, String, com.ericsson.otp.erlang.OtpErlangList)` and `Connection.doRPC(String, String, com.ericsson.otp.erlang.OtpErlangObject[])` ) - the number of the current attempt will not be cached in this class. Set the maximal number of retries using `setMaxRetries(int)`. Attention: All member's functions are synchronised as there can be a single connection policy object used by many threads and the access to the `goodNodes` and `badNodes` members are logically linked together and operations on both need to be performed atomically. Additionally access to `PeerNode` objects are synchronised on themselves. It is therefore important not to use any of this classes methods in blocks that synchronise on any node object. Otherwise deadlocks might occur!!
  Since:
    2.3
  Version:
    2.3
  Author:
    Nico Kruber, kruber@zib.de

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `DefaultConnectionPolicy(List<PeerNode> availableRemoteNodes)` Creates a new connection policy with the given remote nodes.
    `DefaultConnectionPolicy(PeerNode remoteNode)` Creates a new connection policy working with the given remote node.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `availableNodeAdded(PeerNode newNode)` Adds the given node to the `goodNodes` list if it has no failures, otherwise it will be added to `badNodes`.
    `void` | `availableNodeRemoved(PeerNode removedNode)` Removes the node from the `goodNodes` and `badNodes` lists.
    `void` | `availableNodesReset()` Resets the `goodNodes` and `badNodes` members as the list of available nodes has been reset.
    `List<PeerNode>` | `getBadNodes()` Gets a copy of the list of good nodes (contains references to the `PeerNode` objects).
    `List<PeerNode>` | `getGoodNodes()` Gets a copy of the list of good nodes (contains references to the `PeerNode` objects).
    `int` | `getMaxRetries()` Sets the maximal number of automatic connection retries.
    `void` | `nodeConnectSuccess(PeerNode node)` Sets the node's last successful connect time stamp, resets its failure statistics and moves it to the `goodNodes` list.
    `void` | `nodeFailed(PeerNode node)` Sets the given node's last failed connect time stamp and moves it to the `badNodes` list.
    `void` | `nodeFailReset(PeerNode node)` Acts upon a failure reset of the given node.
    `<E extends Exception> PeerNode` | `selectNode(int retry, PeerNode failedNode, E e)` Selects the node to (re-)connect with until the maximal number of `maxRetries` has been reached.
    `void` | `setMaxRetries(int maxRetries)` Gets the maximal number of automatic connection retries.

    - ### Methods inherited from class de.zib.scalaris.ConnectionPolicy

      `selectNode`

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### DefaultConnectionPolicy

          public DefaultConnectionPolicy(PeerNode remoteNode)

      Creates a new connection policy working with the given remote node. Provided for convenience. Attention: This method also synchronises on the node.
      Parameters:
        `remoteNode` - the (only) available remote node

    - #### DefaultConnectionPolicy

          public DefaultConnectionPolicy(List<PeerNode> availableRemoteNodes)

      Creates a new connection policy with the given remote nodes. Attention: This method synchronises on `availableRemoteNodes`. Any time this list is changed, the according methods in this class should be called, i.e. `availableNodeAdded(PeerNode)`, `availableNodeRemoved(PeerNode)`, `availableNodesReset()` to update the good and bad nodes lists.
      Parameters:
        `availableRemoteNodes` - the remote nodes available for connections

  - ### Method Detail

    - #### availableNodeAdded

          public void availableNodeAdded(PeerNode newNode)

      Adds the given node to the `goodNodes` list if it has no failures, otherwise it will be added to `badNodes`. Attention: This method also synchronises on the node.
      Overrides:
        `availableNodeAdded` in class `ConnectionPolicy`
      Parameters:
        `newNode` - the new node

    - #### availableNodeRemoved

          public void availableNodeRemoved(PeerNode removedNode)

      Removes the node from the `goodNodes` and `badNodes` lists.
      Overrides:
        `availableNodeRemoved` in class `ConnectionPolicy`
      Parameters:
        `removedNode` - the removed node

    - #### availableNodesReset

          public void availableNodesReset()

      Resets the `goodNodes` and `badNodes` members as the list of available nodes has been reset.
      Overrides:
        `availableNodesReset` in class `ConnectionPolicy`

    - #### nodeFailed

          public void nodeFailed(PeerNode node)

      Sets the given node's last failed connect time stamp and moves it to the `badNodes` list. Attention: This method also synchronises on the node.
      Overrides:
        `nodeFailed` in class `ConnectionPolicy`
      Parameters:
        `node` - the failed node

    - #### nodeFailReset

          public void nodeFailReset(PeerNode node)

      Acts upon a failure reset of the given node. Resets the node's last failure state.
      Overrides:
        `nodeFailReset` in class `ConnectionPolicy`
      Parameters:
        `node` - the node

    - #### nodeConnectSuccess

          public void nodeConnectSuccess(PeerNode node)

      Sets the node's last successful connect time stamp, resets its failure statistics and moves it to the `goodNodes` list. Attention: This method also synchronises on the node.
      Overrides:
        `nodeConnectSuccess` in class `ConnectionPolicy`
      Parameters:
        `node` - the node

    - #### selectNode

          public <E extends Exception> PeerNode selectNode(int retry,
                                                  PeerNode failedNode,
                                                  E e)
                              throws E extends Exception

      Selects the node to (re-)connect with until the maximal number of `maxRetries` has been reached. Throws an exception if `retry > maxRetries` and thus stops further node connection attempts. Otherwise chooses a random good node or (if there are no good nodes) the least recently failed bad node.
      Specified by:
        `selectNode` in class `ConnectionPolicy`
      Type Parameters:
        `E` - the type of the exception that came from the failed connection and may be re-thrown
      Parameters:
        `retry` - the n'th retry (initial connect = 0, 1st reconnect = 1,...)
        `failedNode` - the node from the previous connection attempt or `null`
        `e` - the exception that came back from the previous connection attempt or `null`
      Returns:
        the new node to connect with
      Throws:
        `E` - if thrown, automatic re-connection attempts will stop
        `UnsupportedOperationException` - is thrown if the operation can not be performed, e.g. the list is empty
        `E extends Exception`
      See Also:
        `Connection.connect()`, `Connection.doRPC(String, String, com.ericsson.otp.erlang.OtpErlangList)`, `Connection.doRPC(String, String, com.ericsson.otp.erlang.OtpErlangObject[])`

    - #### getMaxRetries

          public int getMaxRetries()

      Sets the maximal number of automatic connection retries.
      Returns:
        the maxRetries

    - #### setMaxRetries

          public void setMaxRetries(int maxRetries)

      Gets the maximal number of automatic connection retries.
      Parameters:
        `maxRetries` - the maxRetries to set (>= 0)

    - #### getGoodNodes

          public List<PeerNode> getGoodNodes()

      Gets a copy of the list of good nodes (contains references to the `PeerNode` objects).
      Returns:
        the list of good nodes

    - #### getBadNodes

          public List<PeerNode> getBadNodes()

      Gets a copy of the list of good nodes (contains references to the `PeerNode` objects).
      Returns:
        the list of good nodes