progress datadirect connectxe for jdbc for impala · 2018-02-28 · what'snewinthisrelease?...

Progress® DataDirectConnect XE® for JDBC™ forImpala™

User's Guide

Release 5.1.4

Copyright

© 2018 Progress Software Corporation and/or its subsidiaries or affiliates. All rightsreserved.These materials and all Progress® software products are copyrighted and all rights are reserved by ProgressSoftware Corporation. The information in these materials is subject to change without notice, and ProgressSoftware Corporation assumes no responsibility for any errors that may appear therein. The references in thesematerials to specific platforms supported are subject to change.

Corticon, DataDirect (and design), DataDirect Cloud, DataDirect Connect, DataDirect Connect64, DataDirectXML Converters, DataDirect XQuery, DataRPM, Deliver More Than Expected, Icenium, Kendo UI, NativeScript,OpenEdge, Powered by Progress, Progress, Progress Software Developers Network, Rollbase, SequeLink,Sitefinity (and Design), SpeedScript, Stylus Studio, TeamPulse, Telerik, Telerik (and Design), Test Studio, andWebSpeed are registered trademarks of Progress Software Corporation or one of its affiliates or subsidiariesin the U.S. and/or other countries. Analytics360, AppServer, BusinessEdge, DataDirect Spy, SupportLink,DevCraft, Fiddler, JustAssembly, JustDecompile, JustMock, Kinvey, NativeScript Sidekick, OpenAccess,ProDataSet, Progress Results, Progress Software, ProVision, PSE Pro, Sitefinity, SmartBrowser,SmartComponent, SmartDataBrowser, SmartDataObjects, SmartDataView, SmartDialog, SmartFolder,SmartFrame, SmartObjects, SmartPanel, SmartQuery, SmartViewer, SmartWindow, and WebClient aretrademarks or service marks of Progress Software Corporation and/or its subsidiaries or affiliates in the U.S.and other countries. Java is a registered trademark of Oracle and/or its affiliates. Any other marks containedherein may be trademarks of their respective owners.

Please refer to the readme applicable to the particular Progress product release for any third-partyacknowledgements required to be provided in the documentation associated with the Progress product.

Updated: 2018/02/28

3Progress® DataDirect Connect XE® for JDBC™ for Impala™: User's Guide: Version 5.1.4

Progress® DataDirect Connect XE® for JDBC™ for Impala™: User's Guide: Version 5.1.44

Copyright

Table of Contents

Chapter 1: Welcome to the Progress DataDirect Connect XE for JDBC forImpala Driver.............................................................................................11

What's New in this Release?................................................................................................................12Requirements........................................................................................................................................12Data Source and Driver Classes...........................................................................................................13Connection URL....................................................................................................................................14Version String Information.....................................................................................................................14Connection Properties..........................................................................................................................15Data Types............................................................................................................................................15

getTypeInfo................................................................................................................................16Contacting Technical Support...............................................................................................................20

Chapter 2: Getting Started ..........................................................................23Data Source and Driver Classes...........................................................................................................23Setting the Classpath ...........................................................................................................................24Connecting Using the Driver Manager..................................................................................................24

Passing the Connection URL.....................................................................................................25Testing the Connection...............................................................................................................25

Connecting Using Data Sources...........................................................................................................28How Data Sources Are Implemented.........................................................................................29Creating Data Sources...............................................................................................................29Calling a Data Source in an Application.....................................................................................30Testing a DataSource Connection..............................................................................................30

Chapter 3: Using the Driver.........................................................................35Required Permissions for Java Platform...............................................................................................36

Permissions for Establishing Connections.................................................................................36Granting Access to Java Properties...........................................................................................37Granting Access to Temporary Files..........................................................................................37

Connecting from an Application............................................................................................................37Connecting Using the JDBC Driver Manager.............................................................................37Connecting Using Data Sources................................................................................................41

Using Connection Properties................................................................................................................46Required Properties...................................................................................................................47Data Encryption Properties........................................................................................................47Data Type Handling Properties..................................................................................................49Client Information Properties......................................................................................................50


Contents

Statement Pooling Properties....................................................................................................51Additional Properties..................................................................................................................52

Performance Considerations................................................................................................................54Authentication.......................................................................................................................................55Data Encryption....................................................................................................................................55

Configuring SSL Encryption.......................................................................................................55Configuring SSL Server Authentication......................................................................................56Configuring SSL Client Authentication.......................................................................................57

Client Information..................................................................................................................................58How Databases Store Client Information...................................................................................58Returning Client Information......................................................................................................59Returning MetaData About Client Information Locations...........................................................60

IP Addresses.........................................................................................................................................60Parameter Metadata Support................................................................................................................60

Insert, Update, and Delete Statements......................................................................................61Select Statements......................................................................................................................61SQL Support..............................................................................................................................62

ResultSet Metadata Support.................................................................................................................62Isolation Levels.....................................................................................................................................62Unicode.................................................................................................................................................63Error Handling.......................................................................................................................................63Large Object Support............................................................................................................................63Rowset Support....................................................................................................................................64Timeouts...............................................................................................................................................64Using Scrollable Cursors......................................................................................................................64Limitations on Cloudera Impala Functionality.......................................................................................65Connection Pool Manager....................................................................................................................65

How Connection Pooling Works.................................................................................................65Implementing DataDirect Connection Pooling...........................................................................67Configuring the Connection Pool...............................................................................................70Connecting Using a Connection Pool........................................................................................71Closing the Connection Pool......................................................................................................73Checking the Pool Manager Version..........................................................................................73Enabling Pool Manager Tracing.................................................................................................73Connection Pool Manager Interfaces.........................................................................................74

Statement Pool Monitor........................................................................................................................79Using DataDirect-Specific Methods to Access the Statement Pool Monitor..............................79Using JMX to Access the Statement Pool Monitor.....................................................................82Importing Statements into a Statement Pool..............................................................................83Clearing All Statements in a Statement Pool.............................................................................84Freezing and Unfreezing the Statement Pool............................................................................84Generating a Statement Pool Export File...................................................................................84DataDirect Statement Pool Monitor Interfaces and Classes......................................................85

DataDirect Test......................................................................................................................................87DataDirect Test Tutorial..............................................................................................................87


Contents

Tracking JDBC Calls with DataDirect Spy..........................................................................................120Enabling DataDirect Spy..........................................................................................................120

Chapter 4: Connection Property Descriptions........................................125AccountingInfo....................................................................................................................................128ApplicationName.................................................................................................................................129ClientHostName..................................................................................................................................129ClientUser...........................................................................................................................................130ConnectionRetryCount........................................................................................................................131ConnectionRetryDelay........................................................................................................................132ConvertNull.........................................................................................................................................132CryptoProtocolVersion........................................................................................................................133DatabaseName...................................................................................................................................134DefaultOrderByLimit............................................................................................................................135EncryptionMethod ..............................................................................................................................135HostNameInCertificate........................................................................................................................137ImportStatementPool..........................................................................................................................138InitializationString................................................................................................................................138InsensitiveResultSetBufferSize...........................................................................................................139JavaDoubleToString............................................................................................................................140KeyPassword......................................................................................................................................141KeyStore.............................................................................................................................................141KeyStorePassword.............................................................................................................................142LoginTimeout......................................................................................................................................143MaxPooledStatements........................................................................................................................144Password............................................................................................................................................145PortNumber.........................................................................................................................................145ProgramID...........................................................................................................................................146RegisterStatementPoolMonitorMBean................................................................................................146RemoveColumnQualifiers...................................................................................................................147ServerName........................................................................................................................................148SpyAttributes.......................................................................................................................................148StringDescribeType.............................................................................................................................149TransactionMode................................................................................................................................150TrustStore...........................................................................................................................................151TrustStorePassword............................................................................................................................151UseCurrentSchema............................................................................................................................152User.....................................................................................................................................................153ValidateServerCertificate.....................................................................................................................153

Chapter 5: Troubleshooting......................................................................155Troubleshooting your application........................................................................................................155

Turning On and Off DataDirect Spy Logging............................................................................156


Contents

DataDirect Spy Log Example...................................................................................................156Troubleshooting Connection Pooling..................................................................................................158

Enabling Tracing with the setTracing Method..........................................................................158Pool Manager Trace File Example...........................................................................................159

Troubleshooting Statement Pooling....................................................................................................162Generating an Export File with the exportStatement Method..................................................163Statement Pool Export File Example.......................................................................................163

Configuring Logging............................................................................................................................163Using the JVM for Logging.......................................................................................................164

Chapter 6: Supported SQL Functionality.................................................165Data Definition Language...................................................................................................................166Column Name Qualification................................................................................................................166From Clause........................................................................................................................................166Group By Clause.................................................................................................................................167Having Clause.....................................................................................................................................167Order By Clause.................................................................................................................................167For Update Clause..............................................................................................................................168Set Operators......................................................................................................................................168Subqueries..........................................................................................................................................168SQL Expressions................................................................................................................................169

Constants.................................................................................................................................169Numeric Operators...................................................................................................................169Character Operator..................................................................................................................170Relational Operators................................................................................................................170Logical Operators.....................................................................................................................170Functions..................................................................................................................................171

Restrictions.........................................................................................................................................173

Chapter 7: SQL Escape Sequences for JDBC.........................................175Date, time, and timestamp escape sequences...................................................................................176Scalar Functions.................................................................................................................................176Outer Join Escape Sequences...........................................................................................................177LIKE escape character sequence for wildcards..................................................................................178Procedure Call Escape Sequences....................................................................................................178

Chapter 8: JDBC support..........................................................................179JDBC and JVM Compatibility..............................................................................................................179Supported Functionality......................................................................................................................179

Array.........................................................................................................................................180Blob..........................................................................................................................................180CallableStatement....................................................................................................................181Clob..........................................................................................................................................193


Contents

Connection...............................................................................................................................194ConnectionEventListener.........................................................................................................199ConnectionPoolDataSource.....................................................................................................199DatabaseMetaData..................................................................................................................200DataSource..............................................................................................................................208Driver........................................................................................................................................209ParameterMetaData.................................................................................................................209PooledConnection....................................................................................................................210PreparedStatement..................................................................................................................211Ref............................................................................................................................................216ResultSet..................................................................................................................................216ResultSetMetaData..................................................................................................................227RowSet.....................................................................................................................................228SavePoint.................................................................................................................................228Statement.................................................................................................................................228StatementEventListener...........................................................................................................232Struct........................................................................................................................................232XAConnection..........................................................................................................................233XADataSource.........................................................................................................................233XAResource.............................................................................................................................233

Chapter 9: JDBC Extensions.....................................................................235Using JDBC Wrapper Methods to Access JDBC Extensions.............................................................236DatabaseMetaData interface..............................................................................................................236DDBulkLoad Interface.........................................................................................................................237ExtConnection Interface......................................................................................................................244ExtDatabaseMetaData Interface.........................................................................................................249ExtLogControl class............................................................................................................................249

Chapter 10: Designing JDBC Applications for PerformanceOptimization............................................................................................251

Using Database Metadata Methods....................................................................................................252Minimizing the Use of Database Metadata Methods................................................................252Avoiding Search Patterns.........................................................................................................253Using a Dummy Query to Determine Table Characteristics.....................................................253

Returning Data....................................................................................................................................254Returning Long Data................................................................................................................254Reducing the Size of Returned Data........................................................................................255Choosing the Right Data Type.................................................................................................255Retrieving Result Sets..............................................................................................................255

Selecting JDBC Objects and Methods ...............................................................................................256Using Parameter Markers as Arguments to Stored Procedures..............................................256Using the Statement Object Instead of the PreparedStatement Object...................................256


Contents

Using Batches Instead of Prepared Statements......................................................................257Choosing the Right Cursor.......................................................................................................258Using get Methods Effectively..................................................................................................258Retrieving Auto Generated Keys..............................................................................................259

Managing Connections and Updates..................................................................................................259Managing Connections............................................................................................................260Managing Commits in Transactions.........................................................................................260Choosing the Right Transaction Model....................................................................................261Using updateXXX Methods......................................................................................................261Using getBestRowIdentifier......................................................................................................261

Glossary.......................................................................................................263

Index.............................................................................................................267


Contents

1Welcome to the ProgressDataDirect ConnectXE for JDBC for Impala Driver

The Progress DataDirect Connect XE for JDBC for Impala driver supports Cloudera Impala, versions 1.3 andhigher.

The Cloudera Impala server is compatible with data stored in various file formats. In addition, Cloudera Impalacan work with data stored in other systems through the use of storage handlers. The driver is designed to workseamlessly with the file formats and storage handlers used by the server.

For details, see the following topics:

• What's New in this Release?

• Requirements

• Data Source and Driver Classes

• Connection URL

• Version String Information

• Connection Properties

• Data Types

• Contacting Technical Support


What's New in this Release?Changes Since the 5.1.4 ReleaseFor the latest certifications and enhancements, refer to the release notes for Progress DataDirect for JDBCdrivers.

• Certifications

• Cloudera Impala 2.4, 2.5, and 2.6.

Driver version 5.1.4.000083 (F000302.U000131)

• Cloudera Impala 2.2 and 2.3.

Driver version 5.1.4.000062 (F000260.U000115)

• Driver Enhancements

• The driver has been enhanced to support SSL data encryption. See Data Encryption on page 55 andData Encryption Properties on page 47 for details.

• The driver no longer registers the Statement Pool Monitor as a JMX MBean by default. To register theStatement Pool Monitor and manage statement pooling with standard JMX API calls, the newRegisterStatementPoolMonitorMBean connection property must be set to true. See Statement PoolMonitor on page 79 and RegisterStatementPoolMonitorMBean on page 146 for details.

Highlights of the 5.1.4 Release• Certifications

• Cloudera Impala 2.0 and 2.1.

• Driver Enhancements

• The driver has been enhanced to support the Char and Vachar data type with Cloudera Impala 2.1 andhigher. See Data Types on page 15 for details.

• Support for result set holdability has been added to the driver.

Release Features• The driver supports standard SQL query language for read-write access to Cloudera Impala data stores.

See Supported SQL Functionality on page 165 for details.

• The driver supports all JDBC Core functions. See JDBC support on page 179 for details.

• Supports Cloudera Impala data types. See Data Types on page 15 for details.

RequirementsThe driver is compliant with JDBC 4.0 and earlier specifications. The following table lists the product requirementsfor using the driver.


Chapter 1: Welcome to the Progress DataDirect Connect XE for JDBC for Impala Driver

https://www.progress.com/jdbc/whats-new

Table 1: Product Requirements

Product RequirementsFor Applications Using...

Java SE 6 or higherJDBC 4.0 API


Java SE 5 or higherJSR 114 Rowsets


Note: Standard installations of Java SE on some platforms do not include the jar file containing the extendedencoding set that is required to support some of the less common database code pages. Check your Java SEinstallation to make sure that the charsets.jar is installed in the lib subdirectory of your Java SE installationdirectory. If you do not have the charsets.jar file, re-install Java SE, making sure that you install the internationalversion of Java SE.

Note: To use the driver on a Java Platform with standard Security Manager enabled, certain permissions mustbe set in the security policy file of the Java Platform. See "Required Permissions for Java Platform" for details.

See alsoRequired Permissions for Java Platform on page 36

Data Source and Driver ClassesThe driver class for the Impala driver is:

com.ddtek.jdbc.impala.ImpalaDriver

Two data source classes are provided with the driver. Which data source class you use depends on the JDBCfunctionality your application requires. The following table shows the recommended data source class to usewith different JDBC specifications.

Table 2: Choosing a Data Source Class

Data Source ClassJVM VersionIf your applicationrequires...

com.ddtek.jdbcx.impala.ImpalaDataSource40Java SE 6 orhigher

JDBC 4.0 functionality andhigher

com.ddtek.jdbcx.impala.ImpalaDataSourceJava SE 5 orhigher

JDBC 3.x functionality andearlier specifications

See "Connecting Using Data Sources" for information about connecting using data sources.

See alsoConnecting Using Data Sources on page 28


Data Source and Driver Classes

Connection URLAfter registering the driver, the required connection information needs to be passed in the form of a connectionURL. The connection URL takes the form:

jdbc:datadirect:impala://servername:[port][;property=value[;...]]

where:

servername

specifies the name or the IP address of the server to which you want to connect.

port

specifies the port number of the server listener. The default is 21050.

property=value

specifies connection property settings. Multiple properties are separated by a semi-colon. For moreinformation on connection properties, see "Using Connection Properties."

The install_dir/samples directory, where install_dir is your product installation directory, containsa sample application that illustrates the steps of connecting to a Cloudera Impala server.

This example shows how to establish a connection to a Cloudera Impala server with user ID/passwordauthentication:

Connection conn = DriverManager.getConnection("jdbc:datadirect:impala://Server3:21050;DatabaseName=Test;User=admin;Password=adminpass");

See alsoUsing Connection Properties on page 46

Version String InformationThe DatabaseMetaData.getDriverVersion() method returns a Driver Version string in the format:

M.m.s.bbbbbb(FYYYYYY.UZZZZZZ)

where:

M is the major version number.

m is the minor version number.

s is the service pack number.

bbbbbb is the driver build number.

YYYYYY is the framework build number.

ZZZZZZ is the utl build number.



For example:

5.1.4.000002(F000001.U000002)|____| |_____| |_____|Driver Frame Utl

Connection PropertiesThe driver includes over 20 connection properties. You can use these connection properties to customize thedriver for your environment. Connection properties can be used to accomplish different tasks, such asimplementing driver functionality and optimizing performance. You can specify connection properties in aconnection URL or within a JDBC data source object.

See "Using Connection Properties" and "Connection Property Descriptions" for more information.

See alsoUsing Connection Properties on page 46Connection Property Descriptions on page 125

Data TypesThe following table shows how the Impala data types are mapped to the standard JDBC data types.

Table 3: Impala Data Types

JDBCImpala

BIGINTBigint

BOOLEANBoolean

CHARChar1

DECIMALDecimal2

DOUBLEDouble

REALFloat

INTEGERInt

SMALLINTSmallint

VARCHAR or LONGVARCHAR4String3

1 Supported for Cloudera Impala 2.1 and higher.2 Supported for Cloudera Impala 1.4 and higher.4 If the StringDescribeType connection property is set to varchar (the default), the String data type maps to VARCHAR. If

StringDescribeType is set to longvarchar, String maps to LONGVARCHAR.3 Maximum of 2 GB


Connection Properties

JDBCImpala

TIMESTAMPTimestamp

TINYINTTinyint

VARCHARVarchar5

getTypeInfoThe following table provides getTypeInfo results for all sources supported by the driver.

Table 4: getTypeInfo

MINIMUM_SCALE = 0

NULLABLE = 1

NUM_PREC_RADIX = 10

PRECISION = 19

SEARCHABLE = 3

SQL_DATA_TYPE = NULL

SQL_DATETIME_SUB = NULL

UNSIGNED_ATTRIBUTE = false

TYPE_NAME = bigint

AUTO_INCREMENT = false

CASE_SENSITIVE = false

CREATE_PARAMS = NULL

DATA_TYPE = -5 (BIGINT)

FIXED_PREC_SCALE = false

LITERAL_PREFIX = NULL

LITERAL_SUFFIX = NULL

LOCAL_TYPE_NAME = bigint

MAXIMUM_SCALE = 0

MINIMUM_SCALE = NULL

NULLABLE = 1

NUM_PREC_RADIX = 10

PRECISION = 1

SEARCHABLE = 2



UNSIGNED_ATTRIBUTE = NULL

TYPE_NAME = boolean

AUTO_INCREMENT = NULL



DATA_TYPE = 16 (BOOLEAN)




LOCAL_TYPE_NAME = boolean

MAXIMUM_SCALE = NULL

5 Supported for Cloudera Impala 2.1 and higher.




NULLABLE = 1

NUM_PREC_RADIX = NULL

PRECISION = 255

SEARCHABLE = 3




TYPE_NAME = char6


CASE_SENSITIVE = true


DATA_TYPE = 1 (CHAR)

FIXED_PREC_SCALE = true

LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = char


MINIMUM_SCALE = 0

NULLABLE = 1

NUM_PREC_RADIX = 10

PRECISION = 38

SEARCHABLE = 3




TYPE_NAME = decimal7




DATA_TYPE = 3 (DECIMAL)




LOCAL_TYPE_NAME = decimal

MAXIMUM_SCALE = 38


NULLABLE = 1

NUM_PREC_RADIX = 10

PRECISION = 15

SEARCHABLE = 3




TYPE_NAME = double




DATA_TYPE = 8 (DOUBLE)




LOCAL_TYPE_NAME = double


6 Supported for Cloudera Impala 2.1 and higher.7 Supported for Cloudera Impala 1.4 and higher.


Data Types


NULLABLE = 1

NUM_PREC_RADIX = 10

PRECISION = 7

SEARCHABLE = 3




TYPE_NAME = float




DATA_TYPE = 7 (REAL)




LOCAL_TYPE_NAME = float


MINIMUM_SCALE = 0

NULLABLE = 1

NUM_PREC_RADIX = 10

PRECISION = 10

SEARCHABLE = 3




TYPE_NAME = int




DATA_TYPE = 4 (INTEGER)




LOCAL_TYPE_NAME = int

MAXIMUM_SCALE = 0

MINIMUM_SCALE = 0

NULLABLE = 1

NUM_PREC_RADIX = 10

PRECISION = 5

SEARCHABLE = 3




TYPE_NAME = smallint




DATA_TYPE = 5 (SMALLINT)



LITERAL_SUFFIX = S

LOCAL_TYPE_NAME = smallint

MAXIMUM_SCALE = 0




NULLABLE = 1


PRECISION = 2147483647

SEARCHABLE = 3




TYPE_NAME = string8




DATA_TYPE = 12 (VARCHAR) or -1(LONGVARCHAR)9


LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = string


MINIMUM_SCALE = 0

NULLABLE = 1


PRECISION = 29

SEARCHABLE = 3




TYPE_NAME = timestamp




DATA_TYPE = 93 (TIMESTAMP)


LITERAL_PREFIX = {ts'

LITERAL_SUFFIX = '}

LOCAL_TYPE_NAME = timestamp

MAXIMUM_SCALE = 9

8 Maximum of 2 GB9 If the StringDescribeType connection property is set to varchar (the default), the String data type maps to VARCHAR. If

StringDescribeType is set to longvarchar, String maps to LONGVARCHAR.


Data Types

MINIMUM_SCALE = 0

NULLABLE = 1

NUM_PREC_RADIX = 10

PRECISION = 3

SEARCHABLE = 3




TYPE_NAME = tinyint




DATA_TYPE = -6 (TINYINT)



LITERAL_SUFFIX = Y

LOCAL_TYPE_NAME = tinyint

MAXIMUM_SCALE = 0

MINIMUM_SCALE = 0

NULLABLE = 1


PRECISION = 2147483647

SEARCHABLE = 3




TYPE_NAME = varchar10




DATA_TYPE = 12 (VARCHAR)


LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = varchar

MAXIMUM_SCALE = 0

Contacting Technical SupportProgress DataDirect offers a variety of options to meet your support needs. Please visit our Web site for moredetails and for contact information:

https://www.progress.com/support

The Progress DataDirect Web site provides the latest support information through our global service network.The SupportLink program provides access to support contact details, tools, patches, and valuable information,including a list of FAQs for each product. In addition, you can search our Knowledgebase for technical bulletinsand other information.

When you contact us for assistance, please provide the following information:

• Your number or the serial number that corresponds to the product for which you are seeking support, or acase number if you have been provided one for your issue. If you do not have a SupportLink contract, theSupportLink representative assisting you will connect you with our Sales team.

10 Supported for Cloudera Impala 2.1 and higher.



https://www.progress.com/support

• Your name, phone number, email address, and organization. For a first-time call, you may be asked for fullinformation, including location.

• The Progress DataDirect product and the version that you are using.

• The type and version of the operating system where you have installed your product.

• Any database, database version, third-party software, or other environment information required to understandthe problem.

• A brief description of the problem, including, but not limited to, any error messages you have received, whatsteps you followed prior to the initial occurrence of the problem, any trace logs capturing the issue, and soon. Depending on the complexity of the problem, you may be asked to submit an example or reproducibleapplication so that the issue can be re-created.

• A description of what you have attempted to resolve the issue. If you have researched your issue on Websearch engines, our Knowledgebase, or have tested additional configurations, applications, or other vendorproducts, you will want to carefully note everything you have already attempted.

• A simple assessment of how the severity of the issue is impacting your organization.


Contacting Technical Support

2Getting Started

After the driver has been installed and defined on your class path, you can connect from your application toyour database in either of the following ways.

• Using the JDBC DriverManager, by specifying the connection URL in theDriverManager.getConnection() method.

• Creating a JDBC DataSource that can be accessed through the Java Naming Directory Interface (JNDI).


• Data Source and Driver Classes

• Setting the Classpath

• Connecting Using the Driver Manager

• Connecting Using Data Sources

Data Source and Driver ClassesThe driver class for the Impala driver is:

com.ddtek.jdbc.impala.ImpalaDriver

Two data source classes are provided with the driver. Which data source class you use depends on the JDBCfunctionality your application requires. The following table shows the recommended data source class to usewith different JDBC specifications.


Table 5: Choosing a Data Source Class

Data Source ClassJVM VersionIf your applicationrequires...

com.ddtek.jdbcx.impala.ImpalaDataSource40Java SE 6 orhigher

JDBC 4.0 functionality andhigher

com.ddtek.jdbcx.impala.ImpalaDataSourceJava SE 5 orhigher

JDBC 3.x functionality andearlier specifications

See "Connecting Using Data Sources" for information about connecting using data sources.

See alsoConnecting Using Data Sources on page 28

Setting the ClasspathThe driver must be defined in your CLASSPATH variable. The CLASSPATH is the search string your JavaVirtual Machine (JVM) uses to locate JDBC drivers on your computer. If the driver is not defined on yourCLASSPATH, you will receive a class not found exception when trying to load the driver. Set your systemCLASSPATH to include the impala.jar file as shown, where install_dir is the path to your product installationdirectory:

install_dir/lib/impala.jar

Windows ExampleCLASSPATH=.;C:\Program Files\Progress\DataDirect\JDBC_51\lib\impala.jar

UNIX ExampleCLASSPATH=.:/opt/Progress/DataDirect/JDBC_51/lib/impala.jar

Connecting Using the Driver ManagerOne way to connect to an Impala database is through the JDBC DriverManager using theDriverManager.getConnection()method. As the following example shows, this method specifies a stringcontaining a connection URL.



Chapter 2: Getting Started

Passing the Connection URLAfter registering the driver, the required connection information needs to be passed in the form of a connectionURL. The connection URL takes the form:


where:

servername


port


property=value






Testing the ConnectionYou can use DataDirect Test

™

to verify your connection. The screen shots in this section were taken on aWindows system.

To test the connection from the driver to your data source, follow these steps:

1. Navigate to the installation directory. The default location is:

• Windows systems: Program Files\Progress\DataDirect\JDBC_51\testforjdbc

• UNIX and Linux systems: /opt/Progress/DataDirect/JDBC_51/testforjdbc

Note: For UNIX/Linux, if you do not have access to /opt, your home directory will be used in its place.

2. From the testforjdbc folder, run the platform-specific tool:

• testforjdbc.bat (on Windows systems)• testforjdbc.sh (on UNIX and Linux systems)


Connecting Using the Driver Manager

The Test for JDBC Tool window appears:

3. Click Press Here to Continue.

The main dialog appears:



4. From the menu bar, select Connection > Connect to DB.

The Select A Database dialog appears:

5. Select the appropriate database template from the Defined Databases field.

6. In the Database field, specify the correct ServerName and PortNumber for your Cloudera Impala datasource.

For example:

jdbc:datadirect:impala://Server3:21050;databaseName=Test


Connecting Using the Driver Manager

7. If required, enter your user name and password in the fields provided.

8. Click Connect.

If the connection information is entered correctly, the JDBC/Database Outputwindow reports that a connectionhas been established. (If a connection is not established, the window reports an error.)

For more information about using DataDirect Test, see "DataDirect Test."

See alsoDataDirect Test on page 87

Connecting Using Data SourcesA JDBC data source is a Java object, specifically a DataSource object, that defines connection informationrequired for a JDBC driver to connect to the database. Each JDBC driver vendor provides their own data sourceimplementation for this purpose. A Progress DataDirect data source is Progress DataDirect’s implementationof a DataSource object that provides the connection information needed for the driver to connect to a database.

Because data sources work with the Java Naming Directory Interface (JNDI) naming service, data sourcescan be created and managed separately from the applications that use them. Because the connection informationis defined outside of the application, the effort to reconfigure your infrastructure when a change is made isminimized. For example, if the database is moved to another database server, the administrator need onlychange the relevant properties of the data source (DataSource object). The applications using the databasedo not need to change because they only refer to the name of the data source.



How Data Sources Are ImplementedData sources are implemented through a data source class. A data source class implements the followinginterfaces:

• javax.sql.DataSource

• javax.sql.ConnectionPoolDataSource (allows applications to use connection pooling)

See "Data Source and Driver Classes" for data source class information.

See alsoData Source and Driver Classes on page 13

Creating Data SourcesThe following examples show how to create and use Progress DataDirect data sources:

• JNDI_LDAP_Example.java can be used to create a JDBC data source and save it in your LDAP directoryusing the JNDI Provider for LDAP.

• JNDI_FILESYSTEM_Example.java can be used to create a JDBC data source and save it in your localfile system using the File System JNDI Provider.

Note:

To connect using a data source, the driver needs to access a JNDI data store to persist the data sourceinformation. To download the JNDI File System Service Provider, go to the Oracle Technology Network JavaSE Support downloads page and make sure that the fscontext.jar and providerutil.jar files from the downloadare on your classpath.

You can use these examples as templates to create your own data sources. These examples are in theinstall_dir/examples/JNDI directory, where install_dir is your product installation directory.

Note:

You must include the javax.sql.* and javax.naming.* classes to create and use Progress DataDirect datasources. The driver provides the necessary JAR files, which contain the required classes and interfaces. If youplan to connect using a JDBC data source, the fscontext.jar and providerutil.jar files, which are shipped withthe JNDI File System Service Provider, must be on your classpath. To download the JNDI File System ServiceProvider, go to the Oracle Technology Network Java SE Support downloads page and select a JNDI version.

Example Data SourceTo configure a data source using the example files, you will need to create a data source definition. The contentrequired to create a data source definition is divided into three sections.


Connecting Using Data Sources

http://www.oracle.com/technetwork/java/javasebusiness/downloads/java-archive-downloads-java-plat-419418.html#7110-jndi-1.2.1-oth-JPR



First, you will need to import the data source class. For example:

import com.ddtek.jdbcx.impala.ImpalaDataSource;

Next, you will need to set the values and define the data source. For example, the following definition containsthe minimum properties required for a connection:

ImpalaDataSource mds = new ImpalaDataSource();mds.setDescription("My Impala Server");mds.setServerName("MyServer");mds.setPortNumber(21050);mds.setDatabaseName("myDB");

Finally, you will need to configure the example application to print out the data source attributes. Note that thiscode is specific to the driver and should only be used in the example application. For example, you would addthe following section for a binary connection using only the minimum properties:

if (ds instanceof ImpalaDataSource){ImpalaDataSource jmds = (ImpalaDataSource) ds;System.out.println("description=" + jmds.getDescription());System.out.println("serverName=" + jmds.getServerName());System.out.println("portNumber=" + jmds.getPortNumber());System.out.println("databaseName=" + jmds.getDatabaseName());System.out.println();}

Calling a Data Source in an ApplicationApplications can call a Progress DataDirect data source using a logical name to retrieve the javax.sql.DataSourceobject. This object loads the specified driver and can be used to establish a connection to the database.

Once the data source has been registered with JNDI, it can be used by your JDBC application as shown in thefollowing code example:

Context ctx = new InitialContext();DataSource ds = (DataSource)ctx.lookup("EmployeeDB");Connection con = ds.getConnection("domino", "spark");

In this example, the JNDI environment is first initialized. Next, the initial naming context is used to find thelogical name of the data source (EmployeeDB). The Context.lookup() method returns a reference to a Javaobject, which is narrowed to a javax.sql.DataSource object. Finally, the DataSource.getConnection() methodis called to establish a connection.

Testing a DataSource ConnectionYou can use DataDirect Test

™




• Windows systems: Program Files\Progress\DataDirect\JDBC_51\testforjdbc• UNIX and Linux systems: /opt/Progress/DataDirect/JDBC_51/testforjdbc



4. From the menu bar, select Connection > Connect to DB via Data Source.


5. Select a datasource template from the Defined Datasources field.

6. Provide the following information:

a) In the Initial Context Factory, specify the location of the initial context provider for your application.

b) In the Context Provider URL, specify the location of the context provider for your application.

c) In the Datasource field, specify the name of your datasource.



7. If you are using user ID/password authentication, enter your user ID and password in the correspondingfields.

8. Click Connect.




3Using the Driver

This section provides information on how to connect to your data store using either the JDBC Driver Manageror DataDirect JDBC data sources, as well as information on how to implement and use functionality supportedby the driver.


• Required Permissions for Java Platform

• Connecting from an Application

• Using Connection Properties

• Performance Considerations

• Authentication

• Data Encryption

• Client Information

• IP Addresses

• Parameter Metadata Support

• ResultSet Metadata Support

• Isolation Levels

• Unicode

• Error Handling

• Large Object Support


• Rowset Support

• Timeouts

• Using Scrollable Cursors

• Limitations on Cloudera Impala Functionality

• Connection Pool Manager

• Statement Pool Monitor

• DataDirect Test

• Tracking JDBC Calls with DataDirect Spy

Required Permissions for Java PlatformUsing the driver on a Java platform with the standard Security Manager enabled requires certain permissionsto be set in the Java SE security policy file java.policy. The default location of this file isjava_install_dir/jre/lib/security.

Note: Security manager may be enabled by default in certain scenarios (for example, when you are runningon an application server or in a Web browser applet).

To run an application on a Java platform with the standard Security Manager, use the following command:

"java -Djava.security.manager application_class_name"

where application_class_name is the class name of the application.

Refer to your Java documentation for more information about setting permissions in the security policy file.

Permissions for Establishing ConnectionsTo establish a connection to the database server, the driver must be granted the permissions as shown in thefollowing example:

grant codeBase "file:/install_dir/lib/-" {permission java.net.SocketPermission "*", "connect";

};

where:

install_dir

is the product installation directory.


Chapter 3: Using the Driver

Granting Access to Java PropertiesTo allow the driver to read the value of various Java properties to perform certain operations, permissions mustbe granted as shown in the following example:

grant codeBase "file:/install_dir/lib/-" {permission java.util.PropertyPermission "*", "read, write";

};

where:

install_dir


Granting Access to Temporary FilesAccess to the temporary directory specified by the JVM configuration must be granted in the Java SE securitypolicy file to use insensitive scrollable cursors or to perform client-side sorting of DatabaseMetaData resultsets. The following example shows permissions that have been granted for the C:\TEMP directory:

grant codeBase "file:/install_dir/lib/-" {// Permission to create and delete temporary files.// Adjust the temporary directory for your environment.

permission java.io.FilePermission "C:\\TEMP\\-", "read,write,delete";};

where:

install_dir


Connecting from an ApplicationOnce the driver is installed and configured, you can connect from your application to your database in eitherof the following ways:

• Using the JDBC Driver Manager, by specifying the connection URL in theDriverManager.getConnection() method.

• Creating a JDBC data source that can be accessed through the Java Naming Directory Interface (JNDI).

Connecting Using the JDBC Driver ManagerOne way to connect to a database is through the JDBC Driver Manager using the DriverManager.getConnection()method. This method specifies a string containing a connection URL. This example shows how to establish aconnection to a data source:

Connection conn = DriverManager.getConnection("jdbc:datadirect:impala://Server3:21050;User=admin;Password=adminpass");


Connecting from an Application

Passing the Connection URLAfter registering the driver, the required connection information needs to be passed in the form of a connectionURL. The connection URL takes the form:


where:

servername


port


property=value






Testing the ConnectionYou can use DataDirect Test

™











4. From the menu bar, select Connection > Connect to DB.


5. Select the appropriate database template from the Defined Databases field.

6. In the Database field, specify the correct ServerName and PortNumber for your Cloudera Impala datasource.

For example:

jdbc:datadirect:impala://Server3:21050;databaseName=Test



7. If required, enter your user name and password in the fields provided.

8. Click Connect.


For more information about using DataDirect Test, see "DataDirect Test."

See alsoDataDirect Test on page 87

Connecting Using Data SourcesA JDBC data source is a Java object, specifically a DataSource object, that defines connection informationrequired for a JDBC driver to connect to the database. Each JDBC driver vendor provides their own data sourceimplementation for this purpose. A Progress DataDirect data source is Progress DataDirect’s implementationof a DataSource object that provides the connection information needed for the driver to connect to a database.

Because data sources work with the Java Naming Directory Interface (JNDI) naming service, data sourcescan be created and managed separately from the applications that use them. Because the connection informationis defined outside of the application, the effort to reconfigure your infrastructure when a change is made isminimized. For example, if the database is moved to another database server, the administrator need onlychange the relevant properties of the data source (DataSource object). The applications using the databasedo not need to change because they only refer to the name of the data source.



How Data Sources Are ImplementedData sources are implemented through a data source class. A data source class implements the followinginterfaces:

• javax.sql.DataSource

• javax.sql.ConnectionPoolDataSource (allows applications to use connection pooling)

See "Data Source and Driver Classes" for data source class information.

See alsoData Source and Driver Classes on page 13

Creating Data SourcesThe following examples show how to create and use Progress DataDirect data sources:

• JNDI_LDAP_Example.java can be used to create a JDBC data source and save it in your LDAP directoryusing the JNDI Provider for LDAP.

• JNDI_FILESYSTEM_Example.java can be used to create a JDBC data source and save it in your localfile system using the File System JNDI Provider.

Note:

To connect using a data source, the driver needs to access a JNDI data store to persist the data sourceinformation. To download the JNDI File System Service Provider, go to the Oracle Technology Network JavaSE Support downloads page and make sure that the fscontext.jar and providerutil.jar files from the downloadare on your classpath.

You can use these examples as templates to create your own data sources. These examples are in theinstall_dir/examples/JNDI directory, where install_dir is your product installation directory.

Note:

You must include the javax.sql.* and javax.naming.* classes to create and use Progress DataDirect datasources. The driver provides the necessary JAR files, which contain the required classes and interfaces. If youplan to connect using a JDBC data source, the fscontext.jar and providerutil.jar files, which are shipped withthe JNDI File System Service Provider, must be on your classpath. To download the JNDI File System ServiceProvider, go to the Oracle Technology Network Java SE Support downloads page and select a JNDI version.

Example Data SourceTo configure a data source using the example files, you will need to create a data source definition. The contentrequired to create a data source definition is divided into three sections.






First, you will need to import the data source class. For example:

import com.ddtek.jdbcx.impala.ImpalaDataSource;

Next, you will need to set the values and define the data source. For example, the following definition containsthe minimum properties required for a connection:

ImpalaDataSource mds = new ImpalaDataSource();mds.setDescription("My Impala Server");mds.setServerName("MyServer");mds.setPortNumber(21050);mds.setDatabaseName("myDB");

Finally, you will need to configure the example application to print out the data source attributes. Note that thiscode is specific to the driver and should only be used in the example application. For example, you would addthe following section for a binary connection using only the minimum properties:

if (ds instanceof ImpalaDataSource){ImpalaDataSource jmds = (ImpalaDataSource) ds;System.out.println("description=" + jmds.getDescription());System.out.println("serverName=" + jmds.getServerName());System.out.println("portNumber=" + jmds.getPortNumber());System.out.println("databaseName=" + jmds.getDatabaseName());System.out.println();}

Calling a Data Source in an ApplicationApplications can call a Progress DataDirect data source using a logical name to retrieve the javax.sql.DataSourceobject. This object loads the specified driver and can be used to establish a connection to the database.

Once the data source has been registered with JNDI, it can be used by your JDBC application as shown in thefollowing code example:

Context ctx = new InitialContext();DataSource ds = (DataSource)ctx.lookup("EmployeeDB");Connection con = ds.getConnection("domino", "spark");

In this example, the JNDI environment is first initialized. Next, the initial naming context is used to find thelogical name of the data source (EmployeeDB). The Context.lookup() method returns a reference to a Javaobject, which is narrowed to a javax.sql.DataSource object. Finally, the DataSource.getConnection() methodis called to establish a connection.

Testing a DataSource ConnectionYou can use DataDirect Test

™








4. From the menu bar, select Connection > Connect to DB via Data Source.


5. Select a datasource template from the Defined Datasources field.

6. Provide the following information:

a) In the Initial Context Factory, specify the location of the initial context provider for your application.

b) In the Context Provider URL, specify the location of the context provider for your application.

c) In the Datasource field, specify the name of your datasource.



7. If you are using user ID/password authentication, enter your user ID and password in the correspondingfields.

8. Click Connect.


Using Connection PropertiesYou can use connection properties to customize the driver for your environment. Connection properties canbe used to accomplish different tasks, such as implementing driver functionality or optimizing performance.

You can specify connection properties using either of the following methods:

• JDBC Driver Manager (see "Connecting Using the JDBC Driver Manager")

• JDBC data sources (see "Connecting Using Data Sources")

Connection properties take the form property=value. All connection property names are case-insensitive.For example, Password is the same as password.

See "Connection Property Descriptions" for an alphabetical list of connection properties and their descriptions.

See alsoConnecting Using the JDBC Driver Manager on page 37



Connecting Using Data Sources on page 28Connection Property Descriptions on page 125

Required PropertiesThe following table summarizes connection properties which are required to connect to a database.

Table 6: Required Properties

CharacteristicProperty

Specifies the name of the Impala database. The database must exist, or theconnection attempt will fail.

DatabaseName on page134

The TCP port of the primary database server that is listening for connections tothe database.

The default is 21050.

PortNumber on page 145

Specifies either the IP address or the server name (if your network supports namedservers) of the primary database server.

ServerName on page 148

See alsoConnection Property Descriptions on page 125

Data Encryption PropertiesThe following table summarizes connection properties which can be used in the implementation of SSL dataencryption, including server and client authentication.

Table 7: Data Encryption Properties


Specifies a cryptographic protocol or comma-separated list of cryptographicprotocols that can be used when SSL is enabled (EncryptionMethod=SSL).

The default is determined by the settings of the JRE.

CryptoProtocolVersion onpage 133


Using Connection Properties


Determines whether data is encrypted and decrypted when transmitted overthe network between the driver and database server.

If set to noEncryption, data is not encrypted or decrypted.

If set to SSL, data is encrypted using SSL. If the database server does notsupport SSL, the connection fails and the driver throws an exception.

Note: Enabling SSL EncryptionMethod=SSL and Transport mode(TransportMode=http) configures the driver to use HTTPS end pointsinstead of HTTP end points.

The default is noEncryption.

EncryptionMethod on page135

Specifies a host name for certificate validation when SSL encryption is enabled(EncryptionMethod=SSL) and validation is enabled(ValidateServerCertificate=true). This property is optional and providesadditional security against man-in-the-middle (MITM) attacks by ensuring thatthe server the driver is connecting to is the server that was requested.

HostNameInCertificate onpage 137

Specifies the password that is used to access the individual keys in the keystorefile when SSL is enabled (EncryptionMethod=SSL) and SSL client authenticationis enabled on the database server. This property is useful when individual keysin the keystore file have a different password than the keystore file.

KeyPassword on page 141

Specifies the directory of the keystore file to be used when SSL is enabled(EncryptionMethod=SSL) and SSL client authentication is enabled on thedatabase server. The keystore file contains the certificates that the client sendsto the server in response to the server’s certificate request.

KeyStore on page 141

Specifies the password that is used to access the keystore file when SSL isenabled (EncryptionMethod=SSL) and SSL client authentication is enabled onthe database server. The keystore file contains the certificates that the clientsends to the server in response to the server’s certificate request.

KeyStorePassword on page142

Specifies the directory of the truststore file to be used when SSL is enabled(EncryptionMethod=SSL) and server authentication is used. The truststore filecontains a list of the Certificate Authorities (CAs) that the client trusts.

TrustStore on page 151




Specifies the password that is used to access the truststore file when SSL isenabled (EncryptionMethod=SSL) and server authentication is used. Thetruststore file contains a list of the Certificate Authorities (CAs) that the clienttrusts.

TrustStorePassword on page151

Determines whether the driver validates the certificate that is sent by thedatabase server when SSL encryption is enabled (EncryptionMethod=SSL).When using SSL server authentication, any certificate that is sent by the servermust be issued by a trusted Certificate Authority (CA).

If set to true, the driver validates the certificate that is sent by the databaseserver.

If set to false, the driver does not validate the certificate that is sent by thedatabase server.

The default is true.

ValidateServerCertificate onpage 153

See alsoConnection Property Descriptions on page 125Data Encryption on page 55

Data Type Handling PropertiesThe following table summarizes connection properties which can be used to handle data types.

Table 8: Data Type Handling Properties


Controls how data conversions are handled for null values.

If set to 0, the driver does not perform the data type check if the value ofthe column is null. This allows null values to be returned even though aconversion between the requested type and the column type is undefined.

If set to 1, the driver checks the data type being requested against thedata type of the table column that stores the data. If a conversion betweenthe requested type and column type is not defined, the driver generatesan "unsupported data conversion" exception regardless of whether thecolumn value is NULL.

The default is 1.

ConvertNull on page 132




Determines which algorithm the driver uses when converting a double orfloat value to a string value. By default, the driver uses its own internalconversion algorithm, which improves performance.

If set to true, the driver uses the JVM algorithm when converting a doubleor float value to a string value. If your application cannot accept roundingdifferences and you are willing to sacrifice performance, set this value totrue to use the JVM conversion algorithm.

If set to false, the driver uses its own internal algorithm when convertinga double or float value to a string value. This value improves performance,but slight rounding differences within the allowable error of the double andfloat data types can occur when compared to the same conversion usingthe JVM algorithm.

The default is false.

JavaDoubleToString on page 140

Specifies whether String columns are described as VARCHAR columns.This property affects ResultSetMetaData calls; it does not affectgetTypeInfo() calls.

If set to varchar, String columns are described as VARCHAR.

If set to longvarchar, String columns are described as LONGVARCHAR.

The default is varchar.

StringDescribeType on page 149

See alsoConnection Property Descriptions on page 125

Client Information PropertiesThe following table summarizes connection properties which can be used to return client information.

Table 9: Client Information Properties


Defines accounting information to be stored in the database. This value is storedlocally and is used for database administration/monitoring purposes.

AccountingInfo on page128

Specifies the name of the application to be stored in the database. This value isstored locally and is used for database administration/monitoring purposes.

ApplicationName on page129

Specifies the host name of the client machine to be stored in the database. Thisvalue is stored locally and is used for database administration/monitoring purposes.

ClientHostName on page129




Specifies the user ID to be stored in the database. This value is stored locally andis used for database administration/monitoring purposes.

ClientUser on page 130

Specifies the driver and version information on the client to be stored in thedatabase. This value is stored locally and is used for databaseadministration/monitoring purposes.

ProgramID on page 146

See also• Connection Property Descriptions on page 125

• Client Information Properties on page 50

Statement Pooling PropertiesThe following table summarizes statement pooling connection properties.

Table 10: Statement Pooling Properties


Specifies the path and file name of the file to be used to load thecontents of the statement pool. When this property is specified,statements are imported into the statement pool from the specified file.

ImportStatementPool on page 138

The maximum number of pooled prepared statements for thisconnection. If set to 0 (the default), the driver's internal preparedstatement pooling is not enabled. If set to a value greater than zero,the driver's internal prepared statement pooling is enabled. Enablingis useful when the driver is not running from within an application serveror another application that provides its own prepared statement pooling.By default, the driver's statement pooling is not enabled.

MaxPooledStatements on page 144

Registers the Statement Pool Monitor as a JMX MBean when statementpooling has been enabled with MaxPooledStatements. This allows youto manage statement pooling with standard JMX API calls and to useJMX-compliant tools, such as JConsole.

If set to true, the driver registers an MBean for the statement poolmonitor for each statement pool. This gives applications access to theStatement Pool Monitor through JMX when statement pooling isenabled.

If set to false, the driver does not register an MBean for the statementpool monitor for any statement pool.

RegisterStatementPoolMonitorMBeanon page 146


• Statement Pool Monitor on page 79



• Performance Considerations on page 54

Additional PropertiesThe following table summarizes additional connection properties.

Table 11: Additional Properties


Specifies the number of times the driver retries connection attempts tothe server until a successful connection is established.

If set to 0, the driver does not try to reconnect after the initial unsuccessfulattempt.

If set to x, the driver retries connection attempts the specified number oftimes. If a connection is not established during the retry attempts, thedriver returns an exception that is generated by the last Cloudera Impalaserver to which it tried to connect.

The default is 5.

ConnectionRetryCount on page 131

Specifies the number of seconds the driver waits between connectionretry attempts when ConnectionRetryCount is set to a positive integer.

If set to 0, the driver does not delay between retries.

If set to x, the driver waits between connection retry attempts the specifiednumber of seconds.

The default is 1 (second).

ConnectionRetryDelay on page 132

Specifies the maximum number of rows returned when a SQL statementcontaining an ORDER BY clause is executed. Cloudera Impala 1.3requires statements containing the ORDER BY clause to limit the numberof rows returned. This option allows these statements to return a resultset without specifying a limit in the application.

If set to -1 (disabled), there is no default limit to the number of rowsreturned by a statement containing an ORDER BY clause.

If set to x, the number of rows returned by a SQL statement containingan ORDER BY clause are limited to the specified number of rows for thesession.

The default is -1 (disabled).

DefaultOrderByLimit on page 135

Specifies one or multiple SQL commands to be executed by the driverafter it has established the connection to the database and has performedall initialization for the connection. If the execution of a SQL commandfails, the connection attempt also fails and the driver throws an exceptionindicating which SQL command or commands failed.

InitializationString on page 138




Determines the amount of memory used by the driver to cache insensitiveresult set data.

If set to -1, the driver caches insensitive result set data in memory.

If set to 0, the driver caches insensitive result set data in memory, up toa maximum of 2 MB.

If set to x, the driver caches insensitive result set data in memory anduses this value to set the size (in KB) of the memory buffer for cachinginsensitive result set data.

The default is 2048.

InsensitiveResultSetBufferSize onpage 139

Specifies the amount of time, in seconds, that the driver waits for aconnection to be established before timing out the connection request.

If set to 0, the driver does not time out a connection request.

If set to x, the driver waits for the specified number of seconds beforereturning control to the application and throwing a timeout exception.

The default is 0.

LoginTimeout on page 143

Specifies a password that is used to connect to the database.Password on page 145

Specifies whether the driver removes 3-part column qualifiers and replacesthem with alias.column qualifiers.

If set to true (enabled), the driver removes 3-part column qualifiers andreplaces them with alias.column qualifiers.

If set to false, the driver does not modify the request.

The default is false (Disabled).

RemoveColumnQualifiers on page147

Enables DataDirect Spy to log detailed information about calls issued bythe driver on behalf of the application. DataDirect Spy is not enabled bydefault.

SpyAttributes on page 148

Specifies how the driver handles manual transactions.

If set to ignore, the data source does not support transactions and thedriver always operates in auto-commit mode. Calls to set the driver tomanual commit mode and to commit transactions are ignored. Calls torollback a transaction cause the driver to throw an exception indicatingthat no transaction is started. Metadata indicates that the driver supportstransactions and the READ UNCOMMITTED transaction isolation level.

If set to noTransactions, the data source and the driver do not supporttransactions. Metadata indicates that the driver does not supporttransactions.

The default is noTransactions.

TransactionMode on page 150




Specifies whether results are restricted to the tables and views in thecurrent schema if a call is made without specifying a schema or if theschema is specified as the wildcard character %. Restricting results tothe tables and views in the current schema improves performance ofcalls that do not specify a schema.

If set to true, the results that are returned from getTables() andgetColumns() methods are restricted to the tables and views in the currentschema.

If set to false, the results that are returned from getTables() andgetColumns() methods are not restricted.

The default is false.

UseCurrentSchema on page 152

Specifies the user name that is used to connect to the database.User on page 153


• Performance Considerations on page 54

Performance ConsiderationsYou can optimize application performance by setting connection properties as described in this topic.

InsensitiveResultSetBufferSize: To improve performance when using scroll-insensitive result sets, the drivercan cache the result set data in memory instead of writing it to disk. By default, the driver caches 2 MB ofinsensitive result set data in memory and writes any remaining result set data to disk. Performance can beimproved by increasing the amount of memory used by the driver before writing data to disk or by forcing thedriver to never write insensitive result set data to disk. The maximum cache size setting is 2 GB.

MaxPooledStatements: To improve performance, the driver's own internal prepared statement pooling shouldbe enabled when the driver does not run from within an application server or from within another applicationthat does not provide its own prepared statement pooling. When the driver's internal prepared statement poolingis enabled, the driver caches a certain number of prepared statements created by an application. For example,if the MaxPooledStatements property is set to 20, the driver caches the last 20 prepared statements createdby the application. If the value set for this property is greater than the number of prepared statements used bythe application, all prepared statements are cached.

See "Designing JDBC Applications for Performance Optimization" for more information about using preparedstatement pooling to optimize performance.

StringDescribeType: To obtain data from String columns with the getClob() method, the StringDescribeTypeconnection property must be set to longvarchar. (Otherwise, calling getClob() results in an "unsupporteddata conversion" exception.) When StringDescribeType is set to longvarchar, the driver not only maps Stringto Longvarchar but also allocates more space to cache the long data. Because more space is allocated for thelong data, your application will incur a performance penalty.



UseCurrentSchema: If your application needs to access tables and views owned only by the current user,performance of your application can be improved by setting this property to true. When this property is set totrue, the driver returns only tables and views owned by the current user when executing getTables() andgetColumns() methods. Setting this property to true is equivalent to passing the user ID used on the connectionas the schemaPattern argument to the getTables() or getColumns() call.

See alsoDesigning JDBC Applications for Performance Optimization on page 251

AuthenticationThe driver supports user ID/password authentication. User ID/password authentication authenticates the userto the database using a database user name and password.

See alsoUsing Connection Properties on page 46Required Properties on page 47

Data EncryptionThe driver supports Secure Sockets Layer (SSL) data encryption. SSL is an industry-standard protocol forsending encrypted data over database connections. SSL works by allowing the client and server to send eachother encrypted data that only they can decrypt. SSL negotiates the terms of the encryption in a sequence ofevents known as the SSL handshake. The handshake involves the following types of authentication:

• SSL server authentication requires the server to authenticate itself to the client.

• SSL client authentication is optional and requires the client to authenticate itself to the server after the serverhas authenticated itself to the client.

Configuring SSL EncryptionThe following steps outline how to configure SSL encryption.

Note: Connection hangs can occur when the driver is configured for SSL and the database server does notsupport SSL. You may want to set a login timeout using the LoginTimeout property to avoid problems whenconnecting to a server that does not support SSL.

To configure SSL encryption:

1. Set the EncryptionMethod property to SSL.

2. Use the CryptoProtocolVersion property to specify acceptable cryptographic protocol versions (for example,TLSv1.2) supported by your server.

3. Specify the location and password of the truststore file used for SSL server authentication. Either set theTrustStore and TrustStorePassword properties or their corresponding Java system properties(javax.net.ssl.trustStore and javax.net.ssl.trustStorePassword, respectively).


Authentication

4. To validate certificates sent by the database server, set the ValidateServerCertificate property to true.

5. Optionally, set the HostNameInCertificate property to a host name to be used to validate the certificate. TheHostNameInCertificate property provides additional security against man-in-the-middle (MITM) attacks byensuring that the server the driver is connecting to is the server that was requested.

6. If your database server is configured for SSL client authentication, configure your keystore information:

a) Specify the location and password of the keystore file. Either set the KeyStore and KeyStorePasswordproperties or their corresponding Java system properties (javax.net.ssl.keyStore andjavax.net.ssl.keyStorePassword, respectively).

b) If any key entry in the keystore file is password-protected, set the KeyPassword property to the keypassword.

Configuring SSL Server AuthenticationWhen the client makes a connection request, the server presents its public certificate for the client to acceptor deny. The client checks the issuer of the certificate against a list of trusted Certificate Authorities (CAs) thatresides in an encrypted file on the client known as a truststore. Optionally, the client may check the subject(owner) of the certificate. If the certificate matches a trusted CA in the truststore (and the certificate’s subjectmatches the value that the application expects), an encrypted connection is established between the client andserver. If the certificate does not match, the connection fails and the driver throws an exception.

To check the issuer of the certificate against the contents of the truststore, the driver must be able to locatethe truststore and unlock the truststore with the appropriate password. You can specify truststore informationin either of the following ways:

• Specify values for the Java system properties javax.net.ssl.trustStore and javax.net.ssl.trustStorePassword.For example:

java -Djavax.net.ssl.trustStore=C:\Certificates\MyTruststore-Djavax.net.ssl.trustStorePassword=MyTruststorePassword

This method sets values for all SSL sockets created in the JVM.

• Specify values for the connection properties TrustStore and TrustStorePassword in the connection URL.For example:

TrustStore=C:\Certficates\MyTruststore

and

TrustStorePassword=MyTruststorePassword

Any values specified by the TrustStore and TrustStorePassword properties override values specified by theJava system properties. This allows you to choose which truststore file you want to use for a particularconnection.

Alternatively, you can configure the drivers to trust any certificate sent by the server, even if the issuer is nota trusted CA. Allowing a driver to trust any certificate sent from the server is useful in test environments becauseit eliminates the need to specify truststore information on each client in the test environment. If the driver isconfigured to trust any certificate sent from the server, the issuer information in the certificate is ignored.



Configuring SSL Client AuthenticationIf the server is configured for SSL client authentication, the server asks the client to verify its identity after theserver has proved its identity. Similar to SSL server authentication, the client sends a public certificate to theserver to accept or deny. The client stores its public certificate in an encrypted file known as a keystore.

The driver must be able to locate the keystore and unlock the keystore with the appropriate keystore password.Depending on the type of keystore used, the driver also may need to unlock the keystore entry with a passwordto gain access to the certificate and its private key.

The drivers can use the following types of keystores:

• Java Keystore (JKS) contains a collection of certificates. Each entry is identified by an alias. The value ofeach entry is a certificate and the certificate’s private key. Each keystore entry can have the same passwordas the keystore password or a different password. If a keystore entry has a password different than thekeystore password, the driver must provide this password to unlock the entry and gain access to the certificateand its private key.

• PKCS #12 keystores. To gain access to the certificate and its private key, the driver must provide thekeystore password. The file extension of the keystore must be .pfx or .p12.

You can specify this information in either of the following ways:

• Specify values for the Java system properties javax.net.ssl.keyStore and javax.net.ssl.keyStorePassword.For example:

java -Djavax.net.ssl.keyStore=C:\Certificates\MyKeystore-Djavax.net.ssl.keyStorePassword=MyKeystorePassword

This method sets values for all SSL sockets created in the JVM.

Note: If the keystore specified by the javax.net.ssl.keyStore Java system property is a JKS and the keystoreentry has a password different than the keystore password, the KeyPassword connection property must specifythe password of the keystore entry (for example, KeyPassword=MyKeyPassword).

• Specify values for the connection properties KeyStore and KeyStorePassword in the connection URL. Forexample:

KeyStore=C:\Certficates\MyKeyStore

and

KeyStorePassword=MyKeystorePassword

Note: If the keystore specified by the KeyStore connection property is a JKS and the keystore entry has apassword different than the keystore password, the KeyPassword connection property must specify the passwordof the keystore entry (for example, KeyPassword=MyKeyPassword).

Any values specified by the KeyStore and KeyStorePassword properties override values specified by the Javasystem properties. This allows you to choose which keystore file you want to use for a particular connection.


Data Encryption

Client InformationMany databases allow applications to store client information associated with a connection. For example, thefollowing types of information can be useful for database administration and monitoring purposes:

• Name of the application currently using the connection.

• User ID for whom the application using the connection is performing work. The user ID may be differentthan the user ID that was used to establish the connection.

• Host name of the client on which the application using the connection is running.

• Product name and version of the driver on the client.

• Additional information that may be used for accounting or troubleshooting purposes, such as an accountingID.

How Databases Store Client InformationTypically, databases that support storing client information do so by providing a register, a variable, or a columnin a system table in which the information is stored. If an application attempts to store information and thedatabase does not provide a mechanism for storing that information, the driver caches the information locally.Similarly, if an application returns client information and the database does not provide a mechanism for storingthat information, the driver returns the locally cached value.

For example, let’s assume that the following code returns a pooled connection to a database and sets a clientapplication name for that connection. In this example, the application sets the application name SALES157using the driver property ApplicationName.

// Get Database ConnectionConnection con = DriverManager.getConnection(

"jdbc:datadirect:impala://Server3:21050;DatabaseName=MyDB;ApplicationName=SALES157","TEST","secret");

...

The application name SALES157 is stored locally by the database. When the connection to the database isclosed, the client information on the connection is reset to an empty string.

Storing Client InformationYour application can store client information associated with a connection using any of the following methods:

• Using the driver connection properties listed in the following table. This table lists the connection propertiesyour application can use to store client information. Client information is stored locally. See "ConnectionProperty Descriptions" for a detailed description of each property.

• Using the following JDBC methods:

• Connection.setClientInfo(properties)

• Connection.setClientInfo(property_name, value)

See "JDBC support" for more information about these JDBC methods.

• Using the JDBC extension methods provided in the com.ddtek.jdbc.extensions package. See "JDBCExtensions" for more information about the com.ddtek.jdbc.extensions package.



Table 12: Client Information Properties


Defines accounting information to be stored in the database. This value is storedlocally and is used for database administration/monitoring purposes.

AccountingInfo on page128

Specifies the name of the application to be stored in the database. This value isstored locally and is used for database administration/monitoring purposes.

ApplicationName on page129

Specifies the host name of the client machine to be stored in the database. Thisvalue is stored locally and is used for database administration/monitoring purposes.

ClientHostName on page129

Specifies the user ID to be stored in the database. This value is stored locally andis used for database administration/monitoring purposes.

ClientUser on page 130

Specifies the driver and version information on the client to be stored in thedatabase. This value is stored locally and is used for databaseadministration/monitoring purposes.

ProgramID on page 146

See alsoConnection Property Descriptions on page 125JDBC support on page 179JDBC Extensions on page 235

Returning Client InformationYour application can return client information in the following ways:

• Using the following JDBC methods:

• Connection.getClientInfo()

• Connection.getClientInfo(property_name)

• DatabaseMetaData.getClientInfoProperties()

See "JDBC support" for more information about these JDBC methods.

• Using the JDBC extension methods provided in the com.ddtek.jdbc.extensions package. See "JDBCExtensions" for more information about the com.ddtek.jdbc.extensions package.

See alsoJDBC support on page 179JDBC Extensions on page 235


Client Information

Returning MetaData About Client Information LocationsYou may want to return metadata about the register, variable, or column in which the database stores clientinformation. For example, you may want to determine the maximum length allowed for a client informationvalue before you store that information. If your application attempts to set a client information value that exceedsthe maximum length allowed by the database, that value is truncated and the driver generates a warning.Determining the maximum length of the value beforehand can avoid this situation.

To return metadata about client information, call the DatabaseMetaData.getClientInfoProperties() method:// Get Database ConnectionConnection con = DriverManager.getConnection(

"jdbc:datadirect:impala://Server3:21050;DatabaseName=jdbc", "test", "secret");DatabaseMetaData metaData = con.getMetaData();ResultSet rs = metaData.getClientInfoProperties();...

The driver returns a result set that provides the following information for each client information propertysupported by the database:

• Property name

• Maximum length of the property value

• Default property value

• Property description

IP AddressesThe driver supports Internet Protocol (IP) addresses in IPv4 format.

The server name specified in a connection URL, or data source, can resolve to an IPv4 address. In the followingexample, the server name Server3 can resolve to an IPv4 address:

jdbc:datadirect:impala://Server3:21050;DatabaseName=Test;User=admin;Password=secret

Alternately, you can specify addresses using IPv4 format in the server portion of the connection URL. Forexample, the following connection URL specifies the server using an IPv4 address:

jdbc:datadirect:impala://123.456.78.90:21050;DatabaseName=Test;User=admin;Password=secret

You also can specify addresses using the ServerName data source property. The following example shows adata source definition that specifies the server name using an IPv4 address:

ImpalaDataSource mds = new ImpalaDataSource();mds.setDescription("My ImpalaDataSource");mds.setServerName("123.456.78.90");...

Parameter Metadata SupportThe driver supports returning parameter metadata as described in this section.



Insert, Update, and Delete StatementsThe driver supports returning parameter metadata for the following forms of Insert statements:

• INSERT INTO foo VALUES (?, ?, ?)

• INSERT INTO foo (col1, col2, col3) VALUES (?, ?, ?)

The driver allows the CAST function to be used in specified SQL. However, if a parameter marker is presentwithin a cast operation, the driver will be unable to obtain the parameter metadata and will throw the exception"The requested parameter metadata is not available for the current statement."

Returning parameter metadata for Update and Delete statements is not supported because Cloudera Impaladoes not have the concept of Update and Delete statements.

Select StatementsThe driver supports returning parameter metadata for Select statements that contain parameters in ANSISQL-92 entry-level predicates, for example, such as COMPARISON, BETWEEN, IN, LIKE, and EXISTSpredicate constructs. Refer to the ANSI SQL reference for detailed syntax.

Parameter metadata can be returned for a Select statement if the statement contains a predicate valueexpression that can be targeted against the source tables in the associated FROM clause. For example:

SELECT * FROM foo WHERE bar > ?

In this case, the value expression "bar" can be targeted against the table "foo" to determine the appropriatemetadata for the parameter.

The following Select statements show further examples for which parameter metadata can be returned:

SELECT col1, col2 FROM foo WHERE col1 = ? and col2 > ?SELECT ... WHERE colname LIKE ?SELECT ... WHERE colname BETWEEN ? and ?SELECT ... WHERE colname IN (?, ?, ?)

Subqueries are supported, but they can only exist in the From clause. In the following example, the secondSelect statement is a subquery:

SELECT * FROM (SELECT * FROM T1 UNION ALL SELECT * FROM T2) sq

ANSI SQL-92 entry-level predicates in a WHERE clause containing GROUP BY, HAVING, or ORDER BYstatements are supported. For example:

SELECT * FROM t1 WHERE col = ? ORDER BY 1

Joins are supported. For example:

SELECT * FROM t1,t2 WHERE t1.col1 = ?

Fully qualified names and aliases are supported. For example:

SELECT A.a, B.b, FROM T1 AS A, T2 AS B WHERE A.a = ? and B.b = ?"


Parameter Metadata Support

SQL SupportThe driver provides support for standard SQL (primarily SQL-92). In addition, the product supports a set ofSQL extensions. For example, the product supports extensions that allow you to change the default schemaor set the maximum number of Web service calls the driver can make when executing a SQL statement.

See alsoSupported SQL Functionality on page 165

ResultSet Metadata SupportIf your application requires table name information, the driver can return table name information in ResultSetmetadata for Select statements. The Select statements for which ResultSet metadata is returned may containaliases, joins, and fully qualified names. The following queries are examples of Select statements for whichthe ResultSetMetaData.getTableName() method returns the correct table name for columns in the Select list:

SELECT id, name FROM EmployeeSELECT E.id, E.name FROM Employee ESELECT E.id, E.name AS EmployeeName FROM Employee ESELECT E.id, E.name, I.location, I.phone FROM Employee E, EmployeeInfo I

WHERE E.id = I.idSELECT id, name, location, phone FROM Employee, EmployeeInfo WHERE id = empIdSELECT Employee.id, Employee.name, EmployeeInfo.location, EmployeeInfo.phone

FROM Employee, EmployeeInfo WHERE Employee.id = EmployeeInfo.id

The table name returned by the driver for generated columns is an empty string. The following query is anexample of a Select statement that returns a result set that contains a generated column (the column named"upper").

SELECT E.id, E.name as EmployeeName, {fn UCASE(E.name)} AS upperFROM Employee E

The driver also can return catalog name information when the ResultSetMetaData.getCatalogName() methodis called if the driver can determine that information. For example, for the following statement, the driver returns"test" for the catalog name and "foo" for the table name:

SELECT * FROM test.foo

The additional processing required to return table name and catalog name information is only performed if theResultSetMetaData.getTableName() or ResultSetMetaData.getCatalogName() methods are called.

Isolation LevelsWhen the TransactionMode connection property is set to ignore, the driver supports the READ COMMITTEDisolation level. When TransactionMode is set to noTransactions, the driver supports no isolation levels.



UnicodeMultilingual JDBC applications can be developed on any operating system using the driver to access bothUnicode and non-Unicode enabled databases. Internally, Java applications use UTF-16 Unicode encoding forstring data. When fetching data, the driver automatically performs the conversion from the character encodingused by the database to UTF-16. Similarly, when inserting or updating data in the database, the driverautomatically converts UTF-16 encoding to the character encoding used by the database.

The JDBC API provides mechanisms for retrieving and storing character data encoded as Unicode (UTF-16)or ASCII. Additionally, the Java String object contains methods for converting UTF-16 encoding of string datato or from many popular character encodings.

Error HandlingSQLExceptionsThe driver reports errors to the application by throwing SQLExceptions. Each SQLException contains thefollowing information:

• Description of the probable cause of the error, prefixed by the component that generated the error

• Native error code (if applicable)

• String containing the XOPEN SQLstate

Driver ErrorsAn error generated by the driver has the format shown in the following example:

[DataDirect][Impala JDBC Driver]Timeout expired.

You may need to check the last JDBC call your application made and refer to the JDBC specification for therecommended action.

Database ErrorsAn error generated by the database has the format shown in the following example:

[DataDirect][Impala JDBC Driver][Impala]Invalid Object Name.

If you need additional information, use the native error code to look up details in your database documentation.

Large Object SupportAlthough Cloudera Impala does not define a Clob data type, the driver allows you to retrieve and update longdata, specifically LONGVARCHAR data, using JDBC methods designed for Clobs. To do this, theStringDescribeType property must be set to longvarchar.

When using these methods to update long data as Clobs, the updates are made to the local copy of the datacontained in the Clob object.


Unicode

Note: The driver does not support retrieving and updating long data using JDBC methods designed for Blobs.

Retrieving and updating long data using JDBC methods designed for Clobs provides some of the same benefitsas retrieving and updating Clobs, such as:

• Provides random access to data

• Allows searching for patterns in the data, such as retrieving long data that begins with a specific characterstring

To provide these benefits normally associated with Clobs, data must be cached. Because data is cached, yourapplication will incur a performance penalty.

Rowset SupportThe driver supports any JSR 114 implementation of the RowSet interface, including:

• CachedRowSets

• FilteredRowSets

• WebRowSets

• JoinRowSets

• JDBCRowSets

Visit https://www.jcp.org/en/jsr/detail?id=114 for more information about JSR 114.

TimeoutsThe driver includes the LoginTimeout connection property. This property allows you to specify the amount oftime the driver waits for a connection to be established before timing out the connection request. See "UsingConnection Properties" and "LoginTimeout" for details.

See alsoUsing Connection Properties on page 46LoginTimeout on page 143

Using Scrollable CursorsThe driver supports only scroll-insensitive, read-only result sets.

Note: When the driver cannot support the requested result set type or concurrency, it automatically downgradesthe cursor and generates one or more SQLWarnings with detailed information.



https://www.jcp.org/en/jsr/detail?id=114

Limitations on Cloudera Impala FunctionalityPlease note the following Cloudera Impala functional limitations:

• No support for transactions

• No support for canceling a running query

• No support for row-level updates or deletes

• No support for stored procedures

• No support for auto-generated keys

For a more complete listing of known issues and limitations for your version of Cloudera Impala, refer to theCloudera Impala user documentation:

http://www.cloudera.com/content/support/en/documentation.html

Note: Cloudera Impala is not designed for OLTP workloads and does not offer row-level updates or deletes.Instead, Impala is designed for batch type jobs over large data sets with high latency. This means that queriessuch as "SELECT * FROM mytable" return quickly. However, other SELECT statements are much slower.

Connection Pool ManagerThe DataDirect Connection Pool Manager allows you to pool connections when accessing databases. Whenyour applications use connection pooling, connections are reused rather than created each time a connectionis requested. Because establishing a connection is among the most costly operations an application mayperform, using Connection Pool Manager to implement connection pooling can significantly improve performance.

How Connection Pooling WorksTypically, creating a connection is the most expensive operation an application performs. Connection poolingallows you to reuse connections rather than create a new one every time an application needs to connect tothe database. Connection pooling manages connection sharing across different user requests to maintainperformance and reduce the number of new connections that must be created. For example, compare thefollowing transaction sequences.

Example A: Without Connection Pooling1. The application creates a connection.

2. The application sends a query to the database.

3. The application obtains the result set of the query.

4. The application displays the result to the end user.

5. The application ends the connection.


Limitations on Cloudera Impala Functionality

http://www.cloudera.com/content/support/en/documentation.html

Example B: With Connection Pooling1. The application requests a connection from the connection pool.

2. If an unused connection exists, it is returned by the pool; otherwise, the pool creates a new connection.

3. The application sends a query to the database.

4. The application obtains the result set of the query.

5. The application displays the result to the end user.

6. The application closes the connection, which returns the connection to the pool.

Note: The application calls the close() method, but the connection remains open and the pool is notified ofthe close request.

The Connection Pool EnvironmentThere is a one-to-one relationship between a JDBC connection pool and a data source, so the number ofconnection pools used by an application depends on the number of data sources configured to use connectionpooling. If multiple applications are configured to use the same data source, those applications share the sameconnection pool as shown in the following figure.

An application may use only one data source, but allow multiple users, each with their own set of login credentials.The connection pool contains connections for all unique users using the same data source as shown in thefollowing figure.

Connections are one of the following types:

• Active connection is a connection that is in use by the application.

• Idle connection is a connection in the connection pool that is available for use.



The DataDirect Connection Pool ManagerConnection pooling is performed in the background and does not affect how an application is coded. To useconnection pooling, an application must use a DataSource object (an object implementing the DataSourceinterface) to obtain a connection instead of using the DriverManager class. A DataSource object registerswith a JNDI naming service. Once a DataSource object is registered, the application retrieves it from the JNDInaming service in the standard way.

Connection pool implementations, such as the DataDirect Connection Pool Manager, use objects that implementthe javax.sql.ConnectionPoolDataSource interface to create the connections managed in a connectionpool. All Progress DataDirect data source objects implement the ConnectionPoolDataSource interface.

The DataDirect Connection Pool Manager creates database connections, referred to as PooledConnections,by using the getPooledConnection() method of the ConnectionPoolDataSource interface. Then, thePool Manager registers itself as a listener to the PooledConnection. When a client application requests aconnection, the Pool Manager assigns an available connection. If a connection is unavailable, the Pool Managerestablishes a new connection and assigns it to that application.

When the application closes the connection, the driver uses the ConnectionEventListener interface tonotify the Pool Manager that the connection is free and available for reuse. The driver also uses theConnectionEventListener interface to notify the Pool Manager when a connection is corrupted so thatthe Pool Manager can remove that connection from the pool.

Using a Connection Pool Data Source ObjectOnce a PooledConnectionDataSource object has been created and registered with JNDI, it can be usedby your JDBC application as shown in the following example:

Context ctx = new InitialContext();ConnectionPoolDataSource ds =(ConnectionPoolDataSource)ctx.lookup("EmployeeDB");Connection conn = ds.getConnection("domino", "spark");

The example begins with the intialization of the JNDI environment. Then, the initial naming context is used tofind the logical name of the JDBC DataSource (EmployeeDB). The Context.lookup method returns areference to a Java object, which is narrowed to a javax.sql.ConnectionPoolDataSource object. Next,the ConnectionPoolDataSource.getPooledConnection() method is called to establish a connectionwith the underlying database. Then, the application obtains a connection from theConnectionPoolDataSource.

Implementing DataDirect Connection PoolingTo use connection pooling, an application must use a DataSource object (an object implementing theDataSource interface) to obtain a connection instead of using the DriverManager class. A DataSourceobject registers with a JNDI naming service. Once a DataSource object is registered, the application retrievesit from the JNDI naming service in the standard way.

To implement DataDirect Connection Pooling, perform the following steps.


Connection Pool Manager

1. Create and register with JNDI a Progress DataDirect data source object. Once created, the DataSourceobject can be used by a connection pool (PooledConnectionDataSource object created in "Creating aDriver DataSource Object") to create connections for one or multiple connection pools.

2. To create a connection pool, you must create and register with JNDI a PooledConnectionDataSourceobject. A PooledConnectionDataSource creates and manages one or multiple connection pools. ThePooledConnectionDataSource uses the driver DataSource object created in "Creating the ConnectionPool" to create the connections for the connection pool.

Creating a Driver DataSource ObjectThe following Java code example creates a Progress DataDirect DataSource object and registers it with a JNDInaming service. The DataSource class is database-dependent. This example is drawn from an Oracle usecase; therefore, the DataSource class is OracleDataSource. Nevertheless, the example informs theimplementation of DataSource objects for most Progress DataDirect drivers.

Note: The DataSource class implements the ConnectionPoolDataSource interface for pooling in addition tothe DataSource interface for non-pooling.

