Manual for the i-net KONNEKTER driver

Version: 2.22
Last Modified: 4. Jan 2017

Table of Content

Table of Contents

1. Introduction

The i-net KONNEKTER driver consists of two parts - the server and the client.?
The server is a multi-threaded Java API with integrated PoolManager. It receives queries from client drivers and forwards them to the appropriate local JDBC drivers for a particular data source. The results of the query processing is sent back to the client.
The client is a JDBC 2.0 driver that connects to the server over TCP/IP and accesses a database using a local JDBC driver for this database on the server. This allows to use one driver on the client site to access various databases over different drivers on the server site.

2. Java and JDBC Versions

The server requires:

  • Java Version: 1.2
  • JDBC Version: 2.0

The client requires:

  • Java Version: 1.1.x or higher
  • JDBC Version: 1.22 or higher

3. The Server

Extract the driver jar file from the zip file you have purchased or downloaded. The name of the jar file is like the drivername. It can be:

  • Oranxo.jar
  • Seropto.jar
  • Sero.jar
  • Auguro.jar

3.1. Installation

Add the file Konnekter_Server.jar to your classpath or extract the jar file in the directory of the application.

3.2. Application Example

Here is the simplest example of the server application.

  import com.inet.jj.srv.*; // imports the server's package
  import java.sql.*;
 
  public class AppServer
  {
  	public static void main(String[] args)
  	{
 
  	// Loads the drivers using by application.
  	try{
  		Class.forName("com.inet.tds.TdsDriver");
  		Class.forName("com.inet.ora.OraDriver");
  		//....
  	}catch(Exception ex){
  		ex.printStackTrace();
  	}
 
  	// Instances the server listening to the default port 9876.
  	JJServer srv = new JJServer();
 
  	// Enables server debugging to the "standard" output.
  	srv.setLogStream(System.out);
 
  	// Enables the debugging of JDBC drivers running on the server.
  	DriverManager.setLogStream(System.out);
 
  	// Starts the server.
  	srv.start();
  	}
  }

See also the file samples/AppServer.java

3.3 API

4. The Client (Driver)

4.1. Installation

For using the driver in a java application add the file Konnekter_Client.jar to your classpath or extract the jar file in the directory of the application.
For using the driver in an applet add the file Konnekter_Client.jar to the Archive attribute of the applet tag, e.g.:

<APPLET CODE="..." Codebase="..." ARCHIVE="Konnekter_Client.jar" WIDTH="100%" HEIGHT="100%">
...
</APPLET>

or extract the jar in the directory of the applet.

4.2. Getting Started

4.2.1. Driver Name

The class name of the driver is: com.inet.jj.cli.JJDriver

4.2.2. Url Syntax

jdbc:inetjj:host[:port][?loglevel=warning];driverURL
jdbc:inetjj:http://proxy-address[[?server=host]&port=port][&loglevel=warning];driverURL
jdbc:inetjj:host[:port][?loglevel=warning];UDS
jdbc:inetjj:http://proxy-address[[?server=host]&port=port][&loglevel=warning];UDS
host the host name on which the server is running
port the port number(by default 9876)
driverURL the url for the required driver on the server
UDS the User Data Source name which was defined on the server
proxy-address the URL of the Konnekter proxy. This can be the proxy.dll in the IIS or the proxy.jsp in a servlet engine or proxy.php for the Apache.
The default values for server is LocalHost and port is 9876.
loglevel Enable a logging independent of the JDBC logging to System.out. The only valid value is “warning”. Currently only a reconnect is logging.

If you use the url of the required driver directly then you can put additional properties (e.g., user, password, etc.) to this driver on the server using methods of DriverManager

  • getConnection(String url, Properties info)
  • getConnection(String url, String user, String password).

For examples:

  • jdbc:inetjj:www.dddd.com:3333;jdbc:inetsyb:www.inetsoftware.de:5000?database=treiber
  • jdbc:inetjj:www.dddd.com;oracleDB assuming that a data source named 'oracleDB' is defined on the server
  • jdbc:inetjj:http://www.dddd.com/scripts/proxy.dll;oracleDB assuming that a data source named 'oracleDB' is defined on the server
  • jdbc:inetjj:http://www.dddd.com/scripts/proxy.dll?server=dbserver&port=3456;oracleDB assuming that a data source named 'oracleDB' is defined on the server

