Using DBIntegrator Client for JDBC

[Top] [Prev][Next][Bottom]



 

Connecting to Data Sources

This section provides instructions for and examples for developing and connecting to the DBIntegrator Client for JDBC's JDBC driver. This section assumes that you have a basic knowledge of Java and SQL. For a detailed description of Java and the JDBC standard, visit JavaSoft's Web site at (www.javasoft.com).

For further information about SQL, consult the documentation of your database management system.

You can connect to a data source in four easy steps. Refer to the sample code at the end of these steps for more details.

1.  Load and register the driver with the JDBC Driver Manager.
A driver can be loaded and registered in three ways:

Class.forName("simba.jdbc.SimbaDriver"); 
The driver will automatically register itself with the JDBC Driver Manager when it is loaded.
simba.jdbc.SimbaDriver sd = new simba.jdbc.SimbaDriver();
2.  Create a database URL

The database URL specifies which data source you want to connect with. The format of a database URL is:

jdbc:simba://<server name>:<server port>/<data source name>
Database URL parameters Description
jdbc:simba  Identifies the driver. 
<server name>  The name of the DBIntegrator Server. It will be the name of your computer in a 1-tier configuration. 
<server port>  The port that DBIntegrator Server is listening on. The default is 1583. This value must be an integer. 
<data source name>  The ODBC name of the data source. 
Table 1: Database URL parameters

3.  Create and set the connection properties.

Properties may simply be the user name and password or more detailed properties for more advanced database configurations. For a list of advanced properties that can be set for DBIntegrator Server, see Table 2, "DBIntegrator Server Properties", and see Table 3, "DBIntegrator Client 'Encoding' Property" for a property used by DBIntegrator Client.

4.  Call DriverManager.getConnection

DriverManager.getConnection specifies the URL and any data source-specific properties and DBIntegrator Server-specific connection properties.

The following table lists the DBIntegrator Server-specific properties.
 
Connection Property  Description 
ArrayFetchOn  Turns array fetching on or off. Setting it to 1 turns it on and 0 turns it off. The default is 1. 
ArrayBufferSize  Sets the network transmission size when array fetching is on. The default is 32 KB. Values from 1 to 63 are valid. If the first row of any set's data, uncompressed, is larger than this buffer the driver will fail. When long variable length columns are among those selected, the data is handled differently, and ArrayBufferSize does not apply.
User  Specifies the user name to connect to the database with. 
Password  Specifies the password to attempt to connect with. 
ExecDesc Short description of application/applet that will appear in "Application" column in DBIntegrator Control.
Table 2: DBIntegrator Server Properties

NOTE: Connection properties not recognized by DBIntegrator Client will be added to the ODBC connection string passed to the DBMS driver on the server.
This table introduces the DBIntegrator Client-specific connection property, Encoding, which is important where the character encoding on the client and server (data source) do not match.
 
Connection Property  Description 
Encoding Specifies the character encoding used by the data source. See the detailed description which follows this table.
Table 3: DBIntegrator Client 'Encoding' Property

The 'Encoding' connection property allows you to access a database which uses a different character encoding than the system the JDBC driver is running on. For instance, when accessing a UTF-8 (Unicode) database, you may need to set 'Encoding' to 'UTF8'. Failure to correctly set this property when required can result in corrupted character (string) data.

By default, the JDBC driver uses the system encoding used by the platform on which the driver is running. In other words, if the 'Encoding' property is not set, the platform's system encoding is used.

For example, if the driver is running on English Windows it assumes all string data from the data source consists of only ASCII characters. If this is not the case, the driver will fail to fetch strings correctly unless 'Encoding' is set to indicate the encoding actually being used by the data source. The JDBC driver must convert fetched strings to Unicode because the Java internal string data type is Unicode. Back to the example, if the fetched strings are not ASCII, the converted strings are likely to be corrupted.

You can specify any Java encoding name (see the Canonical Names listed on the web page at the URL given below) that matches the character set of the database. For example, you can use 'UTF8' for a UTF-8 database, or 'EUC_JP' for a Japanese EUC database.

For details regarding Supported Encodings for Java, please see: http://java.sun.com/j2se/1.3/docs/guide/intl/encoding.doc.html.


Sample Code:

This code would load and register the driver, configure the driver and then connect to the database.

Connection connection = null
String url = new String("jdbc:simba://local.server.com/ServerDataSource");
// Load and register the driver
Class.forName ("Simba.jdbc.SimbaDriver");
//Create the connection properties
Properties props = new Properties();
props.put("user", m_txUserName.getText()); //username
props.put("password", m_txPassword.getText()); //password
props.put("ExecDesc", "DBSample"); //Executable Description
props.put("ArrayBufferSize", "8"); //Set array fetching size to 8K
try
{
m_Connection = DriverManager.getConnection(szurl, props);

// Here is an alternative means of obtaining a connection:
// m_Connection = DriverManager.getConnection(szURL,
// m_txUserName.getText(),

// m_txPassword.getText());
m_Connection.clearWarnings();
}

catch (SQLException e)
{
System.out.println("The driver could not connect: " + e.getMessage());
}

[Top] [Prev][Next][Bottom]


csr@unify.com

Copyright © 1998-9, 2002, Unify Corporation. All rights reserved.