//************************************************************************// This code creates a Progress DataDirect for JDBC data source and// registers it to a JNDI naming service. This JDBC data source uses the// DataSource implementation provided by DataDirect Connect Series// for JDBC Drivers.//// This data source registers its name as <jdbc/ConnectSparkyOracle>.//// NOTE: To connect using a data source, the driver needs to access a JNDI data// store to persist the data source information. To download the JNDI File// System Service Provider, go to://// http://www.oracle.com/technetwork/java/javasebusiness/downloads/// java-archive-downloads-java-plat-419418.html#7110-jndi-1.2.1-oth-JPR////// Make sure that the fscontext.jar and providerutil.jar files from the// download are on your classpath.//************************************************************************// From DataDirect Connect Series for JDBC:import com.ddtek.jdbcx.oracle.OracleDataSource;import javax.sql.*;import java.sql.*;import javax.naming.*;import javax.naming.directory.*;import java.util.Hashtable;public class OracleDataSourceRegisterJNDI{ public static void main(String argv[])

{try {// Set up data source reference data for naming context:// ----------------------------------------------------// Create a class instance that implements the interface// ConnectionPoolDataSourceOracleDataSource ds = new OracleDataSource();ds.setDescription("Oracle on Sparky - Oracle Data Source");ds.setServerName("sparky");ds.setPortNumber(1521);ds.setUser("scott");ds.setPassword("test");// Set up environment for creating initial contextHashtable env = new Hashtable();env.put(Context.INITIAL_CONTEXT_FACTORY,

"com.sun.jndi.fscontext.RefFSContextFactory");env.put(Context.PROVIDER_URL, "file:c:\\JDBCDataSource");Context ctx = new InitialContext(env);// Register the data source to JNDI naming service



ctx.bind("jdbc/ConnectSparkyOracle", ds);} catch (Exception e) {System.out.println(e);return;}

} // Main// class OracleDataSourceRegisterJNDI

Creating the Connection PoolTo create a connection pool, you must create and register with JNDI a PooledConnectionDataSource object.The following Java code creates a PooledConnectionDataSource object and registers it with a JNDI namingservice.

To specify the driver DataSource object to be used by the connection pool to create pooled connections, setthe parameter of the DataSourceName method to the JNDI name of a registered driver DataSource object.For example, the following code sets the parameter of the DataSourceName method to the JNDI name of thedriver DataSource object created in "Creating a Driver DataSource Object."

The PooledConnectionDataSource class is provided by the DataDirect com.ddtek.pool package. See"PooledConnectionDataSource" for a description of the methods supported by the PooledConnectionDataSourceclass.

Note: The following example is drawn from an Oracle use case, but it informs the implementation of connectionpooling for most Progress DataDirect drivers.

//************************************************************************// This code creates a data source and registers it to a JNDI naming service.// This data source uses the PooledConnectionDataSource// implementation provided by the DataDirect com.ddtek.pool package.//// This data source refers to a registered// DataDirect Connect Series for JDBC driver DataSource object.//// This data source registers its name as <jdbc/SparkyOracle>.//// NOTE: To connect using a data source, the driver needs to access a JNDI data// store to persist the data source information. To download the JNDI File// System Service Provider, go to://// http://www.oracle.com/technetwork/java/javasebusiness/downloads/// java-archive-downloads-java-plat-419418.html#7110-jndi-1.2.1-oth-JPR//// Make sure that the fscontext.jar and providerutil.jar files from the// download are on your classpath.//************************************************************************// From the DataDirect connection pooling package:import com.ddtek.pool.PooledConnectionDataSource;

import javax.sql.*;import java.sql.*;import javax.naming.*;import javax.naming.directory.*;import java.util.Hashtable;

public class PoolMgrDataSourceRegisterJNDI{

public static void main(String argv[]){

try {// Set up data source reference data for naming context:// ----------------------------------------------------// Create a pooling manager's class instance that implements// the interface DataSourcePooledConnectionDataSource ds = new PooledConnectionDataSource();



ds.setDescription("Sparky Oracle - Oracle Data Source");

// Specify a registered driver DataSource object to be used// by this data source to create pooled connectionsds.setDataSourceName("jdbc/ConnectSparkyOracle");

// The pool manager will be initiated with 5 physical connectionsds.setInitialPoolSize(5);

// The pool maintenance thread will make sure that there are 5// physical connections availableds.setMinPoolSize(5);

// The pool maintenance thread will check that there are no more// than 10 physical connections availableds.setMaxPoolSize(10);

// The pool maintenance thread will wake up and check the pool// every 20 secondsds.setPropertyCycle(20);

// The pool maintenance thread will remove physical connections// that are inactive for more than 300 secondsds.setMaxIdleTime(300);

// Set tracing off because we choose not to see an output listing// of activities on a connectionds.setTracing(false);

// Set up environment for creating initial contextHashtable env = new Hashtable();env.put(Context.INITIAL_CONTEXT_FACTORY,

"com.sun.jndi.fscontext.RefFSContextFactory");env.put(Context.PROVIDER_URL, "file:c:\\JDBCDataSource");Context ctx = new InitialContext(env);

// Register this data source to the JNDI naming servicectx.bind("jdbc/SparkyOracle", ds);

catch (Exception e) {System.out.println(e);return;

}}

}

See alsoCreating a Driver DataSource Object on page 68PooledConnectionDataSource on page 74

Configuring the Connection PoolYou can configure attributes of a connection pool for optimal performance and scalability using the methodsprovided by the DataDirect Connection Pool Manager classes.

Some commonly set connection pool attributes include:

• Minimum pool size, which is the minimum number of connections that will be kept in the pool for each user

• Maximum pool size, which is the maximum number of connections in the pool for each user

• Initial pool size, which is the number of connections created for each user when the connection pool isinitialized



• Maximum idle time, which is the amount of time a pooled connection remains idle before it is removed fromthe connection pool

See alsoConnection Pool Manager Interfaces on page 74

Configuring the Maximum Pool SizeYou set the maximum pool size using the PooledConnectionDataSource.setMaxPoolSize() method.For example, the following code sets the maximum pool size to 10:

ds.setMaxPoolSize(10);

You can control how the Pool Manager implements the maximum pool size by setting thePooledConnectionDataSource.setMaxPoolSizeBehavior() method:

• If setMaxPoolSizeBehavior(softCap), the number of active connections can exceed the maximumpool size, but the number of idle connections for each user in the pool cannot exceed this limit. If a userrequests a connection and an idle connection is unavailable, the Pool Manager creates a new connectionfor that user. When the connection is no longer needed, it is returned to the pool. If the number of idleconnections exceeds the maximum pool size, the Pool Manager closes idle connections to enforce the poolsize limit. This is the default behavior.

• If setMaxPoolSizeBehavior(hardCap), the total number of active and idle connections cannot exceedthe maximum pool size. Instead of creating a new connection for a connection request if an idle connectionis unavailable, the Pool Manager queues the connection request until a connection is available or the requesttimes out. This behavior is useful if your client or application server has memory limitations or if your databaseserver is licensed for only a certain number of connections.

See alsoPooledConnectionDataSource on page 74

Connecting Using a Connection PoolBecause an application uses connection pooling by referencing the JNDI name of a registeredPooledConnectionDataSource object, code changes are not required for an application to use connectionpooling.

The following example shows Java code that looks up and uses the JNDI-registeredPooledConnectionDataSource object created in "Creating the Connection Pool."

Note: This code example is drawn from an Oracle use case, but it informs the implementation of connectionpooling for most Progress DataDirect drivers.

//********************************************************************// Test program to look up and use a JNDI-registered data source.//// To run the program, specify the JNDI lookup name for the// command-line argument, for example://// java TestDataSourceApp <jdbc/SparkyOracle>//********************************************************************import javax.sql.*;import java.sql.*;import javax.naming.*;



import java.util.Hashtable;public class TestDataSourceApp{ public static void main(String argv[])

{String strJNDILookupName = "";// Get the JNDI lookup name for a data sourceint nArgv = argv.length;if (nArgv != 1) {

// User does not specify a JNDI lookup name for a data source,System.out.println(

"Please specify a JNDI name for your data source");System.exit(0);else {strJNDILookupName = argv[0];

}DataSource ds = null;Connection con = null;Context ctx = null;Hashtable env = null;long nStartTime, nStopTime, nElapsedTime;// Set up environment for creating InitialContext objectenv = new Hashtable();env.put(Context.INITIAL_CONTEXT_FACTORY,

"com.sun.jndi.fscontext.RefFSContextFactory");env.put(Context.PROVIDER_URL, "file:c:\\JDBCDataSource");try {

// Retrieve the DataSource object that is bound to the logical// lookup JNDI namectx = new InitialContext(env);ds = (DataSource) ctx.lookup(strJNDILookupName);catch (NamingException eName) {System.out.println("Error looking up " +

strJNDILookupName + ": " +eName);System.exit(0);

}int numOfTest = 4;int [] nCount = {100, 100, 1000, 3000};for (int i = 0; i < numOfTest; i ++) {

// Log the start timenStartTime = System.currentTimeMillis();for (int j = 1; j <= nCount[i]; j++) {

// Get Database Connectiontry {

con = ds.getConnection("scott", "tiger");// Do something with the connection// ...// Close Database Connectionif (con != null) con.close();} catch (SQLException eCon) {System.out.println("Error getting a connection: " + eCon);System.exit(0);} // try getConnection

} // for j loop// Log the end timenStopTime = System.currentTimeMillis();// Compute elapsed timenElapsedTime = nStopTime - nStartTime;System.out.println("Test number " + i + ": looping " +

nCount[i] + " times");System.out.println("Elapsed Time: " + nElapsedTime + "\n");

} // for i loop// All doneSystem.exit(0);// Main

} // TestDataSourceApp



Note: To use non-pooled connections, specify the JNDI name of a registered driver DataSource object as thecommand-line argument when you run the preceding application. For example, the following command specifiesthe driver DataSource object created in "Creating a Driver DataSource Object": java TestDataSourceAppjdbc/ConnectSparkyOracle

See alsoCreating the Connection Pool on page 69Creating a Driver DataSource Object on page 68

Closing the Connection PoolTo ensure that the connection pool is closed correctly when an application stops running, the application mustnotify the DataDirect Connection Pool Manager when it stops. For applications running on Java SE 5 andhigher, notification occurs automatically when the application stops running.

The PooledConnectionDataSource.close() method also can be used to explicitly close the connectionpool while the application is running. For example, if changes are made to the pool configuration using a poolmanagement tool, the PooledConnectionDataSource.close()method can be used to force the connectionpool to close and re-create the pool using the new configuration values.

Checking the Pool Manager VersionTo check the version of your DataDirect Connection Pool Manager, navigate to the directory containing theDataDirect Connection Pool Manager (install_dir/pool manager where install_dir is your productinstallation directory). At a command prompt, enter the command:

On Windows:java -classpath poolmgr_dir\pool.jar com.ddtek.pool.PoolManagerInfo

On UNIX:java -classpath poolmgr_dir/pool.jar com.ddtek.pool.PoolManagerInfo

where:

poolmgr_dir

is the directory containing the DataDirect Connection Pool Manager.

Alternatively, you can obtain the name and version of the DataDirect Connection Pool Manager programmaticallyby invoking the following static methods:

• com.ddtek.pool.PoolManagerInfo.getPoolManagerName()

• com.ddtek.pool.PoolManagerInfo.getPoolManagerVersion()

Enabling Pool Manager TracingYou can enable Pool Manager tracing by calling setTracing(true) on the PooledConnectionDataSourceconnection. To disable logging, call setTracing(false).



By default, the DataDirect Connection Pool Manager logs its pool activities to the standard output System.out.You can change where the Pool Manager trace information is written by calling the setLogWriter() methodon the PooledConnectionDataSource connection.

See "Troubleshooting Connection Pooling" for information about using a Pool Manager trace file fortroubleshooting.

See alsoTroubleshooting Connection Pooling on page 158

Connection Pool Manager InterfacesThis section describes the methods used by the DataDirect Connection Pool Manager interfaces:PooledConnectionDataSourceFactory, PooledConnectionDataSource, andConnectionPoolMonitor.

PooledConnectionDataSourceFactoryThePooledConnectionDataSourceFactory interface is used to create aPooledConnectionDataSourceobject from a Reference object that is stored in a naming or directory service. These methods are typicallyinvoked by a JNDI service provider; they are not usually invoked by a user application.

DescriptionPooledConnectionDataSourceFactory Methods

Creates a PooledConnectionDataSource object froma Reference object that is stored in a naming or directoryservice. This is an implementation of the method of thesame name defined in thejavax.naming.spi.ObjectFactory interface. Referto the Javadoc for this interface for a description.

static Object getObjectInstance(ObjectrefObj, Name name, Context nameCtx,Hashtable env)

PooledConnectionDataSourceThe PooledConnectionDataSource interface is used to create a PooledConnectionDataSource objectfor use with the DataDirect Connection Pool Manager.

DescriptionPooledConnectionDataSource Methods

Closes the connection pool. All physical connections in the pool areclosed. Any subsequent connection request re-initializes the connectionpool.

void close()

Obtains a physical connection from the connection pool.Connection getConnection()

Obtains a physical connection from the connection pool, where useris the user requesting the connection and password is the passwordfor the connection.

Connection getConnection(Stringuser, String password)

Returns the JNDI name that is used to look up the DataSource objectreferenced by this PooledConnectionDataSource.

String getDataSourceName()




Returns the description of this PooledConnectionDataSource.String getDescription()

Returns the value of the initial pool size, which is the number of physicalconnections created when the connection pool is initialized.

int getInitialPoolSize()

Returns the value of the login timeout, which is the time allowed for thedatabase login to be validated.

int getLoginTimeout()

Returns the writer to which the Pool Manager sends trace informationabout its activities.

PrintWriter getLogWriter()

Returns the value of the maximum idle time, which is the time a physicalconnection can remain idle in the connection pool before it is removedfrom the connection pool.

int getMaxIdleTime()

Returns the value of the maximum pool size. See "Configuring theMaximum Pool Size" for more information about how the Pool Managerimplements the maximum pool size.

int getMaxPoolSize()

Returns the value of the maximum pool size behavior. See "Configuringthe Maximum Pool Size" for more information about how the PoolManager implements the maximum pool size.

int getMaxPoolSizeBehavior()

Returns the value of the minimum pool size, which is the minimumnumber of idle connections to be kept in the pool.

int getMinPoolSize()

Returns the value of the property cycle, which specifies how often thepool maintenance thread wakes up and checks the connection pool.

int getPropertyCycle()

Obtains a javax.naming. Reference object for thisPooledConnectionDataSource. The Reference object contains allthe state information needed to recreate an instance of this data sourceusing the PooledConnectionDataSourceFactory object. Thismethod is typically called by a JNDI service provider when thisPooledConnectionDataSource is bound to a JNDI naming service.

Reference getReference()

Returns an array of Connection Pool Monitors, one for each connectionpool managed by the Pool Manager.

public staticConnectionPoolMonitor[ ]getMonitor()




Returns the name of the Connection Pool Monitor for the connectionpool specified by name. If a pool with the specified name cannot befound, this method returns null. The connection pool name has theform:

jndi_name-user_id

where:

jndi_name

is the name used for the JNDI lookup of the driverDataSource object from which the pooled connection wasobtained and

user_id

is the user ID used to establish the connections contained inthe pool.

public static ConnectionPoolMonitorgetMonitor(String name)

Determines whether tracing is enabled. If enabled, tracing informationis sent to the PrintWriter that is passed to the setLogWriter()method or the standard output System.out if the setLogWriter()method is not called.

boolean isTracing()

Sets the JNDI name, which is used to look up the driver DataSourceobject referenced by this PooledConnectionDataSource. The driverDataSource object bound to this PooledConnectionDataSource,specified by dataSourceName, is not persisted. Any changes madeto the PooledConnectionDataSource bound to the specified driverDataSource object affect this PooledConnectionDataSource.

void setDataSourceName(StringdataSourceName)

Sets the JNDI name associated with thisPooledConnectionDataSource, specified by dataSourceName,and the driver DataSource object, specified by dataSource,referenced by this PooledConnectionDataSource.

The driver DataSource object, specified by dataSource, is persistedwith this PooledConnectionDataSource. Changes made to thespecified driver DataSource object after thisPooledConnectionDataSource is persisted do not affect thisPooledConnectionDataSource.

void setDataSourceName(StringdataSourceName,ConnectionPoolDataSourcedataSource)

Sets the JNDI name, specified by dataSourceName, and context,specified by ctx, to be used to look up the driver DataSourcereferenced by this PooledConnectionDataSource.

The JNDI name, specified by dataSourceName, and context, specifiedby ctx, are used to look up a driver DataSource object. The driverDataSource object is persisted with thisPooledConnectionDataSource. Changes made to the driverDataSource after this PooledConnectionDataSource is persisteddo not affect this PooledConnectionDataSource.

void setDataSourceName(StringdataSourceName, Context ctx)




Sets the description of the PooledConnectionDataSource, wheredescription is the description.

void setDescription(Stringdescription)

Sets the value of the initial pool size, which is the number of connectionscreated when the connection pool is initialized.

void setInitialPoolSize(intinitialPoolSize)

Sets the value of the login timeout, where i is the login timeout, whichis the time allowed for the database login to be validated.

void setLoginTimeout(int i)

If set to true, the timestamp is logged when DataDirect Spy loggingis enabled. If set to false, the timestamp is not logged.

void setLogTimestamp(boolean value)

If set to true, the thread name is logged when DataDirect Spy loggingis enabled. If set to false, the thread name is not logged.

void setLogTname(boolean value)

Sets the writer, where printWriter is the writer to which the streamwill be printed.

void setLogWriter(PrintWriterprintWriter)

Sets the value in seconds of the maximum idle time, which is the timea connection can remain unused in the connection pool before it isclosed and removed from the pool. Zero (0) indicates no limit.

void setMaxIdleTime(intmaxIdleTime)

Sets the value of the maximum pool size, which is the maximum numberof connections for each user allowed in the pool. See "Configuring theMaximum Pool Size" for more information about how the Pool Managerimplements the maximum pool size.

void setMaxPoolSize(intmaxPoolSize)

Sets the value of the maximum pool size behavior, which is eithersoftCap or hardCap.

If setMaxPoolSizeBehavior(softCap), the number of activeconnections may exceed the maximum pool size, but the number ofidle connections in the connection pool for each user cannot exceedthis limit. If a user requests a connection and an idle connection isunavailable, the Pool Manager creates a new connection for that user.When the connection is no longer needed, it is returned to the pool. Ifthe number of idle connections exceeds the maximum pool size, thePool Manager closes idle connections to enforce the maximum poolsize limit. This is the default behavior.

If setMaxPoolSizeBehavior(hardCap), the total number of activeand idle connections cannot exceed the maximum pool size. Insteadof creating a new connection for a connection request if an idleconnection is unavailable, the Pool Manager queues the connectionrequest until a connection is available or the request times out. Thisbehavior is useful if your database server has memory limitations or islicensed for only a specific number of connections.The timeout is setusing the LoginTimeout connection property. If the connection requesttimes out, the driver throws an exception.

See "Configuring the Maximum Pool Size" for more information abouthow the Pool Manager implements the maximum pool size.

void setMaxPoolSizeBehavior(Stringvalue)




Sets the value of the minimum pool size, which is the minimum numberof idle connections to be kept in the connection pool.

void setMinPoolSize(intminPoolSize)

Sets the value in seconds of the property cycle, which specifies howoften the pool maintenance thread wakes up and checks the connectionpool.

void setPropertyCycle(intpropertyCycle)

Enables or disables tracing. If set to true, tracing is enabled; if false,it is disabled. If enabled, tracing information is sent to the PrintWriterthat is passed to the setLogWriter()method or the standard outputSystem.out if the setLogWriter() method is not called.

void setTracing(boolean value)

See alsoConfiguring the Maximum Pool Size on page 71

ConnectionPoolMonitorThe ConnectionPoolMonitor interface is used to return information that is useful for monitoring the statusof your connection pools.

DescriptionConnectionPoolMonitor Methods

Returns the name of the connection pool associated with the monitor.The connection pool name has the form:

jndi_name-user_id

where:

jndi_name

is the name used for the JNDI lookup of thePooledConnectionDataSource object from which thepooled connection was obtained

user_id

is the user ID used to establish the connections contained inthe pool.

String getName()

Returns the number of connections that have been checked out of thepool and are currently in use.

int getNumActive()

Returns the number of connections that are idle in the pool (availableconnections).

int getNumAvailable()

Returns the initial size of the connection pool (the number of availableconnections in the pool when the pool was first created).

int getInitialPoolSize()



DescriptionConnectionPoolMonitor Methods

Returns the maximum number of available connection in the connectionpool. If the number of available connections exceeds this value, thePool Manager removes one or multiple available connections from thepool.

int getMaxPoolSize()

Returns the minimum number of available connections in the connectionpool. When the number of available connections is lower than thisvalue, the Pool Manager creates additional connections and makesthem available.

int getMinPoolSize()

Returns the current size of the connection pool, which is the total ofactive connections and available connections.

int getPoolSize()

Statement Pool MonitorThe driver supports the DataDirect Statement Pool Monitor. You can use the Statement Pool Monitor to loadstatements into and remove statements from the statement pool as well as generate information to help youtroubleshoot statement pooling performance. The Statement Pool Monitor is an integrated component of thedriver, and you can manage statement pooling directly with DataDirect-specific methods. In addition, theStatement Pool Monitor can be enabled as a Java Management Extensions (JMX) MBean. When enabled asa JMX MBean, the Statement Pool Monitor can be used to manage statement pooling with standard JMX APIcalls, and it can easily be used by JMX-compliant tools, such as JConsole.

Using DataDirect-Specific Methods to Access the Statement PoolMonitor

To access the Statement Pool Monitor using DataDirect-specific methods, you should first enable statementpooling. You can enable statement pooling by setting the MaxPooledStatements connection property to a valuegreater than zero (0).

The ExtConnection.getStatementPoolMonitor() method returns an ExtStatementPoolMonitor object for thestatement pool associated with the connection. This method is provided by the ExtConnection interface in thecom.ddtek.jdbc.extensions package. If the connection does not have a statement pool, the method returnsnull.

Once you have an ExtStatementPoolMonitor object, you can use the poolEntries() method of theExtStatementPoolMonitorMBean interface implemented by the ExtStatementPoolMonitor to return a list ofstatements in the statement pool as an array.

See alsoMaxPooledStatements on page 144

Using the poolEntries MethodUsing the poolEntries()method, your application can return all statements in the pool or filter the list basedon the following criteria:

• Statement type (prepared statement or callable statement)


Statement Pool Monitor

• Result set type (forward only, scroll insensitive, or scroll sensitive)

• Concurrency type of the result set (read only and updateable)

The following table lists the parameters and the valid values supported by the poolEntries() method.

Table 13: poolEntries() Parameters

DescriptionValueParameter

Returns only prepared statementsExtStatementPoolMonitor.TYPE_PREPARED_STATEMENTstatementType

Returns only callable statementsExtStatementPoolMonitor.TYPE_CALLABLE_STATEMENT

Returns all statements regardlessof statement type

-1

Returns only statements withforward-only result sets

ResultSet.TYPE_FORWARD_ONLYresultSetType

Returns only statements with scrollinsensitive result sets

ResultSet.TYPE_SCROLL_INSENSITIVE

Returns only statements with scrollsensitive result sets

ResultSet.TYPE_SCROLL_SENSITIVE

Returns statements regardless ofresult set type

-1

Returns only statements with aread-only result set concurrency

ResultSet.CONCUR_READ_ONLYresultSetConcurrency

Returns only statements with anupdateable result set concurrency

ResultSet.CONCUR_UPDATABLE

Returns statements regardless ofresult set concurrency type

-1

The result of the poolEntries() method is an array that contains a String entry for each statement in thestatement pool using the format:

SQL_TEXT=[SQL_text];STATEMENT_TYPE=TYPE_PREPARED_STATEMENT|TYPE_CALLABLE_STATEMENT;RESULTSET_TYPE=TYPE_FORWARD_ONLY|TYPE_SCROLL_INSENSITIVE|TYPE_SCROLL_SENSITIVE;RESULTSET_CONCURRENCY=CONCUR_READ_ONLY|CONCUR_UPDATABLE;AUTOGENERATEDKEYSREQUESTED=true|false;REQUESTEDKEYCOLUMNS=comma-separated_list

where SQL_text is the SQL text of the statement and comma-separated_list is a list of column namesthat will be returned as generated keys.

For example:

SQL_TEXT=[INSERT INTO emp(id, name) VALUES(99, ?)];STATEMENT_TYPE=Prepared Statement;RESULTSET_TYPE=Forward Only;RESULTSET_CONCURRENCY=ReadOnly;AUTOGENERATEDKEYSREQUESTED=false;REQUESTEDKEYCOLUMNS=id,name



Generating a List of Statements in the Statement PoolThe following code shows how to return an ExtStatementPoolMonitor object using a connection and how togenerate a list of statements in the statement pool associated with the connection.

Note: The following example is drawn from a Microsoft SQL Server use case but applies to most ProgressDataDirect drivers.

private void run(String[] args) {Connection con = null;PreparedStatement prepStmt = null;String sql = null;try {

// Create the connection and enable statement poolingClass.forName("com.ddtek.jdbc.sqlserver.SQLServerDriver");con = DriverManager.getConnection(

"jdbc:datadirect:sqlserver://SMITH:1440;" +"RegisterStatementPoolMonitorMBean=true","maxPooledStatements=10","test", "test");

// Prepare a couple of statementssql = "INSERT INTO employees (id, name) VALUES(?, ?)";prepStmt = con.prepareStatement(sql);prepStmt.close();sql = "SELECT name FROM employees WHERE id = ?";prepStmt = con.prepareStatement(sql);prepStmt.close();ExtStatementPoolMonitor monitor =

((ExtConnection) con).getStatementPoolMonitor();System.out.println("Statement Pool - " + monitor.getName());System.out.println("Max Size: " + monitor.getMaxSize());System.out.println("Current Size: " + monitor.getCurrentSize());System.out.println("Hit Count: " + monitor.getHitCount());System.out.println("Miss Count: " + monitor.getMissCount());System.out.println("Statements:");ArrayList statements = monitor.poolEntries(-1, -1, -1);Iterator itr = statements.iterator();while (itr.hasNext()) {

String entry = (String)itr.next();System.out.println(entry);

}}catch (Throwable except) {

System.out.println("ERROR: " + except);}finally {

if (con != null) {try {

con.close();}catch (SQLException except) {}}

}}

In the previous code example, the PoolEntries() method returns all statements in the statement pool regardlessof statement type, result set cursor type, and concurrency type by specifying the value -1 for each parameteras shown in the following code:

ArrayList statements = monitor.poolEntries(-1, -1, -1);



We could have easily filtered the list of statements to return only prepared statements that have a forward-onlyresult set with a concurrency type of updateable using the following code:

ArrayList statements = monitor.poolEntries(ExtStatementPoolMonitor.TYPE_PREPARED_STATEMENT,ResultSet.TYPE_FORWARD_ONLY, ResultSet.CONCUR_UPDATABLE);

Using JMX to Access the Statement Pool MonitorYour application cannot access the Statement Pool Monitor using JMX unless the driver registers the StatementPool Monitor as a JMX MBean. To enable the Statement Pool Monitor as an MBean, statement pooling mustbe enabled with "MaxPooledStatements", and the Statement Pool Monitor MBean must be registered usingthe RegisterStatementPoolMonitorMBean connection property.

When the Statement Pool Monitor is enabled, the driver registers a single MBean for each statement pool. Theregistered MBean name has the following form, where monitor_name is the string returned by theExtStatementPoolMonitor.getName() method:

com.ddtek.jdbc.type=StatementPoolMonitor,name=monitor_name

Note: Registering the MBean exports a reference to the Statement Pool Monitor. The exported reference canprevent garbage collection on connections if the connections are not properly closed. When garbage collectiondoes not take place on these connections, out of memory errors can occur.

To return information about the statement pool, retrieve the names of all MBeans that are registered with thecom.ddtek.jdbc domain and search through the list for the StatementPoolMonitor type attribute. The followingcode shows how to use the standard JMX API calls to return the state of all active statement pools in the JVM:

private void run(String[] args) {if (args.length < 2) {

System.out.println("Not enough arguments supplied");System.out.println("Usage: " + "ShowStatementPoolInfo hostname port");

}String hostname = args[0];String port = args[1];JMXServiceURL url = null;JMXConnector connector = null;MBeanServerConnection server = null;try {

url = new JMXServiceURL("service:jmx:rmi:///jndi/rmi://" +hostname +":" + port + "/jmxrmi");

connector = JMXConnectorFactory.connect(url);server = connector.getMBeanServerConnection();System.out.println("Connected to JMX MBean Server at " +

args[0] + ":" + args[1]);// Get the MBeans that have been registered with the// com.ddtek.jdbc domain.ObjectName ddMBeans = new ObjectName("com.ddtek.jdbc:*");Set<ObjectName> mbeans = server.queryNames(ddMBeans, null);// For each statement pool monitor MBean, display statistics and// contents of the statement pool monitored by that MBeanfor (ObjectName name: mbeans) {

if (name.getDomain().equals("com.ddtek.jdbc") &&name.getKeyProperty("type")

.equals("StatementPoolMonitor")) {System.out.println("Statement Pool - " +

server.getAttribute(name, "Name"));System.out.println("Max Size: " +

server.getAttribute(name, "MaxSize"));System.out.println("Current Size: " +

server.getAttribute(name, "CurrentSize"));System.out.println("Hit Count: " +

server.getAttribute(name, "HitCount"));



System.out.println("Miss Count: " +server.getAttribute(name, "MissCount"));

System.out.println("Statements:");Object[] params = new Object[3];params[0] = new Integer(-1);params[1] = new Integer(-1);params[2] = new Integer(-1);String[] types = new String[3];types[0] = "int";types[1] = "int";types[2] = "int";ArrayList<String>statements = (ArrayList<String>)

server.invoke(name,"poolEntries",params,types);

for (String stmt : statements) {int index = stmt.indexOf(";");System.out.println(" " + stmt.substring(0, index));

}}

}}catch (Throwable except) {

System.out.println("ERROR: " + except);}

}

See alsoMaxPooledStatements on page 144RegisterStatementPoolMonitorMBean on page 146

Importing Statements into a Statement PoolWhen importing statements into a statement pool, for each statement entry in the export file, a statement isadded to the statement pool provided a statement with the same SQL text and statement attributes does notalready exist in the statement pool. Existing statements in the pool that correspond to a statement entry arekept in the pool unless the addition of new statements causes the number of statements to exceed the maximumpool size. In this case, the driver closes and discards some statements until the pool size is shrunk to themaximum pool size.

For example, if the maximum number of statements allowed for a statement pool is 10 and the number ofstatements to be imported is 20, only the last 10 imported statements are placed in the statement pool. Theother statements are created, closed, and discarded. Importing more statements than the maximum numberof statements allowed in the statement pool can negatively affect performance because the driver unnecessarilycreates some statements that are never placed in the pool.

To import statements into a statement pool:

1. Create a statement pool export file. See "Statement Pool Export File Example" for an example of a statementpool export file.

Note: The easiest way to create a statement pool export file is to generate an export file from the statementpool associated with the connection as described in "Generating a Statement Pool Export File."

2. Edit the export file to contain statements to be added to the statement pool.

3. Import the contents of the export file to the statement pool using either of the following methods to specifythe path and file name of the export file:



• Use the ImportStatementPool property. For example:

jdbc:datadirect:impala://Server3:21050;DatabaseName=Test;User=admin;Password=secret;ImportStatementPool=C:\\statement_pooling\\stmt_export.txt

• Use the importStatements() method of the ExtStatementPoolMonitorMBean interface. For example:

ExtStatementPoolMonitor monitor =((ExtConnection)

con).getStatementPoolMonitor().importStatements("C:\\statement_pooling\\stmt_export.txt");

See alsoStatement Pool Export File Example on page 163Generating a Statement Pool Export File on page 84

Clearing All Statements in a Statement PoolTo close and discard all statements in a statement pool, use the emptyPool() method of theExtStatementPoolMonitorMBean interface. For example:

ExtStatementPoolMonitor monitor =((ExtConnection) con).getStatementPoolMonitor().emptyPool();

Freezing and Unfreezing the Statement PoolFreezing the statement pool restricts the statements in the pool to those that were in the pool at the time thepool was frozen. For example, perhaps you have a core set of statements that you do not want replaced bynew statements when your core statements are closed. You can freeze the pool using the setFrozen()method:

ExtStatementPoolMonitor monitor =((ExtConnection) con).getStatementPoolMonitor().setFrozen(true);

Similarly, you can use the same method to unfreeze the statement pool:

ExtStatementPoolMonitor monitor =((ExtConnection) con).getStatementPoolMonitor().setFrozen(false);

When the statement pool is frozen, your application can still clear the pool and import statements into the pool.In addition, if your application is using Java SE 6 or higher, you can use the Statement.setPoolable()method to add or remove single statements from the pool regardless of the pool’s frozen state, assuming thepool is not full. If the pool is frozen and the number of statements in the pool is the maximum, no statementscan be added to the pool.

To determine if a pool is frozen, use the isFrozen() method.

Generating a Statement Pool Export FileYou may want to generate an export file in the following circumstances:



• To import statements to the statement pool, you can create an export file, edit its contents, and import thefile into the statement pool to import statements to the pool.

• To examine the characteristics of the statements in the statement pool to help you troubleshoot statementpool performance.

To generate a statement pool export file, use the exportStatements() method of theExtStatementPoolMonitorMBean interface. For example, the following code exports the contents of thestatement pool associated with the connection to a file named stmt_export.txt:

ExtStatementPoolMonitor monitor =((ExtConnection) con).getStatementPoolMonitor().exportStatements("stmt_export.txt");

See the "Statement Pool Export File Example" topic for information on interpreting the contents of an exportfile.

See alsoStatement Pool Export File Example on page 163

DataDirect Statement Pool Monitor Interfaces and ClassesThis section describes the methods used by the DataDirect Statement Pool Monitor interfaces and classes.

ExtStatementPoolMonitor ClassThis class is used to control and monitor a single statement pool. This class implements theExtStatementPoolMonitorMBean interface.

ExtStatementPoolMonitorMBean Interface

DescriptionExtStatementPoolMonitorMBean Methods

Returns the name of a Statement Pool Monitor instanceassociated with the connection. The name is comprised ofthe name of the driver that established the connection, andthe name and port of the server to which the StatementPool Monitor is connected, and the MBean ID of theconnection.

String getName()

Returns the total number of statements cached in thestatement pool.

int getCurrentSize()




Returns the hit count for the statement pool. The hit countis the number of times a lookup is performed for a statementthat results in a cache hit. A cache hit occurs when theStatement Pool Monitor successfully finds a statement inthe pool with the same SQL text, statement type, result settype, result set concurrency, and requested generated keyinformation.

This method is useful to determine if your workload is usingthe statement pool effectively. For example, if the hit countis low, the statement pool is probably not being used to itsbest advantage.

long getHitCount()

Returns the miss count for the statement pool. The misscount is the number of times a lookup is performed for astatement that fails to result in a cache hit. A cache hitoccurs when the Statement Pool Monitor successfully findsa statement in the pool with the same SQL text, statementtype, result set type, result set concurrency, and requestedgenerated key information.

This method is useful to determine if your workload is usingthe statement pool effectively. For example, if the misscount is high, the statement pool is probably not being usedto its best advantage.

long getMissCount()

Returns the maximum number of statements that can bestored in the statement pool.

int getMaxSize()

Changes the maximum number of statements that can bestored in the statement pool to the specified value.

int setMaxSize(int value)

Closes and discards all the statements in the statementpool.

void emptyPool()

Resets the hit and miss counts to zero (0). See longgetHitCount() and long getMissCount() for moreinformation.

void resetCounts()

Returns a list of statements in the pool. The list is an arraythat contains a String entry for each statement in thestatement pool.

ArrayList poolEntries(int statementType,int resultSetType, int resultSetConcurrency)

Exports statements from the statement pool into thespecified file. The file format contains an entry for eachstatement in the statement pool.

void exportStatements(File file_object)

Exports statements from statement pool into the specifiedfile. The file format contains an entry for each statement inthe statement pool.

void exportStatements(String file_name)




Imports statements from the specified File object into thestatement pool.

void importStatements(File file_object)

Imports statements from the specified file into the statementpool.

void importStatements(String file_name)

Returns whether the state of the statement pool is frozen.When the statement pool is frozen, the statements that canbe stored in the pool are restricted to those that were in thepool at the time the pool was frozen. Freezing a pool isuseful if you have a core set of statements that you do notwant replaced by other statements when the corestatements are closed.

boolean isFrozen()

setFrozen(true) freezes the statement pool.setFrozen(false) unfreezes the statement pool. Whenthe statement pool is frozen, the statements that can bestored in the pool are restricted to those that were in thepool at the time the pool was frozen. Freezing a pool isuseful if you have a core set of statements that you do notwant replaced by other statements when the corestatements are closed.

void setFrozen(boolean)

DataDirect TestUse DataDirect Test to test your JDBC applications and learn the JDBC API. DataDirect Test contains menuselections that correspond to specific JDBC functions, for example, connecting to a database or passing a SQLstatement. DataDirect Test allows you to perform the following tasks:

• Execute a single JDBC method or execute multiple JDBC methods simultaneously, so that you can easilyperform some common tasks, such as returning result sets

• Display the results of all JDBC function calls in one window, while displaying fully commented, JDBC codein an alternate window

DataDirect Test works only with JDBC drivers from Progress DataDirect.

DataDirect Test TutorialThis DataDirect Test tutorial explains how to use the most important features of DataDirect Test (and the JDBCAPI) and assumes that you can connect to a database with the standard available demo table or fine-tune thesample SQL statements shown in this example as appropriate for your environment.

Note: The tutorial describes functionality across a spectrum of data stores. In some cases, the functionalitydescribed may not apply to the driver or data store you are using. Additionally, examples are drawn from avariety of drivers and data stores.


DataDirect Test

Note: The step-by-step examples used in this tutorial do not show typical clean-up routines (for example,closing result sets and connections). These steps have been omitted to simplify the examples. Do not forgetto add these steps when you use equivalent code in your applications.

Configuring DataDirect TestThe default DataDirect Test configuration file is:

install_dir/testforjdbc/Config.txt

where:

install_dir

is your product installation directory.

The DataDirect Test configuration file can be edited as appropriate for your environment using any text editor.All parameters are configurable, but the most commonly configured parameters are:

A list of colon-separated JDBC driver classes.Drivers

The default JDBC driver that appears in the Get Driver URL window.DefaultDriver

A list of comma-separated JDBC URLs. The first item in the list appears asthe default in theDatabase Selectionwindow. You can use one of these URLsas a template when you make a JDBC connection. The default Config.txt filecontains example URLs for most databases.

Databases