4.2.3. Connection Example

  import java.sql.*; // JDBC package
  ...
  String url = "jdbc:inetjj:<host>;<driver url>"; // use your host name and driver url here
  ...
  try {
  	// to create more info for technical support
  	DriverManager.setLogStream(System.out);
 
  	//set a timeout for login and query
  	DriverManager.setLoginTimeout(15);
 
  	//load the class with the driver
  	Class.forName("com.inet.jj.cli.JJDriver");
 
  	//open a connection to the database
  	Connection connection = DriverManager.getConnection(url);
 
  	//to get the driver version
  	DatabaseMetaData conMD = connection.getMetaData();
  	System.out.println("Driver Name:\t" + conMD.getDriverName());
  	System.out.println("Driver Version:\t" + conMD.getDriverVersion());
 
  	//create a statement
  	Statement st = connection.createStatement();
 
  	//execute a query
  	ResultSet rs = st.executeQuery("SELECT * FROM tblExample");
 
  	// read the data and put it to the console
  	while (rs.next()){
  		for(int j=1; j<=rs.getMetaData().getColumnCount(); j++){
  			System.out.print( rs.getObject(j)+"\t");
  		}
  		System.out.println();
  	}
 
  	//close the objects
  	st.close();
  	connection.close();
  } catch(Exception e) {
  	e.printStackTrace();
  }
  ...

See also the file samples/AppClient.java

4.2.4. Using JDBC 2.0 features under Java 1.1.x

If the client runs in Java 1.1.x environment (e.g., in an applet) you can also use JDBC 2.0 methods using the “true” class names instead of interface names. The classes are called JJXXX, where XXX represents the name of the corresponding interface.

For example:

  ...
  JJConnection con = (JJConnection)DriverManager.getConnection("...");
  Statement st = con.createStatement(ResultSet.TYPE_SCROLL_INSENSITIVE, ResultSet.CONCUR_UPDATABLE);
  JJResultSet rs = (JJResultSet)st.executeQuery("select * from jjtest");
  int count = rs.getMetaData().getColumnCount();
  rs.afterLast();
  while(rs.previous())
  {
  	for(int i = 1; i <= count; i++)
  		System.out.print(rs.getObject(i));
  }
  ...

Note: The methods getClob() and getBlob() can be used in JDBC 2.0 only.

4.3. API

4.4. Debugging

To enable the logging of the driver you can use the static method of the DriverManager class with PrintStream as argument:

  DriverManager.setLogStream( System.out ); //logging on the standard output stream
  DriverManager.setLogStream( System.err ); //logging on the standard error output stream
 
  //logging in a file
  DriverManager.setLogStream( new PrintStream( new FileOutputStream( "driver.log" ) ) );

5. Proxy

If you want use port 80 with i-net KONNEKTER but you can't use the port 80 because the port is already in use from your web server then you can use a proxy. The using of port 80 is recommended for the internet. Many internet user can only use port 80.

5.1. Proxy with Internet Information Server (IIS)

  • Copy the Proxy.dll in a directory or a virtual directory of the IIS. The file is in the proxy folder of the download zip file. The recommended directory is scripts.
  • You can rename the dll file if you want it. That you later know which proxy this is. For example JdbcProxy.dll.
  • Set the execute permissions of the directory or virtual directory to “Script and Executable”.
  • IIS 6 or higher only:
    Create a new “Web Service Extension”, add the the proxy.dll and set the status to allowed.
  • Request the URL of the proxy.dll in a browser without any parameter. You should receive a file with a size of 0 byte.
  • Send the URL of the proxy.dll to your applet developers.

5.2. Proxy with a JSP Engine

Deploy the proxy.jsp file in your JSP engine (for example Tomcat). This file can you find? in the proxy folder of the download zip file. See the description of your JSP engine for detail of deploying.

5.3. Proxy with a PHP script

