Connect

Reads the properties to determine which gateway connection to be used and makes a connection to the server. You can connect via HTTP, HTTPS, or SOCKET. However, HTTP and HTTPS do not actually connect to the server until a GetService or Process method is invoked. With a SOCKET connection type, the Connect method is fully functional.

Syntax

public void connect()

Parameters

None.

Results

Throws:

ConfigurationException: When invalid configuration causes the inability to connect to the server. For example, an unknown protocol would cause a ConfigurationException. There is no value in attempting to retry connect() when this error occurs.
ConnectionException: When unable to connect to the server. It might be possible to reconnect, depending on the underlying cause of the exception.
MessageProcessingException: When an error occurs on the server that is not due to Configuration or Connection issues.

Example

Server server = new Server(); 

server.setConnectionProperty(Server.HOST, "localhost"); 
server.setConnectionProperty(Server.PORT, "10119"); 
server.setConnectionProperty(Server.CONNECTION_TYPE, "SOCKET"); 
server.setConnectionProperty(Server.ACCOUNT_ID, "guest"); 
server.setConnectionProperty(Server.ACCOUNT_PASSWORD, ""); 

try 
{ 
	//Connect to server 
	server.connect(); 
} 
catch (ConfgurationException e) 
{ 
	// indicate an error with configuration 
} 
catch (ConnectionException e) 
{ 
	// handle connection issue (retry, report error, etc.) 
} 
catch (MessageProcessingException e) 
{ 
	// report error 
}

Connection Pooling

Connection pooling for the SOCKET connection type is available to the Java client. This section describes how to enable and disable connection pooling. By default connection pooling is disabled.

To enable connection pooling:

Server server = new Server(); Server.setConnectionProperty(Connection.SOCKET_POOL, "true");

To disable connection pooling:

Server server = new Server(); Server.setConnectionProperty(Connection.SOCKET_POOL, "false");

When connection pooling is enabled, the connect() method borrows a connection from the pool, and the disconnect() method returns the connection back to the pool. When pooling, the client must call disconnect() each time to return the connection to the pool.

Each thread should contain its own server, as shown in the following example:

{ 
	...	
	Server server = new Server(); 
	server.setConnectionProperty(Server.HOST, "localhost"); 
	server.setConnectionProperty(Server.PORT, "10119"); 
	server.setConnectionProperty(Server.CONNECTION_TYPE, "SOCKET"); 
	server.setConnectionProperty(Server.ACCOUNT_ID, "yourID"); 
	server.setConnectionProperty(Server.ACCOUNT_PASSWORD, "pwd"); 
	server.setConnectionProperty(Connection.SOCKET_POOL, "true"); 
	server.setConnectionProperty(Connection.SOCKET_POOL_MAX_ACTIVE, "20"); 
	server.setConnectionProperty(Connection.SOCKET_POOL_MIN_IDLE, "10"); 
	server.setConnectionProperty(Connection.SOCKET_POOL_MAX_TOTAL, "25"); 
	server.connect(); 
	...	
	service = server.getService(serviceName); 
	reply = service.process(requestMessage); 
	server.disconnect(); 
	...	
}

The following table lists the constants you can use for connection pooling.

Table 1. Constants for Connection Pooling
Constant Name	Description
SOCKET_POOL	Whether or not to use connection pooling if using the SOCKET connection type. Values are true or false. Default is false.
SOCKET_POOL_MAX_ACTIVE*	Maximum number of active socket connections that may be borrowed from the pool. Default is -1, which indicates no maximum.
SOCKET_POOL_MAX_IDLE*	Maximum number of idle socket connections remaining in the pool. Default is -1, which indicates no maximum.
SOCKET_POOL_MAX_TOTAL*	Maximum total number of pooled socket connections (both active and idle). Default is -1, which indicates no maximum.
SOCKET_POOL_MAX_WAIT*	Maximum amount of time (in milliseconds) to wait before throwing an exception when the pool is exhausted and the "when exhausted" action is WHEN_EXHAUSTED_BLOCK. Default is -1, which indicates no maximum.
SOCKET_POOL_MIN_EVICTABLE_IDLE_TIME_MILLIS*	Minimum amount of time a connection may sit idle in the pool before it is eligible for eviction. Default is 1800000 (30 minutes).
SOCKET_POOL_MIN_IDLE*	Minimum number of connections allowed in the pool before the evictor thread (if active) creates new connections. The default is 0.
SOCKET_POOL_NUM_TESTS_PER_EVICTION_RUN*	Sets the number of idle connections to examine during each run of the evictor thread (if active). Default is -1, which indicates all idle connections are examined.
SOCKET_POOL_TEST_ON_BORROW*	Whether connections will be validated before being borrowed from the pool. Default is true.
SOCKET_POOL_TEST_ON_RETURN*	Whether connections will be validated before being returned to the pool. Default is false.
SOCKET_POOL_TEST_WHILE_IDLE*	Whether connections will be validated by the idle connection eviction thread. Default is false.
SOCKET_POOL_TIME_BETWEEN_EVICTION_RUNS_MILLIS*	Sets the number of milliseconds to sleep between runs of the idle connection evictor thread. When set to zero or a negative number, no idle connection evictor thread will be run. Default is 300000 (5 minutes).
SOCKET_POOL_WHEN_EXHAUSTED_ACTION*	Sets the "when exhausted action" to take when attempting to borrow a connection and none are available. Default is SOCKET_POOL_WHEN_EXHA USTED_BLOCK.
SOCKET_POOL_WHEN_EXHAUSTED_BLOCK*	A "when exhausted action" type indicating that when attempting to borrow a connection and none are available, the caller should block until a new object is available, or the maximum wait time has elapsed.
SOCKET_POOL_WHEN_EXHAUSTED_FAIL*	A "when exhausted action" type indicating that when attempting to borrow a connection and none are available, the caller should fail, throwing a ConnectionException.
SOCKET_POOL_WHEN_EXHAUSTED_GROW*	A "when exhausted action" type indicating that when attempting to borrow a connection and none are available, a new connection will be made anyway.

* Applicable only if using the SOCKET connection type and connection pooling is enabled.