Set to com.sun.jndi.fscontext.RefFSContextFactory if you are usingfile system data sources, or com.sun.jndi.ldap.LdapCtxFactory if youare using LDAP.

InitialContextFactory

The location of the .bindings file if you are using file system data sources, oryour LDAP Provider URL if you are using LDAP.

ContextProviderURL

A list of comma-separated JDBC data sources. The first item in the list appearsas the default in the Data Source Selection window.

Datasources

To connect using a data source, DataDirect Test needs to access a JNDI data store to persist the data sourceinformation. By default, DataDirect Test is configured to use the JNDI File System Service Provider to persistthe data source. You can download the JNDI File System Service Provider from the Oracle Java PlatformTechnology Downloads page.

Make sure that the fscontext.jar and providerutil.jar files from the download are on your classpath.

Starting DataDirect TestHow you start DataDirect Test depends on your platform:

• As a Java application on Windows. Run the testforjdbc.bat file located in the testforjdbcsubdirectory of your product installation directory.

• As a Java application on Linux/UNIX. Run the testforjdbc.sh shell script located in the testforjdbcsubdirectory in the installation directory.

After you start DataDirect Test, the Test for JDBC Tool window appears.





The main Test for JDBC Tool window shows the following information:

• In the Connection List box, a list of available connections.

• In the JDBC/Database Output scroll box, a report indicating whether the last action succeeded or failed.

• In the Java Code scroll box, the actual Java code used to implement the last action.

Tip: DataDirect Test windows contain two Concatenate check boxes. Select a Concatenate check box tosee a cumulative record of previous actions; otherwise, only the last action is shown. Selecting Concatenatecan degrade performance, particularly when displaying large result sets.

Connecting Using DataDirect TestYou can use either of the following methods to connect using DataDirect Test:

• Using a data source

• Using a driver/database selection

Connecting Using a Data SourceTo connect using a data source, DataDirect Test needs to access a JNDI data store to persist the data sourceinformation. By default, DataDirect Test is configured to use the JNDI File System Service Provider to persistthe data source. You can download the JNDI File System Service Provider from the Oracle Java PlatformTechnology Downloads page.

Make sure that the fscontext.jar and providerutil.jar files from the download are on your classpath.

To connect using a data source:


DataDirect Test



1. From the main Test for JDBC Tool window menu, select Connection / Connect to DB via Data Source.The Select A Datasource window appears.

2. Select a data source from the Defined Datasources pane. In the User Name and Password fields, typevalues for the User and Password connection properties; then, click Connect. For information about JDBCconnection properties, refer to your driver's connection property descriptions.

3. If the connection was successful, the Connection window appears and shows the ConnectionEstablished message in the JDBC/Database Output scroll box.

Connecting Using Database SelectionTo connect using database selection:

1. From the Test for JDBC Tool window menu, select Driver / Register Driver. DataDirect Test prompts fora JDBC driver name.

2. In the Please Supply a Driver URL field, specify a driver (for examplecom.ddtek.jdbc.sqlserver.SQLServerDriver); then, click OK.

If the driver was registered successfully, the Test for JDBC Tool window appears with a confirmation inthe JDBC/Database Output scroll box.



3. From the Test for JDBC Tool window, select Connection / Connect to DB. The Select A Databasewindow appears with a list of default connection URLs.

4. Select one of the default driver connection URLs. In the Database field, modify the default values of theconnection URL appropriately for your environment.

Note: There are two entries for DB2: one with locationName and another with databaseName. If you areconnecting to DB2 for Linux/UNIX/Windows, select the entry containing databaseName. If you are connectingto DB2 for z/OS or DB2 for i, select the entry containing locationName.

5. In the User Name and Password fields, type the values for the User and Password connection properties;then, click Connect. For information about JDBC connection properties, refer to your driver's connectionproperty descriptions.

6. If the connection was successful, the Connection window appears and shows the ConnectionEstablished message in the JDBC/Database Output scroll box.


DataDirect Test

Executing a Simple Select StatementThis example explains how to execute a simple Select statement and return the results.

To Execute a Simple Select Statement:

1. From the Connection window menu, select Connection / Create Statement. The Connection windowindicates that the creation of the statement was successful.

2. Select Statement / Execute Stmt Query. DataDirect Test displays a dialog box that prompts for a SQLstatement.

3. Type a Select statement and click Submit. Then, click Close.

4. Select Results / Show All Results. The data from your result set displays in the JDBC/Database Outputscroll box.



5. Scroll through the code in the Java Code scroll box to see which JDBC calls have been implemented byDataDirect Test.

Executing a Prepared StatementThis example explains how to execute a parameterized statement multiple times.

To Execute a Prepared Statement:

1. From the Connection window menu, select Connection / Create Prepared Statement. DataDirect Testprompts you for a SQL statement.

2. Type an Insert statement and click Submit. Then, click Close.

3. Select Statement / Set Prepared Parameters. To set the value and type for each parameter:


DataDirect Test

a) Type the parameter number.

b) Select the parameter type.

c) Type the parameter value.

d) Click Set to pass this information to the JDBC driver.

4. When you are finished, click Close.

5. Select Statement / Execute Stmt Update. The JDBC/Database Output scroll box indicates that one rowhas been inserted.



6. If you want to insert multiple records, repeat Step 3 on page 93 and Step 5 on page 94 for each record.

7. If you repeat the steps described in "Executing a Simple Select Statement," you will see that the previouslyinserted records are also returned.


DataDirect Test

See alsoExecuting a Simple Select Statement on page 92

Retrieving Database Metadata1. From the Connection window menu, select Connection / Get DB Meta Data.

2. Select MetaData / Show Meta Data. Information about the JDBC driver and the database to which you areconnected is returned.



3. Scroll through the Java code in the Java Code scroll box to find out which JDBC calls have been implementedby DataDirect Test.

Metadata also allows you to query the database catalog (enumerate the tables in the database, for example).In this example, we will query all tables with the schema pattern test01.

4. Select MetaData / Tables.

5. In the Schema Pattern field, type test01.

6. Click Ok. The Connection window indicates that getTables() succeeded.

7. Select Results / Show All Results. All tables with a test01 schema pattern are returned.


DataDirect Test

Scrolling Through a Result Set1. From the Connection window menu, select Connection / Create JDBC 2.0 Statement. DataDirect Test

prompts for a result set type and concurrency.

2. Complete the following fields:

a) In the resultSetType field, select TYPE_SCROLL_SENSITIVE.

b) In the resultSetConcurrency field, select CONCUR_READ_ONLY.

c) Click Submit; then, click Close.

3. Select Statement / Execute Stmt Query.

4. Type a Select statement and click Submit. Then, click Close.



5. Select Results / Scroll Results. The Scroll Result Set window indicates that the cursor is positionedbefore the first row.

6. Click the Absolute, Relative, Before, First, Prev, Next, Last, and After buttons as appropriate to navigatethrough the result set. After each action, the Scroll Result Set window displays the data at the currentposition of the cursor.


DataDirect Test

7. Click Close.

Batch Execution on a Prepared StatementBatch execution on a prepared statement allows you to update or insert multiple records simultaneously. Insome cases, this can significantly improve system performance because fewer round trips to the database arerequired.

To Execute a Batch on a Prepared Statement:

1. From the Connection window menu, select Connection / Create Prepared Statement.

Type an Insert statement and click Submit. Then, click Close.

2. Select Statement / Add Stmt Batch.

3. For each parameter:

a) Type the parameter number.

b) Select the parameter type.

c) Type the parameter value.

d) Click Set.



4. Click Add to add the specified set of parameters to the batch. To add multiple parameter sets to the batch,repeat Step 2 on page 100 through Step 4 on page 101 as many times as necessary. When you are finishedadding parameter sets to the batch, click Close.

5. Select Statement / Execute Stmt Batch. DataDirect Test displays the rowcount for each of the elementsin the batch.

6. If you re-execute the Select statement from "Executing a Simple Select Statement," you see that thepreviously inserted records are returned.


DataDirect Test

See alsoExecuting a Simple Select Statement on page 92

Returning ParameterMetaData

Note: Returning ParameterMetaData requires a Java SE 5 or higher JVM.

1. From the Connection window menu, select Connection / Create Prepared Statement.

Type the prepared statement and click Submit. Then, click Close.

2. Select Statement / Get ParameterMetaData. The Connection window displays ParameterMetaData.



Establishing Savepoints

Note: Savepoints require a Java SE 5 or higher JVM.

1. From the Connection window menu, select Connection / Connection Properties.

2. Select TRANSACTION_COMMITTED from the Transaction Isolation drop-down list. Do not select the AutoCommit check box.

3. Click Set; then, click Close.

4. From the Connection window menu, select Connection / Load and Go. The Get Load And Go SQLwindow appears.

5. Type a statement and click Submit.


DataDirect Test

6. Select Connection / Set Savepoint.

7. In the Set Savepoints window, type a savepoint name.

8. Click Apply; then, click Close. The Connection window indicates whether or not the savepoint succeeded.

9. Return to the Get Load And Go SQL window and specify another statement. Click Submit.



10. Select Connection / Rollback Savepoint. In the Rollback Savepoints window, specify the savepointname.

11. Click Apply; then, click Close. The Connection window indicates whether or not the savepoint rollbacksucceeded.

12. Return to the Get Load And Go SQL window and specify another statement.


DataDirect Test

ClickSubmit; then, clickClose. TheConnectionwindow displays the data inserted before the first Savepoint.The second insert was rolled back.

Updatable Result SetsThe following examples explain the concept of updatable result sets by deleting, inserting, and updating a row.

Deleting a Row

1. From the Connection window menu, select Connection / Create JDBC 2.0 Statement.



b) In the resultSetConcurrency field, select CONCUR_UPDATABLE.



3. Click Submit; then, click Close.


5. Specify the Select statement and click Submit. Then, click Close.

6. Select Results / Inspect Results. The Inspect Result Set window appears.


DataDirect Test

7. Click Next. Current Row changes to 1.

8. Click Delete Row.

9. To verify the result, return to the Connection menu and select Connection / Load and Go. The Get LoadAnd Go SQL window appears.

10. Specify the statement that you want to execute and click Submit. Then, click Close.



11. The Connection window shows that the row has been deleted.

Inserting a Row






DataDirect Test



5. Specify the Select statement that you want to execute and click Submit. Then, click Close.




7. Click Move to insert row; Current Row is now Insert row.

8. Change Data Type to int. In Set Cell Value, enter 20. Click Set Cell.

9. Select the second row in the top pane. Change the Data Type to String. In Set Cell Value, enter RESEARCH.Click Set Cell.

10. Select the third row in the top pane. In Set Cell Value, enter DALLAS. Click Set Cell.

11. Click Insert Row.


13. Specify the statement that you want to execute and click Submit. Then, click Close.


DataDirect Test

14. The Connection window shows the newly inserted row.

Caution: The ID will be 3 for the row you just inserted because it is an auto increment column.

Updating a Row









5. Specify the Select statement that you want to execute.




DataDirect Test


9. In Set Cell Value, type RALEIGH. Then, click Set Cell.

10. Click Update Row.


12. Specify the statement that you want to execute.




14. The Connection window shows LOC for accounting changed from NEW YORK to RALEIGH.

Retrieving Large Object Data

Note: LOB support (Blobs and Clobs) requires a Java SE 5 or higher JVM.

The following example uses Clob data; however, this procedure also applies to Blob data. This exampleillustrates only one of multiple ways in which LOB data can be processed.

1. From the Connection window menu, select Connection / Create Statement.


3. Specify the Select statement that you want to execute.


DataDirect Test




7. Deselect Auto Traverse. This disables automatic traversal to the next row.



8. Click Get Cell. Values are returned in the Get Cell Value field.

9. Change the data type to Clob.


DataDirect Test

10. Click Get Cell. The Clob data window appears.



11. Click Get Cell. Values are returned in the Cell Value field.


DataDirect Test

Tracking JDBC Calls with DataDirect SpyDataDirect Spy is functionality that is built into the drivers. It is used to log detailed information about calls yourdriver makes and provide information you can use for troubleshooting. DataDirect Spy provides the followingadvantages:

• Logging is JDBC 4.0-compliant.

• All parameters and function results for JDBC calls can be logged.

• Logging can be enabled without changing the application.

When you enable DataDirect Spy for a connection, you can customize logging by setting one or multiple optionsfor DataDirect Spy. For example, you may want to direct logging to a local file on your machine.

Once logging is enabled for a connection, you can turn it on and off at runtime using the setEnableLogging()method in the com.ddtek.jdbc.extensions.ExtLogControl interface. See "Troubleshooting Your Application" forinformation about using a DataDirect Spy log for troubleshooting.

See alsoTroubleshooting your application on page 155

Enabling DataDirect SpyYou can enable and customize DataDirect Spy logging in either of the following ways.

• Specifying the SpyAttributes connection property for connections using the JDBC DriverManager.

• Specifying DataDirect Spy attributes using a JDBC DataSource.

Using the JDBC Driver ManagerThe SpyAttributes connection property allows you to specify a semi-colon separated list of DataDirect Spyattributes (see "DataDirect Spy Attributes"). The format for the value of the SpyAttributes property is:

(spy_attribute[;spy_attribute]...)

where spy_attribute is any valid DataDirect Spy attribute. See "DataDirect Spy Attributes" for a list ofsupported attributes.

Note: The following examples are drawn from Microsoft SQL Server and DB2 use cases. However, they informthe implementation of DataDirect Spy for most Progress DataDirect drivers.



Example on Windows:The following example uses the JDBC Driver Manager to connect to Microsoft SQL Server while enablingDataDirect Spy:

Class.forName("com.ddtek.jdbc.sqlserver.SQLServerDriver");Connection conn = DriverManager.getConnection

("jdbc:datadirect:sqlserver://Server1:1433;DatabaseName=Test;User=admin;Password=secret;SpyAttributes=(log=(filePrefix)C:\\temp\\spy_;linelimit=80;logTName=yes;timestamp=yes)");

Note: If coding a path on Windows to the log file in a Java string, the backslash character (\) must be precededby the Java escape character, a backslash. For example: log=(filePrefix)C:\\temp\\spy_.

Using this example, DataDirect Spy loads the SQL Server driver and logs all JDBC activity to the spy_x.logfile located in the C:\temp directory (log=(filePrefix)C:\\temp\\spy_), where x is an integer thatincrements by 1 for each connection on which the prefix is specified. The spy_x.log file logs a maximum of80 characters on each line (linelimit=80) and includes the name of the current thread (logTName=yes)and a timestamp on each line in the log (timestamp=yes).

Example on UNIX:The following code example uses the JDBC Driver Manager to connect to DB2 while enabling DataDirect Spy:

Class.forName("com.ddtek.jdbc.db2.DB2Driver");Connection conn = DriverManager.getConnection

("jdbc:datadirect:db2://Server1:50000;DatabaseName=Test;User=TEST;Password=secret;SpyAttributes=(log=(filePrefix)/tmp/spy_;logTName=yes;timestamp=yes)");

Using this example, DataDirect Spy loads the DB2 driver and logs all JDBC activity to the spy_x.log filelocated in the /tmp directory (log=(filePrefix)/tmp/spy_), where x is an integer that incrementsby 1 for each connection on which the prefix is specified. The spy_x.log file includes the name of the currentthread (logTName=yes) and a timestamp on each line in the log (timestamp=yes).

See alsoDataDirect Spy Attributes on page 122

Using JDBC Data SourcesThe drivers implement the following JDBC features:

• JNDI for Naming Databases

• Connection Pooling

You can use DataDirect Spy to track JDBC calls made by a running application with either of these features.The com.ddtek.jdbcx.datasource.Driver DataSource class, where Driver is the driver name, supports settinga semi-colon-separated list of DataDirect Spy attributes (see "DataDirect Spy Attributes").

Note: The following examples are drawn from DB2 and Oracle use cases. However, they inform theimplementation of DataDirect Spy for most Progress DataDirect drivers.


Tracking JDBC Calls with DataDirect Spy

Example on Windows:The following example creates a JDBC data source for the DB2 driver, which enables DataDirect Spy.

DB2DataSource sds=new DB2DataSource():sds.setServerName("Server1");sds.setPortNumber(50000);sds.setSpyAttributes("log=(file)C:\\temp\\spy.log;logIS=yes;logTName=yes");Connection conn=sds.getConnection("TEST","secret");...

Note: If coding a path on Windows to the log file in a Java string, the backslash character (\) must be precededby the Java escape character, a backslash. For example:log=(file)C:\\temp\\spy.log;logIS=yes;logTName=yes.

Using this example, DataDirect Spy would load the DB2 driver and log all JDBC activity to the spy.log filelocated in the C:\temp directory (log=(file)C:\\temp\\spy.log). In addition to regular JDBC activity,the spy.log file also logs activity on InputStream and Reader objects (logIS=yes). It also includes the nameof the current thread (logTName=yes).

Example on UNIX:The following example creates a JDBC data source for the Oracle driver, which enables DataDirect Spy.

OracleDataSource mds = new OracleDataSource();mds.setServerName("Server1");mds.setPortNumber(1521);mds.setSID("ORCL");...sds.setSpyAttributes("log=(file)/tmp/spy.log;logTName=yes");Connection conn=sds.getConnection("TEST","secret");...

Using this example, DataDirect Spy would load the Oracle driver and log all JDBC activity to the spy.log filelocated in the /tmp directory (log=(file)/tmp/spy.log). The spy.log file includes the name of the currentthread (logTName=yes).

See alsoDataDirect Spy Attributes on page 122

DataDirect Spy AttributesDataDirect Spy supports the attributes described in the following table.

Table 14: DataDirect Spy Attributes

DescriptionAttribute

Sets the maximum number of characters that DataDirect Spy logs on a single line.

The default is 0 (no maximum limit).

linelimit=numberofchars

Loads the driver specified by classname.load=classname



DescriptionAttribute

Directs logging to the file specified by filename.

For Windows, if coding a path to the log file in a Java string, the backslash character(\) must be preceded by the Java escape character, a backslash. For example:log=(file)C:\\temp\\spy.log;logIS=yes;logTName=yes.

log=(file)filename

Directs logging to a file prefixed by file_prefix. The log file is namedfile_prefixX.log

where:

X

is an integer that increments by 1 for each connection on which the prefixis specified.

For example, if the attribute log=(filePrefix) C:\\temp\\spy_ is specified on multipleconnections, the following logs are created:

C:\temp\spy_1.logC:\temp\spy_2.logC:\temp\spy_3.log...

If coding a path to the log file in a Java string, the backslash character (\) must bepreceded by the Java escape character, a backslash. For example:log=(filePrefix)C:\\temp\\spy_;logIS=yes;logTName=yes.

log=(filePrefix)file_prefix

Directs logging to the Java output standard, System.out.log=System.out

Specifies whether DataDirect Spy logs activity on InputStream and Reader objects.

When logIS=nosingleread, logging on InputStream and Reader objects is active;however, logging of the single-byte read InputStream.read or single-characterReader.read is suppressed to prevent generating large log files that containsingle-byte or single character read messages.

The default is no.

logIS={yes | no | nosingleread}

Specifies whether DataDirect Spy logs activity on BLOB and CLOB objects.logLobs={yes | no}

Specifies whether DataDirect Spy logs the name of the current thread.

The default is no.

logTName={yes | no}

Specifies whether a timestamp is included on each line of the DataDirect Spy log.The default is no.

timestamp={yes | no}


Tracking JDBC Calls with DataDirect Spy

4Connection Property Descriptions

You can use connection properties to customize the driver for your environment. This section lists the connectionproperties supported by the driver and describes each property. You can use these connection properties witheither the JDBC Driver Manager or a JDBC data source. For a Driver Manager connection, a property isexpressed as a key value pair and takes the form property=value. For a data source connection, a propertyis expressed as a JDBC method and takes the form setproperty(value).

Note: All connection property names are case-insensitive. For example, Password is the same as password.Required properties are noted as such.

Note: The data type listed for each connection property is the Java data type used for the property value in aJDBC data source.

The following table provides a summary of the connection properties supported by the Impala driver and theirdefault values.

Table 15: Impala Driver Properties

DefaultData Source MethodProperty

empty stringsetAccountingInfoAccountingInfo on page 128

empty stringsetApplicationNameApplicationName on page 129

empty stringsetClientHostNameClientHostName on page 129

empty stringsetClientUserClientUser on page 130



5setConnectionRetryCountConnectionRetryCount on page 131

1 (second)setConnectionRetryDelayConnectionRetryDelay on page 132

1setConvertNullConvertNull on page 132

Determined by the JRE settingssetCryptoProtocolVersionCryptoProtocolVersion on page 133

The default databasesetDatabaseNameDatabaseName on page 134

-1setDefaultOrderByLimitDefaultOrderByLimit on page 135

noEncryptionsetEncryptionMethodEncryptionMethod on page 135

empty stringsetHostNameInCertificateHostNameInCertificate on page 137

empty stringsetImportStatementPoolImportStatementPool on page 138

NonesetInitializationStringInitializationString on page 138

2048setInsensitiveResultSetBufferSizeInsensitiveResultSetBufferSize on page139

falsesetJavaDoubleToStringJavaDoubleToString on page 140

NonesetKeyPasswordKeyPassword on page 141

NonesetKeyStoreKeyStore on page 141

NonesetKeyStorePasswordKeyStorePassword on page 142

0setLoginTimeoutLoginTimeout on page 143

NonesetMaxPooledStatementsMaxPooledStatements on page 144

NonesetPasswordPassword on page 145

21050setPortNumberPortNumber on page 145

empty stringsetProgramIDProgramID on page 146

falsesetRegisterStatementPoolMonitorMBeanRegisterStatementPoolMonitorMBeanon page 146

falsesetRemoveColumnQualifiersRemoveColumnQualifiers on page 147

NonesetServerNameServerName on page 148

NonesetSpyAttributesSpyAttributes on page 148

varcharsetStringDescribeTypeStringDescribeType on page 149


Chapter 4: Connection Property Descriptions


noTransactionssetTransactionModeTransactionMode on page 150

NonesetTrustStoreTrustStore on page 151

NonesetTrustStorePasswordTrustStorePassword on page 151

false (results are not restrictedto the tables and views in thecurrent schema)

setUseCurrentSchemaUseCurrentSchema on page 152

NonesetUserUser on page 153


• AccountingInfo

• ApplicationName

• ClientHostName

• ClientUser

• ConnectionRetryCount

• ConnectionRetryDelay

• ConvertNull

• CryptoProtocolVersion

• DatabaseName

• DefaultOrderByLimit

• EncryptionMethod

• HostNameInCertificate

• ImportStatementPool

• InitializationString

• InsensitiveResultSetBufferSize

• JavaDoubleToString

• KeyPassword

• KeyStore

• KeyStorePassword

• LoginTimeout

• MaxPooledStatements

• Password


• PortNumber

• ProgramID

• RegisterStatementPoolMonitorMBean

• RemoveColumnQualifiers

• ServerName

• SpyAttributes

• StringDescribeType

• TransactionMode

• TrustStore

• TrustStorePassword

• UseCurrentSchema

• User

• ValidateServerCertificate

AccountingInfoPurposeDefines accounting information. This value is stored locally and is used for database administration/monitoringpurposes.

Valid Valuesstring

where:

string

is the accounting information.

Data Source MethodsetAccountingInfo

Defaultempty string

Data TypeString

See also• Client Information on page 58




ApplicationNamePurposeSpecifies the name of the application to be stored in the database. This value is stored locally and is used fordatabase administration/monitoring purposes.

Valid Valuesstring

where:

string

is the name of the application.

Data Source MethodsetApplicationName

Defaultempty string

Data TypeString



ClientHostNamePurposeSpecifies the host name of the client machine to be stored in the database. This value is stored locally and isused for database administration/monitoring purposes.

Valid Valuesstring

where:

string

is the host name of the client machine.


ApplicationName

Data Source MethodsetClientHostName

Defaultempty string

Data TypeString



ClientUserPurposeSpecifies the user ID to be stored in the database. This value is stored locally and is used for databaseadministration/monitoring purposes.

Valid Valuesstring

where:

string

is a valid user ID.

Data Source MethodsetClientUser

Defaultempty string

Data TypeString





ConnectionRetryCountPurposeSpecifies the number of times the driver retries connection attempts to the server until a successful connectionis established.

Valid Values0 | x

where:

x

is a positive integer that represents the number of retries.

BehaviorIf set to 0, the driver does not try to reconnect after the initial unsuccessful attempt.

If set to x, the driver retries connection attempts the specified number of times. If a connection is not establishedduring the retry attempts, the driver returns an exception that is generated by the last Cloudera Impala serverto which it tried to connect.

ExampleIf this property is set to 2, the driver retries the server twice after the initial retry attempt.

Notes• If an application sets a login timeout value (for example, using DataSource.loginTimeout or

DriverManager.loginTimeout) and the login timeout expires, the driver ceases connection attempts.

• The ConnectionRetryDelay property specifies the wait interval, in seconds, to occur between retry attempts.

Data Source MethodsetConnectionRetryCount

Default5

Data Typeint


ConnectionRetryCount

ConnectionRetryDelayPurposeSpecifies the number of seconds the driver waits between connection retry attempts when ConnectionRetryCountis set to a positive integer.

Valid Values0 | x

where:

x

is a number of seconds.

BehaviorIf set to 0, the driver does not delay between retries.

If set to x, the driver waits between connection retry attempts the specified number of seconds.

ExampleIf ConnectionRetryCount is set to 2 and this property is set to 3, the driver retries the server twice after theinitial retry attempt. The driver waits 3 seconds between retry attempts.

Data Source MethodsetConnectionRetryDelay

Default1 (second)

Data Typeint

ConvertNullPurposeControls how data conversions are handled for null values.

Valid Values0 | 1



BehaviorIf set to 0, the driver does not perform the data type check if the value of the column is null. This allows nullvalues to be returned even though a conversion between the requested type and the column type is undefined.

If set to 1, the driver checks the data type being requested against the data type of the table column that storesthe data. If a conversion between the requested type and column type is not defined, the driver generates an"unsupported data conversion" exception regardless of whether the column value is NULL.

Data Source MethodsetConvertNull

Default1

Data Typeint

See alsoData Type Handling Properties on page 49

CryptoProtocolVersionPurposeSpecifies a cryptographic protocol or comma-separated list of cryptographic protocols that can be used whenSSL is enabled (EncryptionMethod=SSL).

Valid Valuescryptographic_protocol [[, cryptographic_protocol ]...]

where:

cryptographic_protocol

is one of the following cryptographic protocols:

TLSv1.2 | TLSv1.1 | TLSv1 | SSLv3 | SSLv2

Caution: To avoid vulnerabilities associated with SSLv3 and SSLv2, good security practices recommendusing TLSv1 or higher.

ExampleIf your server supports TLSv1.1 and TLSv1.2, you can specify acceptable cryptographic protocols with thefollowing key-value pair:

CryptoProtocolVersion=TLSv1.1,TLSv1.2


CryptoProtocolVersion

Notes• When multiple protocols are specified, the driver uses the highest version supported by the server. If none

of the specified protocols are supported by the server, the connection fails and the driver returns an error.

• When no value has been specified for CryptoProtocolVersion, the driver establishes an SSL connectionusing the default. If the default is not supported by the server, the connection fails and the driver returns anerror.

Data Source MethodsetCryptoProtocolVersion

DefaultThe default is determined by the settings of the JRE.

Data TypeString

See also• EncryptionMethod on page 135

• Data Encryption on page 55

DatabaseNamePurposeSpecifies the name of the Cloudera Impala database to which you want to connect.

Valid Valuesdatabase_name

where:

database_name

is the name of a valid Cloudera Impala database. If the driver cannot find the specified database,the connection fails.

Data Source MethodsetDatabaseName

DefaultThe default database

Data TypeString



See alsoRequired Properties on page 47

DefaultOrderByLimitPurposeSpecifies the maximum number of rows returned when a SQL statement containing an ORDER BY clause isexecuted. Cloudera Impala 1.3 requires statements containing the ORDER BY clause to limit the number ofrows returned. This option allows these statements to return a result set without specifying a limit in theapplication.

Valid Values-1 | x

where:

x

is a positive integer that represents maximum number of rows returned.

BehaviorIf set to -1 (disabled), there is no default limit to the number of rows returned by a statement containing anORDER BY clause. The application must limit the number of rows returned by SQL statements that containan ORDER BY clause, or Cloudera Impala 1.3 databases will return an error.

If set to x, the number of rows returned by a SQL statement containing an ORDER BY clause are limited tothe specified number of rows for the session. To override this value, specify a new value in a LIMIT clause inthe statement that is being executed.

Data Source MethodsetDefaultOrderByLimit

Default-1 (Disabled)


EncryptionMethodPurposeDetermines whether SSL encryption is used to encrypt and decrypt data transmitted over the network betweenthe driver and database server.


DefaultOrderByLimit

Valid ValuesnoEncryption | SSL

BehaviorIf set to noEncryption, data is not encrypted or decrypted.

If set to SSL, data is encrypted using SSL. If the database server does not support SSL, the connection failsand the driver throws an exception.

Notes• Connection hangs can occur if the driver attempts to connect to a database server that does not support

SSL. You may want to set a login timeout using the LoginTimeout property to avoid problems when connectingto a server that does not support SSL.

• When SSL is enabled, the following properties also apply:

CryptoProtocolVersion

HostNameInCertificate

KeyStore (for SSL client authentication)

KeyStorePassword (for SSL client authentication)

KeyPassword (for SSL client authentication)

TrustStore

TrustStorePassword

ValidateServerCertificate

Data Source MethodsetEncryptionMethod

DefaultnoEncryption

Data TypeString

See alsoData Encryption on page 55

Performance Considerations on page 54



HostNameInCertificatePurposeSpecifies a host name for certificate validation when SSL encryption is enabled (EncryptionMethod=SSL)and validation is enabled (ValidateServerCertificate=true). This property is optional and providesadditional security against man-in-the-middle (MITM) attacks by ensuring that the server the driver is connectingto is the server that was requested.

Valid Valueshost_name | #SERVERNAME#

where:

host_name

is a valid host name.

BehaviorIf host_name is specified, the driver compares the specified host name to the DNSName value of theSubjectAlternativeName in the certificate. If a DNSName value does not exist in the SubjectAlternativeNameor if the certificate does not have a SubjectAlternativeName, the driver compares the host name with theCommon Name (CN) part of the certificate’s Subject name. If the values do not match, the connection fails andthe driver throws an exception.

If #SERVERNAME# is specified, the driver compares the server name specified in the connection URL or datasource of the connection to the DNSName value of the SubjectAlternativeName in the certificate. If a DNSNamevalue does not exist in the SubjectAlternativeName or if the certificate does not have a SubjectAlternativeName,the driver compares the host name to the CN part of the certificate’s Subject name. If the values do not match,the connection fails and the driver throws an exception. If multiple CN parts are present, the driver validatesthe host name against each CN part. If any one validation succeeds, a connection is established.

Notes• If SSL encryption or certificate validation is not enabled, this property is ignored.

• If SSL encryption and validation is enabled and this property is unspecified, the driver uses the server namespecified in the connection URL or data source of the connection to validate the certificate.

Data Source MethodsetHostNameInCertificate

Defaultempty string

Data TypeString


HostNameInCertificate



ImportStatementPoolPurposeSpecifies the path and file name of the file to be used to load the contents of the statement pool. When thisproperty is specified, statements are imported into the statement pool from the specified file.

If the driver cannot locate the specified file when establishing the connection, the connection fails and the driverthrows an exception.

Valid Valuesstring

where:

string

is the path and file name of the file to be used to load the contents of the statement pool.

Data Source MethodsetImportStatementPool

Defaultempty string

Data TypeString

See also• Statement Pool Monitor on page 79

• Statement Pooling Properties on page 51

InitializationStringPurposeSpecifies one or multiple SQL commands to be executed by the driver after it has established the connectionto the database and has performed all initialization for the connection. If the execution of a SQL command fails,the connection attempt also fails and the driver throws an exception indicating which SQL command or commandsfailed.



Valid Valuescommand[[;command]...]

where:

command

is a SQL command.

NotesMultiple commands must be separated by semicolons. In addition, if this property is specified in a connectionURL, the entire value must be enclosed in parentheses when multiple commands are specified.

Examplejdbc:datadirect:impala://ImpalaServer:21050;User=Admin;Password=secret;DatabaseName=CompanyDB;InitializationString=(command1;command2)

Data Source MethodsetInitializationString

DefaultNone

Data TypeString

InsensitiveResultSetBufferSizePurposeDetermines the amount of memory that is used by the driver to cache insensitive result set data.

Valid Values-1 | 0 | x

where:

x

is a positive integer that represents the amount of memory.

BehaviorIf set to -1, the driver caches insensitive result set data in memory. If the size of the result set exceeds availablememory, an OutOfMemoryException is generated. With no need to write result set data to disk, the driverprocesses the data efficiently.


InsensitiveResultSetBufferSize

If set to 0, the driver caches insensitive result set data in memory, up to a maximum of 2 MB. If the size of theresult set data exceeds available memory, then the driver pages the result set data to disk, which can have anegative performance effect. Because result set data may be written to disk, the driver may have to reformatthe data to write it correctly to disk.

If set to x, the driver caches insensitive result set data in memory and uses this value to set the size (in KB) ofthe memory buffer for caching insensitive result set data. If the size of the result set data exceeds availablememory, then the driver pages the result set data to disk, which can have a negative performance effect.Because the result set data may be written to disk, the driver may have to reformat the data to write it correctlyto disk. Specifying a buffer size that is a power of 2 results in efficient memory use.

Data Source MethodsetInsensitiveResultSetBufferSize

Default2048

Data Typeint

See alsoPerformance Considerations

JavaDoubleToStringPurposeDetermines which algorithm the driver uses when converting a double or float value to a string value. By default,the driver uses its own internal conversion algorithm, which improves performance.

Valid Valuestrue | false

BehaviorIf set to true, the driver uses the JVM algorithm when converting a double or float value to a string value. Ifyour application cannot accept rounding differences and you are willing to sacrifice performance, set this valueto true to use the JVM conversion algorithm.

If set to false, the driver uses its own internal algorithm when converting a double or float value to a stringvalue. This value improves performance, but slight rounding differences within the allowable error of the doubleand float data types can occur when compared to the same conversion using the JVM algorithm.

Data Source MethodsetJavaDoubleToString

Defaultfalse



Data TypeBoolean

KeyPasswordPurposeSpecifies the password that is used to access the individual keys in the keystore file when SSL is enabled(EncryptionMethod=SSL) and SSL client authentication is enabled on the database server. This propertyis useful when individual keys in the keystore file have a different password than the keystore file.

Valid Valuesstring

where:

string

is a valid password.

Data Source MethodsetKeyPassword

DefaultNone

Data TypeString



KeyStorePurposeSpecifies the directory of the keystore file to be used when SSL is enabled (EncryptionMethod=SSL) andSSL client authentication is enabled on the database server. The keystore file contains the certificates that theclient sends to the server in response to the server’s certificate request.

This value overrides the directory of the keystore file that is specified by the javax.net.ssl.keyStore Java systemproperty. If this property is not specified, the keystore directory is specified by the javax.net.ssl.keyStore Javasystem property.


KeyPassword

Valid Valuesstring

where:

string

is a valid directory of a keystore file.

Notes• The keystore and truststore files can be the same file.

Data Source MethodsetKeyStore

DefaultNone

Data TypeString



KeyStorePasswordPurposeSpecifies the password that is used to access the keystore file when SSL is enabled (EncryptionMethod=SSL)and SSL client authentication is enabled on the database server. The keystore file contains the certificates thatthe client sends to the server in response to the server’s certificate request.

This value overrides the password of the keystore file that is specified by the javax.net.ssl.keyStorePasswordJava system property. If this property is not specified, the keystore password is specified by thejavax.net.ssl.keyStorePassword Java system property.

Notes• The keystore and truststore files can be the same file.

Valid Valuesstring

where:

string

is a valid password.



Data Source MethodsetKeyStorePassword

DefaultNone

Data TypeString



LoginTimeoutPurposeSpecifies the amount of time, in seconds, that the driver waits for a connection to be established before timingout the connection request.

Valid Values0 | x

where:

x

is a positive integer that represents a number of seconds.

BehaviorIf set to 0, the driver does not time out a connection request.

If set to x, the driver waits for the specified number of seconds before returning control to the application andthrowing a timeout exception.

Data Source MethodsetLoginTimeout

Default0

Data Typeint


LoginTimeout

MaxPooledStatementsPurposeSpecifies the maximum number of pooled prepared statements for this connection. Setting MaxStatements toan integer greater than zero (0) enables the driver’s internal prepared statement pooling, which is useful whenthe driver is not running from within an application server or another application that provides its own preparedstatement pooling.

Valid Values0 | x

where

x

is a positive integer that represents a number of pooled prepared statements.

BehaviorIf set to 0, the driver’s internal prepared statement pooling is not enabled.

If set to x, the driver enables the DataDirect Statement Pool and uses the specified value to cache a certainnumber of prepared statements created by an application. If the value set for this property is greater than thenumber of prepared statements that are used by the application, all prepared statements that are created bythe application are cached. Because CallableStatement is a sub-class of PreparedStatement, CallableStatementsalso are cached.

ExampleIf the value of this property is set to 20, the driver caches the last 20 prepared statements that are created bythe application.

Data Source MethodsetMaxPooledStatements

Default0

Data Typeint

AliasMaxStatements





PasswordPurposeSpecifies a password that is used to connect to the database.

Valid Valuesstring

where:

string

is a valid password. The password is case-sensitive.

Data Source MethodsetPassword

DefaultNone

Data TypeString

PortNumberPurposeSpecifies the TCP port of the primary database server that is listening for connections to the database. Thisproperty is supported only for data source connections.

Valid Valuesport

where:

port

is the port number.

Data Source MethodsetPortNumber

Default21050


Password

Data Typeint

ProgramIDPurposeSpecifies the driver and version information on the client to be stored in the database. This value is storedlocally and is used for database administration/monitoring purposes.

Valid Valuesstring

where:

string

is a value that identifies the product and version of the driver on the client.

ExampleDDJ04200

Data Source MethodsetProgramID

Defaultempty string

Data TypeString



RegisterStatementPoolMonitorMBeanPurposeRegisters the Statement Pool Monitor as a JMX MBean when statement pooling has been enabled withMaxPooledStatements. This allows you to manage statement pooling with standard JMX API calls and to useJMX-compliant tools, such as JConsole.




BehaviorIf set to true, the driver registers an MBean for the statement pool monitor for each statement pool. This givesapplications access to the Statement Pool Monitor through JMX when statement pooling is enabled.

If set to false, the driver does not register an MBean for the statement pool monitor for any statement pool.

NotesRegistering the MBean exports a reference to the Statement Pool Monitor. The exported reference can preventgarbage collection on connections if the connections are not properly closed. When garbage collection doesnot take place on these connections, out of memory errors can occur.

