Package de.zib.scalaris

Class ConnectionFactory

java.lang.Object

de.zib.scalaris.ConnectionFactory

public class ConnectionFactory
extends java.lang.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	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(java.util.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

Modifier and Type	Method	Description
void	addNode(PeerNode node)	Adds a node to the set of nodes available for connections.
void	addNode(java.lang.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(java.lang.String clientName)	Creates a connection to a scalaris erlang node specified by the given parameters.
Connection	createConnection(java.lang.String clientName, boolean clientNameAppendUUID)	Creates a connection to a scalaris erlang node specified by the given parameters.
Connection	createConnection(java.lang.String clientName, boolean clientNameAppendUUID, ConnectionPolicy connectionPolicy)	Creates a connection to a scalaris erlang node specified by the given parameters.
static java.lang.String	fixLocalhostName(java.lang.String node)	Replaces localhost in the node's name to the machine's real host name.
java.lang.String	getClientName()	Returns the name of the (Java) client to use when establishing a connection with erlang.
ConnectionPolicy	getConnectionPolicy()	Gets the current connection policy.
java.lang.String	getCookie()	Returns the cookie name to use for connections.
static ConnectionFactory	getInstance()	Returns the static instance of a connection factory.
static java.lang.String	getLocalhostName()	Returns the name of the local host as determined by findLocalhostName().
java.lang.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.
java.util.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(java.io.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(java.lang.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(java.lang.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(java.lang.String node)	Sets the name of the node to connect to.
void	setProperties(java.util.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(java.util.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(java.util.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(java.lang.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(java.lang.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(java.lang.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 java.lang.String fixLocalhostName(java.lang.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 java.lang.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(java.io.PrintStream out)

Prints the object's properties to the given output stream.

Parameters:

out - the output stream to write to

getNodes

public java.util.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 java.lang.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(java.lang.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(java.lang.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 java.lang.String getCookie()

Returns the cookie name to use for connections.

Returns:

the cookie

setCookie

public void setCookie(java.lang.String cookie)

Sets the cookie name to use for connections.

Parameters:

cookie - the cookie to set

getClientName

public java.lang.String getClientName()

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

Returns:

the clientName

setClientName

public void setClientName(java.lang.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