If you want use Konnekter with Apache or another PHP supported web server then you need:

  1. Copy the file proxy.php in your web server. This file can you find? in the proxy folder of the download zip file.
  2. In the config file php.ini you need to enable the property 'always_populate_raw_post_data=On'. You can find the file with LAMP in '<lampp>/etc'. With the standard installation of Apache you can find it in '/etc/php/apache2'
  3. Restart the web server.

6. Commands

The Commands are SQL statements stored on the server. Each command has its unique name and can be added to the current command list with the method addCommand(command_name, sql_statement) from the JJServer. Each client can access a command by its name and according SQL statement will be executed on the server.

For example, to create a query command like “select * from myTable” do following:

  // assuming that srv is a instance of JJServer
  srv.addCommand("Query 1", "select * from myTable");

Now can a client execute this command passing its name to the server:

  // we need to cast because the executeQueryCommand method is not the JDBC API
  JJStatement jjst = (JJStatement)con.createStatement();
  ResultSet rs = jjst.executeQueryCommand("query 1");

That works also with a PreparedStatement:

  // adds the command on the server
  srv.addCommand("cmd1", "insert into table1 values (?)");

Now call this command on the client:

  // assuming that con is a valid JJConnection.
  // the client needs to know the number of parameters
  PreparedStatement pst = ((JJConnection)con).prepareCommand("cmd1", 1);
  pst.setString(1, "trtrt");
  pst.execute();

Note: the command names are not case sensitive.

For more info see the API documentation.

7. Named Parameters

The Named Parameters are a additionally functionality of the i-net Konnekter. You can define on the server a command contained the named parameters and set they on the client using the method setObject(String paramName, Object value) from JJPreparedStatement. The server is responsible to pass the parameters in the right order.

The syntax: each named parameter containing in the SQL statement must be terminated by '%' character.

For example:

  // adds on the server a command containing the named parameters 'param1' and 'param2'
  srv.addCommand("cmd", "update tabl1 set col1=%param1% where col2 > %param2%");
 
  //on the client we need to cast the java.sql interfaces to the "right" objects
  JJPreparedStatement pst = (JJPreparedStatement)((JJConnection)con).prepareCommand("cmd", 2);
 
  // set the parameter, the parameter order doesn't matter
  pst.setObject("param2", new Integer(100));
  pst.setObject("param1", "trtrt");
  pst.execute();

Note: the parameter names are not case sensitive.

For more info see the API documentation.

8. JavaCommands

The JavaCommands are a extension of the server commands. The JavaCommand object will be created on the server if the client calls the method prepareCommand() or prepareCallCommand() from the JJConnection with a command name which corresponded to a special JavaCommandFactory object stored in the current command list (like a sql command) on the server.
As a JavaCommandFactory object has been added to the command list all client's calls of the method prepareCommand() or prepareCallCommand() will be redirected to the corresponding methods of the JavaCommandFactory object which will create a new JavaCommand object referenced to an object (JJPreparedStatement or JJCallableStatement) on the client. After that all client's request from the corresponding object will be redirected to the JavaCommand object on the server.

The class JavaCommandFactory contains four method corresponded to the JJConnection methods:

  prepareCommand(Connection con),
  prepareCommand(Connection con, int rsType, rsConcur)
  prepareCallCommand(Connection con)
  prepareCallCommand(Connection con, int rsType, rsConcur)

where con is a “real” connection to the database.
The methods throw a SQLException and must be overridden by extended objects. All that methods return a new JavaCommand object.
The class JavaCommand implements the java.sql.CallableStatement interface and one additionally method getObject(String, String) that corresponded to the method in JJPreparedSatatement and using for passing named parameters. The methods do nothing and should be overridden by extended objects.
To use JavaCommands in your application you should only extend the JavaCommand and the JavaCommandFactory classes and use that instance in the corresponding methods.

For more info see the API documentation and the samples samples/MyCommand.java and samples/MyCommandFactory.java.

9. Known problems

  • User-defined types, Array and Ref data types are not supported.

10. Support

Please read this file and our FAQ

If you cannot find your problem in the FAQ then post your problem to our newsgroup providing as much information about what occurred or happened as possible. You can find more info about our support at http://www.inetsoftware.de/support