Data Source MethodsetRegisterStatementPoolMonitorMBean

Defaultfalse

Data Typeboolean



• MaxPooledStatements on page 144

RemoveColumnQualifiersPurposeSpecifies whether the driver removes 3-part column qualifiers and replaces them with alias.column qualifiers.


BehaviorIf set to true (enabled), the driver removes 3-part column qualifiers and replaces them with alias.columnqualifiers.

If set to false, the driver does not modify the request.

Data Source MethodsetRemoveColumnQualifiers


RemoveColumnQualifiers

Defaultfalse (Disabled)

Data Typeboolean


ServerNamePurposeSpecifies either the IP address or the server name (if your network supports named servers) of the primarydatabase server. This property is supported only for data source connections.

Valid Valuesstring

where:

string

is a valid IP address or server name.

Example122.23.15.12 or MyImpalaServer

Data Source MethodsetServerName

DefaultNone

Data TypeString

SpyAttributesPurposeEnables DataDirect Spy to log detailed information about calls issued by the driver on behalf of the application.DataDirect Spy is not enabled by default.



Valid Values(spy_attribute[;spy_attribute]...)

where:

spy_attribute

is any valid DataDirect Spy attribute.

NotesIf coding a path on Windows to the log file in a Java string, the backslash character (\) must be preceded bythe Java escape character, a backslash. For example: log=(file)C:\\temp\\spy.log.

ExampleThe following value instructs the driver to log all JDBC activity to a file using a maximum of 80 characters foreach line.

(log=(file)/tmp/spy.log;linelimit=80)

Data Source MethodsetSpyAttributes

DefaultNone

See alsoTracking JDBC Calls with DataDirect Spy on page 120

StringDescribeTypePurposeSpecifies whether String columns are described as VARCHAR columns. This property affects ResultSetMetaDatacalls; it does not affect getTypeInfo() calls.

Valid Valuesvarchar | longvarchar

BehaviorIf set to varchar, String columns are described as VARCHAR.

If set to longvarchar, String columns are described as LONGVARCHAR.

NotesTo obtain data from String columns with the getClob() method, the StringDescribeType connection propertymust be set to longvarchar. Otherwise, calling getClob() results in an "unsupported data conversion"exception.


StringDescribeType

Data Source MethodsetStringDescribeType

Defaultvarchar

Data TypeString


TransactionModePurposeSpecifies how the driver handles manual transactions.

Valid Valuesignore | noTransactions

BehaviorIf set to ignore, the data source does not support transactions and the driver always operates in auto-commitmode. Calls to set the driver to manual commit mode and to commit transactions are ignored. Calls to rollbacka transaction cause the driver to throw an exception indicating that no transaction is started. Metadata indicatesthat the driver supports transactions and the READ UNCOMMITTED transaction isolation level.

If set to noTransactions, the data source and the driver do not support transactions. Metadata indicatesthat the driver does not support transactions.

NotesImpala does not support transactions, and by default, the Impala driver reports that transactions are notsupported. However, some applications will not operate with a driver that reports transactions are not supported.The TransactionMode connection property allows you to configure the driver to report that it supports transactions.In this mode, the driver ignores requests to enter manual commit mode, start a transaction, or commit atransaction. Requests to rollback a transaction return an error regardless of the transaction mode specified.

Data Source MethodsetTransactionMode

DefaultnoTransactions

Data TypeString



TrustStorePurposeSpecifies the directory of the truststore file to be used when SSL is enabled (EncryptionMethod=SSL) andserver authentication is used. The truststore file contains a list of the Certificate Authorities (CAs) that the clienttrusts.

This value overrides the directory of the truststore file that is specified by the javax.net.ssl.trustStore Javasystem property. If this property is not specified, the truststore directory is specified by the javax.net.ssl.trustStoreJava system property.

This property is ignored if ValidateServerCertificate=false.

Valid Valuesstring

where:

string

is the directory of the truststore file.

Data Source MethodsetTrustStore

DefaultNone

Data TypeString



TrustStorePasswordPurposeSpecifies the password that is used to access the truststore file when SSL is enabled (EncryptionMethod=SSL)and server authentication is used. The truststore file contains a list of the Certificate Authorities (CAs) that theclient trusts.

This value overrides the password of the truststore file that is specified by the javax.net.ssl.trustStorePasswordJava system property. If this property is not specified, the truststore password is specified by thejavax.net.ssl.trustStorePassword Java system property.


TrustStore

This property is ignored if ValidateServerCertificate=false.

Valid Valuesstring

where:

string

is a valid password for the truststore file.

Data Source MethodsetTrustStorePassword

DefaultNone

Data TypeString



UseCurrentSchemaPurposeSpecifies whether results are restricted to the tables and views in the current schema if a call is made withoutspecifying a schema or if the schema is specified as the wildcard character %. Restricting results to the tablesand views in the current schema improves performance of calls that do not specify a schema.


BehaviorIf set to true, the results that are returned from getTables() and getColumns() methods are restricted to thetables and views in the current schema.

If set to false, the results that are returned from getTables() and getColumns() methods are not restricted.

Defaultfalse

Data TypeBoolean




UserPurposeSpecifies the user name that is used to connect to the database.

Valid Valuesstring

where:

string

is a valid user name. The user name is case-insensitive.

DefaultNone

Data TypeString

ValidateServerCertificatePurposeDetermines whether the driver validates the certificate that is sent by the database server when SSL encryptionis enabled (EncryptionMethod=SSL). When using SSL server authentication, any certificate that is sent bythe server must be issued by a trusted Certificate Authority (CA). Allowing the driver to trust any certificate thatis returned from the server even if the issuer is not a trusted CA is useful in test environments because iteliminates the need to specify truststore information on each client in the test environment.


BehaviorIf set to true, the driver validates the certificate that is sent by the database server. Any certificate from theserver must be issued by a trusted CA in the truststore file. If the HostNameInCertificate property is specified,the driver also validates the certificate using a host name. The HostNameInCertificate property is optional andprovides additional security against man-in-the-middle (MITM) attacks by ensuring that the server the driver isconnecting to is the server that was requested.

If set to false, the driver does not validate the certificate that is sent by the database server. The driver ignoresany truststore information that is specified by the TrustStore and TrustStorePassword properties or Java systemproperties.


User

Notes• Truststore information is specified using the TrustStore and TrustStorePassword properties or by using

Java system properties.

Data Source MethodsetValidateServerCertificate

Defaulttrue

Data Typeboolean





5Troubleshooting

This section provides information that can help you troubleshoot problems when they occur.


• Troubleshooting your application

• Troubleshooting Connection Pooling

• Troubleshooting Statement Pooling

• Configuring Logging

Troubleshooting your applicationTo help you troubleshoot any problems that occur with your application, you can use DataDirect Spy to logdetailed information about calls issued by the drivers on behalf of your application. When you enable DataDirectSpy for a connection, you can customize DataDirect Spy logging by setting one or multiple options. See "TrackingJDBC Calls with DataDirect Spy" for information about using DataDirect Spy and instructions on enabling andcustomizing logging.

See alsoTracking JDBC Calls with DataDirect Spy on page 120


Turning On and Off DataDirect Spy LoggingOnce DataDirect Spy logging is enabled for a connection, you can turn on and off the logging at runtime usingthe setEnableLogging() method in the com.ddtek.jdbc.extensions.ExtLogControl interface. When DataDirectSpy logging is enabled, all Connection objects returned to an application provide an implementation of theExtLogControl interface.

The following code example is drawn from a Microsoft SQL Server use case but informs the use of loggingwith DataDirect Spy with most Progress DataDirect drivers. The code shows how to turn off logging usingsetEnableLogging(false).

import com.ddtek.jdbc.extensions.*

// Get Database ConnectionConnection con = DriverManager.getConnection

("jdbc:datadirect:sqlserver://server1:1433;User=TEST;Password=secret;SpyAttributes=(log=(file)/tmp/spy.log");

((ExtLogControl) con).setEnableLogging(false);...

The setEnableLogging() method only turns on and off logging if DataDirect Spy logging has already beenenabled for a connection; it does not set or change DataDirect Spy attributes. See "Enabling DataDirect Spy"for information about enabling and customizing DataDirect Spy logging.

See alsoEnabling DataDirect Spy on page 120

DataDirect Spy Log ExampleThis section provides information to help you understand the content of your own DataDirect Spy logs.

Note: The following code example is drawn from a Microsoft SQL Server use case but informs the use oflogging with DataDirect Spy with most Progress DataDirect drivers.

For example, suppose your application executes the following code and performs some operations:Class.forName("com.ddtek.jdbc.sqlserver.SQLServerDriver");DriverManager.getConnection("jdbc:datadirect:sqlserver:// nc-myserver\\sqlserver2005;useServerSideUpdatableCursors=true;resultsetMetaDataOptions=1;sendStringParametersAsUnicode=true;alwaysReportTriggerResults=false;spyAttributes=(log=(file)c:\\temp\\spy.log)","test04", "test04");

The log file generated by DataDirect Spy would look similar to the following example. Notes provide explanationsfor the referenced text.

spy>> Connection[1].getMetaData()spy>> OK (DatabaseMetaData[1])

spy>> DatabaseMetaData[1].getURL()spy>> OK(jdbc:datadirect:sqlserver://nc-myserver\sqlserver2005:1433;CONNECTIONRETRYCOUNT=5;RECEIVESTRINGPARAMETERTYPE=nvarchar;ALTERNATESERVERS=;DATABASENAME=;PACKETSIZE=16;INITIALIZATIONSTRING=;ENABLECANCELTIMEOUT=false;BATCHPERFORMANCEWORKAROUND=false;AUTHENTICATIONMETHOD=auto;SENDSTRINGPARAMETERSASUNICODE=true;LOGINTIMEOUT=0;WSID=;SPYATTRIBUTES=(log=(file)c:\temp\spy.log);RESULTSETMETADATAOPTIONS=1;ALWAYSREPORTTRIGGERRESULTS=false;TRANSACTIONMODE=implicit;USESERVERSIDEUPDATABLECURSORS=true;SNAPSHOTSERIALIZABLE=false;JAVADOUBLETOSTRING=false;SELECTMETHOD=direct;LOADLIBRARYPATH=;CONNECTIONRETRYDELAY=1;INSENSITIVERESULTSETBUFFERSIZE=2048;MAXPOOLEDSTATEMENTS=0;DESCRIBEPARAMETERS=noDescribe;CODEPAGEOVERRIDE=;NETADDRESS=000000000000;


Chapter 5: Troubleshooting

PROGRAMNAME=;LOADBALANCING=false;HOSTPROCESS=0)11

spy>> DatabaseMetaData[1].getDriverName()spy>> OK (SQLServer)

spy>> DatabaseMetaData[1].getDriverVersion()spy>> OK (3.60.0 (000000.000000.000000))

spy>> DatabaseMetaData[1].getDatabaseProductName()spy>> OK (Microsoft SQL Server)

spy>> DatabaseMetaData[1].getDatabaseProductVersion()spy>> OK (Microsoft SQL Server Yukon - 9.00.1399)

spy>> Connection Options :12

spy>> CONNECTIONRETRYCOUNT=5spy>> RECEIVESTRINGPARAMETERTYPE=nvarcharspy>> ALTERNATESERVERS=spy>> DATABASENAME=spy>> PACKETSIZE=16spy>> INITIALIZATIONSTRING=spy>> ENABLECANCELTIMEOUT=falsespy>> BATCHPERFORMANCEWORKAROUND=falsespy>> AUTHENTICATIONMETHOD=autospy>> SENDSTRINGPARAMETERSASUNICODE=truespy>> LOGINTIMEOUT=0spy>> WSID=spy>> SPYATTRIBUTES=(log=(file)c:\temp\spy.log)spy>> RESULTSETMETADATAOPTIONS=1spy>> ALWAYSREPORTTRIGGERRESULTS=falsespy>> TRANSACTIONMODE=implicitspy>> USESERVERSIDEUPDATABLECURSORS=truespy>> SNAPSHOTSERIALIZABLE=falsespy>> JAVADOUBLETOSTRING=falsespy>> SELECTMETHOD=directspy>> LOADLIBRARYPATH=spy>> CONNECTIONRETRYDELAY=1spy>> INSENSITIVERESULTSETBUFFERSIZE=2048spy>> MAXPOOLEDSTATEMENTS=0spy>> DESCRIBEPARAMETERS=noDescribespy>> CODEPAGEOVERRIDE=spy>> NETADDRESS=000000000000spy>> PROGRAMNAME=spy>> LOADBALANCING=falsespy>> HOSTPROCESS=0spy>> Driver Name = SQLServer13

spy>> Driver Version = 3.60.0 (000000.000000.000000)14

spy>> Database Name = Microsoft SQL Server15

spy>> Database Version = Microsoft SQL Server Yukon - 9.00.139916

spy>> Connection[1].getWarnings()spy>> OK17spy>> Connection[1].createStatementspy>> OK (Statement[1])

spy>> Statement[1].executeQuery(String sql)spy>> sql = select empno,ename,job from emp where empno=7369spy>> OK (ResultSet[1])18

spy>> ResultSet[1].getMetaData()spy>> OK (ResultSetMetaData[1])19

spy>> ResultSetMetaData[1].getColumnCount()spy>> OK (3)20

11 The combination of the URL specified by the application and the default values of all connection properties not specified.12 The combination of the connection properties specified by the application and the default values of all connection properties not specified.13 The name of the driver.14 The version of the driver.15 The name of the database server to which the driver connects.16 The version of the database to which the driver connects.17 The application checks to see if there are any warnings. In this example, no warnings are present.18

The statement select empno,ename,job from emp where empno=7369 is created.19 Some metadata is requested.20 Some metadata is requested.


Troubleshooting your application

spy>> ResultSetMetaData[1].getColumnLabel(int column)spy>> column = 1spy>> OK (EMPNO)21spy>> ResultSetMetaData[1].getColumnLabel(int column)spy>> column = 2spy>> OK (ENAME)22

spy>> ResultSetMetaData[1].getColumnLabel(int column)spy>> column = 3spy>> OK (JOB)23spy>> ResultSet[1].next()spy>> OK (true)24

spy>> ResultSet[1].getString(int columnIndex)spy>> columnIndex = 1spy>> OK (7369)25

spy>> ResultSet[1].getString(int columnIndex)spy>> columnIndex = 2spy>> OK (SMITH)26

spy>> ResultSet[1].getString(int columnIndex)spy>> columnIndex = 3spy>> OK (CLERK)27

spy>> ResultSet[1].next()spy>> OK (false)28spy>> ResultSet[1].close()spy>> OK29

spy>> Connection[1].close()spy>> OK30

Troubleshooting Connection PoolingConnection pooling allows connections to be reused rather than created each time a connection is requested.If your application is using connection pooling through the DataDirect Connection Pool Manager, you cangenerate a trace file that shows all the actions taken by the Pool Manager. See "Connection Pool Manager"for information about using the Pool Manager.

See alsoConnection Pool Manager on page 65

Enabling Tracing with the setTracing MethodYou can enable Pool Manager logging by calling setTracing(true) on the PooledConnectionDataSourceconnection. To disable tracing, call setTracing(false) on the connection.

By default, the DataDirect Connection Pool Manager logs its pool activities to the standard output System.out.You can change where the Pool Manager trace information is written by calling the setLogWriter() method onthe PooledConnectionDataSource connection.

21 Some metadata is requested.22 Some metadata is requested.23 Some metadata is requested.24 The first row is retrieved and the application retrieves the result values.25 The first row is retrieved and the application retrieves the result values.26 The first row is retrieved and the application retrieves the result values.27 The first row is retrieved and the application retrieves the result values.28 The application attempts to retrieve the next row, but only one row was returned for this query.29 After the application has completed retrieving result values, the result set is closed.30 The application finishes and disconnects.



Pool Manager Trace File ExampleThe following example shows a DataDirect Connection Pool Manager trace file. Notes provide explanationsfor the referenced text to help you understand the content of your own Pool Manager trace files.

Note: The example is drawn from a Microsoft SQL Server use case but applies to most Progress DataDirectdrivers.

jdbc/SQLServerNCMarkBPool: *** ConnectionPool Created(jdbc/SQLServerNCMarkBPool,com.ddtek.jdbcx.sqlserver.SQLServerDataSource@1835282, 5, 5, 10, scott)31

jdbc/SQLServerNCMarkBPool: Number pooled connections = 0.jdbc/SQLServerNCMarkBPool: Number free connections = 0.

jdbc/SQLServerNCMarkBPool: Enforced minimum!32

NrFreeConnections was: 0jdbc/SQLServerNCMarkBPool: Number pooled connections = 5.jdbc/SQLServerNCMarkBPool: Number free connections = 5.

jdbc/SQLServerNCMarkBPool: Reused free connection.33


jdbc/SQLServerNCMarkBPool: Reused free connection.jdbc/SQLServerNCMarkBPool: Number pooled connections = 5.jdbc/SQLServerNCMarkBPool: Number free connections = 3.




jdbc/SQLServerNCMarkBPool: Created new connection.34

31 The Pool Manager creates a connection pool. In this example, the characteristics of the connection pool are shown using the following format:

(JNDI_name,DataSource_class,initial_pool_size,min_pool_size,max_pool_size,user)

where:

JNDI_name is the JNDI name used to look up the connection pool (for example, jdbc/SQLServerNCMarkBPool).

DataSource_class is the DataSource class associated with the connection pool (for examplecom.ddtek.jdbcx.sqlserver.SQLServerDataSource).

initial_pool_size is the number of physical connections created when the connection pool is initialized (for example, 5).

min_pool_size is the minimum number of physical connections be kept open in the connection pool (for example, 5).

max_pool_size is the maximum number of physical connections allowed within a single pool at any one time. When this number isreached, additional connections that would normally be placed in a connection pool are closed (for example, 10).

user is the name of the user establishing the connection (for example, scott).32 The Pool Manager checks the pool size. Because the minimum pool size is five connections, the Pool Manager creates new connections to

satisfy the minimum pool size.33 The driver requests a connection from the connection pool. The driver retrieves an available connection.34 The driver requests a connection from the connection pool. Because a connection is unavailable, the Pool Manager creates a new connection

for the request.


Troubleshooting Connection Pooling


jdbc/SQLServerNCMarkBPool: Created new connection.jdbc/SQLServerNCMarkBPool: Number pooled connections = 7.jdbc/SQLServerNCMarkBPool: Number free connections = 0.





jdbc/SQLServerNCMarkBPool: Connection was closed and added to the cache.35


jdbc/SQLServerNCMarkBPool: Connection was closed and added to the cache.jdbc/SQLServerNCMarkBPool: Number pooled connections = 11.jdbc/SQLServerNCMarkBPool: Number free connections = 2.










35 A connection is closed by the application and returned to the connection pool.





jdbc/SQLServerNCMarkBPool: Enforced maximum!37


jdbc/SQLServerNCMarkBPool: Enforced minimum!NrFreeConnections was: 10jdbc/SQLServerNCMarkBPool: Number pooled connections = 10.jdbc/SQLServerNCMarkBPool: Number free connections = 10.

jdbc/SQLServerNCMarkBPool: Enforced maximum!NrFreeConnections was: 10jdbc/SQLServerNCMarkBPool: Number pooled connections = 10.jdbc/SQLServerNCMarkBPool: Number free connections = 10.

jdbc/SQLServerNCMarkBPool: Enforced minimum!NrFreeConnections was: 10jdbc/SQLServerNCMarkBPool: Number pooled connections = 10.jdbc/SQLServerNCMarkBPool: Number free connections = 10.


jdbc/SQLServerNCMarkBPool: Dumped free connection.38


jdbc/SQLServerNCMarkBPool: Dumped free connection.jdbc/SQLServerNCMarkBPool: Number pooled connections = 8.jdbc/SQLServerNCMarkBPool: Number free connections = 8.







jdbc/SQLServerNCMarkBPool: Dumped free connection.

36 The Pool Manager checks the pool size. Because the number of connections in the connection pool is greater than the minimum pool size,five connections, no action is taken by the Pool Manager.

37 The Pool Manager checks the pool size. Because the number of connections in the connection pool is greater than the maximum pool size,10 connections, a connection is closed and discarded from the pool.

38 The Pool Manager detects that a connection was idle in the connection pool longer than the maximum idle timeout. The idle connection isclosed and discarded from the pool.


Troubleshooting Connection Pooling






jdbc/SQLServerNCMarkBPool: Closing a pool of the groupjdbc/SQLServerNCMarkBPool40


jdbc/SQLServerNCMarkBPool: Pool closed41


Troubleshooting Statement PoolingSimilar to connection pooling, statement pooling provides performance gains for applications that execute thesame SQL statements multiple times in the life of the application. The DataDirect Statement Pool Monitorprovides the following functionality to help you troubleshoot problems that may occur with statement pooling:

• You can generate a statement pool export file that shows you all statements in the statement pool. Eachstatement pool entry in the file includes information about statement characteristics such as the SQL textused to generate the statement, statement type, result set type, and result set concurrency type.

• You can use the following methods of the ExtStatementPoolMonitorMBean interface to return usefulinformation to determine if your workload is using the statement pool effectively:

• The getHitCount() method returns the hit count for the statement pool. The hit count should be high forgood performance.

• The getMissCount() method returns the miss count for the statement pool. The miss count should below for good performance.

See alsoStatement Pool Monitor on page 79

39 The Pool Manager detects that the number of connections dropped below the limit set by the minimum pool size, five connections. The PoolManager creates new connections to satisfy the minimum pool size.

40 The Pool Manager closes one of the connection pools in the pool group. A pool group is a collection of pools created from the samePooledConnectionDataSource call. Different pools are created when different user IDs are used to retrieve connections from the pool. A poolgroup is created for each user ID that requests a connection. In our example, because only one user ID was used, only one pool group isclosed.

41 The Pool Manager closed all the pools in the pool group. The connection pool is closed.



Generating an Export File with the exportStatement MethodYou can generate an export file by calling the exportStatements() method of the ExtStatementPoolMonitorMBeaninterface. For example, the following code exports the contents of the statement pool associated with theconnection to a file named stmt_export:

ExtStatementPoolMonitor monitor =((ExtConnection) con).getStatementPoolMonitor();

exportStatements(stmt_export.txt)

Statement Pool Export File ExampleThe following example shows a sample export file. The footnotes provide explanations for the referenced textto help you understand the content of your own statement pool export files.

[DDTEK_STMT_POOL]42

VERSION=143

[STMT_ENTRY]44

SQL_TEXT=[INSERT INTO emp(id, name) VALUES(?,?)]STATEMENT_TYPE=Prepared StatementRESULTSET_TYPE=Forward OnlyRESULTSET_CONCURRENCY=Read OnlyAUTOGENERATEDKEYSREQUESTED=falseREQUESTEDKEYCOLUMNS=

[STMT_ENTRY]45

SQL_TEXT=[INSERT INTO emp(id, name) VALUES(99,?)]STATEMENT_TYPE=Prepared StatementRESULTSET_TYPE=Forward OnlyRESULTSET_CONCURRENCY=Read OnlyAUTOGENERATEDKEYSREQUESTED=falseREQUESTEDKEYCOLUMNS=id,name

Configuring LoggingYou can configure logging using a standard Java properties file that is shipped with your JVM. See Using theJVM for Logging on page 164 for details.

42 A string that identifies the file as a statement pool export file.43 The version of the export file.44 The first statement pool entry. Each statement pool entry lists the SQL text, statement type, result set type, result set concurrency type, and

generated keys information.45 The next statement pool entry.


Configuring Logging

Using the JVM for LoggingIf you want to configure logging using the properties file that is shipped with your JVM, use a text editor tomodify the properties file in your JVM. Typically, this file is named logging.properties and is located in theJRE/lib subdirectory of your JVM. The JRE looks for this file when it is loading.

You can also specify which properties file to use by setting the java.util.logging.config.file system property. Ata command prompt, enter:

java -Djava.util.logging.config.file=properties_file

where:

properties_file

is the name of the properties file you want to load.



6Supported SQL Functionality

The Progress DataDirect Connect XE for JDBC for Impala driver supports an extended set of SQL-92, in additionto the syntax for Impala SQL, which is a subset of SQL-92 and HiveQL.

Refer to the Impala SQL Language Reference documentation for information about using Impala SQL.


• Data Definition Language

• Column Name Qualification

• From Clause

• Group By Clause

• Having Clause

• Order By Clause

• For Update Clause

• Set Operators

• Subqueries

• SQL Expressions

• Restrictions


http://www.cloudera.com/content/cloudera-content/cloudera-docs/Impala/latest/Installing-and-Using-Impala/ciiu_langref.html

Data Definition LanguageThe Impala driver supports a broad set of DDL, including (but not limited to) the following:

• CREATE Database and DROP Database

• CREATE Table and DROP Table

• ALTER Table and ALTER Partition statements

• CREATE View and DROP View

• CREATE Function and DROP Function

Refer to the Impala Language Reference documentation for information about using Impala SQL.

Column Name QualificationA column can only be qualified with a single name. Furthermore, a table can be qualified with a database (JDBCschema) name in the FROM clause, and in some cases, must also be aliased. Aliasing may not be necessaryif the database qualifier is not the current database.

The driver can work around these limitations using the Remove Column Qualifiers connection option.

• If set to 1, the driver removes three-part column qualifiers and replaces them with alias.column qualifiers.

• If set to 0, the driver does not do anything with the request.

Suppose you have the following ANSI SQL query:

SELECT schema.table1.col1,schema.table2.col2 FROM schema.table1,schema.table2WHERE schema.table1.col3=schema.table2.col3

If the Remove Column Qualifiers connection option is enabled, the driver replaces the three-part columnqualifiers:

SELECT table1.col1,table2.col2 FROM schema.table1 table1 JOIN schema.table2 table2WHERE table1.col3 = table2.col3

From ClauseLEFT, RIGHT, and FULL OUTER JOINs are supported, as are LEFT SEMI JOINs and CROSS JOINs usingthe equal comparison operator, as shown in the following examples:

SELECT a.* FROM a JOIN b ON (a.id = b.id AND a.department = b.department)

SELECT a.val, b.val, c.val FROM a JOIN b ON (a.key = b.key1) JOIN c ON(c.key = b.key2)

SELECT a.val, b.val FROM a LEFT OUTER JOIN b ON (a.key=b.key)WHERE a.ds='2009-07-07' AND b.ds='2009-07-07'

However, the following syntax fails because of the use of non-equal comparison operators.


Chapter 6: Supported SQL Functionality

http://www.cloudera.com/content/cloudera-content/cloudera-docs/Impala/latest/Installing-and-Using-Impala/ciiu_langref.html

SELECT a.* FROM a JOIN b ON (a.id <> b.id)

Impala SQL does not support join syntax in the form of a comma-separated list of tables. The driver, however,overcomes this limitation by translating the SQL into Impala SQL, as shown in the following examples.

Impala SQL TranslationANSI SQL 92 QuerySELECT * FROM t1 t1 JOIN t2 t2 WHERE a = bSELECT * FROM t1, t2 WHERE a =

b

SELECT * FROM t1 y JOIN t2 x WHERE a = bSELECT * FROM t1 y, t2 x WHEREa = b

SELECT * FROM t2 t2 JOIN (SELECT * FROM t1 t1) xSELECT * FROM t2, (SELECT *FROM t1) x

Group By ClauseThe Group By clause is supported, with the following Entry SQL level restrictions:

• The COLLATE clause is not supported.

• SELECT DISTINCT is not supported.

• The grouping column reference cannot be an alias. The following queries fail because fc is an alias for theintcol column:

SELECT intcol AS fc, COUNT (*) FROM p_gtable GROUP BY fc

SELECT f(col) as fc, COUNT (*) FROM table_name GROUP BY fc

Having ClauseThe Having Clause is supported, with the following Entry SQL level restriction: a GROUP BY clause is required.

Order By ClauseThe Order By clause is supported, with the following Entry SQL level restrictions:

• An integer sort key is not allowed.

• The COLLATE clause is not supported.

• A LIMIT clause or a default ORDER BY limit for result sets is required.

Default ORDER BY LimitImpala will not return result sets for statements containing an order by clause unless a limit clause is includedor a default limit is specified for result sets. A default limit can be set in the server; however, this limits the resultsets for all queries, not just statements containing the ORDER BY clause.

The driver can work around these limitations by using the DefaultOrderByLimit connection property.


Group By Clause

where:

x

is a positive integer that represents maximum number of rows returned.

If set to x, the number of rows returned by a SQL statement containing an ORDER BY clause are limited tothe specified number of rows for the session. To override this value, specify a new value in a LIMIT clause inthe statement that is being executed.

If set to -1(disabled), there is no default limit the number of rows returned by a statement containing an ORDERBY clause. The application must limit the number of rows returned by SQL statements that contain an ORDERBY clause, or Impala will return an error.

For Update ClauseNot supported in this release. If present, the driver strips the For Update clause from the query.

Set OperatorsSupported, with the following Entry SQL level restrictions:

• UNION is not supported.

Therefore, the following query fails:

SELECT * FROM t1 UNION SELECT * FROM t2

• UNION ALL is supported.

Therefore, the following query works:

SELECT * FROM t1 UNION ALL SELECT * FROM t2

In addition, INTERSECT or EXCEPT are not supported.

SubqueriesA query is an operation that retrieves data from one or more tables or views. In this reference, a top-level queryis called a Select statement, and a query nested within a Select statement is called a subquery.

Subqueries are supported, with the following Entry SQL level restriction: subqueries can only exist in the FROMand WHERE clauses, that is, in a derived table. In the following example, the second Select statement is asubquery:

SELECT * FROM (SELECT * FROM t1 UNION ALL SELECT * FROM t2) sq

Although Impala currently does not support IN or EXISTS subqueries, you can efficiently implement thesemantics by rewriting queries to use LEFT SEMI JOIN.



SQL ExpressionsAn expression is a combination of one or more values, operators, and SQL functions that evaluate to a value.You can use expressions in the Where and Having clauses of Select statements.

Expressions enable you to use mathematical operations as well as character string manipulation operators toform complex queries.

Valid expression elements are:

• Constants on page 169

• Numeric Operators on page 169

• Character Operator on page 170

• Relational Operators on page 170

• Logical Operators on page 170

• Functions on page 171

ConstantsImpala uses binary literals for internal functions. Although the driver supports binary literals, no useful informationis returned.

Numeric OperatorsYou can use a numeric operator in an expression to negate, add, subtract, multiply, and divide numeric values.The result of this operation is also a numeric value. The + and - operators are also supported in date/time fieldsto allow date arithmetic.

The following table lists the supported arithmetic operators.

Table 16: Numeric Operators

Impala SQL OperatorEntry SQL Level Operator

Supported*

Supported+

Supported-

Supported/

N/A^ (XOR)

N/A% (Mod)

N/A& (bitwise AND)


SQL Expressions

Character OperatorThe concatenation operator (||) is not supported; however, the CONCAT function is supported by Impala SQL.SELECT CONCAT('Name is', ’(ename FROM emp)’)

Relational OperatorsRelational operators compare one expression to another. The following table lists the supported relationaloperators.

Table 17: Relational Operators Supported with Impala

Support in Impala SQLEntry SQL Level Operator

Supported<>

Supported<

Supported<=

Supported=

Supported<=>

Supported>

Supported>=

SupportedIS [NOT] NULL

Supported[NOT] BETWEEN x AND y

Supported[NOT] IN

SupportedEXISTS

Supported, except that no collate clause is allowed[NOT] LIKE

SupportedRLIKE

SupportedREGEXP

Logical OperatorsA logical operator combines the results of two component conditions to produce a single result or to invert theresult of a single condition. The following table lists the supported logical operators.



Table 18: Logical Operators

Support in Impala HQLOperator

SupportedNOT !

SupportedAND &&

SupportedOR ||

FunctionsThe following tables show how SQL-92 functions are supported in the Impala Query Language. Additionalmethods may be supported with JDBC Escapes. See "Scalar Functions" for more information.

Table 19: Set Functions Supported

Support in Impala SQLSet Function

SupportedCount

SupportedAVG

SupportedMIN

SupportedMAX

SupportedSUM

SupportedDISTINCT

SupportedALL

Table 20: Numeric Functions Supported

Support in Impala SQLNumeric Function

Not supported. Use LENGTH(string) instead.CHAR_LENGTH CHARACTER_LENGTH

Not supportedPosition...In

Not supportedBIT_LENGTH(s)

Not supportedOCTET_LENGTH(str)

Not supportedEXTRACT...FROM

Table 21: String Functions Supported

Support in Impala SQLString Function

SupportedSubstring


SQL Expressions

Support in Impala SQLString Function

Not supportedConvert … using

Supported.TRIM

Not supported. Use LTRIM.Leading

Not supported. Use RTRIM.Trailing

Not supported (default behavior of TRIM)Both

Table 22: Date/Time Functions Supported

Support in Impala SQLDate/Time Function

Not supported46CURRENT_DATE( )

Not supported46CURRENT_TIME( )

Not supported. Use UNIX_TIMESTAMP()46.CURRENT_TIMESTAMP

Table 23: System Functions Supported

Support in Impala SQLSystem Function

Supported.CASE ... END

Supported.COALESCE

Not supported.46NULLIF

Supported.CAST

See alsoScalar Functions on page 176

46 Supported by JDBC Escapes



RestrictionsCloudera Impala has the following SQL restrictions:

• Column values and parameters are always nullable.

• No support for row-level updates or deletes

• No support for stored procedures

• No ROWID support

• No support for materialized views

• No support for synonyms

• Primary and foreign keys are not supported.

• Support for indexes is incomplete.

• A single quote within a string literal must be escaped using a \ instead of using a single quote. Becausestring literals can be expressed with either single or double quotation marks, Impala's would be written as'Impala\'s' or "Impala\'s".


Restrictions

7SQL Escape Sequences for JDBC

Language features, such as outer joins and scalar function calls, are commonly implemented by databasesystems. The syntax for these features is often database-specific, even when a standard syntax has beendefined. JDBC defines escape sequences that contain the standard syntax for the following language features:

• Date, time, and timestamp literals

• Scalar functions such as numeric, string, and data type conversion functions

• Outer joins

• Escape characters for wildcards used in LIKE clauses

• Procedure calls

The escape sequence used by JDBC is:

{extension}

The escape sequence is recognized and parsed by the drivers, which replaces the escape sequences withdata store-specific grammar.


• Date, time, and timestamp escape sequences

• Scalar Functions

• Outer Join Escape Sequences

• LIKE escape character sequence for wildcards

• Procedure Call Escape Sequences


Date, time, and timestamp escape sequencesThe escape sequence for date, time, and timestamp literals is:

{literal-type 'value'}

where:

literal-type

is one of the following:

Value FormatDescriptionliteral-type

yyyy-mm-ddDated

hh:mm:ss []Timet

yyyy-mm-dd hh:mm:ss[.f...]Timestampts

Example:

UPDATE Orders SET OpenDate={d '1995-01-15'} WHERE OrderID=1023

Scalar FunctionsYou can use scalar functions in SQL statements with the following syntax:

{fn scalar-function}

where:

scalar-function

is a scalar function supported by the driver as indicated in the following table.

Example:

SELECT id, name FROM emp WHERE name LIKE {fn UCASE('Smith')}

Table 24: Supported Scalar Functions

System FunctionsTimedate FunctionsNumericFunctions

String Functions

DBNAMECURDATEABSASCII

CURRENT_DATEACOSCONCAT IFNULL

CURRENT_TIMEASININSERT

CURRENT_TIMESTAMPATANLCASE

CURTIMECEILINGLEFT


Chapter 7: SQL Escape Sequences for JDBC

System FunctionsTimedate FunctionsNumericFunctions

String Functions

DAYOFMONTHCOSLENGTH

EXTRACTCOTLOCATE

HOURDEGREESLOCATE2

MINUTEEXPLTRIM

MONTHFLOORREPEAT

NOWLOGREPLACE

QUARTERLOG10RIGHT

SECONDMODPRTRIM

TIMESTAMPADD 47PISPACE

TIMESTAMPDIFFPOWERSUBSTRING

WEEKRADIANSUCASE

YEARRAND

ROUND

SIGN

SIN

SQRT

TAN

Outer Join Escape SequencesJDBC supports the SQL-92 left, right, and full outer join syntax. The escape sequence for outer joins is:

{oj outer-join}

where:

outer-join

is table-reference {LEFT | RIGHT | FULL} OUTER JOIN {table-reference |outer-join} ON search-condition

table-reference

is a database table name.

search-condition

is the join condition you want to use for the tables.

47 Cloudera Impala is limited to adding only days to a timestamp.


Outer Join Escape Sequences

Example:

SELECT Customers.CustID, Customers.Name, Orders.OrderID, Orders.StatusFROM {oj Customers LEFT OUTER JOIN

Orders ON Customers.CustID=Orders.CustID}WHERE Orders.Status='OPEN'

The driver supports the following outer join escape sequences:

• Left outer joins

• Right outer joins

• Full outer joins

LIKE escape character sequence for wildcardsYou can specify the character to be used to escape wildcard characters (% and _, for example) in LIKE clauses.The escape sequence for escape characters is:

{escape 'escape-character'}

where:

escape-character

is the character used to escape the wildcard character.

For example, the following SQL statement specifies that an asterisk (*) be used as the escape character in theLIKE clause for the wildcard character %:

SELECT col1 FROM table1 WHERE col1 LIKE '*%%' {escape '*'}

Procedure Call Escape SequencesA procedure is an executable object stored in the data store. Generally, it is one or more SQL statements thathave been precompiled. The escape sequence for calling a procedure is:

{[?=]call procedure-name[(parameter[,parameter]...)]}

where:

procedure-name

specifies the name of a stored procedure.

parameter

specifies a stored procedure parameter.


Chapter 7: SQL Escape Sequences for JDBC

8JDBC support

Progress DataDirect for JDBC drivers are compatible with JDBC 2.0, 3.0, 4.0, 4.1, and 4.2. The following topicsdescribe support for JDBC interfaces and methods across the JDBC driver product line. Support for JDBCinterfaces and methods depends, in part, on which driver you are using.


• JDBC and JVM Compatibility

• Supported Functionality

JDBC and JVM CompatibilityThe drivers are compatible with JDBC 2.0, 3.0, 4.0, 4.1, and 4.2. The drivers are supported on Java SE 6 andhigher JVMs.

Supported FunctionalityThis section lists functionality supported for the following JDBC interfaces.


Array

CommentsSupportedVersionIntroduced

Array Methods

Yes4.0void free()

Yes2.0 CoreObject getArray()

The drivers ignore the map argument.Yes2.0 CoreObject getArray(map)

Yes2.0 CoreObject getArray(long, int)

The drivers ignore the map argument.Yes2.0 CoreObject getArray(long, int, map)

Yes2.0 Coreint getBaseType()

Yes2.0 CoreString getBaseTypeName()

Yes2.0 CoreResultSet getResultSet()

The drivers ignore the map argument.Yes2.0 CoreResultSet getResultSet(map)

