ConnectionFactory
Date: 2016-02-29

de.zib.scalaris

## Class ConnectionFactory

- java.lang.Object
- - de.zib.scalaris.ConnectionFactory

-     public class ConnectionFactory
      extends Object

  Provides means to create connections to scalaris nodes. This class uses a singleton-alike pattern providing a global (static) instance through its `getInstance()` method but also allowing for object construction which might be useful when using multiple threads each creating its own connections. The location of the default configuration file used by `ConnectionFactory()` can be overridden by specifying the `scalaris.java.config` system property - otherwise the class tries to load `scalaris.properties`. A specific property can also be overridden specifying a (non-empty) system property with its name. A user-defined `Properties` object can also be used by creating objects with `ConnectionFactory(Properties)` or setting the new values with `setProperties(Properties)` but must provide the following values (default values as shown)
  - `scalaris.node = "node1@localhost"`
  - `scalaris.cookie = "chocolate chip cookie"`
  - `scalaris.client.name = "java_client"`
  - `scalaris.client.appendUUID = "true"`
  Note: `scalaris.node` can be a whitespace, ',' or ';' separated list of available nodes. See `DefaultConnectionPolicy` about how this list is used when connections are setup or when existing connections fail. Since Java and Erlang both need to known the same node name in order to connect, any "@localhost" in such a name is translated using `fixLocalhostName(String)` to a real node name. The best method of changing this name is to use the name Erlang uses - it can be provided by setting the `scalaris.erlang.nodename` system property. If this is not set or empty, we will try to look-up the name ourselves (see `getLocalhostName()`. The `connectionPolicy` set will be passed on to created connections. Changing it via `setConnectionPolicy(ConnectionPolicy)` will not change previously created connections - they keep the old policy. By default, `DefaultConnectionPolicy` is used.
  Since:
    2.0
  Version:
    3.20
  Author:
    Nico Kruber, kruber@zib.de

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `ConnectionFactory()` Constructor, sets the parameters to use for connections according to values given in a `scalaris.properties` file and falls back to default values if values don't exist.
    `ConnectionFactory(Properties properties)` Constructor, sets the parameters to use for connections according to values given in the given `Properties` object and falls back to default values if values don't exist.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addNode(PeerNode node)` Adds a node to the set of nodes available for connections.
    `void` | `addNode(String node)` Adds a node to the set of nodes available for connections.
    `Connection` | `createConnection()` Creates a connection to a scalaris erlang node specified by the given parameters.
    `Connection` | `createConnection(ConnectionPolicy connectionPolicy)` Creates a connection to a scalaris erlang node specified by the given parameters.
    `Connection` | `createConnection(String clientName)` Creates a connection to a scalaris erlang node specified by the given parameters.
    `Connection` | `createConnection(String clientName, boolean clientNameAppendUUID)` Creates a connection to a scalaris erlang node specified by the given parameters.
    `Connection` | `createConnection(String clientName, boolean clientNameAppendUUID, ConnectionPolicy connectionPolicy)` Creates a connection to a scalaris erlang node specified by the given parameters.
    `static String` | `fixLocalhostName(String node)` Replaces `localhost` in the node's name to the machine's real host name.
    `String` | `getClientName()` Returns the name of the (Java) client to use when establishing a connection with erlang.
    `ConnectionPolicy` | `getConnectionPolicy()` Gets the current connection policy.
    `String` | `getCookie()` Returns the cookie name to use for connections.
    `static ConnectionFactory` | `getInstance()` Returns the static instance of a connection factory.
    `static String` | `getLocalhostName()` Returns the name of the local host as determined by `findLocalhostName()`.
    `String` | `getNode()` Deprecated. This method returns the names of all nodes available for connection as a String (as previously when only one node was used), use the new `getNodes()` method instead.
    `List<PeerNode>` | `getNodes()` Gets a copy of the list of nodes available for connections.
    `boolean` | `isClientNameAppendUUID()` Returns whether an UUID is appended to client names or not.
    `void` | `printProperties()` Prints the object's properties to System.out.
    `void` | `printProperties(PrintStream out)` Prints the object's properties to the given output stream.
    `void` | `removeNode(PeerNode node)` Removes a node from the set of nodes available for connections.
    `void` | `setClientName(String clientName)` Sets the name of the (Java) client to use when establishing a connection with erlang.
    `void` | `setClientNameAppendUUID(boolean clientNameAppendUUID)` Sets whether to append an UUID to client names or not.
    `void` | `setConnectionPolicy(ConnectionPolicy connectionPolicy)` Sets the connection policy to use for new connections.
    `void` | `setCookie(String cookie)` Sets the cookie name to use for connections.
    `void` | `setNode(PeerNode node)` Sets the name of the node to connect to.
    `void` | `setNode(String node)` Sets the name of the node to connect to.
    `void` | `setProperties(Properties properties)` Sets the object's members used for creating connections to erlang to values provided by the given `Properties` object.
    `void` | `testAllNodes()` (Re-)evaluates all currently set nodes by trying to establish a connection to each of them.

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

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

- - ### Constructor Detail

    - #### ConnectionFactory

          public ConnectionFactory()

      Constructor, sets the parameters to use for connections according to values given in a `scalaris.properties` file and falls back to default values if values don't exist. By default the config file is assumed to be in the same directory as the classes. Specify the `scalaris.java.config` system property to set a different location. Default values are:
      - `scalaris.node = "node1@localhost"`
      - `scalaris.cookie = "chocolate chip cookie"`
      - `scalaris.client.name = "java_client"`
      - `scalaris.client.appendUUID = "true"`
      These properties can be overridden by specifying (non-empty) system properties with their names.

    - #### ConnectionFactory

          public ConnectionFactory(Properties properties)

      Constructor, sets the parameters to use for connections according to values given in the given `Properties` object and falls back to default values if values don't exist. The `Properties` object should provide the following values (default values as shown):
      - `scalaris.node = "node1@localhost"`
      - `scalaris.cookie = "chocolate chip cookie"`
      - `scalaris.client.name = "java_client"`
      - `scalaris.client.appendUUID = "true"`
      Parameters:
        `properties` -

  - ### Method Detail

    - #### getInstance

          public static ConnectionFactory getInstance()

      Returns the static instance of a connection factory.
      Returns:
        a connection factory

    - #### setProperties

          public void setProperties(Properties properties)

      Sets the object's members used for creating connections to erlang to values provided by the given `Properties` object. The `Properties` object should provide the following values (default values as shown):
      - `scalaris.node = "node1@localhost"`
      - `scalaris.cookie = "chocolate chip cookie"`
      - `scalaris.client.name = "java_client"`
      - `scalaris.client.appendUUID = "true"`
      NOTE: Existing connections are not changed!
      Parameters:
        `properties` - the object to get the connection parameters from

    - #### createConnection

          public Connection createConnection(String clientName,
                                    boolean clientNameAppendUUID,
                                    ConnectionPolicy connectionPolicy)
                                      throws ConnectionException

      Creates a connection to a scalaris erlang node specified by the given parameters. Uses the given client name. If `clientNameAppendUUID` is specified a pseudo UUID is appended to the given name. BEWARE that scalaris nodes accept only one connection per client name!
      Parameters:
        `clientName` - the name that identifies the java client
        `clientNameAppendUUID` - override the object's setting for `clientNameAppendUUID`
        `connectionPolicy` - override the connection policy that will be used for the new connection
      Returns:
        the created connection
      Throws:
        `ConnectionException` - if the connection fails
      Since:
        2.3

    - #### createConnection

          public Connection createConnection(String clientName,
                                    boolean clientNameAppendUUID)
                                      throws ConnectionException

      Creates a connection to a scalaris erlang node specified by the given parameters. Uses the given client name. If `clientNameAppendUUID` is specified a pseudo UUID is appended to the given name. BEWARE that scalaris nodes accept only one connection per client name!
      Parameters:
        `clientName` - the name that identifies the java client
        `clientNameAppendUUID` - override the object's setting for `clientNameAppendUUID`
      Returns:
        the created connection
      Throws:
        `ConnectionException` - if the connection fails

    - #### createConnection

          public Connection createConnection(String clientName)
                                      throws ConnectionException

      Creates a connection to a scalaris erlang node specified by the given parameters. Uses the given client name. If `clientNameAppendUUID` has been set, a pseudo UUID is appended to the given name. BEWARE that scalaris nodes accept only one connection per client name!
      Parameters:
        `clientName` - the name that identifies the java client
      Returns:
        the created connection
      Throws:
        `ConnectionException` - if the connection fails

    - #### createConnection

          public Connection createConnection(ConnectionPolicy connectionPolicy)
                                      throws ConnectionException

      Creates a connection to a scalaris erlang node specified by the given parameters. Uses the given connection policy. If `clientNameAppendUUID` has been set, a pseudo UUID is appended to the given name. BEWARE that scalaris nodes accept only one connection per client name!
      Parameters:
        `connectionPolicy` - override the connection policy that will be used for the new connection
      Returns:
        the created connection
      Throws:
        `ConnectionException` - if the connection fails
      Since:
        3.10

    - #### createConnection

          public Connection createConnection()
                                      throws ConnectionException

      Creates a connection to a scalaris erlang node specified by the given parameters.
      Returns:
        the created connection
      Throws:
        `ConnectionException` - if the connection fails

    - #### fixLocalhostName

          public static String fixLocalhostName(String node)

      Replaces `localhost` in the node's name to the machine's real host name. Due to a "feature" of OtpErlang >= 1.4.1 erlang nodes are now only reachable by their official host name - so `...@localhost` does not work anymore if there is a real host name.
      Parameters:
        `node` - the name of the node to use
      Returns:
        the node's official host name as returned by `InetAddress.getHostName()`

    - #### getLocalhostName

          public static final String getLocalhostName()

      Returns the name of the local host as determined by `findLocalhostName()`.
      Returns:
        the local host' name or `localhost` if no IP address was found

    - #### printProperties

          public void printProperties()

      Prints the object's properties to System.out.

    - #### printProperties

          public void printProperties(PrintStream out)

      Prints the object's properties to the given output stream.
      Parameters:
        `out` - the output stream to write to

    - #### getNodes

          public List<PeerNode> getNodes()

      Gets a copy of the list of nodes available for connections. The `PeerNode` elements of the list will not be copied!
      Returns:
        a set of nodes
      Since:
        2.3

    - #### getNode

          @Deprecated
          public String getNode()

      Deprecated. This method returns the names of all nodes available for connection as a String (as previously when only one node was used), use the new `getNodes()` method instead.
      Returns the name of the first node available for connection. WARNING: If `nodes` contains multiple nodes, only the first of them will be returned. This is not necessarily the one the class will set up connections with!
      Returns:
        the name of the first node or an empty string if the list is empty

    - #### setNode

          public void setNode(String node)

      Sets the name of the node to connect to. The list of nodes available for connection will be cleared at first, the node will then be added.
      Parameters:
        `node` - the node to set (will not be mangled by `fixLocalhostName(String)`!)
      See Also:
        `addNode(String)`

    - #### setNode

          public void setNode(PeerNode node)

      Sets the name of the node to connect to. The list of nodes available for connection will be cleared at first, the node will then be added.
      Parameters:
        `node` - the node to set (will not be mangled by `fixLocalhostName(String)`!)
      Since:
        3.16
      See Also:
        `addNode(PeerNode)`

    - #### addNode

          public void addNode(String node)

      Adds a node to the set of nodes available for connections.
      Parameters:
        `node` - the node to add (will not be mangled by `fixLocalhostName(String)`!)
      Since:
        2.3
      See Also:
        `setNode(String)`

    - #### addNode

          public void addNode(PeerNode node)

      Adds a node to the set of nodes available for connections.
      Parameters:
        `node` - the node to add
      Since:
        3.16
      See Also:
        `setNode(String)`

    - #### removeNode

          public void removeNode(PeerNode node)

      Removes a node from the set of nodes available for connections.
      Parameters:
        `node` - the node to remove
      Since:
        2.3
      See Also:
        `getNodes()`

    - #### testAllNodes

          public void testAllNodes()

      (Re-)evaluates all currently set nodes by trying to establish a connection to each of them. Note: This resets all `PeerNode` statistics collected before.
      Since:
        3.20

    - #### getCookie

          public String getCookie()

      Returns the cookie name to use for connections.
      Returns:
        the cookie

    - #### setCookie

          public void setCookie(String cookie)

      Sets the cookie name to use for connections.
      Parameters:
        `cookie` - the cookie to set

    - #### getClientName

          public String getClientName()

      Returns the name of the (Java) client to use when establishing a connection with erlang.
      Returns:
        the clientName

    - #### setClientName

          public void setClientName(String clientName)

      Sets the name of the (Java) client to use when establishing a connection with erlang.
      Parameters:
        `clientName` - the clientName to set

    - #### isClientNameAppendUUID

          public boolean isClientNameAppendUUID()

      Returns whether an UUID is appended to client names or not.
      Returns:
        `true` if an UUID is appended, `false` otherwise

    - #### setClientNameAppendUUID

          public void setClientNameAppendUUID(boolean clientNameAppendUUID)

      Sets whether to append an UUID to client names or not.
      Parameters:
        `clientNameAppendUUID` - `true` if an UUID is appended, `false` otherwise

    - #### setConnectionPolicy

          public void setConnectionPolicy(ConnectionPolicy connectionPolicy)

      Sets the connection policy to use for new connections. Warning: this will effectively disconnect the previous connection policy from any updates to the list of available nodes (they will still use the same list but will not be able to react on changes). Prefer not to change the default policy after connections have been created.
      Parameters:
        `connectionPolicy` - the connection policy to set
      Since:
        2.3

    - #### getConnectionPolicy

          public ConnectionPolicy getConnectionPolicy()

      Gets the current connection policy.
      Returns:
        the currently used connection policy
      Since:
        2.3