de.zib.scalaris
Class ConnectionFactory

java.lang.Object
  extended by 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)

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
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
 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: 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):

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): 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