Yes2.0 CoreResultSet getResultSet(long, int)

The drivers ignore the map argument.Yes2.0 CoreResultSet getResultSet(long, int, map)

Blob


Blob Methods

Yes4.0void free()

The drivers support using data types thatmap to the JDBC LONGVARBINARY datatype.

Yes2.0 CoreInputStream getBinaryStream()


Yes2.0 Corebyte[] getBytes(long, int)


Yes2.0 Corelong length()


Chapter 8: JDBC support


Blob Methods

The Informix driver requires that the patternparameter (which specifies the Blob objectdesignating the BLOB value for which tosearch) be less than or equal to a maximumvalue of 4096 bytes.

All other drivers support using data typesthat map to the JDBC LONGVARBINARYdata type.

Yes2.0 Corelong position(Blob, long)

The Informix driver requires that the patternparameter (which specifies the byte arrayfor which to search) be less than or equalto a maximum value of 4096 bytes. All otherdrivers support using data types that mapto the JDBC LONGVARBINARY data type.

Yes2.0 Corelong position(byte[], long)


Yes3.0OutputStream setBinaryStream(long)


Yes3.0int setBytes(long, byte[])


Yes3.0int setBytes(long, byte[], int, int)


Yes3.0void truncate(long)

CallableStatement


CallableStatement Methods

The drivers for Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw an "invalid parameterbindings" exception when your applicationcalls output parameters.

The Progress OpenEdge driver throws an"unsupported method" exception.

Yes2.0 CoreArray getArray(int)


Supported Functionality



Supported for the SQL Server driver only.

All other drivers throw an "unsupportedmethod" exception.

Yes3.0Array getArray(String)


Yes4.0Reader getCharacterStream(int)

The drivers for Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw an "unsupported method"exception.

Yes4.0Reader getCharacterStream(String)


Yes2.0 CoreBigDecimal getBigDecimal(int)


Yes1.0BigDecimal getBigDecimal(int, int)


All other drivers throw "unsupportedmethod" exception.

Yes3.0BigDecimal getBigDecimal(String)



Yes2.0 CoreBlob getBlob(int)



Yes3.0Blob getBlob(String)






Yes1.0boolean getBoolean(int)



Yes3.0boolean getBoolean(String)


Yes1.0byte getByte(int)



Yes3.0byte getByte(String)


Yes1.0byte [] getBytes(int)

Supported for the SQL Server driver only.All other drivers throw "unsupportedmethod" exception.

Yes3.0byte [] getBytes(String)



Yes2.0 CoreClob getClob(int)

Supported for the SQL Server driver onlyusing with data types that map to the JDBCLONGVARCHAR data type.


Yes3.0Clob getClob(String)






Yes1.0Date getDate(int)


Yes2.0 CoreDate getDate(int, Calendar)



Yes3.0Date getDate(String)



Yes3.0Date getDate(String, Calendar)


Yes1.0double getDouble(int)



Yes3.0double getDouble(String)


Yes1.0float getFloat(int)



Yes3.0float getFloat(String)


Yes1.0int getInt(int)







Yes3.0int getInt(String)


Yes1.0long getLong(int)



Yes3.0long getLong(String)


Yes4.0Reader getNCharacterStream(int)


Yes4.0Reader getNCharacterStream(String)


Yes4.0NClob getNClob(int)


Yes4.0NClob getNClob(String)

The drivers for Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw "unsupported method"exception.

Yes4.0String getNString(int)


Yes4.0String getNString(String)


Yes1.0Object getObject(int)





The drivers ignore the Map argument.Yes2.0 CoreObject getObject(int, Map)



Yes3.0Object getObject(String)

Supported for the SQL Server driver only.The SQL Server driver ignores the Mapargument.


Yes3.0Object getObject(String, Map)



No2.0 CoreRef getRef(int)

The drivers throw "unsupported method"exception.

No3.0Ref getRef(String)


Yes1.0short getShort(int)



Yes3.0short getShort(String)


Yes4.0SQLXML getSQLXML(int)


Yes4.0SQLXML getSQLXML(String)


Yes1.0String getString(int)







Yes3.0String getString(String)


Yes1.0Time getTime(int)


Yes2.0 CoreTime getTime(int, Calendar)



Yes3.0Time getTime(String)

Supported for SQL Server driver only.


Yes3.0Time getTime(String, Calendar)


Yes1.0Timestamp getTimestamp(int)


Yes2.0 CoreTimestamp getTimestamp(int, Calendar)



Yes3.0Timestamp getTimestamp(String)



Yes3.0Timestamp getTimestamp(String, Calendar)


No3.0URL getURL(int)






No3.0URL getURL(String)

Yes4.0boolean isWrapperFor(Class<?> iface)


Yes1.0void registerOutParameter(int, int)


Yes1.0void registerOutParameter(int, int, int)


The Oracle driver supports the Stringargument.

For all other drivers, the String argument isignored.

Yes2.0 Corevoid registerOutParameter(int, int, String)




Yes3.0void registerOutParameter(String, int)




Yes3.0void registerOutParameter(String, int, int)







All other drivers throw "unsupportedmethod" exception. String/typenameignored.

Yes3.0void registerOutParameter(String, int, String)

Supported for the Oracle driver only.


Yes2.0 Corevoid setArray(int, Array)



Yes4.0void setAsciiStream(String, InputStream)



Yes3.0void setAsciiStream(String, InputStream,int)



Yes4.0void setAsciiStream(String, InputStream,long)



Yes3.0void setBigDecimal(String, BigDecimal)



Yes4.0void setBinaryStream(String, InputStream)



Yes3.0void setBinaryStream(String, InputStream,int)



Yes4.0void setBinaryStream(String, InputStream,long)







Yes4.0void setBlob(String, Blob)



Yes4.0void setBlob(String, InputStream)



Yes4.0void setBlob(String, InputStream, long)



Yes3.0void setBoolean(String, boolean)



Yes3.0void setByte(String, byte)



Yes3.0void setBytes(String, byte [])



Yes3.0void setCharacterStream(String, Reader,int)



Yes4.0void setCharacterStream(String,InputStream, long)



Yes4.0void setClob(String, Clob)



Yes4.0void setClob(String, Reader)



Yes4.0void setClob(String, Reader, long)







Yes3.0void setDate(String, Date)



Yes3.0void setDate(String, Date, Calendar)



Yes3.0void setDouble(String, double)



Yes3.0void setFloat(String, float)



Yes3.0void setInt(String, int)



Yes3.0void setLong(String, long)

Yes4.0void setNCharacterStream(String, Reader,long)

Yes4.0void setNClob(String, NClob)

Yes4.0void setNClob(String, Reader)

Yes4.0void setNClob(String, Reader, long)

Yes4.0void setNString(String, String)

Yes2.0 Corevoid setNull(int, int, String)



Yes3.0void setNull(String, int)



Yes3.0void setNull(String, int, String)







Yes3.0void setObject(String, Object)



Yes3.0void setObject(String, Object, int)



Yes3.0void setObject(String, Object, int, int)



Yes3.0void setShort(String, short)


Yes4.0void setSQLXML(String, SQLXML)



Yes3.0void setString(String, String)



Yes3.0void setTime(String, Time)



Yes3.0void setTime(String, Time, Calendar)



Yes3.0void setTimestamp(String, Timestamp)



Yes3.0void setTimestamp(String, Timestamp,Calendar)

Yes4.0<T> T unwrap(Class<T> iface)






No3.0void setURL(String, URL)

Yes1.0boolean wasNull()

Clob


Clob Methods

Yes4.0void free()

All drivers support using with data types thatmap to the JDBC LONGVARCHAR datatype.

Yes2.0 CoreInputStream getAsciiStream()


Yes2.0 CoreReader getCharacterStream()


Yes4.0Reader getCharacterStream(long, long)


Yes2.0 CoreString getSubString(long, int)


Yes2.0 Corelong length()


The Informix driver requires that thesearchStr parameter be less than or equalto a maximum value of 4096 bytes.

Yes2.0 Corelong position(Clob, long)


The Informix driver requires that thesearchStr parameter be less than or equalto a maximum value of 4096 bytes.

Yes2.0 Corelong position(String, long)




Clob Methods


Yes3.0 CoreOutputStream setAsciiStream(long)


Yes3.0 CoreWriter setCharacterStream(long)


Yes3.0 Coreint setString(long, String)


Yes3.0 Coreint setString(long, String, int, int)


Yes3.0 Corevoid truncate(long)

Connection


Connection Methods

Yes1.0void clearWarnings()

When a connection is closed while atransaction is still active, that transaction isrolled back.

Yes1.0void close()

Yes1.0void commit()

Yes4.0Blob createBlob()

Yes4.0Clob createClob()

Yes4.0NClob createNClob()

The drivers throw an unsupported methodexception.

No4.0createArrayOf(String, Object[])

Only the Oracle driver supports this method.Yes4.0createStruct(String, Object[])

Yes4.0SQLXML createSQLXML()

Yes1.0Statement createStatement()




Connection Methods

For the DB2 driver,ResultSet.TYPE_SCROLL_SENSITIVE isdowngraded toTYPE_SCROLL_INSENSITIVE.

For the drivers for Oracle Eloqua, OracleSales Cloud, Oracle Service Cloud, andSalesforce, be aware that scroll-sensitiveresult sets are expensive from both a Webservice call and a performance perspective.The drivers expend a network round trip foreach row that is fetched.

Yes2.0 CoreStatement createStatement(int, int)

With the exception of the DB2 driver, thespecified holdability must match thedatabase default holdability. Otherwise, an"unsupported method" exception is thrown.

For the DB2 driver, the method can becalled regardless of whether the specifiedholdability matches the database defaultholdability.

No3.0Statement createStatement(int, int, int)


All other drivers throw "unsupported method"exception.

Yes1.0Struct createStruct(String, Object[])

Yes1.0boolean getAutoCommit()

The drivers for the listed database systemsreturn an empty string because they do nothave the concept of a catalog: AmazonRedshift, Apache Cassandra, Apache Hive,Apache Spark SQL, Greenplum, Impala,MongoDB, Oracle, Oracle Eloqua, OracleSales Cloud, Oracle Service Cloud,PostgreSQL, and Salesforce.

Yes1.0String getCatalog()

The drivers for Apache Cassandra,MongoDB, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, and Salesforcedo not support storing or retrieving clientinformation.

Yes4.0String getClientInfo()


Yes4.0String getClientInfo(String)

Yes3.0int getHoldability()




Connection Methods

Yes1.0DatabaseMetaData getMetaData()

Yes1.0int getTransactionIsolation()

Always returns empty java.util.HashMap.Yes2.0 CoreMap getTypeMap()

Yes1.0SQLWarning getWarnings()

Yes1.0boolean isClosed()

Yes1.0boolean isReadOnly()

Yes4.0boolean isValid()


Always returns the same String that waspassed in from the application.

Yes1.0String nativeSQL(String)

Yes1.0CallableStatement prepareCall(String)

For the drivers for Apache Cassandra, DB2,MongoDB, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce, ResultSet.TYPE_SCROLL_SENSITIVE is downgraded toTYPE_SCROLL_INSENSITIVE.

Yes2.0 CoreCallableStatement prepareCall(String, int,int)

The DB2 driver allows this method whetheror not the specified holdability is the sameas the default holdability.

The other drivers throw the exception"Changing the default holdability is notsupported" when the specified holdabilitydoes not match the default holdability.

Yes3.0CallableStatement prepareCall(String, int,int, int)

Yes1.0PreparedStatement prepareStatement(String)

Yes3.0PreparedStatement prepareStatement(String, int)




Connection Methods

For the DB2 driver,ResultSet.TYPE_SCROLL_ SENSITIVE isdowngraded toTYPE_SCROLL_INSENSITIVE.

For the drivers for Apache Cassandra,MongoDB, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce, be aware that scroll-sensitiveresult sets are expensive from both a Webservice call and a performance perspective.The drivers expend a network round trip foreach row that is fetched.

Yes2.0 CorePreparedStatement prepareStatement(String, int, int)

All drivers throw "unsupported method"exception.

No3.0PreparedStatement prepareStatement(String, int, int, int)

Supported for the Oracle and SQL Serverdrivers.


Yes3.0PreparedStatement prepareStatement(String, int[])



Yes3.0PreparedStatement prepareStatement(String, String [])

The DB2 driver only supports with DB2 V8.xand higher for Linux/UNIX/Windows, DB2for z/OS (all versions), and DB2 for i.

The drivers for Apache Cassandra,MongoDB, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, and Salesforcethrow an "unsupported method" exception.

Yes3.0void releaseSavepoint(Savepoint)

Yes1.0void rollback()

The DB2 driver only supports with DB2 V8.xfor i.


Yes3.0void rollback(Savepoint)

The drivers for Apache Cassandra, ApacheHive, Apache Spark SQL, Impala,MongoDB, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, and Salesforcethrow "transactions not supported" exceptionif set to false.

Yes1.0void setAutoCommit(boolean)




Connection Methods

The driver for the listed database systemsignore any value set by the Stringargument.The corresponding drivers returnan empty string because they do not havethe concept of a catalog: Amazon Redshift,Apache Cassandra, Apache Hive, ApacheSpark SQL, Greenplum, Impala, MongoDB,Oracle, Oracle Eloqua, Oracle Sales Cloud,Oracle Service Cloud, PostgreSQL, andSalesforce.

Yes1.0void setCatalog(String)


Yes4.0String setClientInfo(Properties)


Yes4.0String setClientInfo(String, String)

The DB2 driver supports the Holdabilityparameter value.

For other drivers, the Holdability parametervalue is ignored.

Yes3.0void setHoldability(int)

Yes1.0void setReadOnly(boolean)

The DB2 driver only supports with DB2 V8.xand higher for Linux/UNIX/Windows, DB2for z/OS (all versions), and DB2 for i. Inaddition, the DB2 driver only supportsmultiple nested savepoints for DB2 V8.2 andhigher for Linux/UNIX/Windows.


Yes3.0Savepoint setSavepoint()




Connection Methods

The DB2 driver only supports with DB2 V8.xand higher for Linux/UNIX/Windows, DB2for z/OS (all versions), and DB2 for i. Inaddition, the DB2 driver only supportsmultiple nested savepoints for DB2 V8.2 andhigher for Linux/UNIX/Windows.


Yes3.0Savepoint setSavepoint(String)

The drivers for Apache Cassandra, ApacheHive, Apache Spark SQL, Impala,MongoDB, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, and Salesforceignore any specified transaction isolationlevel.

Yes1.0void setTransactionIsolation(int)

The drivers ignore this connection method.Yes2.0 Corevoid setTypeMap(Map)


ConnectionEventListener


ConnectionEventListener Methods

Yes3.0void connectionClosed(event)

Yes3.0void connectionErrorOccurred(event)

ConnectionPoolDataSource


ConnectionPoolDataSource Methods

Yes2.0 Optionalint getLoginTimeout()

Yes2.0 OptionalPrintWriter getLogWriter()

Yes2.0 OptionalPooledConnection getPooledConnection()

Yes2.0 OptionalPooledConnection getPooledConnection(String, String)




ConnectionPoolDataSource Methods

Yes2.0 Optionalvoid setLoginTimeout(int)

Yes2.0 Optionalvoid setLogWriter(PrintWriter)

DatabaseMetaData


DatabaseMetaData Methods

Yes4.0booleanautoCommitFailureClosesAllResultSets()

Yes1.0boolean allProceduresAreCallable()

Yes1.0boolean allTablesAreSelectable()

Yes1.0booleandataDefinitionCausesTransactionCommit()

Yes1.0booleandataDefinitionIgnoredInTransactions()

Yes2.0 Coreboolean deletesAreDetected(int)

Not supported by the SQL Server andSybase drivers.

Yes1.0boolean doesMaxRowSizeIncludeBlobs()

The Oracle driver may return results.

All other drivers return an empty result set.

Yes3.0getAttributes(String, String, String, String)

Yes1.0ResultSet getBestRowIdentifier(String,String, String, int, boolean)

Yes1.0ResultSet getCatalogs()

Yes1.0String getCatalogSeparator()

Yes1.0String getCatalogTerm()


Yes4.0String getClientInfoProperties()





Not supported by the drivers for ApacheHive, Apache Spark SQL, Impala, OracleEloqua, and Oracle Sales Cloud.

Yes1.0ResultSet getColumnPrivileges(String,String, String, String)

Yes1.0ResultSet getColumns(String, String, String,String)

Yes2.0 CoreConnection getConnection()

Yes1.0ResultSet getCrossReference(String, String,String, String, String, String)

The drivers for Apache Cassandra,MongoDB, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, and Salesforcereturn an empty result set.

Not supported by the drivers for ApacheHive, Apache Spark SQL, or Impala.

Yes4.0ResultSet getFunctions()

The drivers for Apache Cassandra,MongoDB, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, and Salesforcereturn an empty result set.

Not supported by the drivers for ApacheHive, Apache Spark SQL, or Impala.

Yes4.0ResultSet getFunctionColumns()

Yes3.0int getDatabaseMajorVersion()

Yes3.0int getDatabaseMinorVersion()

Yes1.0String getDatabaseProductName()

Yes1.0String getDatabaseProductVersion()

Yes1.0int getDefaultTransactionIsolation()

Yes1.0int getDriverMajorVersion()

Yes1.0int getDriverMinorVersion()

Yes1.0String getDriverName()

Yes1.0String getDriverVersion()

Yes1.0ResultSet getExportedKeys(String, String,String)

Yes1.0String getExtraNameCharacters()





Yes1.0String getIdentifierQuoteString()

Yes1.0ResultSet getImportedKeys(String, String,String)

Yes1.0ResultSet getIndexInfo(String, String, String,boolean, boolean)

Yes3.0int getJDBCMajorVersion()

Yes3.0int getJDBCMinorVersion()

Yes1.0int getMaxBinaryLiteralLength()

Yes1.0int getMaxCatalogNameLength()

Yes1.0int getMaxCharLiteralLength()

Yes1.0int getMaxColumnNameLength()

Yes1.0int getMaxColumnsInGroupBy()

Yes1.0int getMaxColumnsInIndex()

Yes1.0int getMaxColumnsInOrderBy()

Yes1.0int getMaxColumnsInSelect()

Yes1.0int getMaxColumnsInTable()

Yes1.0int getMaxConnections()

Yes1.0int getMaxCursorNameLength()

Yes1.0int getMaxIndexLength()

Yes1.0int getMaxProcedureNameLength()

Yes1.0int getMaxRowSize()

Yes1.0int getMaxSchemaNameLength()

Yes1.0int getMaxStatementLength()

Yes1.0int getMaxStatements()

Yes1.0int getMaxTableNameLength()

Yes1.0int getMaxTablesInSelect()





Yes1.0int getMaxUserNameLength()

Yes1.0String getNumericFunctions()

Yes1.0ResultSet getPrimaryKeys(String, String,String)

For the drivers for Oracle Service Cloud,and Salesforce, SchemaName andProcedureName must be explicit values;they cannot be patterns.

The drivers for Apache Cassandra andMongoDB return an empty result set.

Not supported for the drivers for ApacheHive, Apache Spark SQL, or Impala.

Yes1.0ResultSet getProcedureColumns(String,String, String, String)

The drivers for Apache Cassandra,MongoDB, Oracle Eloqua, and Oracle SalesCloud return an empty result set.

Not supported for the drivers for ApacheHive, Apache Spark SQL, or Impala.

Yes1.0ResultSet getProcedures(String, String,String)

Yes1.0String getProcedureTerm()

Yes3.0int getResultSetHoldability()

Yes1.0ResultSet getSchemas()

Yes4.0ResultSet getSchemas(catalog, pattern)

Yes1.0String getSchemaTerm()

Yes1.0String getSearchStringEscape()

Yes1.0String getSQLKeywords()

Yes3.0int getSQLStateType()

Yes1.0String getStringFunctions()

Returns an empty result set.Yes3.0ResultSet getSuperTables(String, String,String)

Returns an empty result set.Yes3.0ResultSet getSuperTypes(String, String,String)

Yes1.0String getSystemFunctions()





Not supported for the drivers for ApacheHive, Apache Spark SQL, Impala, OracleEloqua, and Oracle Sales Cloud.

Yes1.0ResultSet getTablePrivileges(String, String,String)

Yes1.0ResultSet getTables(String, String, String,String [])

Yes1.0ResultSet getTableTypes()

Yes1.0String getTimeDateFunctions()

Yes1.0ResultSet getTypeInfo()

Supported for Oracle only.Yes2.0 CoreResultSet getUDTs(String, String, String,int [])

Yes1.0String getURL()

Yes1.0String getUserName()

Yes1.0ResultSet getVersionColumns(String, String,String)

Yes2.0 Coreboolean insertsAreDetected(int)

Yes1.0boolean isCatalogAtStart()

Yes1.0boolean isReadOnly()


Yes3.0boolean locatorsUpdateCopy()

Yes1.0boolean nullPlusNonNullIsNull()

Yes1.0boolean nullsAreSortedAtEnd()

Yes1.0boolean nullsAreSortedAtStart()

Yes1.0boolean nullsAreSortedHigh()

Yes1.0boolean nullsAreSortedLow()

Yes2.0 Coreboolean othersDeletesAreVisible(int)

Yes2.0 Coreboolean othersInsertsAreVisible(int)

Yes2.0 Coreboolean othersUpdatesAreVisible(int)

Yes2.0 Coreboolean ownDeletesAreVisible(int)





Yes2.0 Coreboolean ownInsertsAreVisible(int)

Yes2.0 Coreboolean ownUpdatesAreVisible(int)

Yes1.0boolean storesLowerCaseIdentifiers()

Yes1.0booleanstoresLowerCaseQuotedIdentifiers()

Yes1.0boolean storesMixedCaseIdentifiers()

Yes1.0booleanstoresMixedCaseQuotedIdentifiers()

Yes1.0boolean storesUpperCaseIdentifiers()

Yes1.0booleanstoresUpperCaseQuotedIdentifiers()

Yes1.0booleansupportsAlterTableWithAddColumn()

Yes1.0booleansupportsAlterTableWithDropColumn()

Yes1.0boolean supportsANSI92EntryLevelSQL()

Yes1.0boolean supportsANSI92FullSQL()

Yes1.0boolean supportsANSI92IntermediateSQL()

Yes2.0 Coreboolean supportsBatchUpdates()

Yes1.0booleansupportsCatalogsInDataManipulation()

Yes1.0booleansupportsCatalogsInIndexDefinitions()

Yes1.0booleansupportsCatalogsInPrivilegeDefinitions()

Yes1.0booleansupportsCatalogsInProcedureCalls()

Yes1.0booleansupportsCatalogsInTableDefinitions()

Yes1.0boolean supportsColumnAliasing()





Yes1.0boolean supportsConvert()

Yes1.0boolean supportsConvert(int, int)

Yes1.0boolean supportsCoreSQLGrammar()

Yes1.0boolean supportsCorrelatedSubqueries()

Yes1.0boolean supportsDataDefinitionAndDataManipulationTransactions()

Yes1.0booleansupportsDataManipulationTransactionsOnly()

Yes1.0booleansupportsDifferentTableCorrelationNames()

Yes1.0boolean supportsExpressionsInOrderBy()

Yes1.0boolean supportsExtendedSQLGrammar()

Yes1.0boolean supportsFullOuterJoins()

Yes3.0boolean supportsGetGeneratedKeys()

Yes1.0boolean supportsGroupBy()

Yes1.0boolean supportsGroupByBeyondSelect()

Yes1.0boolean supportsGroupByUnrelated()

Yes1.0booleansupportsIntegrityEnhancementFacility()

Yes1.0boolean supportsLikeEscapeClause()

Yes1.0boolean supportsLimitedOuterJoins()

Yes1.0boolean supportsMinimumSQLGrammar()

Yes1.0boolean supportsMixedCaseIdentifiers()

Yes1.0booleansupportsMixedCaseQuotedIdentifiers()

Yes3.0boolean supportsMultipleOpenResults()

Yes1.0boolean supportsMultipleResultSets()

Yes1.0boolean supportsMultipleTransactions()





Yes3.0boolean supportsNamedParameters()

Yes1.0boolean supportsNonNullableColumns()

Yes1.0booleansupportsOpenCursorsAcrossCommit()

Yes1.0booleansupportsOpenCursorsAcrossRollback()

Yes1.0booleansupportsOpenStatementsAcrossCommit()

Yes1.0booleansupportsOpenStatementsAcrossRollback()

Yes1.0boolean supportsOrderByUnrelated()

Yes1.0boolean supportsOuterJoins()

Yes1.0boolean supportsPositionedDelete()

Yes1.0boolean supportsPositionedUpdate()

Yes2.0 Coreboolean supportsResultSetConcurrency(int,int)

Yes3.0boolean supportsResultSetHoldability(int)

Yes2.0 Coreboolean supportsResultSetType(int)

Yes3.0boolean supportsSavePoints()

Yes1.0booleansupportsSchemasInDataManipulation()

Yes1.0booleansupportsSchemasInIndexDefinitions()

Yes1.0booleansupportsSchemasInPrivilegeDefinitions()

Yes1.0booleansupportsSchemasInProcedureCalls()

Yes1.0booleansupportsSchemasInTableDefinitions()

Yes1.0boolean supportsSelectForUpdate()





Yes4.0booleansupportsStoredFunctionsUsingCallSyntax()

Yes1.0boolean supportsStoredProcedures()

Yes1.0booleansupportsSubqueriesInComparisons()

Yes1.0boolean supportsSubqueriesInExists()

Yes1.0boolean supportsSubqueriesInIns()

Yes1.0boolean supportsSubqueriesInQuantifieds()

Yes1.0boolean supportsTableCorrelationNames()

Yes1.0booleansupportsTransactionIsolationLevel(int)

Yes1.0boolean supportsTransactions()

Yes1.0boolean supportsUnion()

Yes1.0boolean supportsUnionAll()


Yes2.0 Coreboolean updatesAreDetected(int)

Yes1.0boolean usesLocalFilePerTable()

Yes1.0boolean usesLocalFiles()

DataSourceThe DataSource interface implements the javax.naming.Referenceable and java.io.Serializable interfaces.


DataSource Methods

Yes2.0 OptionalConnection getConnection()

Yes2.0 OptionalConnection getConnection(String, String)

Yes2.0 Optionalint getLoginTimeout()

Yes2.0 OptionalPrintWriter getLogWriter()




DataSource Methods


Yes2.0 Optionalvoid setLoginTimeout(int)

Enables DataDirect Spy, which traces JDBCinformation into the specified PrintWriter.

Yes2.0 Optionalvoid setLogWriter(PrintWriter)


Driver


Driver Methods

Yes1.0boolean acceptsURL(String)

Yes1.0Connection connect(String, Properties)

Yes1.0int getMajorVersion()

Yes1.0int getMinorVersion()

Yes1.0DriverPropertyInfo [] getPropertyInfo(String,Properties)

ParameterMetaData


ParameterMetaData Methods

The DB2 driver supports parametermetadata for stored procedures forDB2 V8.x and higher forLinux/UNIX/Windows, DB2 for z/OS (allversions), and DB2 for i.

Yes3.0String getParameterClassName(int)

Yes3.0int getParameterCount()


Yes3.0int getParameterMode(int)




ParameterMetaData Methods


Yes3.0int getParameterType(int)


Yes3.0String getParameterTypeName(int)


Yes3.0int getPrecision(int)


Yes3.0int getScale(int)


Yes3.0int isNullable(int)


Yes3.0boolean isSigned(int)


Yes1.0boolean jdbcCompliant()


PooledConnection


PooledConnection Methods

Yes2.0 Optionalvoid addConnectionEventListener(listener)




PooledConnection Methods

Yes4.0void addStatementEventListener(listener)

Yes2.0 Optionalvoid close()

A pooled connection object can have onlyone Connection object open (the one mostrecently created). The purpose of allowingthe server (PoolManager implementation)to invoke this a second time is to give anapplication server a way to take aconnection away from an application andgive it to another user (a rare occurrence).The drivers do not support the "reclaiming"of connections and will throw an exception.

Yes2.0 OptionalConnection getConnection()

Yes2.0 OptionalvoidremoveConnectionEventListener(listener)

Yes4.0voidremoveStatementEventListener(listener)

PreparedStatement


PreparedStatement Methods

Yes2.0 Corevoid addBatch()

Yes1.0void clearParameters()

Yes1.0boolean execute()

Yes1.0ResultSet executeQuery()

Yes1.0int executeUpdate()

Yes2.0 CoreResultSetMetaData getMetaData()

Yes3.0ParameterMetaDatagetParameterMetaData()



All other drivers throw an "unsupportedmethod" exception.

Yes2.0 Corevoid setArray(int, Array)

Yes4.0void setAsciiStream(int, InputStream)





Yes1.0void setAsciiStream(int, InputStream, int)

Yes4.0void setAsciiStream(int, InputStream, long)

Yes1.0void setBigDecimal(int, BigDecimal)

When used with Blobs, the DB2 driver onlysupports with DB2 V8.x and higher forLinux/UNIX/Windows, DB2 for z/OS (allversions), and DB2 for i.

Yes4.0void setBinaryStream(int, InputStream)


Yes1.0void setBinaryStream(int, InputStream, int)


Yes4.0void setBinaryStream(int, InputStream, long)


All other drivers support using with datatypes that map to the JDBCLONGVARBINARY data type.

Yes2.0 Corevoid setBlob(int, Blob)



Yes4.0void setBlob(int, InputStream)



Yes4.0void setBlob(int, InputStream, long)

Yes1.0void setBoolean(int, boolean)

Yes1.0void setByte(int, byte)






Yes1.0void setBytes(int, byte [])

Yes4.0void setCharacterStream(int, Reader)

Yes2.0 Corevoid setCharacterStream(int, Reader, int)

Yes4.0void setCharacterStream(int, Reader, long)

Drivers support using with data types thatmap to the JDBC LONGVARBINARY datatype.

Yes2.0 Corevoid setClob(int, Clob)


Yes4.0void setClob(int, Reader)


Yes4.0void setClob(int, Reader, long)

Yes1.0void setDate(int, Date)

Yes2.0 Corevoid setDate(int, Date, Calendar)

Yes1.0void setDouble(int, double)

Yes1.0void setFloat(int, float)

Yes1.0void setInt(int, int)

Yes1.0void setLong(int, long)

For the drivers for Apache Cassandra,MongoDB, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce, N methods are identical to theirnon-N counterparts.

Yes4.0void setNCharacterStream(int, Reader)

For the drivers for Apache Cassandra,MongoDB, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce,N methods are identical to theirnon-N counterparts.

Yes4.0void setNCharacterStream(int, Reader, long)






Yes4.0void setNClob(int, NClob)


Yes4.0void setNClob(int, Reader)


Yes4.0void setNClob(int, Reader, long)

Yes1.0void setNull(int, int)

Yes2.0 Corevoid setNull(int, int, String)

Yes4.0void setNString(int, String)

Yes1.0void setObject(int, Object)

Yes1.0void setObject(int, Object, int)

Yes1.0void setObject(int, Object, int, int)





The DB2 driver supports setting a timeoutvalue, in seconds, for a statement withDB2 V8.x and higher forLinux/UNIX/Windows and DB2 V8.1 andhigher for z/OS. If the execution of thestatement exceeds the timeout value, thestatement is timed out by the databaseserver, and the driver throws an exceptionindicating that the statement was timed out.The DB2 driver throws an "unsupportedmethod" exception with other DB2 versions.

The Informix driver throws an "unsupportedmethod" exception.

The drivers for MongoDB, Oracle Eloqua,Oracle Sales Cloud, Oracle Service Cloud,and Salesforce ignore any value set usingthis method. Use the WSTimeout connectionproperty to set a timeout value.

The drivers for Apache Cassandra andMongoDB ignore any value set using thismethod.

All other drivers support setting a timeoutvalue, in seconds, for a statement. If theexecution of the statement exceeds thetimeout value, the statement is timed out bythe database server, and the driver throwsan exception indicating that the statementwas timed out.

Yes1.0void setQueryTimeout(int)


No2.0 Corevoid setRef(int, Ref)

Yes1.0void setShort(int, short)

Yes4.0void setSQLXML(int, SQLXML)

Yes1.0void setString(int, String)

Yes1.0void setTime(int, Time)

Yes2.0 Corevoid setTime(int, Time, Calendar)

Yes1.0void setTimestamp(int, Timestamp)

Yes2.0 Corevoid setTimestamp(int, Timestamp,Calendar)





This method was deprecated in JDBC 2.0.All drivers throw "unsupported method"exception.

No1.0void setUnicodeStream(int, InputStream,int)



No3.0void setURL(int, URL)

Ref


Ref MethodsRef interface

No2.0 Core(all)

ResultSet


ResultSet Methods

Yes2.0 Coreboolean absolute(int)

Yes2.0 Corevoid afterLast()

Yes2.0 Corevoid beforeFirst()

Yes2.0 Corevoid cancelRowUpdates()


Yes1.0void close()

Yes2.0 Corevoid deleteRow()

Yes1.0int findColumn(String)

Yes2.0 Coreboolean first()

Yes2.0 CoreArray getArray(int)


No2.0 CoreArray getArray(String)

Yes1.0InputStream getAsciiStream(int)




ResultSet Methods

Yes1.0InputStream getAsciiStream(String)

Yes2.0 CoreBigDecimal getBigDecimal(int)

Yes1.0BigDecimal getBigDecimal(int, int)

Yes2.0 CoreBigDecimal getBigDecimal(String)

Yes1.0BigDecimal getBigDecimal(String, int)

The DB2 driver supports for all DB2 versionswhen retrieving BINARY, VARBINARY, andLONGVARBINARY data. The DB2 driveronly supports with DB2 V8.x and higher forLinux/UNIX/Windows, DB2 for z/OS (allversions), and DB2 for i when retrieving Blobdata.

Yes1.0InputStream getBinaryStream(int)


Yes1.0InputStream getBinaryStream(String)



Yes2.0 CoreBlob getBlob(int)



Yes2.0 CoreBlob getBlob(String)

Yes1.0boolean getBoolean(int)

Yes1.0boolean getBoolean(String)

Yes1.0byte getByte(int)

Yes1.0byte getByte(String)




ResultSet Methods


Yes1.0byte [] getBytes(int)


Yes1.0byte [] getBytes(String)

Yes2.0 CoreReader getCharacterStream(int)

Yes2.0 CoreReader getCharacterStream(String)


Yes2.0 CoreClob getClob(int)


Yes2.0 CoreClob getClob(String)

Yes2.0 Coreint getConcurrency()


No1.0String getCursorName()

Yes1.0Date getDate(int)

Yes2.0 CoreDate getDate(int, Calendar)

Yes1.0Date getDate(String)

Yes2.0 CoreDate getDate(String, Calendar)

Yes1.0double getDouble(int)

Yes1.0double getDouble(String)

Yes2.0 Coreint getFetchDirection()

Yes2.0 Coreint getFetchSize()

Yes1.0float getFloat(int)




ResultSet Methods

Yes1.0float getFloat(String)

Yes4.0int getHoldability()

Yes1.0int getInt(int)

Yes1.0int getInt(String)

Yes1.0long getLong(int)

Yes1.0long getLong(String)

Yes1.0ResultSetMetaData getMetaData()

Yes4.0Reader getNCharacterStream(int)

Yes4.0Reader getNCharacterStream(String)

Yes4.0NClob getNClob(int)

Yes4.0NClob getNClob(String)

Yes4.0String getNString(int)

Yes4.0String getNString(String)

The DB2 driver returns a Long object whencalled on Bigint columns.

Yes1.0Object getObject(int)

The Oracle and Sybase drivers support theMap argument. For all other drivers, the Mapargument is ignored.

Yes2.0 CoreObject getObject(int, Map)

Yes1.0Object getObject(String)

The Oracle and Sybase drivers support theMap argument. For all other drivers, the Mapargument is ignored.

Yes2.0 CoreObject getObject(String, Map)


No2.0 CoreRef getRef(int)


No2.0 CoreRef getRef(String)

Yes2.0 Coreint getRow()

Yes1.0short getShort(int)

Yes1.0short getShort(String)




ResultSet Methods

Yes4.0SQLXML getSQLXML(int)

Yes4.0SQLXML getSQLXML(String)

Yes2.0 CoreStatement getStatement()

Yes1.0String getString(int)

Yes1.0String getString(String)

Yes1.0Time getTime(int)

Yes2.0 CoreTime getTime(int, Calendar)

Yes1.0Time getTime(String)

Yes2.0 CoreTime getTime(String, Calendar)

Yes1.0Timestamp getTimestamp(int)

Yes2.0 CoreTimestamp getTimestamp(int, Calendar)

Yes1.0Timestamp getTimestamp(String)

Yes2.0 CoreTimestamp getTimestamp(String, Calendar)

Yes2.0 Coreint getType()


No1.0InputStream getUnicodeStream(int)


No1.0InputStream getUnicodeStream(String)


No3.0URL getURL(int)


No3.0URL getURL(String)


Yes2.0 Corevoid insertRow()

Yes2.0 Coreboolean isAfterLast()

Yes2.0 Coreboolean isBeforeFirst()




ResultSet Methods


Yes2.0 Coreboolean isFirst()

Yes2.0 Coreboolean isLast()


Yes2.0 Coreboolean last()

Yes2.0 Corevoid moveToCurrentRow()

Yes2.0 Corevoid moveToInsertRow()

Yes1.0boolean next()

Yes2.0 Coreboolean previous()

Yes2.0 Corevoid refreshRow()

Yes2.0 Coreboolean relative(int)

Yes2.0 Coreboolean rowDeleted()

Yes2.0 Coreboolean rowInserted()

Yes2.0 Coreboolean rowUpdated()

Yes2.0 Corevoid setFetchDirection(int)

Yes2.0 Corevoid setFetchSize(int)



No3.0void updateArray(int, Array)


No3.0void updateArray(String, Array)

Yes2.0 Corevoid updateAsciiStream(int, InputStream,int)

Yes4.0void updateAsciiStream(int, InputStream,long)

Yes4.0void updateAsciiStream(String, InputStream)

Yes2.0 Corevoid updateAsciiStream(String, InputStream,int)




ResultSet Methods

Yes4.0void updateAsciiStream(String, InputStream,long)

Yes2.0 Corevoid updateBigDecimal(int, BigDecimal)

Yes2.0 Corevoid updateBigDecimal(String, BigDecimal)

Yes4.0void updateBinaryStream(int, InputStream)

Yes2.0 Corevoid updateBinaryStream(int, InputStream,int)

Yes4.0void updateBinaryStream(int, InputStream,long)

Yes4.0void updateBinaryStream(String,InputStream)

Yes2.0 Corevoid updateBinaryStream(String,InputStream, int)

Yes4.0void updateBinaryStream(String,InputStream, long)



Yes3.0void updateBlob(int, Blob)



Yes4.0void updateBlob(int, InputStream)



