org.otfeed
Class OTConnectionFactory

java.lang.Object
  org.otfeed.OTConnectionFactory

All Implemented Interfaces:

IConnectionFactory

public class OTConnectionFactory
extends java.lang.Object
implements IConnectionFactory

Factory of connections to the OpenTick service. This is the root object of the OpenTick client API. It is used to establish a connection to the OpenTick service.

Before calling the connect(org.otfeed.OTConnectionSpec, org.otfeed.event.IConnectionStateListener) method, one have to set username/password and at least one host in the hosts.

Sample usage

Sample usage can be like this:

 OTConnectionFactory factory = new OTConnectionFactory();

 factory.setUsername("super-trooper");
 factory.setPassword("kick-me");
 factory.getHostList().add(new OTHost("feed1.opentick.com", 10015));

 IConnection connection = factory.connect(null);

 ListExchangesCommand command = new ListExchangesCommand(new IDataDelegate {
         public void onData(OTExchange exchange) {
                 System.out.println(exchange);
         }
 });
 
 IRequest request = connection.prepareRequest(command);
 request.submit();
 request.waitForCompletion();

 connection.shutdown();
 connection.waitForCompletion();
 

Avoid starting more than one simultaneous connection

Note that one can establish as many connection as she wishes, by calling connect(org.otfeed.OTConnectionSpec, org.otfeed.event.IConnectionStateListener) method multiple times. However, this is not recommended. The reasons are: the avoidance of synchronization issues, and conservation of resources.

Synchronization is a concern, because listener methods are called by a separate event-dispatching thread. Every connection starts its own event-displatching thread.

Resources are a concern, because each connection takes a significant amount of resources. For example, current implementation creates three threads and one client socket per connection.

Therefore, the recommentded practice is to limit number of connections (e.g. work with a single connection per whole application). Each connection can handle unlimited number of simultaneous requests very efficiently. Another benefit of having just a single connection per application is that one can avoid need for synchronization by assuming that all business logic is done by the event-dispatching thread. When needed, calls from outside can be translated to the event-dispatching thread by calling IConnection.runInEventThread(java.lang.Runnable) method on the connection object.

OTPooledConnectionFactory class can be used to simulate "simultaneous" connections while keeping only a single actual connection to the Opentick server.

No automatic reconnect after connection was lost