11. Changes

11.1. Changes in Version 1.00

  • Commands, Named Parameters and JavaCommands are now supported.
  • Following methods were added to the class JJServer:
    + addCommand(String, String)
    + addCommand(String, JavaCommandFactory)
    + removeCommand(String)
    + removeAllCommands()
    + getCommand(String)
    + getConnectedClientCount()
    + getConnectedHostNames(String)
    + getConnectedHostNames()
    + getConnection(String)
    + getCurrentExecutingCommands()
    + getDBConnectionCount()
    + getDBFreeConnectionCount()
    + setMaxConnectionCount(int)
    + getMaxConnectionCount()
    + getPoolLoginTimeout()
    + setPoolLoginTimeout(int)
    + getPoolTimeout()
    + setPoolTimeout(int)
    + setOnlyCommandMode(boolean)
    + getOnlyCommandMode()
  • Following methods were added to the class JJConnection:
    + prepareCommand(String)
    + prepareCommand(String,int,int)
    + prepareCommandCall(String)
    + prepareCommandCall(String,int,int)
  • Following methods were added to the class JJPreparedStatement:
    + setObject(String,Object)
  • Following methods were added to the class JJStatement:
    + executeCommand(String)
    + executeQueryCommand(String)
    + executeUpdateCommand(String)
  • Following methods were added to the class JJResultSet:
    + fillList(int, Vector)
    + fillList(int, List)
    + fillList(int, Choice)
    + fillList(String, Vector)
    + fillList(String, List)
    + fillList(String, Choice)

11.2. Changes in Version 1.01

  • Bug with deleteRow() was fixed.
  • Bug with return from methods execute() and getUpdateCount() was fixed.
  • Bug with Batch update was fixed.
  • The methods fillList(int[], Object[]) and fillList(String[], Object[]) were added to the class JJResultSet.
  • Following methods were added to the class JJServer:
    + getCurrentExecutingCommands(String)
    + getCurrentExecutingCommands(String)
    + getOpenCallableStatementCount()
    + getOpenCallableStatementCount(String)
    + getOpenStatementCount()
    + getOpenStatementCount(String)
    + getOpenPreparedStatementCount()
    + getOpenPreparedStatementCount(String)
    + getOpenJavaCommandCount()
    + getOpenJavaCommandCount(String)
    + getOpenResultSetCount()
    + getOpenResultSetCount(String)

11.3. Changes in Version 1.02

  • Bug with getConnectedHostNames() was fixed.
  • Bug with ResultSet.deleteRow() was fixed.
  • Statement.setQueryTimeout() works now.
  • Bug with Connection.isClosed() was fixed.
  • A bug was fixed that could produce a java.lang.StackOverflowError in JDK 1.4.x if an exception had occurred.
  • Following methods were added to the class JJServer:
    + getOpenedCommands()
    + getOppenedCommands(String)
  • The class CommandResultSet has been added.

11.4. Changes in Version 2.00

  • HTTP tunnel was added

11.5. Changes in Version 2.01

  • The AbstractMethodError with getColumnLabel on a JDBC 1.22 driver was fixed.
  • A performance increment was added

11.6. Changes in Version 2.02

  • That the driver can hang (or a timeout exception) with specific API call orders was fixed.

11.7. Changes in Version 2.03

  • The exception “[JJServer] Required Object is closed.” for multiple calls of a Statement was fixed.
  • A reconnect was added if a single socket error occured between client and server.

11.8. Changes in Version 2.04

  • Every Statement is using its own channel now. This increment the parallelism of the driver.

11.9. Changes in Version 2.05

  • Increment the network block size to increment the performance.

11.10. Changes in Version 2.06

  • Methods JJServer.setLogLevel(int) and JJServer.getLogLevel() was added.
  • The Client URL property “loglevel” was added.