Yes4.0void updateBlob(int, InputStream, long)




ResultSet Methods



Yes3.0void updateBlob(String, Blob)



Yes4.0void updateBlob(String, InputStream)



Yes4.0void updateBlob(String, InputStream, long)

Yes2.0 Corevoid updateBoolean(int, boolean)

Yes2.0 Corevoid updateBoolean(String, boolean)

Yes2.0 Corevoid updateByte(int, byte)

Yes2.0 Corevoid updateByte(String, byte)

Yes2.0 Corevoid updateBytes(int, byte [])

Yes2.0 Corevoid updateBytes(String, byte [])

Yes4.0void updateCharacterStream(int, Reader)

Yes2.0 Corevoid updateCharacterStream(int, Reader,int)

Yes4.0void updateCharacterStream(int, Reader,long)

Yes4.0void updateCharacterStream(String,Reader)

Yes2.0 Corevoid updateCharacterStream(String,Reader, int)

Yes4.0void updateCharacterStream(String,Reader, long)




ResultSet Methods


Yes3.0void updateClob(int, Clob)


Yes4.0void updateClob(int, Reader)


Yes4.0void updateClob(int, Reader, long)


Yes3.0void updateClob(String, Clob)


Yes4.0void updateClob(String, Reader)


Yes4.0void updateClob(String, Reader, long)

Yes2.0 Corevoid updateDate(int, Date)

Yes2.0 Corevoid updateDate(String, Date)

Yes2.0 Corevoid updateDouble(int, double)

Yes2.0 Corevoid updateDouble(String, double)

Yes2.0 Corevoid updateFloat(int, float)

Yes2.0 Corevoid updateFloat(String, float)

Yes2.0 Corevoid updateInt(int, int)

Yes2.0 Corevoid updateInt(String, int)

Yes2.0 Corevoid updateLong(int, long)

Yes2.0 Corevoid updateLong(String, long)

For the drivers for MongoDB, Oracle Eloqua,Oracle Sales Cloud, Oracle Service Cloud,and Salesforce, N methods are identical totheir non-N counterparts.

Yes4.0void updateNCharacterStream(int, Reader)




ResultSet Methods


Yes4.0void updateNCharacterStream(int, Reader,long)


Yes4.0void updateNCharacterStream(String,Reader)


Yes4.0void updateNCharacterStream(String,Reader, long)


Yes4.0void updateNClob(int, NClob)


Yes4.0void updateNClob(int, Reader)


Yes4.0void updateNClob(int, Reader, long)


Yes4.0void updateNClob(String, NClob)


Yes4.0void updateNClob(String, Reader)


Yes4.0void updateNClob(String, Reader, long)


Yes4.0void updateNString(int, String)




ResultSet Methods


Yes4.0void updateNString(String, String)

Yes2.0 Corevoid updateNull(int)

Yes2.0 Corevoid updateNull(String)

Yes2.0 Corevoid updateObject(int, Object)

Yes2.0 Corevoid updateObject(int, Object, int)

Yes2.0 Corevoid updateObject(String, Object)

Yes2.0 Corevoid updateObject(String, Object, int)


No3.0void updateRef(int, Ref)


No3.0void updateRef(String, Ref)

Yes2.0 Corevoid updateRow()

Yes2.0 Corevoid updateShort(int, short)

Yes2.0 Corevoid updateShort(String, short)

Yes4.0void updateSQLXML(int, SQLXML)

Yes4.0void updateSQLXML(String, SQLXML)

Yes2.0 Corevoid updateString(int, String)

Yes2.0 Corevoid updateString(String, String)

Yes2.0 Corevoid updateTime(int, Time)

Yes2.0 Corevoid updateTime(String, Time)

Yes2.0 Corevoid updateTimestamp(int, Timestamp)

Yes2.0 Corevoid updateTimestamp(String, Timestamp)

Yes1.0boolean wasNull()



ResultSetMetaData


ResultSetMetaData Methods

Yes1.0String getCatalogName(int)

Yes2.0 CoreString getColumnClassName(int)

Yes1.0int getColumnCount()

Yes1.0int getColumnDisplaySize(int)

Yes1.0String getColumnLabel(int)

Yes1.0String getColumnName(int)

Yes1.0int getColumnType(int)

Yes1.0String getColumnTypeName(int)

Yes1.0int getPrecision(int)

Yes1.0int getScale(int)

Yes1.0String getSchemaName(int)

Yes1.0String getTableName(int)

Yes1.0boolean isAutoIncrement(int)

Yes1.0boolean isCaseSensitive(int)

Yes1.0boolean isCurrency(int)

Yes1.0boolean isDefinitelyWritable(int)

Yes1.0int isNullable(int)

Yes1.0boolean isReadOnly(int)

Yes1.0boolean isSearchable(int)

Yes1.0boolean isSigned(int)


Yes1.0boolean isWritable(int)




RowSet


RowSet Methods

No2.0 Optional(all)

SavePoint


SavePoint Methods

The DB2 driver only supports with DB2 V8.xand higher for Linux/UNIX/Windows, DB2for z/OS ((all versions), and DB2 for i.

Yes3.0(all)

Statement


Statement Methods

All drivers throw "invalid method call"exception for PreparedStatement andCallableStatement.

Yes2.0 Corevoid addBatch(String)

The DB2 driver cancels the execution of thestatement with DB2 V8.x and higher for

Yes1.0void cancel()

Linux/UNIX/Windows and DB2 V8.1 andhigher for z/OS. If the statement is canceledby the database server, the driver throwsan exception indicating that it was canceled.The DB2 driver throws an "unsupportedmethod" exception with other DB2 versions.

The drivers for Apache Cassandra, Impala,Informix, MongoDB, Progess OpenEdge,Oracle Service Cloud, Oracle Eloqua, OracleSales Cloud, and Salesforce throw an"unsupported method" exception.

The Apache Hive, Apache Spark SQL48,Greenplum, Oracle, PostgreSQL, SQLServer, Sybase, and Amazon Redshiftdrivers cancel the execution of thestatement. If the statement is canceled bythe database server, the driver throws anexception indicating that it was canceled.

48 Supported only for Apache Spark SQL 2.0 and higher. For earlier versions of Apache Spark SQL, the driver throws an "unsupportedmethod" exception.




Statement Methods

Yes2.0 Corevoid clearBatch()


Yes1.0void close()


Yes1.0boolean execute(String)

Yes3.0boolean execute(String, int)



Yes3.0boolean execute(String, int [])



Yes3.0boolean execute(String, String [])

Yes2.0 Coreint [] executeBatch()


Yes1.0ResultSet executeQuery(String)


Yes1.0int executeUpdate(String)

Yes3.0int executeUpdate(String, int)



Yes3.0int executeUpdate(String, int [])



Yes3.0int executeUpdate(String, String [])

Yes2.0 CoreConnection getConnection()

Yes2.0 Coreint getFetchDirection()




Statement Methods

Yes2.0 Coreint getFetchSize()

The DB2, SQL Server, and Sybase driversreturn the last value inserted into an identity

Yes3.0ResultSet getGeneratedKeys()

column. If an identity column does not existin the table, the drivers return an emptyresult set.

The Informix driver returns the last valueinserted into a Serial or Serial8 column. If aSerial or Serial8 column does not exist inthe table, the driver returns an empty resultset.

The Oracle driver returns the ROWID of thelast row that was inserted.

The drivers for Apache Cassandra,MongoDB, Oracle Eloqua, Oracle ServiceCloud, and Salesforce return the ID of thelast row that was inserted.

Auto-generated keys are not supported inany of the other drivers.

Yes1.0int getMaxFieldSize()

Yes1.0int getMaxRows()

Yes1.0boolean getMoreResults()

Yes3.0boolean getMoreResults(int)

The DB2 driver returns the timeout value,in seconds, set for the statement with

Yes1.0int getQueryTimeout()

DB2 V8.x and higher forLinux/UNIX/Windows and DB2 V8.1 andhigher for z/OS. The DB2 driver returns 0with other DB2 versions.

The Apache Hive, Apache Spark SQL,Impala, Informix and Progress OpenEdgedrivers return 0.

The drivers for Apache Cassandra,Greenplum, Oracle, PostgreSQL,SQL Server, Sybase, and Amazon Redshiftreturn the timeout value, in seconds, set forthe statement.

The drivers for Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, and Salesforcereturn an "unsupported method" exception.




Statement Methods

Yes1.0ResultSet getResultSet()

Yes2.0 Coreint getResultSetConcurrency()

Yes3.0int getResultSetHoldability()

Yes2.0 Coreint getResultSetType()

Yes1.0int getUpdateCount()



Yes4.0boolean isPoolable()


Throws "unsupported method" exception.No1.0void setCursorName(String)

Ignored.Yes1.0void setEscapeProcessing(boolean)

Yes2.0 Corevoid setFetchDirection(int)

Yes2.0 Corevoid setFetchSize(int)

Yes1.0void setMaxFieldSize(int)

Yes1.0void setMaxRows(int)

Yes4.0void setPoolable(boolean)

The DB2 driver supports setting a timeoutvalue, in seconds, for a statement with

Yes1.0void setQueryTimeout(int)

DB2 V8.x and higher forLinux/UNIX/Windows and DB2 V8.1 andhigher for z/OS. If the execution of thestatement exceeds the timeout value, thestatement is timed out by the databaseserver, and the driver throws an exceptionindicating that the statement was timed out.The DB2 driver throws an "unsupportedmethod" exception with other DB2 versions.

The drivers for Apache Hive, Apache SparkSQL, Impala, and Informix throw an"unsupported method" exception.




Statement Methods

The drivers for Greenplum, Oracle,PostgreSQL, Progress OpenEdge,SQL Server, Sybase, and Amazon Redshiftsupport setting a timeout value, in seconds,for a statement. If the execution of thestatement exceeds the timeout value, thestatement is timed out by the databaseserver, and the driver throws an exceptionindicating that the statement was timed out.

The drivers for Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, and Salesforceignore any value set using this method. Usethe WSTimeout connection property to seta timeout.

The drivers for Apache Cassandra andMongoDB driver ignore any value set usingthis method.


StatementEventListener


StatementEventListener Methods

Yes4.0void statementClosed(event)

Yes4.0void statementErrorOccurred(event)

Struct


Struct Methods

Supported for the Oracle driver only. Allother drivers throw "unsupported method"exception.

Yes2.0(all)



XAConnection


XAConnection Methods

Supported for all drivers except AmazonRedshift, Apache Hive, Apache Spark SQL,DB2 V8.1 for z/OS, Greenplum, Impala,Oracle Eloqua, Oracle Sales Cloud, andPostgreSQL.

Yes2.0 Optional(all)

XADataSource


XADataSource Methods



XAResource


XAResource Methods





9JDBC Extensions

This section describes the JDBC extensions provided by the com.ddtek.jdbc.extensions package. Someextensions apply to select drivers. In some cases, the functionality described may not apply to the driver ordata store you are using. The interfaces in the com.ddtek.jdbc.extensions are:

DescriptionInterface/Class

The methods in this interface are used with the drivers for Oracle Eloqua,Oracle Sales Cloud, Oracle Service Cloud, and Salesforce to extend thestandard JDBC metadata results returned by theDatabaseMetaData.getColumns() method to include an additional column.

DatabaseMetadata

Methods that allow your application to perform bulk load operations.DDBulkLoad

Methods that allow you to perform the following actions:

• Store and return client information.

• Switch the user associated with a connection to another user to minimizethe number of connections that are required in a connection pool.

• Access the DataDirect Statement Pool Monitor from a connection.

ExtConnection


DescriptionInterface/Class

Methods that allow your application to return client information parameters.ExtDatabaseMetaData

Methods that allow you to determine if DataDirect Spy logging is enabledand turning on and off DataDirect Spy logging if enabled.

ExtLogControl


• Using JDBC Wrapper Methods to Access JDBC Extensions

• DatabaseMetaData interface

• DDBulkLoad Interface

• ExtConnection Interface

• ExtDatabaseMetaData Interface

• ExtLogControl class

Using JDBC Wrapper Methods to Access JDBCExtensions

The Wrapper methods allow an application to access vendor-specific classes. The following example showshow to access the DataDirect-specific ExtConnection class using the Wrapper methods:

ExtStatementPoolMonitor monitor = null;Class<ExtConnection> cls = ExtConnection.class;if (con.isWrapperFor(cls)) {

ExtConnection extCon = con.unwrap(cls);extCon.setClientUser("Joe Smith");monitor = extCon.getStatementPoolMonitor();

}...if(monitor != null) {

long hits = monitor.getHitCount();long misses = monitor.getMissCount();

}...

DatabaseMetaData interfaceThe drivers for Oracle Eloqua, Oracle Sales Cloud, Oracle Service Cloud, and Salesforce extend the standardJDBC metadata results returned by the DatabaseMetaData.getColumns()method to include the followingadditional columns.


Chapter 9: JDBC Extensions

Table 25: DatabaseMetaData.getColumns() method

DescriptionData TypeColumn

Provides an indication of whether the column can be used as anExternal ID. External ID columns can be used as the lookup columnfor insert and upsert operations and foreign-key relationship values.Valid values are:

• YES: The column can be used as an external ID.

• NO: The column cannot be used as an external ID.

The standard catalog table SYSTEM_COLUMNS is also extended toinclude the IS_EXTERNAL_ID column.

VARCHAR (3), NOTNULL

IS_EXTERNAL_ID

The text label for this column. If not present, this field is null.VARCHAR (128)LABEL

The drivers for Oracle Eloqua, Oracle Sales Cloud, Oracle Service Cloud, and Salesforce extend the standardJDBC metadata results returned by the DatabaseMetaData.getTables() method to include the followingadditional column.

Table 26: DatabaseMetaData.getTables() Method

DescriptionData TypeColumn

The text label for this table. If not present, this field is null.VARCHAR (128)LABEL

DDBulkLoad InterfaceDescriptionDDBulkLoad Methods

Clears all warnings that were generated by this DDBulkLoad object.void clearWarnings()

Releases a DDBulkLoad object’s resources immediately instead ofwaiting for the connection to close.

void close()

Exports all rows from the table into the specified CSV file specified bya file reference. The table is specified using the setTableName()method. If the CSV file does not already exist, the driver creates it whenthe export() method is executed. In addition, the driver creates a bulkload configuration file matching the CSV file. This method also returnsthe number of rows that were successfully exported from the table.

long export(File)

Exports all rows from the specified ResultSet into the CSV file specifiedby a file reference. If the CSV file does not already exist, the drivercreates it when the export() method is executed. In addition, the drivercreates a bulk load configuration file matching the CSV file. This methodalso returns the number of rows that were successfully exported fromthe ResultSet object.

long export(ResultSet, File)


DDBulkLoad Interface

DescriptionDDBulkLoad Methods

Exports all rows from the table into the CSV file specified by name.The table is specified using the setTableName() method. If the CSVfile does not already exist, the driver creates it when the export() methodis executed. In addition, the driver creates a bulk load configuration filematching the CSV file. This method also returns the number of rowsthat were successfully exported from the table.

long export(String)

Returns the number of rows that the driver sends at a time when bulkloading data.

long getBatchSize()

Returns the maximum size (in bytes) of binary data that can be exportedto the CSV file. Once this size is reached, binary data is written to oneor multiple external overflow files.

long getBinaryThreshold()

Returns the maximum size (in bytes) of character data that can beexported to the CSV file. Once this size is reached, character data iswritten to one or multiple external overflow files.

long getCharacterThreshold()

Returns the code page that the driver uses for the CSV file.String getCodePage()

Returns the name of the bulk load configuration file.String getConfigFile()

Returns the name of the discard file. The discard file contains rows thatwere unable to be loaded as the result of a bulk load operation.

String getDiscardFile()

Returns the number of errors that can occur before this DDBulkLoadobject ends the bulk load operation.

long getErrorTolerance()

Returns the name of the log file. The log file records information abouteach bulk load operation.

String getLogFile()

Returns the maximum number of rows from the CSV file or ResultSetobject the driver will load when the load() method is executed.

long getNumRows()

Returns the properties specified for a DDBulkLoad object. Propertiesare specified using the setProperties() method.

Properties getProperties()

Returns the size (in KB) of the buffer that is used to read the CSV file.long getReadBufferSize()

Returns the position (number of the row) in a CSV file or ResultSetobject from which the driver starts loading. The position is specifiedusing the setStartPosition() method.

long getStartPosition()

Returns the name of the table to which the data is loaded into orexported from.

void getTableName()

Returns the number of seconds the bulk load operation requires tocomplete before it times out. The timeout is specified using thesetTimeout() method.

long getTimeout()

Returns any warnings generated by this DDBulkLoad object.SQLWarning getWarnings()




Returns the maximum number of warnings that can occur. Once themaximum number is reached, the bulk load operation ends.

long getWarningTolerance()

Loads data from the CSV file specified by a file reference into a table.The table is specified using the setTableName() method. This methodalso returns the number of rows that have been successfully loaded.

If logging is enabled using the setLogFile() method, information aboutthe bulk load operation is recorded in the log file. If a discard file iscreated using the setDiscardFile() method, rows that were unable tobe loaded are recorded in the discard file.

Before the bulk load operation is performed, your application can verifythat the data in the CSV file is compatible with the structure of the targettable using the validateTableFromFile() method.

long load(File)

Loads data from the CSV file specified by file name into a table. Thetable is specified using the setTableName() method. This method alsoreturns the number of rows that have been successfully loaded.

If logging is enabled using the setLogFile() method, information aboutthe bulk load operation is recorded in the log file. If a discard file iscreated using the setDiscardFile() method, rows that were unable tobe loaded are recorded in the discard file.

Before the bulk load operation is performed, your application can verifythat the data in the CSV file is compatible with the structure of the targettable using the validateTableFromFile() method.

long load(String)

Loads data from a ResultSet object into the table specified using thesetTableName() method. This method also returns the number of rowsthat have been successfully loaded.

If logging is enabled using the setLogFile() method, information aboutthe bulk load operation is recorded in the log file.

The structure of the table that produced the ResultSet object mustmatch the structure of the target table. If not, the driver throws anexception.

long load(ResultSet)

Specifies the number of rows that the driver sends at a time when bulkloading data. Performance can be improved by increasing the numberof rows the driver loads at a time because fewer network round tripsare required. Be aware that increasing the number of rows that areloaded also causes the driver to consume more memory on the client.

If unspecified, the driver uses a value of 2048.

void setBatchSize(long)




Specifies the maximum size (in bytes) of binary data to be exported tothe CSV file. Any column with data over this threshold is exported intoindividual external overflow files and a marker of the format{DD LOBFILE "filename"} is placed in the CSV file to signify thatthe data for this column is located in an external file. The format foroverflow file names is:

csv_filename_xxxxxx.lob

where:

csv_filename

is the name of the CSV file.

xxxxxx

is a 6-digit number that increments the overflow file.

For example, if multiple overflow files are created for a CSV file namedCSV1, the file names would look like this:

CSV1.000001.lobCSV1.000002.lobCSV1.000003.lob...

If set to -1, the driver does not overflow binary data to external files.If unspecified, the driver uses a value of 4096.

void setBinaryThreshold(long)




Specifies the maximum size (in bytes) of character data to be exportedto the CSV file. Any column with data over this threshold is exportedinto individual external overflow files and a marker of the format{DD LOBFILE "filename"} is placed in the CSV file to signify thatthe data for this column is located in an external file. The format foroverflow file names is:

csv_filename_xxxxxx.lob

where:

csv_filename

is the name of the CSV file.

xxxxxx

is a 6-digit number that increments the overflow file.

For example, if multiple overflow files are created for a CSV file namedCSV1, the file names would look like this:

CSV1.000001.lobCSV1.000002.lobCSV1.000003.lob...

If set to -1, the driver does not overflow character data to externalfiles.If unspecified, the driver uses a value of 4096.

void setCharacterThreshold(long)

Specifies the code page the driver uses for the CSV file.void setCodePage(String)

Specifies the fully qualified directory and file name of the bulk loadconfiguration file. If the Column Info section in the bulk loadconfiguration file is specified, the driver uses it to map the columns inthe CSV file to the columns in the target table when performing a bulkload operation.

If unspecified, the name of the bulk load configuration file is assumedto be csv_filename.xml, where csv_filename is the file name ofthe CSV file.

If set to an empty string, the driver does not try to use the bulk loadconfiguration file and reads all data from the CSV file as character data.

void setConfigFile(String)

Specifies the fully qualified directory and file name of the discard file.The discard file contains rows that were unable to be loaded from aCSV file as the result of a bulk load operation. After fixing the reportedissues in the discard file, the bulk load can be reissued, using thediscard file as the CSV file. If unspecified, a discard file is not created.

void setDiscardFile(String)




Specifies the maximum number of errors that can occur. Once themaximum number is reached, the bulk load operation ends. Errors arewritten to the log file. If set to 0, no errors are tolerated; the bulk loadoperation fails if any error is encountered. Any rows that were processedbefore the error occurred are loaded. If unspecified or set to -1, aninfinite number of errors are tolerated.

void setErrorTolerance(long)

Specifies the fully qualified directory and file name of the log file. Thelog file records information about each bulk load operation.If unspecified,a log file is not created.

void setLogFile(String)

Specifies the maximum number of rows from the CSV file or ResultSetobject the driver will load.

void setNumRows()

Specifies one or more of the following properties for a DDBulkLoadobject:

tableName numRowscodePage binaryThresholdtimeout characterThresholdlogFile errorTolerancediscardFile warningToleranceconfigFile readBufferSizestartPosition batchSizeoperation

Except for the operation property, these properties also can be setusing the corresponding setxxx() methods, which provide a descriptionof the values that can be set.

The operation property defines which type of bulk operation will beperformed when a load method is called. The operation property acceptsthe following values: insert, update, delete, or upsert. The defaultvalue is insert.

void setProperties(Properties)

Specifies the size (in KB) of the buffer that is used to read the CSV file.If unspecified, the driver uses a value of 2048.

void setReadBufferSize(long)

Specifies the position (number of the row) in a CSV file or ResultSetobject from which the bulk load operation starts. For example, if a valueof 10 is specified, the first 9 rows of the CSV file are skipped and thefirst row loaded is row 10.

void setStartPosition()




When loading data into a table, specifies the name of the table intowhich the data is loaded (tablename).

Optionally, for the Salesforce driver, you can specify the column namesthat identify which columns to update in the table(destinationColumnList). Specifying column names is usefulwhen loading data from a CSV file into a table. The column namesused in the column list must be the names reported by the driver forthe columns in the table. For example, if you are loading data into theSalesforce system column NAME, the column list must identify thecolumn as SYS_NAME.

If destinationColumnList is not specified, a one-to-one mappingis performed between the columns in the CSV file and the columns inthe table.

destinationColumnList has the following format:

(destColumnName [,destColumnName]...)

where:

destColumnName

is the name of the column in the table to be updated.

The number of specified columns must match the number of columnsin the CSV file. For example, the following call tells the driver to updatethe Name, Address, City, State, PostalCode, Phone, and Websitecolumns:

bulkload.setTableName("account(Name, Address,City,State, PostalCode, Phone, Website)")

When exporting data from a table, specifies the name of the table fromwhich the data is exported. If the specified table does not exist, thedriver throws an exception.

void setTableName(tablename([destinationColumnList]))

Sets the maximum number of seconds that can elapse for this bulkload operation to complete. Once this number is reached, the bulk loadoperation times out.

void setTimeout(long)




Specifies the maximum number of warnings that can occur. Once themaximum is reached, the bulk load operation ends. Warnings are writtento the log file.

If set to 0, no warnings are tolerated; the bulk load operation fails if anywarning is encountered.

If unspecified or set to -1, an infinite number of warnings are tolerated.

void setWarningTolerance(long)

Verifies the metadata in the bulk load configuration file against thestructure of the table to which the data is loaded. This method is usedto ensure that the data in a CSV file is compatible with the structure ofthe target table before the actual bulk load operation is performed. Thedriver performs checks to detect mismatches of the following types:

Data types

Column sizes

Code pages

Column info

This method returns a Properties object with an entry for each of thesechecks:

• If no mismatches are found, the Properties object does not containany messages.

• If minor mismatches are found, the Properties object lists theproblems.

• If problems are detected that would prevent a successful bulk loadoperation, for example, if the target table does not exist, the driverthrows an exception.

Properties validateTableFromFile()

ExtConnection InterfaceThe methods of this interface are supported for all drivers.

DescriptionExtConnection Methods

Closes the current connection and marks the connection as closed.This method does not attempt to obtain any locks when closing theconnection. If subsequent operations are performed on the connection,the driver throws an exception.

void abortConnection()

Supported by the Oracle driver only for use with Oracle VARRAY andTABLE data types. Creates an array object.

Connection createArray(String, Object[])




Returns the accounting client information on the connection or an emptystring if the accounting client information value or the connection hasnot been set.

If getting accounting client information is supported by the databaseand this operation fails, the driver throws an exception.

String getClientAccountingInfo()

Returns the name of the client application on the connection or anempty string if the client name value for the connection has not beenset.

If getting client name information is supported by the database and thisoperation fails, the driver throws an exception.

String getClientApplicationName()

Returns the name of the host used by the client application on theconnection or an empty string if the client hostname value in thedatabase has not been set.

If getting host name information is supported by the database and thisoperation fails, the driver throws an exception.

String getClientHostname()

Returns the user ID of the client on the connection or an empty stringif the client user ID value for the connection has not been set. Theuser ID may be different from the user ID establishing the connection.

If getting user ID application information is supported by the databaseand this operation fails, the driver throws an exception.

String getClientUser()

Returns the current user of the connection. If reauthentication wasperformed on the connection, the current user may be different thanthe user that created the connection. For the DB2 and Oracle drivers,the current user is the same as the user reported byDatabaseMetaData.getUserName(). For the SQL Server driver, thecurrent user is the login user name. DatabaseMetaData.getUserName()reports the user name the login user name is mapped to in thedatabase.

String getCurrentUser()

Supported by the SQL Server driver to return the network timeout. Thenetwork timeout is the maximum time (in milliseconds) that a connection,or objects created by a connection, will wait for the database to replyto an application request. A value of 0 means that no network timeoutexists.

See void setNetworkTimeout(int) for details about setting a networktimeout.

int getNetworkTimeout()

Returns an ExtStatementPoolMonitor object for the statement poolassociated with the connection. If the connection does not have astatement pool, this method returns null.

ExtStatementPoolMonitorgetStatementPoolMonitor()


ExtConnection Interface


Specifies a non-null string that resets the current user on the connectionto the user that created the connection. It also restores the currentschema, current path, or current database to the original value usedwhen the connection was created. If reauthentication was performedon the connection, this method is useful to reset the connection to theoriginal user.

For the SQL Server driver, the current user is the login user name.Thedriver throws an exception in the following circumstances:

• The driver cannot change the current user to the initial user.

• A transaction is active on the connection.

void resetUser(String)

Specifies a non-null string that sets the accounting client informationon the connection. Some databases include this information in theirusage reports. The maximum length allowed for accounting informationfor a particular database can be determined by calling theExtDatabaseMetaData.getClientAccountingInfoLength() method. If thelength of the information specified is longer than the maximum lengthallowed, the information is truncated to the maximum length, and thedriver generates a warning.

If setting accounting client information is supported by the databaseand this operation fails, the driver throws an exception.

void setClientAccountingInfo(String)

Specifies a non-null string that sets the name of the client applicationon the connection. The maximum client name length allowed for aparticular database can be determined by calling theExtDatabaseMetaData.getClientApplicationNameLength() method. Ifthe length of the client application name specified is longer than themaximum name length allowed, the name is truncated to the maximumlength allowed, and the driver generates a warning.

If setting client name information is supported by the database and thisoperation fails, the driver throws an exception.

void setClientApplicationName(String)

Specifies a non-null string that sets the name of the host used by theclient application on the connection. The maximum hostname lengthallowed for a particular database can be determined by calling theExtDatabaseMetaData.getClientHostnameLength() method. If the lengthof the hostname specified is longer than the maximum hostname lengthallowed, the hostname is truncated to the maximum hostname length,and the driver generates a warning.

If setting hostname information is supported by the database and thisoperation fails, the driver throws an exception.

void setClientHostname(String)




Specifies a non-null string that sets the user ID of the client on theconnection. This user ID may be different from the user ID establishingthe connection. The maximum user ID length allowed for a particulardatabase can be determined by calling theExtDatabaseMetaData.getClientUserLength() method. If the length ofthe user ID specified is longer than the maximum length allowed, theuser ID is truncated to the maximum user ID length, and the drivergenerates a warning.

If setting user ID information is supported by the database and thisoperation fails, the driver throws an exception.

void setClientUser(String)

Specifies a non-null string that sets the current user on the connection.This method is used to perform reauthentication on a connection. Forthe SQL Server driver, the current user is the login user name. Thedriver throws an exception in the following circumstances:

• The driver is connected to a database server that does not supportreauthentication.

• The database server rejects the request to change the user on theconnection.


void setCurrentUser(String)

Specifies a non-null string that sets the current user on the connection.This method is used to perform reauthentication on a connection. Inaddition, this method sets options that control how the driver handlesreauthentication. The options that are supported depend on the driver.See the DB2 driver, Oracle driver, and SQL Server driver chapters forinformation on which options are supported by each driver. For theSQL Server driver, the current user is the login user name. The driverthrows an exception in the following circumstances:




void setCurrentUser(String, Properties)


ExtConnection Interface


Specifies a non-null string that sets the current user on the connectionto the user specified by the javax.security.auth.Subject object. Thismethod is used to perform reauthentication on a connection. For theSQL Server driver, the current user is the login user name. The driverthrows an exception in the following circumstances:

• The driver does not support reauthentication.




voidsetCurrentUser(javax.security.auth.Subject)

Specifies a non-null string that sets the current user on the connectionto the user specified by the javax.security.auth.Subject object. Thismethod is used to perform reauthentication on a connection. In addition,this method sets options that control how the driver handlesreauthentication. The options that are supported depend on the driver.See your user's guide for information on which options are supportedby each driver.

For the SQL Server driver, the current user is the login user name.

The driver throws an exception in the following circumstances:

• The driver does not support reauthentication.




voidsetCurrentUser(javax.security.auth.Subject,Properties)

Supported by the SQL Server driver to set the network timeout. Thenetwork timeout is the maximum time (in milliseconds) that a connection,or objects created by a connection, will wait for the database to replyto an application request. If this limit is exceeded, the connection orobjects are closed and the driver returns an exception indicating thata timeout occurred. A value of 0 means that no network timeout exists.

Note that if a query timeout occurs before a network timeout, theexecution of the statement is cancelled. Both the connection and thestatement can be used. If a network timeout occurs before a querytimeout or if the query timeout fails because of network problems, theconnection is closed and neither the connection or the statement canbe used.

void setNetworkTimeout(int)

Indicates whether the connection supports reauthentication. If true isreturned, you can perform reauthentication on the connection. If falseis returned, any attempt to perform reauthentication on the connectionthrows an exception.

boolean supportsReauthentication()



ExtDatabaseMetaData InterfaceDescriptionExtDatabaseMetaData Methods

Returns the maximum length of the client application name. A value of0 indicates that the client application name is stored locally in the driver,not in the database. There is no maximum length if the applicationname is stored locally.

int getClientApplicationNameLength()

Returns the maximum length of the client user ID. A value of 0 indicatesthat the client user ID is stored locally in the driver, not in the database.There is no maximum length if the client user ID is stored locally.

int getClientUserLength()

Returns the maximum length of the hostname. A value of 0 indicatesthat the hostname is stored locally in the driver, not in the database.There is no maximum length if the hostname is stored locally.

int getClientHostnameLength()

Returns the maximum length of the accounting information. A value of0 indicates that the accounting information is stored locally in the driver,not in the database. There is no maximum length if the hostname isstored locally.

int getClientAccountingInfoLength()

ExtLogControl classDescriptionExtLogControl Methods

If DataDirect Spy was enabled when the connection was created, youcan turn on or off DataDirect Spy logging at runtime using this method.If true, logging is turned on. If false, logging is turned off. If DataDirectSpy logging was not enabled when the connection was created, callingthis method has no effect.

void setEnableLogging(boolean enable|disable)

Indicates whether DataDirect Spy logging was enabled when theconnection was created and whether logging is turned on. If the returnedvalue is true, logging is turned on. If the returned value is false, loggingis turned off.

boolean getEnableLogging()


ExtDatabaseMetaData Interface

10Designing JDBC Applications forPerformance Optimization

Developing performance-oriented JDBC applications is not easy. JDBC drivers do not throw exceptions to tellyou when your code is running too slow. This chapter presents some general guidelines for improving JDBCapplication performance that have been compiled by examining the JDBC implementations of numerousshipping JDBC applications. These guidelines include:

• Use DatabaseMetaData methods appropriately

• Return only required data

• Select functions that optimize performance

• Manage connections and updates

Following these general guidelines can help you solve some common JDBC system performance problems,such as those listed in the following table.

See guidelines in…SolutionProblem

Using Database Metadata Methods onpage 252

Reduce network traffic.Network communication is slow.

Using Database Metadata Methods onpage 252

Selecting JDBC Objects and Methodson page 256

Simplify queries.Evaluation of complex SQL queries onthe database server is slow and canreduce concurrency.


See guidelines in…SolutionProblem

Returning Data on page 254

Selecting JDBC Objects and Methodson page 256

Optimize application-to-driverinteraction.

Excessive calls from the application tothe driver slow performance.

Managing Connections and Updateson page 259

Limit disk I/O.Disk I/O is slow.

In addition, most JDBC drivers provide options that improve performance, often with a trade-off in functionality.If your application is not affected by functionality that is modified by setting a particular option, significantperformance improvements can be realized.

Note: The section describes functionality across a spectrum of data stores. In some cases, the functionalitydescribed may not apply to the driver or data store you are using. In addition, examples are drawn from avariety of drivers and data stores.


• Using Database Metadata Methods

• Returning Data

• Selecting JDBC Objects and Methods

• Managing Connections and Updates

Using Database Metadata MethodsBecause database metadata methods that generate ResultSet objects are slow compared to other JDBCmethods, their frequent use can impair system performance. The guidelines in this section will help you optimizesystem performance when selecting and using database metadata.

Minimizing the Use of Database Metadata MethodsCompared to other JDBC methods, database metadata methods that generate ResultSet objects are relativelyslow. Applications should cache information returned from result sets that generate database metadata methodsso that multiple executions are not needed.

Although almost no JDBC application can be written without database metadata methods, you can improvesystem performance by minimizing their use. To return all result column information mandated by the JDBCspecification, a JDBC driver may have to perform complex queries or multiple queries to return the necessaryresult set for a single call to a database metadata method. These particular elements of the SQL language areperformance-expensive.

Applications should cache information from database metadata methods. For example, call getTypeInfo() oncein the application and cache the elements of the result set that your application depends on. It is unlikely thatany application uses all elements of the result set generated by a database metadata method, so the cacheof information should not be difficult to maintain.


Chapter 10: Designing JDBC Applications for Performance Optimization

Avoiding Search PatternsUsing null arguments or search patterns in database metadata methods results in generating time-consumingqueries. In addition, network traffic potentially increases due to unwanted results. Always supply as manynon-null arguments as possible to result sets that generate database metadata methods.

Because database metadata methods are slow, invoke them in your applications as efficiently as possible.Many applications pass the fewest non-null arguments necessary for the function to return success. For example:

ResultSet WSrs = WSdbmd.getTables(null, null, "WSTable", null);

In this example, an application uses the getTables() method to determine if the WSTable table exists. A JDBCdriver interprets the request as: return all tables, views, system tables, synonyms, temporary tables, and aliasesnamed "WSTable" that exist in any database schema inside the database catalog.

In contrast, the following request provides non-null arguments as shown:

String[] tableTypes = {"TABLE"};WSdbmd.getTables("cat1", "johng", "WSTable", "tableTypes");

Clearly, a JDBC driver can process the second request more efficiently than it can process the first request.

Sometimes, little information is known about the object for which you are requesting information. Any informationthat the application can send the driver when calling database metadata methods can result in improvedperformance and reliability.

Using a Dummy Query to Determine Table CharacteristicsAvoid using the getColumns() method to determine characteristics about a database table. Instead, use adummy query with getMetadata().

Consider an application that allows the user to choose the columns to be selected. Should the application usegetColumns() to return information about the columns to the user or instead prepare a dummy query and callgetMetadata()?

Case 1: GetColumns() MethodResultSet WSrc = WSc.getColumns(... "UnknownTable" ...);// This call to getColumns will generate a query to// the system catalogs... possibly a join// which must be prepared, executed, and produce// a result set. . .WSrc.next();string Cname = getString(4);. . .// user must return N rows from the server// N = # result columns of UnknownTable// result column information has now been obtained

Case 2: GetMetadata() Method// prepare dummy queryPreparedStatement WSps = WSc.prepareStatement

("SELECT * FROM UnknownTable WHERE 1 = 0");// query is never executed on the server - only preparedResultSetMetaData WSsmd=WSps.getMetaData();int numcols = WSrsmd.getColumnCount();...


Using Database Metadata Methods

int ctype = WSrsmd.getColumnType(n)...// result column information has now been obtained// Note we also know the column ordering within the// table! This information cannot be// assumed from the getColumns example.

In both cases, a query is sent to the server. However, in Case 1, the potentially complex query must be preparedand executed, result description information must be formulated, and a result set of rows must be sent to theclient. In Case 2, we prepare a simple query where we only return result set information. Clearly, Case 2 is thebetter performing model.

To somewhat complicate this discussion, let us consider a DBMS server that does not natively support preparinga SQL statement. The performance of Case 1 does not change but the performance of Case 2 improves slightlybecause the dummy query must be evaluated in addition to being prepared. Because the Where clause of thequery always evaluates to FALSE, the query generates no result rows and should execute without accessingtable data. For this situation, Case 2 still outperforms Case 1.

In summary, always use result set metadata to return table column information, such as column names, columndata types, and column precision and scale. Only use the getColumns() method when the requested informationcannot be obtained from result set metadata (for example, using the table column default values).

Returning DataTo return data efficiently, return only the data that you need and choose the most efficient method of doing so.The guidelines in this section will help you optimize system performance when retrieving data with JDBCapplications.

Returning Long DataBecause retrieving long data across a network is slow and resource intensive, applications should not requestlong data unless it is necessary.

Most users do not want to see long data. If the user does want to see these result items, then the applicationcan query the database again, specifying only the long columns in the Select list. This method allows theaverage user to return the result set without having to pay a high performance penalty for network traffic.

Although the best method is to exclude long data from the Select list, some applications do not formulate theSelect list before sending the query to the JDBC driver (that is, some applications SELECT * FROMtable_name ...). If the Select list contains long data, most drivers are forced to return that long data at fetchtime, even if the application does not ask for the long data in the result set. When possible, the designer shouldattempt to implement a method that does not return all columns of the table.

For example, consider the following code:

ResultSet rs = stmt.executeQuery("SELECT * FROM Employees WHERE SSID = '999-99-2222'");

rs.next();string name = rs.getString(1);



Remember that a JDBC driver cannot interpret an application's final intention. When a query is executed, thedriver has no way to know which result columns an application will use. A driver anticipates that an applicationcan request any of the result columns that are returned. When the JDBC driver processes the rs.next request,it will probably return at least one, if not more, result rows from the database server across the network. In thiscase, a result row contains all the column values for each row, including an employee photograph if theEmployees table contains such a column. If you limit the Select list to contain only the employee name column,it results in decreased network traffic and a faster performing query at runtime. For example:

ResultSet rs = stmt.executeQuery("SELECT name FROM Employees WHERE SSID = '999-99-2222'");

rs.next();string name = rs.getString(1);

Additionally, although the getClob() and getBlob() methods allow the application to control how long data isreturned in the application, the designer must realize that in many cases, the JDBC driver emulates thesemethods due to the lack of true Large Object (LOB) locator support in the DBMS. In such cases, the drivermust return all the long data across the network before exposing the getClob() and getBlob() methods.

Reducing the Size of Returned DataSometimes long data must be returned. When this is the case, remember that most users do not want to see100 KB, or more, of text on the screen.

To reduce network traffic and improve performance, you can reduce the size of any data being returned tosome manageable limit by calling setMaxRows(), setMaxFieldSize(), and the driver-specific setFetchSize().Another method of reducing the size of the data being returned is to decrease the column size.

In addition, be careful to return only the rows you need. If you return five columns when you only need twocolumns, performance is decreased, especially if the unnecessary rows include long data.

Choosing the Right Data TypeRetrieving and sending certain data types can be expensive. When you design a schema, select the data typethat can be processed most efficiently. For example, integer data is processed faster than floating-point data.Floating-point data is defined according to internal database-specific formats, usually in a compressed format.The data must be decompressed and converted into a different format so that it can be processed by thedatabase wire protocol.

Retrieving Result SetsMost JDBC drivers cannot implement scrollable cursors because of limited support for scrollable cursors in thedatabase system. Unless you are certain that the database supports using a scrollable result set, rs, for example,do not call rs.last and rs.getRow() methods to find out how many rows the result set contains. For JDBC driversthat emulate scrollable cursors, calling rs.last results in the driver retrieving all results across the network toreach the last row. Instead, you can either count the rows by iterating through the result set or get the numberof rows by submitting a query with a Count column in the Select clause.

In general, do not write code that relies on the number of result rows from a query because drivers must fetchall rows in a result set to know how many rows the query will return.


Returning Data

Selecting JDBC Objects and MethodsThe guidelines in this section will help you to select which JDBC objects and methods will give you the bestperformance.

Using Parameter Markers as Arguments to Stored ProceduresWhen calling stored procedures, always use parameter markers for argument markers instead of using literalarguments. JDBC drivers can call stored procedures on the database server either by executing the procedureas a SQL query or by optimizing the execution by invoking a Remote Procedure Call (RPC) directly on thedatabase server. When you execute a stored procedure as a SQL query, the database server parses thestatement, validates the argument types, and converts the arguments into the correct data types.

Remember that SQL is always sent to the database server as a character string, for example, {callgetCustName(12345)}. In this case, even though the application programmer may have assumed that theonly argument to getCustName() was an integer, the argument is actually passed inside a character string tothe server. The database server parses the SQL query, isolates the single argument value 12345, and convertsthe string 12345 into an integer value before executing the procedure as a SQL language event.

By invoking a RPC on the database server, the overhead of using a SQL character string is avoided. Instead,the JDBC driver constructs a network packet that contains the parameters in their native data type formats andexecutes the procedure remotely.

Case 1: Not Using a Server-Side RPCIn this example, the stored procedure getCustName() cannot be optimized to use a server-side RPC. Thedatabase server must treat the SQL request as a normal language event, which includes parsing the statement,validating the argument types, and converting the arguments into the correct data types before executing theprocedure.

CallableStatement cstmt = conn.prepareCall("call getCustName(12345)");ResultSet rs = cstmt.executeQuery();

Case 2: Using a Server-Side RPCIn this example, the stored procedure getCustName() can be optimized to use a server-side RPC. Becausethe application avoids literal arguments and calls the procedure by specifying all arguments as parameters,the JDBC driver can optimize the execution by invoking the stored procedure directly on the database as anRPC. The SQL language processing on the database server is avoided and execution time is greatly improved.

CallableStatement cstmt = conn.prepareCall("call getCustName(?)}");cstmt.setLong(1,12345);ResultSet rs = cstmt.executeQuery();

Using the StatementObject Instead of the PreparedStatementObjectJDBC drivers are optimized based on the perceived use of the functions that are being executed. Choosebetween the PreparedStatement object and the Statement object depending on how you plan to use the object.The Statement object is optimized for a single execution of a SQL statement. In contrast, the PreparedStatementobject is optimized for SQL statements to be executed two or more times.



The overhead for the initial execution of a PreparedStatement object is high. The advantage comes withsubsequent executions of the SQL statement. For example, suppose we are preparing and executing a querythat returns employee information based on an ID. Using a PreparedStatement object, a JDBC driver wouldprocess the prepare request by making a network request to the database server to parse and optimize thequery. The execute results in another network request. If the application will only make this request once duringits life span, using a Statement object instead of a PreparedStatement object results in only a single networkroundtrip to the database server. Reducing network communication typically provides the most performancegains.

This guideline is complicated by the use of prepared statement pooling because the scope of execution islonger. When using prepared statement pooling, if a query will only be executed once, use the Statementobject. If a query will be executed infrequently, but may be executed again during the life of a statement poolinside a connection pool, use a PreparedStatement object. Under similar circumstances without statementpooling, use the Statement object.

Using Batches Instead of Prepared StatementsUpdating large amounts of data typically is done by preparing an Insert statement and executing that statementmultiple times, resulting in numerous network roundtrips. To reduce the number of JDBC calls and improveperformance, you can send multiple queries to the database at a time using the addBatch method of thePreparedStatement object. For example, let us compare the following examples, Case 1 and Case 2.

Case 1: Executing Prepared Statement Multiple TimesPreparedStatement ps = conn.prepareStatement(

"INSERT INTO employees VALUES (?, ?, ?)");for (n = 0; n < 100; n++) {

ps.setString(name[n]);ps.setLong(id[n]);ps.setInt(salary[n]);ps.executeUpdate();

}

Case 2: Using a BatchPreparedStatement ps = conn.prepareStatement(

"INSERT INTO employees VALUES (?, ?, ?)");for (n = 0; n < 100; n++) {

ps.setString(name[n]);ps.setLong(id[n]);ps.setInt(salary[n]);ps.addBatch();

}ps.executeBatch();

In Case 1, a prepared statement is used to execute an Insert statement multiple times. In this case, 101 networkroundtrips are required to perform 100 Insert operations: one roundtrip to prepare the statement and 100additional roundtrips to execute its iterations. When the addBatch method is used to consolidate 100 Insertoperations, as demonstrated in Case 2, only two network roundtrips are required—one to prepare the statementand another to execute the batch. Although more database CPU cycles are involved by using batches,performance is gained through the reduction of network roundtrips. Remember that the biggest gain inperformance is realized by reducing network communication between the JDBC driver and the database server.


Selecting JDBC Objects and Methods

Choosing the Right CursorChoosing the appropriate type of cursor allows maximum application flexibility. This section summarizes theperformance issues of three types of cursors: forward-only, insensitive, and sensitive.

A forward-only cursor provides excellent performance for sequential reads of all rows in a table. For retrievingtable data, there is no faster way to return result rows than using a forward-only cursor; however, forward-onlycursors cannot be used when the rows to be returned are not sequential.

Insensitive cursors are ideal for applications that require high levels of concurrency on the database serverand require the ability to scroll forwards and backwards through result sets. The first request to an insensitivecursor fetches all the rows and stores them on the client. In most cases, the first request to an insensitive cursorfetches all the rows and stores them on the client. If a driver uses "lazy" fetching (fetch-on-demand), the firstrequest may include many rows, if not all rows.The initial request is slow, especially when long data is returned.Subsequent requests do not require any network traffic (or, when a driver uses "lazy" fetching, requires limitednetwork traffic) and are processed quickly.

Because the first request is processed slowly, insensitive cursors should not be used for a single request ofone row. Developers should also avoid using insensitive cursors when long data or large result sets are returnedbecause memory can be exhausted. Some insensitive cursor implementations cache the data in a temporarytable on the database server and avoid the performance issue, but most cache the information local to theapplication.

Sensitive cursors, or keyset-driven cursors, use identifiers such as a ROWID that already exist in the database.When you scroll through the result set, the data for these identifiers is returned. Because each request generatesnetwork traffic, performance can be very slow. However, returning non-sequential rows does not further affectperformance.

To illustrate this point further, consider an application that normally returns 1000 rows to an application. Atexecute time, or when the first row is requested, a JDBC driver does not execute the Select statement thatwas provided by the application. Instead, the JDBC driver replaces the Select list of the query with a keyidentifier, for example, ROWID. This modified query is then executed by the driver and all 1000 key values arereturned by the database server and cached for use by the driver. Each request from the application for a resultrow directs the JDBC driver to look up the key value for the appropriate row in its local cache, construct anoptimized query that contains a Where clause similar to WHERE ROWID=?, execute the modified query, andreturn the single result row from the server.

Sensitive cursors are the preferred scrollable cursor model for dynamic situations when the application cannotafford to buffer the data associated with an insensitive cursor.

Using get Methods EffectivelyJDBC provides a variety of methods to return data from a result set (for example, getInt(), getString(), andgetObject()). The getObject() method is the most generic and provides the worst performance when thenon-default mappings are specified because the JDBC driver must perform extra processing to determine thetype of the value being returned and generate the appropriate mapping. Always use the specific method forthe data type.

To further improve performance, provide the column number of the column being returned, for example,getString(1), getLong(2), and getInt(3), instead of the column name. If the column names are notspecified, network traffic is unaffected, but costly conversions and lookups increase. For example, supposeyou use:

getString("foo")...

The JDBC driver may need to convert foo to uppercase and then compare foo with all columns in the columnlist, which is costly. If the driver is able to go directly to result column 23, a large amount of processing is saved.



For example, suppose you have a result set that has 15 columns and 100 rows, and the column names arenot included in the result set. You are interested in only three columns: EMPLOYEENAME (string),EMPLOYEENUMBER (long integer), and SALARY (integer). If you specify getString("EmployeeName"),getLong("EmployeeNumber"), and getInt("Salary"), each column name must be converted to theappropriate case of the columns in the database metadata and lookups would increase considerably.Performance improves significantly if you specify getString(1), getLong(2), and getInt(15).

Retrieving Auto Generated KeysMany databases have hidden columns (pseudo-columns) that represent a unique key for each row in a table.Typically, using these types of columns in a query is the fastest way to access a row because thepseudo-columns usually represent the physical disk address of the data. Prior to JDBC 3.0, an applicationcould only return the value of the pseudo-columns by executing a Select statement immediately after insertingthe data. For example:

//insert rowint rowcount = stmt.executeUpdate (

"INSERT INTO LocalGeniusList (name)VALUES ('Karen')");

