Chapter 2 Programming Information

Implementing custom socket plug-ins

This section discusses how to plug a custom socket implementation into an application to customize the communication between a client and server. javax.net.ssl.SSLSocket is an example of a socket that you could customize to enable encryption.

com.sybase.jdbcx.SybSocketFactory is a Sybase extension interface that contains the createSocket(String, int, Properties) method that returns a java.net.Socket.For a jConnect version 4.1 or later driver to load a custom socket, an application must:

Implement this interface
Define the createSocket(..) method

jConnect uses the new socket for its subsequent input/output operations. Classes that implement SybSocketFactory create sockets and provide a general framework for the addition of public socket-level functionality.

/**
 * Returns  a socket connected to a ServerSocket on the named host,
 * at  the given port.
 * @param host  the server  host
 * @param port  the server port
 * @param  props  Properties passed in through the connection
 * @returns  Socket
 * @exception IOException, UnknownHostException
 */
 public  java.net.Socket createSocket(String host, int port, Properties props) throws  IOException, UnknownHostException;

Passing in properties allows instances of SybSocketFactory to use connection properties to implement an intelligent socket.

When you implement SybSocketFactory to produce a socket, the same application code can use different kinds of sockets by passing the different kinds of factories or pseudo-factories that create sockets to the application. You can customize factories with parameters used in socket construction. For example, you could customize factories to return sockets with different networking time outs or security parameters already configured. The sockets returned to the application can be subclasses of java.net.Socket to directly expose new APIs for features such as compression, security, record marking, statistics collection, or firewall tunnelling (javax.net.SocketFactory).

SybSocketFactory is intended to be an overly simplified javax.net.SocketFactory, enabling applications to bridge from java.net.* to javax.net.* if desired.

To use a custom socket with jConnect:

Provide a Java class that implements com.sybase.jdbcx.SybSocketFactory. See "Creating and configuring a custom socket".
Set the SYBSOCKET_FACTORY connection property so that jConnect can use your implementation to obtain a socket.

SYBSOCKET_FACTORY connection property

To use a custom socket with jConnect, set the SYBSOCKET_FACTORY connection property to a string that is either:

The name of a class that implements com.sybase.jdbcx.SybSocketFactory

or
DEFAULT, which instantiates a new java.net.Socket( )

See "Setting connection properties" for instructions on how to set SYBSOCKET_FACTORY.

Creating and configuring a custom socket

Once jConnect obtains a custom socket, it uses the socket to connect to a server. Any configuration of the socket must be completed before jConnect obtains it.

This section explains how to plug in an SSL socket implementation, such as javax.net.ssl.SSLSocket, with jConnect.

Currently, only Adaptive Server version 12.5 and later supports SSL.

The following example shows how an implementation of SSL can create an instance of SSLSocket, configure it, and then return it. In the example, the MySSLSocketFactory class implements SybSocketFactory and extends javax.net.ssl.SSLSocketFactory to implement SSL. It contains two createSocket methods--one for SSLSocketFactory and one for SybSocketFactory--that:

Create an SSL socket
Invoke SSLSocket.setEnableCipherSuites( ) to specify the cipher suites available for encryption
Return the socket to be used by jConnect

Example

public class MySSLSocketFactory extends  SSLSocketFactory
 	implements SybSocketFactory
 {
 /**
 * Create  a socket, set the cipher suites it can use, return 
 * the  socket.
 * Demonstrates how cither suites could  be hard-coded into the
 * implementation.
 *
 * See  javax.net.SSLSocketFactory#createSocket
 */

public Socket createSocket(String host, int port)
 	throws  IOException, UnknownHostException
 {
 	// Prepare  an array containing the cipher suites that are to 
 	// be  enabled.
 	String enableThese[] =
 	{
 			"SSL_DH_DSS_EXPORT_WITH_DES40_CBC_SHA",
 			"SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5",
 			"SSL_DH_RSA_EXPORT_WITH_DES40_CBC_SHA"
 	}
 	;
 	Socket  s =
 			SSLSocketFactory.getDefault().createSocket(host,  port);
 	((SSLSocket)s).setEnabledCipherSuites(enableThese);
 	return  s;
 }

/**
 * Return  an SSLSocket.
 * Demonstrates how to set cipher  suites based on connection
 * properties like:
 * Properties _props = new  Properties();
 * Set other url, password, etc.  properties.
 * _props.put(("CIPHER_SUITES_1",
 *		"SSL_DH_DSS_EXPORT_WITH_DES40_CBC_SHA");
 * _props.put("CIPHER_SUITES_2",
 *		"SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5");
 * _props.put("CIPHER_SUITES_3",
 * 		"SSL_DH_RSA_EXPORT_WITH_DES40_CBC_SHA");
 * _conn = _driver.getConnection(url, _props);
 *
 * See  com.sybase.jdbcx.SybSocketFactory#createSocket
 */

public Socket createSocket(String host, int port, 
 	Properties  props)
 	throws IOException, UnknownHostException
 {
 	// check  to see if cipher suites are set in the connection
 	// properites
 	Vector  cipherSuites = new Vector();
 	String  cipherSuiteVal = null;
 	int cipherIndex = 1;
 	do
 	{
 			if((cipherSuiteVal = props.getProperty("CIPHER_SUITES_"
 					+ cipherIndex++)) == null)
 			{
 					if(cipherIndex <= 2)
 					{
 							// No  cipher suites available
 							// return  what the object considers its default
 							// SSLSocket,  with cipher suites enabled.
 							return  createSocket(host, port);
 					}
 					else
 					{
 							// we  have at least one cipher suite to enable
 							// per  request on the connection
 							break;
 					}
 					else
 					}
 							// add  to the cipher suit Vector, so that
 							// we  may enable them together
 							cipherSuites.addElement(cipherSuiteVal);
 					}
 			}
 			while(true);

			// lets  you create a String[] out of the created vector
 			String  enableThese[] = new String[cipherSuites.size()];
 			cipherSuites.copyInto(enableThese);

			// enable  the cipher suites
 			Socket  s =
 					SSLSocketFactory.getDefault().createSocket
 						(host,  port);
 			((SSLSocket)s).setEnabledCipherSuites(enableThese);

			// return  the SSLSocket
 			return s;
 	}

	// other methods
 }

Since jConnect requires no information about the kind of socket it is, you must complete any configuration before you return a socket.

For additional information, see:

Encrypt.java - located in the sample (jConnect 4.x) and sample2 (jConnect 5.x) subdirectories of your jConnect directory, this sample shows you how to use the SybSocketFactory interface with jConnect applications.
MySSLSocketFactory.java - also located in the sample (jConnect 4.x) and sample2 (jConnect 5.x) subdirectories of your jConnect directory, this is a sample implementation of the SybSocketFactory interface that you can plug in to your application and use.