11.11. Changes in Version 2.07 (18. Jan 2006)

  • A hanging on getConnection() with bad login with proxy was fixed.
  • A hanging on Connection.close() with a proxy and the Microsoft VM was fixed.
  • Many bug fixes for CallabaleStatements that can hang the connection was fixed.
  • The not working method getCrossReference() was fixed.
  • Support for writing BLOB/CLOB was added.
  • A bug with the precision of BigDecimal was fixed.
  • A hanging with proxy and large requests (>4096 bytes) was fixed.
  • Problems with executeBatch() was fixed.
  • The creating of a Statement, PreparedStatement or CallabaleStatement throws an SQLException on a closed connection now.
  • Slow execution with IIS proxy and large requests (>4096 bytes) and old IIS (<6) was fixed.
  • Fix for very rare random errors under heavy load. The random errors can be like “Required object xyz is closed.” or a ClassCastException.

11.12. Changes in Version 2.08 (26. Sept 2006)

  • The method ResultSet.getString() on a CLOB column returns the string value of the CLOB now.
  • The method fillList() was fixed for MySQL because this DBMS does not support ResultSet.rowDeleted().
  • Searching for column names also in the column labels for MySQL.
  • The methods setLobToStream() and isLobToStream() was added.

11.13. Changes in Version 2.09 (14. Mar 2007)

  • JJServer.removeUDS(String) now clears the pool.
  • A port scan could stop the server from listening.
  • Support for https proxying added.
  • The method JJStatement.executeQueryCommand() now also works together with JJServer.setOnlyCommandMode(true).

11.14. Changes in Version 2.10 (13. Sep 2007)

  • The performance of proxies was improved with a thread pool (server) and a socket pool (ISAPI).
  • CallableStatements which return a ResultSet could cause the system to hang. This was fixed.

11.15. Changes in Version 2.11 (6. Mar 2008)

  • Added the file proxy.php.

11.16. Changes in Version 2.12 (11. Mar 2009)

  • Fixed a hanging connection (until a timeout occurred) after a wrong login.
  • A NPE in Connection.isClosed() when Connection.close() was called at the same time was fixed.

11.17. Changes in Version 2.13 (2. Oct 2009)

  • Unused Sockets will be closed after 5 minutes and unused threads on the server will be terminated.
  • Improve the speed by reducing the roundtrips to the server.
  • Error messages improved.
  • Added the file proxy.aspx

11.18. Changes in Version 2.14 (14. Apr 2010)

  • A memory leak on a exception on executeQuery() was fixed.
  • A very rare protocol violation could occur if a ResultSet was closed 2 times.

11.19. Changes in Version 2.15 (15. Oct 2010)

  • The class JavaCommand now saves the properties query timeout, fetch size, max rows and max field size which are set from the client.

11.19. Changes in Version 2.16 (23. Mar 2011)

  • Sockets are faster free to reduce the needed resources.

11.19. Changes in Version 2.17 (26. Oct 2011)

  • Fixed SocketTimeoutExceptions on the server side.
  • Fixed a protocol violation after a call of setter in a Statement after a call of executeXXX().
  • Removed synchronized from Statement.cancel().
  • Fixed the wrong computer name with the PHP proxy.

11.20. Changes in Version 2.18 (30. Mar 2012)

  • Query statistics were added.
  • Fixed a NullPointerException in Connection.isClosed().
  • Improved the error logging on the server.
  • Use isValid() for a JDBC 4 driver.

11.21. Changes in Version 2.19 (12. Oct 2012)

  • Fixed a potential rare deadlock in Connection.close() and reduced the timeout of isClosed() to 1 second.

11.22. Changes in Version 2.20 (15. Apr 2015)

  • Reduce a timeout problem with Connection.isClosed() in networks with large latency.
  • Add a JJServer constructor with a ClassLoader parameter.
  • The mimetype for the Konnekter Proxy is set to “application/konnekter” now.

11.23. Changes in Version 2.21 (19. Apr 2016)

  • Property initSQL added.
  • Fix a thread bug in the query tracker.
  • Close returning connections with an active transaction to prevent dead locks.

11.24. Changes in Version 2.22 (4. Jan 2017)

  • Fix a rare ArrayIndexOutOfBoundsException on call of JJServer.getConnection.

Copyright by i-net software
More info and updates can be found at http://www.inetsoftware.de/

© 2000-2017 i-net software

 

© Copyright 1996 - 2017, i-net software; All Rights Reserved.