// now get the disk address – rowid -// for the newly inserted rowResultSet rs = stmt.executeQuery (

"SELECT rowid FROM LocalGeniusListWHERE name = 'Karen'");

Retrieving pseudo-columns this way has two major flaws. First, retrieving the pseudo-column requires a separatequery to be sent over the network and executed on the server. Second, because there may not be a primarykey over the table, the search condition of the query may be unable to uniquely identify the row. In the lattercase, multiple pseudo-column values can be returned, and the application may not be able to determine whichvalue is actually the value for the most recently inserted row.

An optional feature of the JDBC 3.0 specification is the ability to return auto-generated key information for arow when the row is inserted into a table. For example:

int rowcount = stmt.executeUpdate("INSERT INTO LocalGeniusList(name) VALUES('Karen')",

// insert row AND return keyStatement.RETURN_GENERATED_KEYS);ResultSet rs = stmt.getGeneratedKeys();// key is automatically available

Now, the application contains a value that can be used in a search condition to provide the fastest access tothe row and a value that uniquely identifies the row, even when a primary key doesn't exist on the table.

The ability to return keys provides flexibility to the JDBC developer and creates performance boosts whenaccessing data.

Managing Connections and UpdatesThe guidelines in this section will help you to manage connections and updates to improve system performancefor your JDBC applications.


Managing Connections and Updates

Managing ConnectionsConnection management is important to application performance. Optimize your application by connectingonce and using multiple Statement objects, instead of performing multiple connections. Avoid connecting to adata source after establishing an initial connection.

Although gathering driver information at connect time is a good practice, it is often more efficient to gather it inone step rather than two steps. For example, some applications establish a connection and then call a methodin a separate component that reattaches and gathers information about the driver. Applications that are designedas separate entities should pass the established connection object to the data collection routine instead ofestablishing a second connection.

Another bad practice is to connect and disconnect several times throughout your application to perform SQLstatements. Connection objects can have multiple Statement objects associated with them. Statement objects,which are defined to be memory storage for information about SQL statements, can manage multiple SQLstatements.

You can improve performance significantly with connection pooling, especially for applications that connectover a network or through the World Wide Web. Connection pooling lets you reuse connections. Closingconnections does not close the physical connection to the database. When an application requests a connection,an active connection is reused, thus avoiding the network round trips needed to create a new connection.

Typically, you can configure a connection pool to provide scalability for connections. The goal is to maintain areasonable connection pool size while ensuring that each user who needs a connection has one availablewithin an acceptable response time. To achieve this goal, you can configure the minimum and maximum numberof connections that are in the pool at any given time, and how long idle connections stay in the pool. In addition,to help minimize the number of connections required in a connection pool, you can switch the user associatedwith a connection to another user, a process known as reauthentication. Not all databases supportreauthentication.

In addition to connection pooling tuning options, JDBC also specifies semantics for providing a preparedstatement pool. Similar to connection pooling, a prepared statement pool caches PreparedStatement objectsso that they can be re-used from a cache without application intervention. For example, an application maycreate a PreparedStatement object similar to the following SQL statement:

SELECT name, address, dept, salary FROM personnelWHERE empid = ? or name = ? or address = ?

When the PreparedStatement object is created, the SQL query is parsed for semantic validation and a queryoptimization plan is produced. The process of creating a prepared statement can be extremely expensive interms of performance with some database systems. Once the prepared statement is closed, a JDBC3.0-compliant driver places the prepared statement into a local cache instead of discarding it. If the applicationlater attempts to create a prepared statement with the same SQL query, a common occurrence in manyapplications, the driver can simply retrieve the associated statement from the local cache instead of performinga network roundtrip to the server and an expensive database validation.

Connection and statement handling should be addressed before implementation. Thoughtfully handlingconnections and statements improves application performance and maintainability.

Managing Commits in TransactionsCommitting transactions is slow because of the amount of disk I/O and potentially network round trips that arerequired. Always turn off Autocommit by using Connection.setAutoCommit(false).



What does a commit actually involve? The database server must flush back to disk every data page thatcontains updated or new data. This is usually a sequential write to a journal file, but nevertheless, it involvesdisk I/O. By default, Autocommit is on when connecting to a data source, and Autocommit mode usually impairsperformance because of the significant amount of disk I/O needed to commit every operation.

Furthermore, most database servers do not provide a native Autocommit mode. For this type of server, theJDBC driver must explicitly issue a COMMIT statement and a BEGIN TRANSACTION for every operation sentto the server. In addition to the large amount of disk I/O required to support Autocommit mode, a performancepenalty is paid for up to three network requests for every statement issued by an application.

Although using transactions can help application performance, do not take this tip too far. Leaving transactionsactive can reduce throughput by holding locks on rows for longer than necessary, preventing other users fromaccessing the rows. Commit transactions in intervals that allow maximum concurrency.

Choosing the Right Transaction ModelMany systems support distributed transactions; that is, transactions that span multiple connections. Distributedtransactions are at least four times slower than normal transactions due to the logging and network round tripsnecessary to communicate between all the components involved in the distributed transaction (the JDBC driver,transaction monitor, and DBMS). Unless distributed transactions are required, avoid using them. Instead, uselocal transactions when possible. Many Java application servers provide a default transaction behavior thatuses distributed transactions.

For the best system performance, design the application to run using a single Connection object.

Using updateXXX MethodsAlthough programmatic updates do not apply to all types of applications, developers should attempt to useprogrammatic updates and deletes. Using the updateXXX methods of the ResultSet object allows the developerto update data without building a complex SQL statement. Instead, the developer simply supplies the columnin the result set that is to be updated and the data that is to be changed. Then, before moving the cursor fromthe row in the result set, the updateRow() method must be called to update the database as well.

In the following code fragment, the value of the Age column of the ResultSet object rs is returned using thegetInt() method, and the updateInt() method is used to update the column with an int value of 25. TheupdateRow() method is called to update the row in the database with the modified value.

int n = rs.getInt("Age");// n contains value of Age column in the resultset rs...rs.updateInt("Age", 25);rs.updateRow();

In addition to making the application more easily maintainable, programmatic updates usually result in improvedperformance. Because the database server is already positioned on the row for the Select statement in process,performance-expensive operations to locate the row that needs to be changed are unnecessary. If the rowmust be located, the server usually has an internal pointer to the row available (for example, ROWID).

Using getBestRowIdentifierUse getBestRowIdentifier() to determine the optimal set of columns to use in the Where clause for updatingdata. Pseudo-columns often provide the fastest access to the data, and these columns can only be determinedby using getBestRowIdentifier().


Managing Connections and Updates

Some applications cannot be designed to take advantage of positioned updates and deletes. Some applicationsformulate the Where clause by calling getPrimaryKeys() to use all searchable result columns or by callinggetIndexInfo() to find columns that may be part of a unique index. These methods usually work, but can resultin fairly complex queries.

Consider the following example:

ResultSet WSrs = WSs.executeQuery("SELECT first_name, last_name, ssn, address, city, state, zip FROM emp");

// fetchdata...WSs.executeQuery (

"UPDATE emp SET address = ?WHERE first_name = ? AND last_name = ? AND ssn = ?AND address = ? AND city = ? AND state = ? AND zip = ?");

// fairly complex query

Applications should call getBestRowIdentifier() to return the optimal set of columns (possibly a pseudo-column)that identifies a specific record. Many databases support special columns that are not explicitly defined by theuser in the table definition, but are "hidden" columns of every table (for example, ROWID and TID). Thesepseudo-columns generally provide the fastest access to the data because they typically are pointers to theexact location of the record. Because pseudo-columns are not part of the explicit table definition, they are notreturned from getColumns(). To determine if pseudo-columns exist, call getBestRowIdentifier().

Consider the previous example again:

...ResultSet WSrowid = getBestRowIdentifier()

(... "emp", ...);...WSs.executeUpdate("UPDATE EMP SET ADDRESS = ? WHERE ROWID = ?");// fastest access to the data!

If your data source does not contain special pseudo-columns, the result set of getBestRowIdentifier() consistsof the columns of the most optimal unique index on the specified table (if a unique index exists). Therefore,your application does not need to call getIndexInfo() to find the smallest unique index.



Glossary

authenticationThe process of identifying a user, typically based on a user ID and password. Authentication ensures that theuser is who they claim to be. See also client authentication, NTLM authentication, OS authentication, and userID/password authentication.

bulk loadThe process of sending large numbers of rows of data to the database in a continuous stream instead of innumerous smaller database protocol packets. This process also is referred to as bulk copy.

client authenticationClient authentication uses the user ID and password of the user logged onto the system on which the driver isrunning to authenticate the user to the database. The database server depends on the client to authenticatethe user and does not provide additional authentication. See also authentication.

client load balancingClient load balancing distributes new connections in a computing environment so that no one server isoverwhelmed with connection requests.

connection poolingConnection pooling allows you to reuse connections rather than create a new one every time a driver needsto establish a connection to the database. Connection pooling manages connection sharing across differentuser requests to maintain performance and reduce the number of new connections that must be created. Seealso DataDirect Connection Pool Manager.

connection retryConnection retry defines the number of times the driver attempts to connect to the primary and, if configured,alternate database servers after an initial unsuccessful connection attempt. Connection retry can be an importantstrategy for system recovery.

connection URLA connection URL is a string passed by an application to the Driver Manager that contains information requiredto establish a connection. See also Driver Manager.

DataDirect Connection Pool ManagerThe DataDirect Connection Pool Manager is a component shipped with Progress DataDirect drivers that allowsapplications to use connection pooling.


DataDirect DB2 Package ManagerA Java graphical tool shipped with DataDirect Connect Series for JDBC for creating, dropping, and replacingDB2 packages for DB2.

DataDirect SpyDataDirect Spy allows you to track and log detailed information about JDBC calls made by the drivers at runtime.This functionality is built into the drivers.

DataDirect TestDataDirect Test is a menu-driven component shipped with Progress DataDirect drivers that helps you debugyour applications and learn how to use the drivers. DataDirect Test displays the results of all JDBC functioncalls in one window, while displaying fully commented, Java JDBC code in an alternate window.

data sourceA data source is a DataSource object that provides the connection information needed to connect to a database.The main advantage of using a data source is that it works with the Java Naming Directory Interface (JNDI)naming service, and it is created and managed apart from the applications that use it.

Driver ManagerThe main purpose of the Driver Manager is to load drivers for the application. The Driver Manager also processesJDBC initialization calls and maps data sources to a specific driver.

failoverFailover allows an application to connect to an alternate, or backup, database server. Progress DataDirectdrivers provide different levels of failover: connection failover, extended connection failover, and select failover.

indexA database structure used to improve the performance of database activity. A database table can have one ormore indexes associated with it.

isolation levelAn isolation level represents a particular locking strategy employed in the database system to improve dataconsistency. The higher the isolation level number, the more complex the locking strategy behind it. The isolationlevel provided by the database determines how a transaction handles data consistency.

The American National Standards Institute (ANSI) defines four isolation levels:

• Read uncommitted (0)

• Read committed (1)

• Repeatable read (2)

• Serializable (3)

J2EEJ2EE (Java 2 Platform, Enterprise Edition) technology and its component-based model simplify enterprisedevelopment and deployment. The J2EE platform manages the infrastructure and supports the Web servicesto enable development of secure, robust and interoperable business applications. Also known as Java EE(Java Platform, Enterprise Edition).

JDBC data sourceSee data source.

JNDIThe Java Naming and Directory Interface (JNDI) is a standard extension to the Java platform, providing Javatechnology-enabled applications with a unified interface to multiple naming and directory services in theenterprise. As part of the Java Enterprise API set, JNDI enables seamless connectivity to heterogeneousenterprise naming and directory services. Developers can now build powerful and portable directory-enabledapplications using this industry standard.


Glossary

JTAJTA (Java Transaction API) specifies standard Java interfaces between a transaction manager and the partiesinvolved in a distributed transaction system: the resource manager, the application server, and the transactionalapplications.

KerberosKerberos is an OS authentication protocol that provides authentication using secret key cryptography. Seealso authentication and OS authentication.

load balancingSee client load balancing.

locking levelLocking is a database operation that restricts a user from accessing a table or record. Locking is used insituations where more than one user might try to use the same table at the same time. By locking the table orrecord, the system ensures that only one user at a time can affect the data.

NTLM authenticationNTLM (NT LAN Manager) is an authentication protocol that provides security for connections between Windowsclients and servers. See also authentication and OS authentication.

OS authenticationOS authentication can take advantage of the user name and password maintained by the operating system toauthenticate users to the database or use another set of user credentials specified by the application. Byallowing the database to share the user name and password used for the operating system, users with a validoperating system account can log into the database without supplying a user name and password. See alsoauthentication, Kerberos authentication, and NTLM authentication.

reauthenticationThe process of switching the user associated with a connection to another user to help minimize the numberof connections required in a connection pool.

resource adapterA resource adapter is a system-level software driver used by an application server to connect to an EnterpriseInformation Service (EIS). The resource adapter communicates with the server to provide the underlyingtransaction, security, and connection pooling mechanisms.

Secure Socket LayerSecure Socket Layer (SSL) is an industry-standard protocol for sending encrypted data over databaseconnections. SSL secures the integrity of your data by encrypting information and providing SSL client/SSLserver authentication. See also SSL client/server authentication.

SSL client and server authenticationSSL (Secure Socket Layer) works by allowing the client and server to send each other encrypted data thatonly they can decrypt. SSL negotiates the terms of the encryption in a sequence of events known as the SSLhandshake. The handshake involves the following types of authentication:

• SSL server authentication requires the server to authenticate itself to the client.

• SSL client authentication is optional and requires the client to authenticate itself to the server after the serverhas authenticated itself to the client.

See also Secure Socket Layer.

UnicodeA standard for representing characters as integers. Unlike ASCII, which uses 7 bits for each character, Unicodeuses 16 bits, which means that it can represent more than 65,000 unique characters. This is necessary formany languages, such as Greek, Chinese, and Japanese.

user ID and password authenticationUser ID and password authentication authenticates the user to the database using a database user name andpassword. See also authentication.


Glossary

Index

Aaccessing the DataDirect Statement Pool Monitor 82AccountingInfo 128addresses

IPv4 60applet

Java Platform, permissions for 36application

connecting with driver 37troubleshooting 155

ApplicationName 129arithmetic operators 169Array interface, methods 180ASCII

encoding 63authentication

client 57server (SSL) 56SSL 57user ID/password 55

auto generated keysexample, retrieving 259performance optimization 259

Autocommit mode 260

Bbatch inserts and updates

batch execution on a prepared statement withDataDirect Test 100using instead of prepared statements 257

Blobusing to return long data 63

Blob interface, methods 180Blobs

retrieving with DataDirect Test 115

CCallableStatement interface, methods 181certificate

validation 153Certificate Authority (CA)

SSL 56certificate validation 153changing the maximum pool size behavior 71character operators 170classes

data source and driver 13, 23

CLASSPATHsetting 24

clearing statements in the statement pool 84client authentication

SSL 57client information

connection properties 50how databases store 58maximum length of a value, determining 60metadata, returning 60overview 58returning 59storing 58

ClientHostName 129ClientUser 130Clob

using to return long data 63Clob interface, methods 193Clobs

retrieving with DataDirect Test 115closing the connection pool 73column name qualification 166committing transactions 260concatenation operator 170connecting

connection URL 14, 25, 38DataDirect Test

using a data source 89using driver/database selection 90

using connection pool 71using DataDirect Test 89with data sources 28–29, 41–42with JDBC Driver Manager 24

connectiontesting 25, 30, 38, 43

Connection interface, methods 194connection management 260Connection object

managing connections 260transaction model 261

Connection Pool Managerversion information 73

connection poolingconfiguring 70connection pool

closing 73connecting using 71

DataDirect Connection Pool Manager trace file 159javax.sql.ConnectionPoolDataSource interface 29, 42performance optimization 260


Index

connection pooling (continued)using 65

connection propertiesAccouningInfo 128additional 52alphabetical listing 125ApplicationName 129ClientHostName 129ClientUser 130ConnectionRetryCount 131ConnectionRetryDelay 132ConvertNull 132CryptoProtocolVersion 133data encryption 47, 50data type handling 49DatabaseName 134DefaultOrderByLimit 135EncryptionMethod 135HostNameInCertificate 137ImportStatementPool 138InitializationString 138InsensitiveResultSetBufferSize 139JavaDoubleToString 140KeyPassword 141KeyStore 141KeyStorePassword 142LoginTimeout 143MaxStatements 144overview 46Password 145performance considerations 54PortNumber 145RegisterStatementPoolMonitorMBean 146RemoveColumnQualifiers 147required 47ServerName 148SpyAttributes 120, 122, 148statement pooling 51StringDescribeType 149TransactionMode 150TrustStore 151TrustStorePassword 151UseCurrentSchema 152User 153ValidateServerCertificate 153

connection URLoverview 14, 25, 38

ConnectionEventListener interface, methods 199ConnectionPoolDataSource interface, methods 199ConnectionPoolMonitor

interface 78ConnectionRetryCount 131ConnectionRetryDelay 132constants 169converting

null values 132

ConvertNull 132copyrightCryptoProtocolVersion 133cursors

choosing 258

Ddata encryption

configuring 55SSL 47, 55

data source class 13, 23data sources

calling in an application 30, 43connecting with 28, 37, 41connection pooling 65creating 29, 42, 68–69implementing 29, 42specifying SpyAttributes 120

data type handlingconnection properties 49

data types 15data types, choosing for performance 255database

table characteristics, using dummy query todetermine 253

database metadataretrieving with DataDirect Test 96

DatabaseMetaData interface 236DatabaseMetaData interface, methods 200DatabaseName 134DataDirect Connection Pool Manager

trace file 158–159tracing, enabling 73, 158version information 73

DataDirect Spyattributes 122enabling 120logging 155–156overview 120setEnableLogging() method 156SpyAttributes connection property 148troubleshooting 155

DataDirect Spy, enabling 121DataDirect Statement Pool Monitor

accessingusing the JMX API 82

classes and interfaces 85DataDirect Test

batch execution 100configuring 88connecting with 89database metadata, retrieving 96deleting rows 106executing

Select statement 92


Index

DataDirect Test (continued)executing prepared statement 93inserting rows 106, 109LOB support 115ParameterMetaData, returning 102result set, scrolling through 98savepoints, establishing 103starting 88testing a connection 25, 30, 38, 43tutorial 87updatable result sets 106updating rows 106, 112using 87

DataSourceconnection pooling 67–69

DataSource interface, methods 208date

escape sequence 176date/time functions 171DDBulkLoad interface, methods 237DefaultOrderByLimit 135defaults

for connection properties 125Delete statements 61deleting rows

with DataDirect Test 106driver

overview 11driver class 13, 23Driver interface, methods 209Driver Manager

connecting with 37Driver Version string

format 14DriverManager

specifying SpyAttributes 120dummy query, using to determine table characteristics253

Eencryption

configuring 55SSL 55

EncryptionMethod 135error handling

format 63escape sequences

date, time, and timestamp 176LIKE escape character for wildcards 178outer join 177procedure call 178

export file for statement poolexample 163generating 84

ExtConnection interface, methods 244

ExtDatabaseMetaData interface, methods 249extensions package

datadirect.jdbc.extensions package 235ExtLogControl class, methods 249ExtLogControl interface 156ExtStatementPoolMonitor class 85ExtStatementPoolMonitorMBean interface 85

Fforward-only cursor

performance implications 258freezing the statement pool 84From clause 166functional limitations 65functions 171

GgetBestRowIdentifier() method 261getBlob() method 254getClob() method 254getObject() method 258getTypeInfo() method 16

HHaving clause 167help, online 20HostNameInCertificate 137

Iimporting statements into the statement pool 83ImportStatementPool 138initial pool size 70InitializationString 138InputStream object, DataDirect Spy 121insensitive cursors

performance implications 258temporary files 37

InsensitiveResultSetBufferSize 139Insert statements 61inserting rows

with DataDirect Test 109Interfaces, JDBC 179IP addresses

IPv4 support 60isolation levels 62

JJava Naming Directory Interface (JNDI)

connecting with 37data source connection 24


Index

Java Naming Directory Interface (JNDI) (continued)data sources 28, 41initializing environment 30, 43

Java Platformaccessing temporary files 37permissions 36–37Security Manager 36

Java properties, accessing 37Java SE

requirements 12JavaDoubleToString 140JDBC

functionality supported 179interfaces 179JVM compatibility 179methods supported 179SQL escape sequences 175versions supported 179

JDBC data source, specifying SpyAttributes 121JDBC data sources

connecting with 28, 41JDBC Driver Manager

connecting with 24, 37specifying SpyAttribute 120

JDBC extensionsintroduction 235wrapper methods to access 236

JNDI Provider for LDAPsaving JDBC data source 29, 42

JSR 114 Rowsetsrequirements 12

JSR 114, Rowsets 64JTA support

transactionmodel, choosing for performance 261

JTA transaction supportmanaging commits 260

JVMJDBC compatibility 179properties file 164

KKeyPassword 141keyset-driven cursors, performance implications 258keystore

SSL 57KeyStore 141KeyStorePassword 142

LLarge Object (LOB) support 63LDAP Directory

saving JDBC data source 29, 42

LIKE escape character for wildcards escape sequence178limitations on functionality 65literals

arguments, using parameter markers 256date 176time 176timestamp 176

LOBs supportexecuting a query with DataDirect Test 115

locking levels 62logging

DataDirect Spy 156JVM properties file 164with DataDirect Spy 120

logical operators 170LoginTimeout 143long data

using Blobs and Clobs to return 63long data, retrieving and performance 254

Mmaximum idle time 70maximum pool size 70maximum pool size behavior 71MaxStatements 144MBean name, registering 82memory usage, tuning

InsensitiveResultSetBufferSize 139metadata

JDBC extensions 236metadata about client information 60metadata methods, minimizing use of 252methods

Array interface 180Blob interface 180CallableStatement interface 181Clob interface 193Connection interface 194ConnectionEventListener interface 199ConnectionPoolDataSource interface 199DatabaseMetaData interface 200DataSource interface 208DDBulkLoad interface 237Driver interface 209ExtConnection interface 244ExtDatabaseMetaData interface 249ExtLogControl class 249ParameterMetaData interface 209PooledConnection interface 210PreparedStatement interface 211Ref interface 216ResultSet interface 216ResultSetMetaData interface 227RowSet interface 228


Index

methods (continued)SavePoint interface 228Statement interface 228StatementEventListener interface 232Struct interface 232XAConnection interface 233XADataSource interface 233XAResource interface 233

minimum pool size 70multilingual applications

development 63

Nnull values

handling for data conversions 132numeric functions 171

Oobject

Connectionmanaging connections 260transaction model 261

Long (DB2) 219PooledConnectionDataSource

connecting with 71PreparedStatement

using Statement object instead of 256ResultSet

database metadata 252generating 252updating data 261

Statementusing instead of PreparedStatement object 256using multiple 260

using addBatch() instead of PreparedStatement 257operators

arithmetic 169concatenation 170logical 170relational 170

Order By clause 167outer join escape sequences 177overview 11

Pparameter markers, using as arguments to storedprocedures 256parameter metadata

returning with DataDirect Test 102ParameterMetaData interface, methods 209Password 145performance considerations 54

performance optimizationauto generated keys, retrieving 259batches, using instead of prepared statements 257commits, managing 260connection

management 260pooling 260

database metadata methods 252designing JDBC applications 259get methods, using effectively 258getBestRowIdentifier() 261result sets, retrieving 255retrieving long data 254scrollable cursors 255selecting JDBC objects and methods 256transaction model, choosing 261update methods of the ResultSet object 261updating data 261

permissionsJava Platform 36Java properties 37temporary files 37

PooledConnection interface, methods 210PooledConnectionDataSource

interface 74PooledConnectionDataSource object

connecting with 71creating 67, 69, 74

PooledConnectionDataSourceFactoryinterface 74

poolEntries() method 79PortNumber 145prepared statement

pooling 144prepared statement pooling

registering JMX MBean 146prepared statement pooling, performance optimization260prepared statement, executing with DataDirect Test 93prepared statements

using batches instead of 257PreparedStatement interface, methods 211PreparedStatement object

performanceimplications of using Statement object instead256of prepared statement pool 260

prepared statement pooling 260using Statement object instead of 256

procedure call escape sequence 178

RReader object, DataDirect Spy 121Ref interface, methods 216


Index

Reference objectcreating PooledConnectionDataSource object 74

registering MBean name 82RegisterStatementPoolMonitorMBean 146relational operators 170RemoveColumnQualifiers 147requirements

Java SE 12JSR 114 Rowsets 12SSL 12

result setsdeleting rows with DataDirect Test 106inserting rows with DataDirect Test 106scrolling through a result set with DataDirect Test 98updating rows with DataDirect Test 106

result sets, scrollableperformance optimization 255

ResultSet interface, methods 216ResultSet metadata 62ResultSet object

database metadata 252generating 252updating data 261

ResultSetMetaData interface, methods 227returning client information 59RowSet interface, methods 228Rowsets 64

SSavePoint interface, methods 228savepoints

establishing with DataDirect Test 103scalar functions 176scroll-insensitive result sets 64scrollable cursors 64search patterns, avoiding 253security

authentication 55SSL 47

Security ManagerJava Platform 36

Select statementexecuting with DataDirect Test 92

sensitive cursorsperformance implications 258

server authenticationconfiguring 56

server-side RPCs 256ServerName 148session timeouts 64set functions 171setEnableLogging() 156SpyAttributes 120, 122, 148SQL escape sequences

date, time, and timestamp 176

SQL escape sequences (continued)LIKE escape character for wildcards 178outer join 177procedure call 178scalar functions 176

SQL expressions 169SQL statement support 165SQLExceptions

reporting 63SSL

Certificate Authority (CA) 56client authentication 55, 57configuring 55data encryption properties 47keystore 57requirements 12server authentication 55–56truststore 56

Statement interface, methods 228Statement object

Connection object association 260using instead of PreparedStatement object 256using multiple 260when to use 256

statement poolclearing statements 84export file, generating 84freezing and unfreezing 84importing statements to 83

statement pool export fileexample 163generating 163

Statement Pool Monitoraccessing with DataDirect-specific methods 79classes and interfaces 85poolEntries() method 79

statement poolingconnection properties 51statement pool export file 163troubleshooting problems 162

StatementEventListener interface, methods 232stored procedures

escape sequences 178parameter markers as arguments, using 256

storing client information 58string functions 171StringDescribeType 149Struct interface, methods 232subqueries 168support

online help 20technical support 20

syntaxconnection URL 14, 25, 38

system functions 171


Index

TTechnical Support 20testing a connection

instructions 25, 30, 38, 43The Impala Wire Protocol driver

Group By clause 167time literal

escape sequence 176timeout, connection 143timeouts 64timestamp literal

escape sequence 176tracing, enabling for Pool Manager 73TransactionMode 62, 150transactions , See JTA supporttroubleshooting

connection pooling problems 158statement pooling problems 162your application 155

truststoreSSL 56

TrustStore 151TrustStorePassword 151

Uunderstanding the maximum pool size 71unfreezing the statement pool 84Unicode support 63UNIX CLASSPATH

setting 24updatable result sets 64updatable result sets, DataDirect Test 106

Update statements 61updating rows

with DataDirect Test 112URL

connecting with 37UseCurrentSchema 152User 153user ID/password

authentication 55using

JMX API 82UTF-16

conversion 63encoding 63

VValidateServerCertificate 153Version string information

format 14

WWindows CLASSPATH

setting 24Wrapper methods

to access JDBC Extensions 236

XXAConnection interface, methods 233XADataSource interface, methods 233XAResource interface, methods 233


Index


Index

progress datadirect connectxe for jdbc for impala · 2018-02-28 · what'snewinthisrelease?...

Documents