This API does not provide the feature of automatic re-connect on connection loss. This is because the underlying protocol does not allow for reliable re-start of ongoing requests (there is no notion of request "progress", that can be used to re-submit the request). Original driver provided by OpenTick (see http://www.opentick.com) does attempt to do such a reconnect, with the risk of loosing some data, and getting duplicate historic data.

We feel that since re-connect can easily lead to surprising and often not obvious data problems, its much safer to terminate all pending requests, and let the application to decide what to do next (maybe terminate, or reconnect).

Following outlines the steps that application have to take in order to recover gracefully from lost connection connection. We assume that it was a historical data request.

1. Remember the latest data timestamp.
2. Discard all the data that has this timestamp (because it may be incomplete).
3. Re-connect to the server.
4. Re-issue the request using the remembered timestamp as the starting date.

Apparently, this is better be done by the application level, not the driver.

Constructor Summary

OTConnectionFactory()
Creates new OTConnectionFactory.

OTConnectionFactory(java.lang.String username, java.lang.String password, java.util.Set<OTHost> hostList)
Creates new OTConnectionFactory and initializes all its properties.

Method Summary

IConnection	connect(IConnectionStateListener listener) Deprecated.
IConnection	connect(OTConnectionSpec spec, IConnectionStateListener list) Starts asynchronous connection process.
long	getConnectTimeoutMillis() Gets connection timeout (in milliseconds).
java.util.concurrent.Executor	getExecutor() Executor service (factory of threads).
long	getHeartbeatIntervalMillis() Gets heartbeat interval value (in milliseconds).
java.util.List<OTHost>	getHostList() Deprecated.
java.util.Set<OTHost>	getHosts() Returns set of addresses.
java.lang.String	getPassword() Gets login password.
IStreamerFactory	getStreamerFactory() Low-level IO object, responsible for connecting and delivering/receiving raw frames.
java.lang.String	getUsername() Gets login name.
void	setConnectTimeoutMillis(long val) Sets connection timeout (in milliseconds).
void	setExecutor(java.util.concurrent.Executor val) Sets executor service.
void	setHeartbeatIntervalMillis(long val) Sets heartbeat interval value (in milliseconds).
void	setHostList(java.util.List<OTHost> val) Deprecated.
void	setHosts(java.util.Set<OTHost> val) Sets list of servers.
void	setPassword(java.lang.String val) Sets login password.
void	setStreamerFactory(IStreamerFactory val) Sets streamer factory.
void	setUsername(java.lang.String val) Sets login name.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

OTConnectionFactory

public OTConnectionFactory()

Creates new OTConnectionFactory.

OTConnectionFactory

public OTConnectionFactory(java.lang.String username,
                           java.lang.String password,
                           java.util.Set<OTHost> hostList)

Creates new OTConnectionFactory and initializes all its properties.

Parameters:

username - username.

password - password.

hostList - list of hosts.

Method Detail

setUsername

public void setUsername(java.lang.String val)

Sets login name. Username must be set before calling connect(org.otfeed.OTConnectionSpec, org.otfeed.event.IConnectionStateListener)

Parameters:

val - login name.

getUsername

public java.lang.String getUsername()

Gets login name.

Returns:

username login name.

setPassword

public void setPassword(java.lang.String val)

Sets login password. Password must be set before calling connect(org.otfeed.OTConnectionSpec, org.otfeed.event.IConnectionStateListener)

Parameters:

val - login password.

getPassword

public java.lang.String getPassword()

Gets login password.

Returns:

login password.

getHostList

@Deprecated
public java.util.List<OTHost> getHostList()

Deprecated.

Please, use getHosts() instead.

Returns:

a wrapper around hosts set - for backward compatibility.

setHostList

@Deprecated
public void setHostList(java.util.List<OTHost> val)

Deprecated.

Please use setHosts(java.util.Set) instead.

Parameters:

val - collection of addresses.

getHosts

public java.util.Set<OTHost> getHosts()

Returns set of addresses. Allows client to control collection list by doing the following:

    session.getHosts().add(new OTHost("feed1.opentick.com", 10015));
    session.getHosts().add(new OTHost("feed2.opentick.com", 10015));
 

Client must configure at least one server address before calling connect(org.otfeed.OTConnectionSpec, org.otfeed.event.IConnectionStateListener) method. Initially, this list is empty (but not null).

Returns:

modifiable set of server addresses.

setHosts

public void setHosts(java.util.Set<OTHost> val)

Sets list of servers. Allows client to control collection of hosts by doing the following:

    Set hosts = new HashSet();
    hosts.add(new OTHost("feed1.opentick.com", 10015));
    hosts.add(new OTHost("feed2.opentick.com", 10015));
    session.setHosts(hosts);
 

Client must configure at least one server address before calling connect(org.otfeed.OTConnectionSpec, org.otfeed.event.IConnectionStateListener) method.

Parameters:

val - list of server addresses.

setConnectTimeoutMillis

public void setConnectTimeoutMillis(long val)

Sets connection timeout (in milliseconds). Default value is 20 000, which is 20secs. This value can be useful only if there are many "bad" servers in the hosts list, so that it takes significant time to reach the one that answers the connection request. There is rarely any need to change this value.

Parameters:

val - connection timeout value.

getConnectTimeoutMillis

public long getConnectTimeoutMillis()

Gets connection timeout (in milliseconds).

Returns:

connection timeout value.

setHeartbeatIntervalMillis

public void setHeartbeatIntervalMillis(long val)

Sets heartbeat interval value (in milliseconds). When connected, client periodically sends heartbeat messages to the server. If server does not receive any message from client for some time, it will close the connection. OpenTick recommends the heartbeat to be between 1sec and 10sec. Default value is 10 000, which is 10secs.

Parameters:

val - heartbeat interval value.

getHeartbeatIntervalMillis

public long getHeartbeatIntervalMillis()

Gets heartbeat interval value (in milliseconds).

Returns:

heartbeat interval value.

getStreamerFactory

public IStreamerFactory getStreamerFactory()

Low-level IO object, responsible for connecting and delivering/receiving raw frames. Normally, you will not need to change this.

The default value is the "correct" real-life streamer implementation, see LoginStreamerFactory.getStreamerFactory().

You may want to change this only for the puproses of testing, debugging, or mocking.

Returns:

streamer factory.

setStreamerFactory

public void setStreamerFactory(IStreamerFactory val)

Sets streamer factory.

Parameters:

val - streamer factory.

getExecutor

public java.util.concurrent.Executor getExecutor()

Executor service (factory of threads). Note that implementation must support at least three concurrent threads. For example, SingleThreadedExecutor will not work!

Returns:

executor service.

setExecutor

public void setExecutor(java.util.concurrent.Executor val)

Sets executor service.

Parameters:

val - executor service to use. Default is Executors.newCachedThreadPool().

connect

public IConnection connect(OTConnectionSpec spec,
                           IConnectionStateListener list)

Starts asynchronous connection process. This method does not block, it returns IConnection object immediately. Pass OTConnectionSpec instance as first parameter to specify connection destination, username/password, and other connection properties. This parameter is optional. If not used (meaning user passes null), values set on the factory instance are used instead.

Note that username, password, and hosts properties are required. Use list parameter to monitor the connection progress. For more details, see IConnectionStateListener. If caller is not interested in monitoring connection progress, it can pass null as list paramater.

Specified by:

connect in interface IConnectionFactory

Parameters:

spec - connection specification. Optional.

list - connection state listener. Optional.

Returns:

connection object.

Throws:

java.lang.IllegalStateException - if username/password pair is not set, or if hostList is empty.

connect

@Deprecated
public IConnection connect(IConnectionStateListener listener)

Deprecated.

Please use IConnectionFactory.connect(OTConnectionSpec, IConnectionStateListener) method.

Specified by:

connect in interface IConnectionFactory