progress datadirect for jdbc forapache cassandra · 2016-01-10 li kumar jones home: 2855551122...

Progress® DataDirect® forJDBC™ for ApacheCassandra™

User's Guide

6.0.0 Release

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/03/28

3Progress® DataDirect® for JDBC™ for Apache Cassandra™: User's Guide: Version 6.0.0

Progress® DataDirect® for JDBC™ for Apache Cassandra™: User's Guide: Version 6.0.04

Copyright

Table of Contents

Chapter 1: Welcome to the Progress DataDirect for JDBC for ApacheCassandra Driver......................................................................................11

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

Collection Types.........................................................................................................................15Tuple and User-Defined Types...................................................................................................18Nested Complex Types..............................................................................................................21

Data Types............................................................................................................................................22getTypeInfo()..............................................................................................................................24

Contacting Technical Support...............................................................................................................32

Chapter 2: Getting started...........................................................................35Driver and Data Source Classes...........................................................................................................35Connecting Using the DriverManager...................................................................................................36

Setting the Classpath ................................................................................................................36Passing the Connection URL.....................................................................................................37Testing the Connection...............................................................................................................37

Connecting Using Data Sources...........................................................................................................40How Data Sources Are Implemented.........................................................................................41Creating Data Sources...............................................................................................................41Calling a Data Source in an Application.....................................................................................41

Chapter 3: Using the Driver.........................................................................43Connecting from an Application............................................................................................................44

Driver and Data Source Classes................................................................................................44Connecting Using the DriverManager........................................................................................44Connecting Using Data Sources................................................................................................48

Using Connection Properties................................................................................................................50Required Properties...................................................................................................................50Mapping Properties....................................................................................................................51Authentication Properties...........................................................................................................51Data Encryption Properties........................................................................................................52Statement Pooling Properties....................................................................................................53


Contents

Additional Properties..................................................................................................................54Performance Considerations................................................................................................................55Authentication.......................................................................................................................................56

Configuring User ID/Password Authentication...........................................................................56Configuring the Driver for Kerberos Authentication....................................................................57

Data Encryption....................................................................................................................................64Configuring SSL Encryption.......................................................................................................64Configuring SSL Server Authentication......................................................................................65Configuring SSL Client Authentication.......................................................................................66

Identifiers...............................................................................................................................................67IP Addresses.........................................................................................................................................67Parameter Metadata Support................................................................................................................68

Insert and Update Statements...................................................................................................68Select Statements......................................................................................................................68

Isolation Levels.....................................................................................................................................69Unicode.................................................................................................................................................69Error Handling.......................................................................................................................................69Large Object (LOB) Support.................................................................................................................70Rowset Support....................................................................................................................................70Executing CQL......................................................................................................................................71Connection Pool Manager....................................................................................................................71

How Connection Pooling Works.................................................................................................71Implementing DataDirect Connection Pooling...........................................................................73Configuring the Connection Pool...............................................................................................76Connecting Using a Connection Pool........................................................................................77Closing the Connection Pool......................................................................................................78Checking the Pool Manager Version..........................................................................................79Enabling Pool Manager Tracing.................................................................................................79Connection Pool Manager Interfaces.........................................................................................79

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

DataDirect Test......................................................................................................................................92DataDirect Test Tutorial..............................................................................................................93

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

Chapter 4: Connection Property Descriptions........................................129AuthenticationMethod.........................................................................................................................132


Contents

CreateMap..........................................................................................................................................133EncryptionMethod...............................................................................................................................134FetchSize............................................................................................................................................135HostNameInCertificate........................................................................................................................136ImportStatementPool..........................................................................................................................137InitializationString................................................................................................................................138InsensitiveResultSetBufferSize...........................................................................................................139KeyPassword......................................................................................................................................140KeyspaceName...................................................................................................................................140KeyStore.............................................................................................................................................141KeyStorePassword.............................................................................................................................142LogConfigFile......................................................................................................................................143LoginConfigName...............................................................................................................................143LoginTimeout......................................................................................................................................144MaxPooledStatements........................................................................................................................145NativeFetchSize..................................................................................................................................146Password............................................................................................................................................147PortNumber.........................................................................................................................................148ReadConsistency................................................................................................................................149ReadOnly............................................................................................................................................150RegisterStatementPoolMonitorMBean................................................................................................150ResultMemorySize..............................................................................................................................151SchemaMap........................................................................................................................................153ServerName........................................................................................................................................154ServicePrincipalName.........................................................................................................................155SpyAttributes.......................................................................................................................................156TransactionMode................................................................................................................................157TrustStore...........................................................................................................................................158TrustStorePassword............................................................................................................................159User.....................................................................................................................................................159ValidateServerCertificate.....................................................................................................................160WriteConsistency................................................................................................................................161

Chapter 5: Troubleshooting......................................................................163Troubleshooting your application........................................................................................................163

Turning On and Off DataDirect Spy Logging............................................................................164DataDirect Spy Log Example...................................................................................................164

Troubleshooting Connection Pooling..................................................................................................166Enabling Tracing with the setTracing Method..........................................................................166Pool Manager Trace File Example...........................................................................................166

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

Troubleshooting Out-of-Memory Errors..............................................................................................171


Contents

Troubleshooting Operation Timeouts..................................................................................................171Using Java logging..............................................................................................................................172

Logging Components...............................................................................................................173Configuring Logging.................................................................................................................174

Contacting Technical Support.............................................................................................................175

Chapter 6: Supported SQL Functionality.................................................177Data Definition Language (DDL).........................................................................................................177Delete..................................................................................................................................................178Insert...................................................................................................................................................179Refresh Map (EXT).............................................................................................................................180Select..................................................................................................................................................180

Select Clause...........................................................................................................................181Update.................................................................................................................................................191SQL Expressions................................................................................................................................193

Column Names........................................................................................................................193Literals......................................................................................................................................193Operators.................................................................................................................................196Functions..................................................................................................................................199Conditions................................................................................................................................199

Subqueries..........................................................................................................................................200IN Predicate.............................................................................................................................201EXISTS Predicate....................................................................................................................201UNIQUE Predicate...................................................................................................................201Correlated Subqueries.............................................................................................................202

Chapter 7: SQL Escape Sequences for JDBC.........................................205Date, time, and timestamp escape sequences...................................................................................206Scalar Functions.................................................................................................................................206Outer Join Escape Sequences...........................................................................................................207LIKE escape character sequence for wildcards..................................................................................208Native and Refresh Escape Sequences.............................................................................................208

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

Array.........................................................................................................................................212Blob..........................................................................................................................................212CallableStatement....................................................................................................................213Clob..........................................................................................................................................225Connection...............................................................................................................................226ConnectionEventListener.........................................................................................................231ConnectionPoolDataSource.....................................................................................................231


Contents

DatabaseMetaData..................................................................................................................232DataSource..............................................................................................................................240Driver........................................................................................................................................241ParameterMetaData.................................................................................................................241PooledConnection....................................................................................................................242PreparedStatement..................................................................................................................243Ref............................................................................................................................................248ResultSet..................................................................................................................................248ResultSetMetaData..................................................................................................................259RowSet.....................................................................................................................................260SavePoint.................................................................................................................................260Statement.................................................................................................................................260StatementEventListener...........................................................................................................264Struct........................................................................................................................................264XAConnection..........................................................................................................................265XADataSource.........................................................................................................................265XAResource.............................................................................................................................265

Chapter 9: JDBC Extensions.....................................................................267Using JDBC Wrapper Methods to Access JDBC Extensions.............................................................268DatabaseMetaData interface..............................................................................................................268DDBulkLoad Interface.........................................................................................................................269ExtConnection Interface......................................................................................................................276ExtDatabaseMetaData Interface.........................................................................................................281ExtLogControl class............................................................................................................................281

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

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

Returning Data....................................................................................................................................286Returning Long Data................................................................................................................286Reducing the Size of Returned Data........................................................................................287Choosing the Right Data Type.................................................................................................287Retrieving Result Sets..............................................................................................................287

Selecting JDBC Objects and Methods ...............................................................................................288Using Parameter Markers as Arguments to Stored Procedures..............................................288Using the Statement Object Instead of the PreparedStatement Object...................................288Using Batches Instead of Prepared Statements......................................................................289Choosing the Right Cursor.......................................................................................................290Using get Methods Effectively..................................................................................................290


Contents

Retrieving Auto Generated Keys..............................................................................................291Managing Connections and Updates..................................................................................................291

Managing Connections............................................................................................................292Managing Commits in Transactions.........................................................................................292Choosing the Right Transaction Model....................................................................................293Using updateXXX Methods......................................................................................................293Using getBestRowIdentifier......................................................................................................293

Glossary.......................................................................................................295

Index.............................................................................................................299


Contents

1Welcome to the Progress DataDirect forJDBC for Apache Cassandra Driver

The Progress® DataDirect® for JDBC™ for Apache Cassandra™ driver supports SQL read-write access to DataStaxEnterprise 4.6 or higher and Apache Cassandra 2.0 or higher. To support SQL access to Cassandra, the drivercreates a relational map of native Cassandra data and translates SQL statements to CQL. Cassandra complexdata types Map, List, Set, Tuple, and user-defined types are supported alongside primitive CQL types. Thedriver optimizes performance when executing joins by leveraging data relationships among Cassandra objectsto minimize the amount of data that needs to be fetched over the network. Relationships among objects canbe reported with the metadata methods getTables(), getColumns(), getTypeInfo(), getPrimaryKeys(),getExportedKeys(), and getBestRowIdentifier().

For details, see the following topics:

• What's New in this Release?

• Requirements

• Driver and Data Source Classes

• Version String Information

• Connection Properties

• Complex Type Normalization

• Data Types

• Contacting Technical Support


What's New in this Release?Changes since 6.0.0 Release• Driver Enhancements

• The driver has been enhanced to support all the data consistency levels for read and write operationsthat are supported by Apache Cassandra data stores. Data consistency levels are configured using theReadConsistency and WriteConsistency connection properties. For additional information, seeReadConsistency on page 149 and WriteConsistency on page 161.

• The driver has been enhanced to support SSL, incorporating the addition of eight new connectionproperties. See Data Encryption on page 64 and Data Encryption Properties on page 52 for details.

• The driver has been enhanced to support Kerberos authentication. See Authentication on page 56 andAuthentication Properties on page 51 for details.

• The driver has been enhanced to support Cassandra's tunable consistency functionality with theReadConsistency and WriteConsistency connection properties. See ReadConsistency on page 149 andWriteConsistency on page 161 for details.

• The driver has been enhanced to improve the handling of large result sets and reduce the likelihood ofout-of-memory errors through the introduction of the FetchSize, NativeFetchSize, and ResultMemorySizeconnection properties. See FetchSize on page 135, NativeFetchSize on page 146, and WriteConsistencyon page 161 for details.

• Changed Behavior

• The SchemaDefinition connection property has been replaced with the SchemaMap connection property.See SchemaMap on page 153 for details.

Highlights of the 6.0.0 Release• Supports SQL read-write access to DataStax Enterprise 4.6 or higher and Apache Cassandra 2.0 or higher.

See Supported SQL Functionality on page 177 for details.

• Supports JDBC core functions. See JDBC support on page 211 for details.

• Supports user id/password authentication. See Authentication on page 56 for details.

• Supports Cassandra data types, including the complex types Tuple, user-defined types, Map, List and Set.See Data Types on page 22 for details.

• Generates a relational view of Cassandra data. Tuple and user-defined types are flattened into a relationalparent table, while collection types are mapped as relational child tables. See Complex Type Normalizationon page 15 for details.

• Supports Native and Refresh escape sequences to embed CQL commands in SQL-92 statements. SeeNative and Refresh Escape Sequences on page 208 for details.

• Supports Cassandra's tunable consistency functionality with ReadConsistency on page 149 andWriteConsistency on page 161 connection properties.

• Supports the handling of large result sets with FetchSize on page 135, NativeFetchSize on page 146, andResultMemorySize on page 151 connection properties.

• Includes the TransactionMode on page 157 connection property which allows you to configure the driver toreport that it supports transactions, even though Cassandra does not support transactions. This providesa workaround for applications that do not operate with a driver that reports transactions are not supported.


Chapter 1: Welcome to the Progress DataDirect for JDBC for Apache Cassandra Driver

• Supports Binary Large Objects (BLOBs). See Large Object (LOB) Support on page 70 for details.

• Supports connection pooling. See Connection Pool Manager on page 71 for details.

• Supports statement pooling. See Statement Pool Monitor on page 84 for details.

• Includes the LoginTimeout on page 144 connection property which allows you to specify how long the driverwaits for a connection to be established before timing out the connection request.

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

Table 1: Product Requirements

Product RequirementsFor Applications Using...

Java SE 6 or higherJDBC 4.0 API


Java SE 6 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 theinternational version of Java SE.

Driver and Data Source ClassesThe driver class is:

com.ddtek.jdbc.cassandra.CassandraDriver

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.


Requirements

Table 2: Choosing a Data Source Class

Data Source ClassJVM VersionIf your applicationrequires...

com.ddtek.jdbcx.cassandra.CassandraDataSource40Java SE 6 orhigher

JDBC 4.0 functionality andhigher

com.ddtek.jdbcx.cassandra.CassandraDataSourceJava SE 6 orhigher

JDBC 3.x functionality andearlier specifications

See Connecting Using Data Sources on page 40 for information about Progress DataDirect data sources.

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

M.m.s.bbbbbb(CXXXX.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.

XXXX is the cloud adapter build number.

YYYYYY is the framework build number.

ZZZZZZ is the utl build number.

For example:

6.0.0.000002(C0003.F000001.U000002)|____| |___| |_____| |_____|Driver Cloud 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 on page 50 and Connection Property Descriptions on page 129 for moreinformation.



Complex Type NormalizationTo support SQL access to Apache Cassandra, the driver maps the Cassandra data model to a relationalschema. This process involves the normalization of complex types. You may need to be familiar with thenormalization of complex types to formulate SQL queries correctly. The driver handles the normalization ofcomplex types in the following manner:

• If collection types (Map, List, and Set) are discovered, the driver normalizes the Cassandra table into a setof parent-child tables. Primitive types are mapped to a parent table, while each collection type is mappedto a child table that has a foreign key relationship to the parent table.

• Non-nested Tuple and user-defined types (also referred to as Usertype) are flattened into a parent tablealongside primitive types.

• Any nested complex types (Tuple, user-defined types, Map, List, and Set) are exposed as JSON-stylestrings in the parent table.

The normalization of complex types is described in greater detail in the following topics.

Collection TypesCassandra collection types include the Map, List, and Set types. If collection types are discovered, the drivernormalizes the native data into a set of parent-child tables. Primitive types are normalized in a parent table,while each collection type is normalized in a child table that has a foreign key relationship to the parent table.Take for example the following Cassandra table:

CREATE TABLE employee (empid int PRIMARY KEY,phone map<varchar, varint>,client list<varchar>,review set<date>);

The following employee table is a tabular representation of the native Cassandra table with data included. Inthis example, four distinct relational tables are created. A parent table is created based on the empid column,and a child table is created for each of the three collection types (Map, List, and Set).

Table 3: employee (native)

reviewclientphoneempid

(primary key)

set<date>list<varchar>map<varchar, varint>int

2013-12-07

2015-01-22

2016-01-10

Li

Kumar

Jones

home: 2855551122

mobile: 2855552347

office: 2855555566

spouse: 2855556782

103

2015-01-22

2016-01-12

Yanev

Bishop

Bogdanov

home: 2855555678

mobile: 2855553335

office: 2855555462

105


Complex Type Normalization

The Parent TableThe parent table is comprised of the primitive integer type column empid and takes its name from the nativetable. A SQL statement would identify the column as employee.empid.

Table 4: employee (relational parent)

empid

(primary key)

int

103

105

A SQL insert on the employee parent table would take the form:

INSERT INTO employee (empid) VALUES (107)

The Map Child TableThe Map collection is normalized into a three column child table called employee_phone. The name of thetable is formulated by concatenating the name of the native table and the name of the Map column. A foreignkey relationship to the parent table is maintained via the employee_empid column, and the Map's key valuepairs are resolved into separate keycol and valuecol columns. In a SQL statement, these columns wouldbe identified as the employee_phone.employee_empid, employee_phone.keycol, andemployee_phone.valuecol, respectively.

Table 5: employee_phone (relational child of the map column)

valuecolkeycolemployee_empid

(foreign key)

varintvarcharint

2855551122home103

2855552347mobile103

2855555566office103

2855556782spouse103

2855555678home105

2855553335mobile105

2855555462office105



A SQL insert on the employee_phone child table would take the form1 :

INSERT INTO employee_phone (employee_empid, keycol, valuecol) VALUES (107, 'mobile',2855552391)

The List Child TableThe List collection is normalized into a three column child table called employee_client. The name of thetable is formulated by concatenating the name of the native table and the name of the List column. A foreignkey relationship to the parent table is maintained via the employee_empid column; the order of the elementsin the List is maintained via the current_list_index column; and the elements themselves are containedin the client column. SQL statements would identify these columns asemployee_client.employee_empid, employee_client.current_list_index, andemployee_client.client, respectively.

Table 6: employee_client (relational child of the list column)

clientcurrent_list_indexemployee_empid

(foreign key)

varcharintint

Li0103

Kumar1103

Jones2103

Yanev0105

Bishop1105

Bogdanov2105

A SQL insert on the employee_client child table would take the form1 :

INSERT INTO employee_client (employee_empid, client) VALUES (107, 'Nelson')

The Set Child TableThe Set collection is normalized into a two column child table called employee_review. The name of thetable is formulated by concatenating the name of the native table and the name of the Set column. A foreignkey relationship to the parent table is maintained via the empid column, while the elements of the Set are givenin natural order in the review column. In this child table, SQL statements would identify these columns asemployee_review.employee_empid and employee_review.review

1 The driver supports an insert on a child table prior to an insert on a parent table, circumventing referential integrity constraintsassociated with traditional RDBMS. To maintain integrity between parent and child tables, it is recommended that an insert beperformed on the parent table for each foreign key value added to the child. If such an insert is not first performed, the driverautomatically inserts a row into the parent tables that contains only the primary key values and NULL values for all non-primarykey columns.



Table 7: employee_review (relational child of the set column)

reviewemployee_empid

(foreign key)

dateint

2013-12-07103

2015-01-22103

2016-01-10103

2015-01-22105

2016-01-12105

A SQL insert on the employee_client child table would take the form1 :

INSERT INTO employee_review (employee_empid, review) VALUES (107, '2015-01-20')

Update SupportUpdate is supported for primitive types, non-nested Tuple types, and non-nested user-defined types. Updateis also supported for value columns (valuecol) in non-nested Map types. The driver does not support updateson List types, Set types, or key columns (keycol) in Map types because the values in each are part of theprimary key of their respective child tables and primary key columns cannot be updated. If an Update is attemptedwhen not allowed, the driver issues the following error message:

[DataDirect][Cassandra JDBC Driver][Cassandra]syntax error or access rule violation:UPDATE not permitted for column: column_name

Tuple and User-Defined TypesThe driver supports Tuple and user-defined complex types which were introduced with Apache Cassandra 2.1.As long as there are no complex types nested in either the Tuple or user-defined types, the driver normalizesTuple and user-defined types by flattening them into a relational version of the native Cassandra table. Takefor example the following Cassandra table:

CREATE TABLE agents1 (agentid int PRIMARY KEY,email varchar,contact tuple<varchar,varchar,varchar>);

The following agents1 table is a tabular representation of the native Cassandra table with data included.



Table 8: agents1 (native)

contactemailagentid

(primary key)

tuple<varchar, varchar, varchar>varcharint

tv

newspaper

blog

[email protected]

radio

tv

magazine

[email protected]

For the relational version of agents1, all fields are retained as separate columns, and columns with primitivetypes (agentid and email) correspond directly to columns in the native table. In turn, tuple fields are flattenedinto columns using a <tuplename>_<ordinal> naming pattern. The driver normalizes agents1 in thefollowing manner.

Table 9: agents1 (relational)

contact_3contact_2contact_1emailagentid

(primary key)

varcharvarcharvarcharvarcharint

[email protected]

[email protected]

A SQL command would take the following form:

INSERT INTO agents1 (agentid,email,contact_1,contact_2,contact_3) VALUES(839,'[email protected]','radio','tv','magazine')

The driver also flattens user-defined types when normalizing native Cassandra tables. In the following example,the native Cassandra agents2 table incorporates the user-defined address type.

CREATE TYPE address (street varchar,city varchar,state varchar,zip int);

CREATE TABLE agents2 (agentid int PRIMARY KEY,email varchar,location frozen<address>);

The following agents2 table is a tabular representation of the native Cassandra table with data included.




locationemailagentid

(primary key)

address<street: varchar, city: varchar,state: varchar, zip: int>

varcharint

street: 1551 Main Street

city: Pittsburgh

state: PA

zip: 15237

[email protected]

street: 422 First Street

city: Richmond

state: VA

zip: 23235

[email protected]

As with the previous example, all fields are retained as separate columns in the relational version of the table,and columns with primitive types (agentid and email) correspond directly to columns in the native table.Here a <columnname>_<fieldname> naming pattern is used to flatten the fields of the user-defined addresstype into columns. The driver normalizes agents2 in the following manner.


location_ziplocation_statelocation_citylocation_streetemailagentid

(primary key)

intvarcharvarcharvarcharvarcharint

15237PAPittsburgh1551 MainStreet

[email protected]

23235VARichmond422 FirstStreet

[email protected]

A SQL command would take the following form:

INSERT INTO agents2(agentid,email,location_street,location_city,location_state,location_zip) VALUES(839,'[email protected]','9 Fifth Street', 'Morrisville', 'NC', 27566)



Nested Complex TypesThe nesting of complex types within Tuple and user-defined types is permitted in CQL. The driver does notnormalize such nested types, but rather the data is passed as a JSON-style string. For example, consider thetable contacts which contains the columns id and contact. While id is a primitive int column, contactis a user-defined info column which contains name, email, and location fields. The location field itselfis a nested user-defined address column which contains street, city, state, and zip fields. In CQL, thestructure of this table would take the following form:

CREATE TYPE address (street varchar,city varchar,state varchar,zip int);

CREATE TYPE info (name varchar,email varchar,location frozen<address>);

CREATE TABLE contacts (id int PRIMARY KEY,contact frozen<info>);

The following tabular representation of the contacts table shows how the driver returns data when complextypes are nested in other complex types. Because the complex user-defined type address is embedded inthe complex user-defined type info, the entire contact column is returned by the driver as a JSON string.

Note: You can retrieve this string data by calling the DatabaseMetaData.getColumns() method.

Table 12: contacts (relational)

contactid

(primary key)

info<name: varchar, email: varchar, location: address<street: varchar, city:varchar, state: varchar, zip: int>>

int

{name: 'Jude', email: '[email protected]', location: {street:'101 Main Street', city: 'Albany', state:'NY', zip: 12210}}

034

{name: 'Karen', email: '[email protected]', location: {street:'150 First Street', city: 'Portland', state: 'OR', zip: 97214}}

056

When executing SQL commands involving nested complex types, the data must be passed as a JSON string.Furthermore, the syntax you use to connote the JSON string depends on whether you are passing the stringdirectly in a SQL command or setting the JSON string as a parameter on a prepared statement.

Note: Hints for parsing JSON-style strings are provided in the Remark column of the getColumns() result.



Connoting the JSON-Style String in a SQL StatementWhen passing the string directly in a SQL command, you must use the correct SQL syntax and escapes tomaintain the structure of the data. To begin, the entire JSON string must be passed in single quotation marks('). Furthermore, if the JSON string contains nested strings, two single quotation marks are used to indicatestring values. The first quotation mark is an escape connoting the second embedded quotation mark. Thefollowing command inserts a new row into the contacts table.

Note: In accordance with Java syntax, the Insert statement is placed in double quotation marks. However, inthe JSON string, two single quotation marks are used to indicate string values. The first quotation mark is anescape connoting the second embedded quotation mark.

Stmt.executeUpdate("INSERT INTO contacts (id, contact) VALUES (075, '{name: ''Albert'', " +"email: ''[email protected]'', location: {street: ''12 North Street'', " +"city: ''Durham'', state:''NC'', zip: 27704}}')");

After the insert has been executed, the Select command SELECT contact FROM contacts WHERE id= 75 returns:

{name: 'Albert',email: '[email protected]',location: {street: '12 North Street',

city: 'Durham',state:'NC',zip: 27704}

}

Connoting the JSON-Style String as a Parameter Value on a Prepared StatementWhen setting the JSON string as a parameter value, you must follow Java syntax by placing the JSON stringin double quotation marks. Escapes are not used to connote embedded single quotation marks. For example:

pstmt.setString(2,"{name: 'Albert', email: '[email protected]', location: " +

"{street: '12 North Street', city: 'Durham', state:'NC', " +"zip: 27704}}")

Data TypesThe following table lists the Cassandra data types supported by the driver and how they are mapped to JDBCdata types.

The complex types List, Map, Set, Tuple, and user-defined types have no direct JDBC mapping. However, thedriver normalizes these types to provide SQL access to Cassandra. For details on how complex types aremapped, see "Complex Type Normalization."

See "getTypeInfo()" for getTypeInfo() results of data types supported by the driver.

Table 13: Data Type Mapping

JDBCApache Cassandra

VARCHARASCII



JDBCApache Cassandra

BIGINTBIGINT

LONGVARBINARYBLOB

BOOLEANBOOLEAN

BIGINTCOUNTER2

DATEDATE3

DECIMALDECIMAL

DOUBLEDOUBLE

REALFLOAT

VARCHARINET

INTEGERINT

LONGVARCHARLIST4

LONGVARCHARMAP4

LONGVARCHARSET4

SMALLINTSMALLINT3

TIMETIME3

TIMESTAMPTIMESTAMP

CHARTIMEUUID

TINYINTTINYINT3

LONGVARCHARTUPLE4

LONGVARCHARUSERTYPE5

CHARUUID

VARCHARVARCHAR

DECIMALVARINT

2 Update is supported for Counter columns when all the other columns in the row comprise that row’s primary key. See Updateon page 191 for details.

3 Supported for Apache Cassandra 2.2 and higher.4 See Complex Type Normalization on page 15 for details on how complex types are mapped.5 Also referred to as user-defined types. These are data types created with the CQL CREATE TYPE statement. See Complex

Type Normalization on page 15 for details on how Usertype is mapped.


Data Types

See alsoComplex Type Normalization on page 15

getTypeInfo()The DatabaseMetaData.getTypeInfo() method returns information about data types. The following table providesgetTypeInfo() results for supported Apache Cassandra data types.

Table 14: getTypeInfo()

MINIMUM_SCALE = NULL

NULLABLE = 1

NUM_PREC_RADIX = NULL

PRECISION = 2000000000

SEARCHABLE = 3

SQL_DATA_TYPE = NULL

SQL_DATETIME_SUB = NULL

UNSIGNED_ATTRIBUTE = NULL

TYPE_NAME = ascii

AUTO_INCREMENT = NULL

CASE_SENSITIVE = true

CREATE_PARAMS = NULL

DATA_TYPE = 12 (VARCHAR)

FIXED_PREC_SCALE = false

LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = ascii

MAXIMUM_SCALE = NULL

MINIMUM_SCALE = 0

NULLABLE = 1

NUM_PREC_RADIX = 10

PRECISION = 19

SEARCHABLE = 3



UNSIGNED_ATTRIBUTE = false

TYPE_NAME = bigint

AUTO_INCREMENT = false

CASE_SENSITIVE = false


DATA_TYPE = -5 (BIGINT)


LITERAL_PREFIX = NULL

LITERAL_SUFFIX = NULL

LOCAL_TYPE_NAME = bigint

MAXIMUM_SCALE = 0




NULLABLE = 1



SEARCHABLE = 2




TYPE_NAME = blob




DATA_TYPE = -4 (LONGVARBINARY)


LITERAL_PREFIX = X'

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = blob



NULLABLE = 1


PRECISION = 1

SEARCHABLE = 2




TYPE_NAME = boolean




DATA_TYPE = 16 (BOOLEAN)




LOCAL_TYPE_NAME = boolean


MINIMUM_SCALE = 0

NULLABLE = 1

NUM_PREC_RADIX = 10

PRECISION = 19

SEARCHABLE = 3




TYPE_NAME = counter6




DATA_TYPE = -5 (BIGINT)




LOCAL_TYPE_NAME = counter

MAXIMUM_SCALE = 0

6 Update is supported for Counter columns when all the other columns in the row comprise that row’s primary key. See Updateon page 191 for details.


Data Types

MINIMUM_SCALE = 0

NULLABLE = 1


PRECISION = 10

SEARCHABLE = 3




TYPE_NAME = date7




DATA_TYPE = 91 (DATE)


LITERAL_PREFIX = date'

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = date

MAXIMUM_SCALE = 0

MINIMUM_SCALE = 0

NULLABLE = 1

NUM_PREC_RADIX = 10

PRECISION = 38

SEARCHABLE = 3




TYPE_NAME = decimal




DATA_TYPE = 3 (DECIMAL)




LOCAL_TYPE_NAME = decimal

MAXIMUM_SCALE = 100

MINIMUM_SCALE = 0

NULLABLE = 1

NUM_PREC_RADIX = 10

PRECISION = 15

SEARCHABLE = 3




TYPE_NAME = double




DATA_TYPE = 8 (DOUBLE)


LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = double

MAXIMUM_SCALE = 0

7 Supported for Apache Cassandra 2.2 and higher.



MINIMUM_SCALE = 0

NULLABLE = 1

NUM_PREC_RADIX = 10

PRECISION = 7

SEARCHABLE = 3




TYPE_NAME = float




DATA_TYPE = 7 (REAL)




LOCAL_TYPE_NAME = float

MAXIMUM_SCALE = 0


NULLABLE = 1


PRECISION = 39

SEARCHABLE = 3




TYPE_NAME = inet






LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = inet


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


Data Types


NULLABLE = 1



SEARCHABLE = 0




TYPE_NAME = list8




DATA_TYPE = -1 (LONGVARCHAR)


LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = list



NULLABLE = 1



SEARCHABLE = 0




TYPE_NAME = map8






LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = map



NULLABLE = 1



SEARCHABLE = 0




TYPE_NAME = set8






LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = set


8 See Complex Type Normalization on page 15 for details on how complex types are mapped.



MINIMUM_SCALE = 0

NULLABLE = 1

NUM_PREC_RADIX = 10

PRECISION = 5

SEARCHABLE = 3




TYPE_NAME = smallint7




DATA_TYPE = 5 (SMALLINT)




LOCAL_TYPE_NAME = smallint

MAXIMUM_SCALE = 0

MINIMUM_SCALE = 0

NULLABLE = 1


PRECISION = 18

SEARCHABLE = 3




TYPE_NAME = time7




DATA_TYPE = 92 (TIME)


LITERAL_PREFIX = time'

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = time

MAXIMUM_SCALE = 9

MINIMUM_SCALE = 0

NULLABLE = 1


PRECISION = 23

SEARCHABLE = 3




TYPE_NAME = timestamp




DATA_TYPE = 93 (TIMESTAMP)


LITERAL_PREFIX = timestamp'

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = timestamp

MAXIMUM_SCALE = 3


Data Types


NULLABLE = 1


PRECISION = 36

SEARCHABLE = 3




TYPE_NAME = timeuuid




DATA_TYPE = 1 (CHAR)


LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = timeuuid


MINIMUM_SCALE = 0

NULLABLE = 1

NUM_PREC_RADIX = 10

PRECISION = 3

SEARCHABLE = 3




TYPE_NAME = tinyint7




DATA_TYPE = -6 (TINYINT)




LOCAL_TYPE_NAME = tinyint

MAXIMUM_SCALE = 0


NULLABLE = 1



SEARCHABLE = 0




TYPE_NAME = tuple8






LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = tuple





NULLABLE = 1



SEARCHABLE = 0




TYPE_NAME = usertype9






LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = usertype



NULLABLE = 1


PRECISION = 36

SEARCHABLE = 3




TYPE_NAME = uuid




DATA_TYPE = 1 (CHAR)


LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = uuid


9 Also referred to as user-defined types. These are data types created with the CQL CREATE TYPE statement. See ComplexType Normalization on page 15 for details on how Usertype is mapped.


Data Types


NULLABLE = 1



SEARCHABLE = 3




TYPE_NAME = varchar


CASE_SENSITIVE = true




LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = varchar


MINIMUM_SCALE = 0

NULLABLE = 1

NUM_PREC_RADIX = 10

PRECISION = 100

SEARCHABLE = 3




TYPE_NAME = varint




DATA_TYPE = 3 (DECIMAL)




LOCAL_TYPE_NAME = varint

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.

• 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).


• Driver and Data Source Classes

• Connecting Using the DriverManager

• Connecting Using Data Sources












Connecting Using the DriverManagerOne way to connect to a Cassandra keyspace is through the JDBC DriverManager using theDriverManager.getConnection()method. As the following example shows, this method specifies a stringcontaining a connection URL.

Connection conn = DriverManager.getConnection("jdbc:datadirect:cassandra://MyServer:9042;KeyspaceName=MyKS");

Note: A Cassandra keyspace is equivalent to a relational database.

Setting the ClasspathThe driver must be defined on your CLASSPATH before you can connect. The CLASSPATH is the searchstring your Java Virtual Machine (JVM) uses to locate JDBC drivers on your computer. If the driver is not definedon your CLASSPATH, you will receive a class not found exception when trying to load the driver. Set yoursystem CLASSPATH to include the cassandra.jar file as shown, where install_dir is the path to yourproduct installation directory.

install_dir/lib/cassandra.jar

Windows ExampleCLASSPATH=.;C:\Program Files\Progress\DataDirect\JDBC_60\lib\cassandra.jar

UNIX ExampleCLASSPATH=.:/opt/Progress/DataDirect/JDBC_60/lib/cassandra.jar


Chapter 2: Getting started

Passing the Connection URLAfter setting the CLASSPATH, the required connection information needs to be passed in the form of aconnection URL. The connection URL takes the form:

jdbc:datadirect:cassandra://server:port;KeyspaceName=keyspace;[property=value[;...]]

where:

server

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

port

specifies the port of the server that is listening for connections to the Cassandra keyspace. Thedefault is 9042.

keyspace

specifies the default name of the Cassandra keyspace to which the driver connects. This value isused as the default qualifier for unqualified table names in SQL queries. Note that a Cassandrakeyspace is equivalent to a relational database.

property=value

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

This example shows how to establish a connection to a Cassandra data store:


Testing the ConnectionYou can also use DataDirect Test™ to establish and test a DriverManager connection. The screen shots in thissection were taken on a Windows system.

Take the following steps to establish a connection.

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

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

• UNIX and Linux systems: /opt/Progress/DataDirect/JDBC_60/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 DriverManager

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 theDatabase field, specify the ServerName, PortNumber, and KeyspaceName for your Apache Cassandradata store.

For example:

jdbc:datadirect:cassandra://MyServer:9042;keyspaceName=MyKS


Connecting Using the DriverManager

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

Attention: User ID/password authentication is not supported for the preview version of the driver.

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 on page 92.

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 DataSource object. The applications using the database do not needto 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 alsoDriver and Data Source Classes on page 13Connection Pool Manager on page 71

Creating Data SourcesThe following example files provide details on creating and using Progress DataDirect data sources with theJava Naming Directory Interface (JNDI), where install_dir is the product installation directory.

• install_dir/Examples/JNDI/JNDI_LDAP_Example.java can be used to create a JDBC data sourceand save it in your LDAP directory using the JNDI Provider for LDAP.

• install_dir/Examples/JNDI/JNDI_FILESYSTEM_Example.java can be used to create a JDBCdata source and save it in your local file system using the File System JNDI Provider.

See "Example Data Source" for an example data source definition for the example files.

To connect using a JNDI data source, the driver needs to access a JNDI data store to persist the data sourceinformation. For a JNDI file system implementation, you must download the File System Service Provider fromthe Oracle Technology Network Java SE Support downloads page, unzip the files to an appropriate location,and add the fscontext.jar and providerutil.jar files to your CLASSPATH. These steps are notrequired for LDAP implementations because the LDAP Service Provider has been included with Java SE sinceJava 2 SDK, v1.3.

Calling a Data Source in an ApplicationApplications can call a Progress DataDirect data source using a logical name to retrieve thejavax.sql.DataSource object. This object loads the specified driver and can be used to establish aconnection 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");


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

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 aJava object, which is narrowed to a javax.sql.DataSource object. Then, theDataSource.getConnection() method is called to establish a connection.



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.


• Connecting from an Application

• Using Connection Properties

• Performance Considerations

• Authentication

• Data Encryption

• Identifiers

• IP Addresses

• Parameter Metadata Support

• Isolation Levels

• Unicode

• Error Handling

• Large Object (LOB) Support

• Rowset Support

• Executing CQL


• Connection Pool Manager

• Statement Pool Monitor

• DataDirect Test

• Tracking JDBC Calls with DataDirect Spy

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 DriverManagerOne way to connect to a Cassandra keyspace is through the JDBC DriverManager using theDriverManager.getConnection()method. As the following example shows, this method specifies a stringcontaining a connection URL.


Note: A Cassandra keyspace is equivalent to a relational database.


Chapter 3: Using the Driver

Setting the ClasspathThe driver must be defined on your CLASSPATH before you can connect. The CLASSPATH is the searchstring your Java Virtual Machine (JVM) uses to locate JDBC drivers on your computer. If the driver is not definedon your CLASSPATH, you will receive a class not found exception when trying to load the driver. Set yoursystem CLASSPATH to include the cassandra.jar file as shown, where install_dir is the path to yourproduct installation directory.

install_dir/lib/cassandra.jar

Windows ExampleCLASSPATH=.;C:\Program Files\Progress\DataDirect\JDBC_60\lib\cassandra.jar

UNIX ExampleCLASSPATH=.:/opt/Progress/DataDirect/JDBC_60/lib/cassandra.jar

Passing the Connection URLAfter setting the CLASSPATH, the required connection information needs to be passed in the form of aconnection URL. The connection URL takes the form:

jdbc:datadirect:cassandra://server:port;KeyspaceName=keyspace;[property=value[;...]]

where:

server

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

port

specifies the port of the server that is listening for connections to the Cassandra keyspace. Thedefault is 9042.

keyspace

specifies the default name of the Cassandra keyspace to which the driver connects. This value isused as the default qualifier for unqualified table names in SQL queries. Note that a Cassandrakeyspace is equivalent to a relational database.

property=value

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

This example shows how to establish a connection to a Cassandra data store:



Connecting from an Application

Testing the ConnectionYou can also use DataDirect Test™ to establish and test a DriverManager connection. The screen shots in thissection were taken on a Windows system.

Take the following steps to establish a connection.

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

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

• UNIX and Linux systems: /opt/Progress/DataDirect/JDBC_60/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)

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 theDatabase field, specify the ServerName, PortNumber, and KeyspaceName for your Apache Cassandradata store.



For example:

jdbc:datadirect:cassandra://MyServer:9042;keyspaceName=MyKS

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

Attention: User ID/password authentication is not supported for the preview version of the driver.

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 on page 92.

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 DataSource object. The applications using the database do not needto 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 alsoDriver and Data Source Classes on page 13Connection Pool Manager on page 71

Creating Data SourcesThe following example files provide details on creating and using Progress DataDirect data sources with theJava Naming Directory Interface (JNDI), where install_dir is the product installation directory.

• install_dir/Examples/JNDI/JNDI_LDAP_Example.java can be used to create a JDBC data sourceand save it in your LDAP directory using the JNDI Provider for LDAP.

• install_dir/Examples/JNDI/JNDI_FILESYSTEM_Example.java can be used to create a JDBCdata source and save it in your local file system using the File System JNDI Provider.

See "Example Data Source" for an example data source definition for the example files.

To connect using a JNDI data source, the driver needs to access a JNDI data store to persist the data sourceinformation. For a JNDI file system implementation, you must download the File System Service Provider fromthe Oracle Technology Network Java SE Support downloads page, unzip the files to an appropriate location,and add the fscontext.jar and providerutil.jar files to your CLASSPATH. These steps are notrequired for LDAP implementations because the LDAP Service Provider has been included with Java SE sinceJava 2 SDK, v1.3.

Calling a Data Source in an ApplicationApplications can call a Progress DataDirect data source using a logical name to retrieve thejavax.sql.DataSource object. This object loads the specified driver and can be used to establish aconnection 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 aJava object, which is narrowed to a javax.sql.DataSource object. Then, theDataSource.getConnection() method is called to establish a connection.

Using Connection PropertiesYou can use connection properties to customize the driver for your environment. This section organizesconnection properties according to functionality. You can use connection properties with either the JDBCDriverManager or a JDBC DataSource. For a DriverManager connection, a property is expressed as akey value pair and takes the form property=value. For a DataSource connection, a property is expressedas a JDBC method and takes the form setproperty(value). Connection property names are case-insensitive.For example, Password is the same as password.

Note: In a JDBC DataSource, string values must be enclosed in double quotation marks, for example,setKeyspaceName("MyKS").

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

See alsoConnecting Using the DriverManager on page 36Connecting Using Data Sources on page 40Connection Property Descriptions on page 129

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

Table 17: Required Properties

CharacteristicProperty

Specifies the default name of the Cassandra keyspace to which the driver connects.This value is used as the default qualifier for unqualified table names in SQLqueries. Note that a Cassandra keyspace is equivalent to a relational database.

KeyspaceName on page140

Specifies the port of the server that is listening for connections to the Cassandrakeyspace. The default is 9042.

PortNumber on page 148

Specifies the name or the IP address of the server to which you want to connect.ServerName on page 154

See alsoConnection Property Descriptions on page 129



Mapping PropertiesThe following table summarizes connection properties involved in mapping a native data model to a relationaldata model.

Table 18: Mapping Properties


Determines whether the driver creates the internal files required for a relationalview of the native data when establishing a connection.

CreateMap on page 133

Specifies the name and location of the configuration file used to create therelational map of native data. The driver looks for this file when connecting tothe server. If the file does not exist, the driver creates one.

SchemaMap on page 153

See alsoComplex Type Normalization on page 15Connection Property Descriptions on page 129

Authentication PropertiesThe following table summarizes connection properties related to authentication.

Table 19: Authentication Properties


Determines which authentication method the driver uses when establishing aconnection. The default is userIdPassword.

AuthenticationMethod onpage 132

Specifies the default name of the Cassandra keyspace to which the driver connects.This value is used as the default qualifier for unqualified table names in SQLqueries.

KeyspaceName on page140

Specifies the name of the entry in the JAAS login configuration file that containsthe authentication technology used by the driver to establish a Kerberos connection.The LoginModule-specific items found in the entry are passed on to theLoginModule. The default is JDBC_DRIVER_01.

LoginConfigName onpage 143

Specifies the password used to connect to your database for user ID/passwordauthentication.

Password on page 147

Specifies the three-part service principal name registered with the key distributioncenter (KDC) in a Kerberos configuration. When no value is specified, the driverbuilds a service principle name based on environment variables.

ServicePrincipalName onpage 155

Specifies the user ID for user ID/password authentication or the user principalname for Kerberos authentication.

User on page 159


Using Connection Properties


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

Table 20: Data Encryption Properties


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

To enable SSL, set EncryptionMethod to SSL.

The default is noEncryption.

EncryptionMethod on page 134

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 136

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 140

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 158




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 page159

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).

The default is true.

ValidateServerCertificate onpage 160

See alsoData Encryption on page 64Connection Property Descriptions on page 129Authentication Properties on page 51

Statement Pooling PropertiesThe following table summarizes statement pooling connection properties.

Table 21: 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 specifiedfile.

ImportStatementPool on page 137

Specifies the maximum number of prepared statements to bepooled for each connection and enables the driver’s internalprepared statement pooling when set to an integer greater thanzero (0). The driver’s internal prepared statement pooling providesperformance benefits when the driver is not running from withinan application server or another application that provides its ownstatement pooling.

MaxPooledStatements on page 145

Registers the Statement Pool Monitor as a JMX MBean whenstatement pooling has been enabled with MaxPooledStatements.This allows you to manage statement pooling with standard JMXAPI calls and to use JMX-compliant tools, such as JConsole.

RegisterStatementPoolMonitorMBean onpage 150

See alsoStatement Pool Monitor on page 84


Using Connection Properties

Connection Property Descriptions on page 129

Additional PropertiesThe following table summarizes additional connection properties.

Table 22: Additional Properties


Specifies the number of rows that the driver processes before returningdata to the application when executing a Select. This value provides asuggestion to the driver as to the number of rows it should internallyprocess before returning control to the application. The driver may fetchfewer rows to conserve memory when processing exceptionally widerows.

FetchSize 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.

InsensitiveResultSetBufferSize onpage 139

Specifies the filename of the configuration file used to initialize driverlogging.

LogConfigFile on page 143

The amount of time, in seconds, that the driver waits for a connection tobe established before timing out the connection request.

LoginTimeout on page 144

Specifies the number of rows of data the driver attempts to fetch fromthe native data source on each request submitted to the server.

NativeFetchSize on page 146

Specifies how many replicas must respond to a read request beforereturning data to the client application.

ReadConsistency on page 149

Specifies whether the connection supports read-only access to the datasource.

ReadOnly on page 150

Specifies the maximum size, in megabytes, of an intermediate result setthat the driver holds in memory. When this threshold is reached, the driverwrites a portion of the result set to disk in temporary files.

ResultMemorySize on page 151

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 156

Specifies how the driver handles manual transactions.TransactionMode on page 157

Determines the number of replicas on which the write must succeedbefore returning an acknowledgment to the client application.

WriteConsistency on page 161




Performance ConsiderationsYou can optimize application performance by adopting guidelines described in this section.

EncryptionMethod: Data encryption may adversely affect performance because of the additional overhead(mainly CPU usage) required to encrypt and decrypt data.

FetchSize/NativeFetchSize: The connection properties FetchSize and NativeFetchSize can be used to adjustthe trade-off between throughput and response time. In general, setting larger values for FetchSize andNativeFetchSize will improve throughput, but can reduce response time.

For example, if an application attempts to fetch 100,000 rows from the native data source and NativeFetchSizeis set to 500, the driver must make 200 round trips across the network to get the 100,000 rows. If, however,NativeFetchSize is set to 10000, the driver only needs to make 10 round trips to retrieve 100,000 rows. Networkround trips are expensive, so generally, minimizing these round trips increases throughput.

For many applications, throughput is the primary performance measure, but for interactive applications, suchas Web applications, response time (how fast the first set of data is returned) is more important than throughput.For example, suppose that you have a Web application that displays data 50 rows to a page and that, onaverage, you view three or four pages. Response time can be improved by setting FetchSize to 50 (the numberof rows displayed on a page) and NativeFetchSize to 200. With these settings, the driver fetches all of therows from the native data source that you would typically view in a single session and only processes the rowsneeded to display the first page.

Note: FetchSize provides a suggestion to the driver as to the number of rows it should internally processbefore returning control to the application. The driver may fetch fewer rows to conserve memory when processingexceptionally wide rows.

InsensitiveResultSetBufferSize: To improve performance, insensitive result set data can be cached insteadof written to disk. If the size of the result set data is greater than the size allocated for the cache, the driverwrites the result set to disk. The maximum cache size setting is 2 GB.

JVM Heap Size: JVM heap size can be used to address memory and performance concerns. By increasingthe max Java heap size, you increase the amount of data the driver may accumulate in memory. This canreduce the likelihood of out-of-memory errors and improve performance by ensuring that result sets fit easilywithin the JVM's free heap space. In addition, when a limit is imposed by setting ResultMemorySize to -1,increasing the max Java heap size can improve performance by reducing the need to write to disk, or removingit altogether.

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 PerformanceOptimization" for more information about using prepared statement pooling to optimize performance.)


Performance Considerations

ResultMemorySize: ResultMemorySize can affect performance in two main ways. First, if the size of the resultset is larger than the value specified for ResultMemorySize, the driver writes a portion of the result set to disk.Since writing to disk is an expensive operation, performance losses will be incurred. Second, when you removeany limit on the size of an intermediate result set by setting ResultMemorySize to 0, you can realize performancegains for result sets that easily fit within the JVM's free heap space. However, the same setting can diminishperformance for result sets that barely fit within the JVM's free heap space.

See alsoEncryptionMethod on page 134FetchSize on page 135InsensitiveResultSetBufferSize on page 139MaxPooledStatements on page 145ResultMemorySize on page 151Troubleshooting Out-of-Memory Errors on page 171Designing JDBC Applications for Performance Optimization on page 283

AuthenticationThe driver supports user ID/password and Kerberos authentication with the AuthenticationMethod connectionproperty.

When AuthenticationMethod=userIdPassword (default), the driver uses SCRAM-SHA-1 user ID/passwordauthentication. The User property provides the user ID, and the Password property provides the password.

When AuthenticationMethod=kerberos, the driver uses Kerberos authentication.

When AuthenticationMethod=none, the driver does not attempt to authenticate with the server.

See alsoAuthenticationMethod on page 132

Configuring User ID/Password AuthenticationTake the following steps to configure user ID/Password authentication:

1. Set the AuthenticationMethod property to userIdPassword.

2. If necessary, set the KeyspaceName connection property.

If authentication has not been enabled, client applications will have access to all keyspaces on the server.If authentication has been enabled, a client application will only have access to the keyspace specified bythe KeyspaceName property assuming it has the required permissions.

Even when authentication has not been enabled, KeyspaceName is strongly recommended because itsvalue functions as the default qualifier for unqualified tables in SQL queries.

3. Set the User property to provide the user ID.

4. Set the Password property to provide the password.

See alsoAuthenticationMethod on page 132



KeyspaceName on page 140User on page 159Password on page 147

Configuring the Driver for Kerberos AuthenticationTo configure the driver for Kerberos authentication, take the following steps.

1. Verify that your environment meets the requirements outlined in "Kerberos Authentication Requirements."

2. Use one of the following methods to integrate the JAAS configuration file into your Kerberos environment.(See "The JAAS Login Configuration File" for details about this file.)

Option 1. Specify a login configuration file directly in your application with thejava.security.auth.login.config system property. For example:

System.setProperty("java.security.auth.login.config","install_dir/lib/JDBCDriverLogin.conf");

Note: The install_dir/lib/JDBCDriverLogin.conf file is the JAAS login configuration file installedwith the driver. You can use this file or another file as your JAAS login configuration file.

Option 2. Set up a default configuration. Modify the Java security properties file to indicate the URL of thelogin configuration file with the login.config.url.n property where n is an integer connoting separate,consecutive login configuration files. When more than one login configuration file is specified, then the filesare read and concatenated into a single configuration.

a) Open the Java security properties file. The security properties file is the java.security file in the/jre/lib/security directory of your Java installation.

b) Find the line # Default login configuration file in the security properties file.

c) Below the # Default login configuration file line, add the URL of the login configuration fileas the value for a login.config.url.n property. For example:

# Default login configuration filelogin.config.url.1=file:${user.home}/.java.login.configlogin.config.url.2=file:install_dir/lib/JDBCDriverLogin.conf

3. Modify your JAAS login configuration file to include an entry with authentication technology that the drivercan use to establish a Kerberos connection. (See "The JAAS Login Configuration File" for details about thisfile.)

JAAS login configuration file entries begin with an entry name followed by one or more LoginModule items.Each LoginModule item contains information that is passed to the LoginModule. A login configuration fileentry takes the following form.

entry_name {login_module flag_value module_options

};


Authentication

where:

entry_name

is the name of the login configuration file entry. The driver's LoginConfigName connection propertycan be used to specify the name of this entry. JDBC_DRIVER_01 is the default entry name forthe JDBCDriverLogin.conf file installed with the driver.

login_module

is the fully qualified class name of the authentication technology used with the driver.

flag_value

specifies whether the success of the module is required, requisite, sufficient, oroptional.

module_options

specifies available options for the LoginModule. These options vary depending on the LoginModulebeing used.

The following examples show that the LoginModule used for a Kerberos implementation depends on yourJRE.

Oracle JRE

JDBC_DRIVER_01 {com.sun.security.auth.module.Krb5LoginModule required useTicketCache=true;

};

IBM JRE

JDBC_DRIVER_01 {com.ibm.security.auth.module.Krb5LoginModule required useDefaultCcache=true;

};

4. Set the Kerberos realm name and the KDC name for that realm using either of the following methods.

Note: If using Windows Active Directory, the Kerberos realm name is the Windows domain name and theKDC name is the Windows domain controller name.

Option 1. Modify the krb5.conf file to include the default realm name and the KDC name for that realm.(See "The krb5.conf File" for details about using and locating the krb5.conf file.)

For example, if the realm name is XYZ.COM and the KDC name is kdc1, your krb5.conf file would includethe following entries.

[libdefaults]default_realm = XYZ.COM

[realms]XYZ.COM = {kdc = kdc1}



Option 2. Specify the Java system properties, java.security.krb5.realm andjava.security.krb5.kdc, in your application. For example, if the realm name is XYZ.COM and theKDC name is kdc1, your application would include the following settings.

System.setProperty("java.security.krb5.realm","XYZ.COM");System.setProperty("java.security.krb5.kdc","kdc1")

Note: Even if you do not use the krb5.conf file to specify the realm and KDC names, you may need tomodify your krb5.conf file to suit your environment. Refer to your database vendor documentation forinformation.

If you do not specify a valid Kerberos realm and a valid KDC name, the following exception is thrown.

Message:[DataDirect][Cassandra JDBC Driver]Could not establish a connection usingintegrated security: No valid credentials provided

5. Set the driver's AuthenticationMethod connection property to kerberos. (See "AuthenticationMethod" fordetails.)

6. If any of the following statements is valid, specify the service principal name with the ServicePrincipalNameconnection property. (See "ServicePrincipalName" for details on the composition of the service principalname.)

Note: The ServicePrincipalName takes the following form.

Service_Name/Fully_Qualified_Domain_Name@REALM_NAME

• You are using a service name other than the default service name cassandra.

• The fully qualified domain name (FQDN) in your connection string is different from the FQDN registeredwith the KDC.

• You are using a Kerberos realm other than the default realm specified in the krb5.conf file.

7. If necessary, set the User connection property. (See "User" for details.)

In most circumstances, there is no need to set the User connection property. By default, the driver uses theuser principal name in the Kerberos Ticket Granting Ticket (TGT) as the value for the User property.

8. If necessary, set the KeyspaceName connection property. (See "KeyspaceName" for details.)

If authentication has not been enabled, client applications will have access to all keyspaces on the server.If authentication has been enabled, a client application will only have access to the keyspace specified bythe KeyspaceName property assuming it has the required permissions.

Even when authentication has not been enabled, KeyspaceName is strongly recommended because itsvalue functions as the default qualifier for unqualified tables in SQL queries.

9. If you want the driver to use user credentials other than the server user’s operating system credentials,include code in your application to obtain and pass a javax.security.auth.Subject used forauthentication. (See "Specifying User Credentials for Kerberos Authentication (Delegation of Credentials)"for details.)

10. Establish a procedure for obtaining a Kerberos Ticket Granting Ticket (TGT) for your environment. (See"Obtaining a Kerberos Ticket Granting Ticket" for details.)

Scenario 1. For Windows Active Directory configurations, Active Directory automatically obtains a TGT.


Authentication

Scenario 2. For non-Active Directory configurations, you can enable the application to obtain a TGT ineither of the following ways.

a) Automate the method of obtaining the TGT as with a keytab. (See your Kerberos documentation fordetails.)

b) Require the application user to obtain the TGT with a kinit command when logging on.

A TGT can be obtained with a kinit command to the Kerberos server. For example, the following commandrequests a TGT from the server with a lifetime of 10 hours, which is renewable for 5 days.

kinit -l 10h -r 5d user@REALM

Note: The klist command can be used on Windows or UNIX/Linux systems to verify that a TGT hasbeen obtained.

See alsoKerberos Authentication Requirements on page 60The JAAS Login Configuration File on page 61LoginConfigName on page 143The krb5.conf File on page 62AuthenticationMethod on page 132ServicePrincipalName on page 155User on page 159KeyspaceName on page 140Specifying User Credentials for Kerberos Authentication (Delegation of Credentials) on page 63Obtaining a Kerberos Ticket Granting Ticket on page 64

Kerberos Authentication RequirementsVerify that your environment meets the requirements listed in the following table before you configure the driverfor Kerberos authentication.

Note: For Windows Active Directory, the domain controller must administer both the database server and theclient.

Table 23: Kerberos Configuration Requirements

RequirementsComponent

The database server must be running Apache Cassandra 2.1 or higher.Database server



RequirementsComponent

The Kerberos server is the machine where the user IDs for authenticationare administered. The Kerberos server is also the location of the Kerberoskey distribution center (KDC). Network authentication must be providedby one of the following methods.

• Windows Active Directory on one of the following operating systems:

• Windows Server 2003 or higher

• Windows 2000 Server Service Pack 3 or higher

• MIT Kerberos 1.5 or higher

Kerberos server

Java SE 6 or higher must be installed.Client

See alsoConfiguring the Driver for Kerberos Authentication on page 57

The JAAS Login Configuration FileThe Java Authentication and Authorization Service (JAAS) login configuration file contains one or more entriesthat specify authentication technologies to be used by applications. To establish Kerberos connections withthe driver, the login configuration file must be referenced either by setting thejava.security.auth.login.config system property or by setting up a default configuration using theJava security properties file. In addition, the login configuration file must include an entry for the driver. (See"Configuring the Driver for Kerberos Authentication" for details.)

You can create your own JAAS login configuration file, or you can use the JDBCDriverLogin.conf fileinstalled with the driver. This file is installed in the /lib directory of the product installation directory. In eithercase, the login configuration file must include an entry that specifies the authentication technology to be usedby the driver to establish a Kerberos connection.

JAAS login configuration file entries begin with an entry name followed by one or more LoginModule items.Each LoginModule item contains information that is passed to the LoginModule. A login configuration file entrytakes the following form.

entry_name {login_module flag_value module_options

};


Authentication

where:

entry_name

is the name of the login configuration file entry. The driver's LoginConfigName connection propertycan be used to specify the name of this entry. JDBC_DRIVER_01 is the default entry name for theJDBCDriverLogin.conf file installed with the driver.

login_module

is the fully qualified class name of the authentication technology used with the driver.

flag_value

specifies whether the success of the module is required, requisite, sufficient, or optional.

module_options

specifies available options for the LoginModule. These options vary depending on the LoginModulebeing used.

The following examples show that the LoginModule used for a Kerberos implementation depends on your JRE.

Oracle JRE


};

IBM JRE

JDBC_DRIVER_01 {com.ibm.security.auth.module.Krb5LoginModule required useDefaultCcache=true;

};

Refer to Java Authentication and Authorization Service documentation for information about the JAAS loginconfiguration file and implementing authentication technologies.

See alsoConfiguring the Driver for Kerberos Authentication on page 57LoginConfigName on page 143

The krb5.conf FileThe krb5.conf file contains Kerberos configuration information. Typically, the default realm name and theKDC name for that realm are specified in the krb5.conf file. However, you can specify the realm and KDCnames directly in your application with the java.security.krb5.realm and java.security.krb5.kdcsystem properties. Setting these system properties will override the settings in the krb5.conf file.

When a client application does not use the java.security.krb5.realm and java.security.krb5.kdcsystem properties, the JVM looks for a krb5.conf file that contains the realm and KDC names. The JVM firstlooks for the krb5.conf file in the location specified with the java.security.krb5.conf system property.If this system property has not been used, then the JVM continues looking for the krb5.conf file using aninternal algorithm. The JVM must be able to locate the krb5.conf to establish a Kerberos connection. Referto your vendor's JVM documentation for the list of directories that the JVM searches in order to find thekrb5.conf file.



Depending on your environment, other modifications may need to be made to your krb5.conf file. Refer tothe following resources for more information on configuring Kerberos and the krb5.conf file.

• Your database vendor documentation

• "Keberos Requirements" in Java™ Documentation

• "krb5.conf" in MIT Kerberos Documentation


Specifying User Credentials for Kerberos Authentication (Delegation ofCredentials)By default, when Kerberos authentication is used, the driver takes advantage of the user name and passwordmaintained by the operating system to authenticate users to the database. By allowing the database to sharethe user name and password used for the operating system, users with a valid operating system account canlog into the database without supplying a user name and password.

Many application servers or Web servers act on behalf of the client user logged on the machine on which theapplication is running, rather than the server user. If you want the driver to use user credentials other than theoperating system user name and password, include code in your application to obtain and pass ajavax.security.auth.Subject used for authentication as shown in the following example.

import javax.security.auth.Subject;import javax.security.auth.login.LoginContext;import java.sql.*;// The following code creates a javax.security.auth.Subject instance// used for authentication. Refer to the Java Authentication// and Authorization Service documentation for details on using a// LoginContext to obtain a Subject.LoginContext lc = null;Subject subject = null;try {

lc = new LoginContext("JaasSample", new TextCallbackHandler());lc.login();subject = lc.getSubject();

}catch (Exception le) {

... // display login error}// This application passes the javax.security.auth.Subject// to the driver by executing the driver code as the subjectConnection con =

(Connection) Subject.doAs(subject, new PrivilegedExceptionAction() {

public Object run() {

Connection con = null;try {

Class.forName("com.ddtek.jdbc.cassandra.CassandraDriver");String url = "jdbc:datadirect:cassandra://myServer:27017";con = DriverManager.getConnection(url);}

catch (Exception except) {... //log the connection error

Return null;}

return con;}

});


Authentication

// This application now has a connection that was authenticated with// the subject. The application can now use the connection.Statement stmt = con.createStatement();String sql = "SELECT * FROM employee";ResultSet rs = stmt.executeQuery(sql);... // do something with the results


Obtaining a Kerberos Ticket Granting TicketKerberos uses the credentials in a Ticket Granting Ticket (TGT) to verify the identity of users and control accessto services. Depending on your environment, you will need to establish a procedure for obtaining a TGT.

For Windows Active Directory configurations, Active Directory automatically obtains a TGT.

For non-Active Directory configurations, you can enable the application to obtain a TGT in one of two ways.First, you can automate the method of obtaining the TGT as with a keytab. Second, you can require theapplication user to obtain the TGT with a kinit command when logging on.

A TGT can be obtained directly with a kinit command to the Kerberos server. For example, the followingcommand requests a TGT from the server with a lifetime of 10 hours, which is renewable for 5 days.

kinit -l 10h -r 5d user@REALM

Note: The klist command can be used on Windows or UNIX/Linux systems to verify that a TGT has beenobtained.

Refer to your Kerberos documentation for more information on automating the process of obtaining a TGT.


Data EncryptionSSL works by allowing the client and server to send each other encrypted data that only they can decrypt. SSLnegotiates the terms of the encryption in a sequence of events known as the SSL handshake. The handshakeinvolves 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. 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).

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

4. 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.

5. 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.

See alsoData Encryption Properties on page 52Configuring SSL Server Authentication on page 65Configuring SSL Client Authentication on page 66

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.


Data Encryption

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

jdbc:datadirect:cassandra://MyServer:9042;KeyspaceName=MyKS;Password=secr3t;TrustStore=C:\Certficates\MyTruststore.jks;TrustStorePassword=MyTruststorePassword;User=jsmith;

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:

jdbc:datadirect:cassandra://MyServer:9042;KeyspaceName=MyKS;KeyStore=C:\Certficates\MyTruststore.jks;KeyStorePassword=MyKeystorePassword;Password=secr3t;User=jsmith;



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.

IdentifiersIdentifiers are used to refer to objects exposed by the driver, such as tables and columns. The driver supportsboth quoted and unquoted identifiers for naming objects. The maximum length of both quoted and unquotedidentifiers is 48 characters for table names and 128 characters for column names. Quoted identifiers must beenclosed in double quotation marks (""). The characters supported in quoted identifiers depends on the versionof Cassandra being used. For details on valid characters, refer to the Cassandra documentation for yourdatabase version.

Naming conflicts can arise from restrictions imposed by third party applications, from the normalization of nativedata, or from the truncation of object names. The driver avoids naming conflicts by appending an underscoreseparator and integer (for example, _1) to identifiers with the same name. For example, if a third party applicationrestricts the naming of three columns such that each column retains the name address, the driver wouldexpose the columns in the following manner:

• address

• address_1

• address_2

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

The server name specified in the connection URL, or data source, can resolve to an IPv4 or IPv6 address. Forexample, the following URL can resolve to either type of address::

jdbc:datadirect:cassandra://MyServer:9042;KeyspaceName=MyKS

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

jdbc:datadirect:cassandra://123.456.78.90:9042;KeyspaceName=MyKS

You also can specify addresses in either format using the ServerName data source property. The followingexample shows a data source definition that specifies the server name using IPv6 format:

CassandraDataSource mds = new CassandraDataSource();mds.setDescription("My CassandraDataSource");mds.setServerName("[ABCD:EF01:2345:6789:ABCD:EF01:2345:6789]");...

Note: When specifying IPv6 addresses in a connection URL or data source property, the address must beenclosed by brackets.


Identifiers

In addition to the normal IPv6 format, the drivers support IPv6 alternative formats for compressed and IPv4/IPv6combination addresses. For example, the following connection URL specifies the server using IPv6 format,but uses the compressed syntax for strings of zero bits:

jdbc:datadirect:cassandra://[2001:DB8:0:0:8:800:200C:417A]:9042;KeyspaceName=MyKS

Similarly, the following connection URL specifies the server using a combination of IPv4 and IPv6:

jdbc:datadirect:cassandra://[0000:0000:0000:0000:0000:FFFF:123.456.78.90]:54321;KeyspaceName=MyKS

For complete information about IPv6, go to the following URL:

http://tools.ietf.org/html/rfc4291#section-2.2

Parameter Metadata SupportThe driver supports returning parameter metadata as described in Insert and Update Statements on page 68and Select Statements on page 68.

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

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

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

• UPDATE employee SET col1=?, col2=?, col3=? WHERE col1 operator ? [{AND | OR}col2 operator ?]

where:

operator

is any of the following SQL operators:

=, <, >, <=, >=, and <>.

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 one of the following conditions is true:

• The statement contains a predicate value expression that can be targeted against the source tables in theassociated 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.



http://tools.ietf.org/html/rfc4291#section-2.2

• The statement contains a predicate value expression part that is a nested query. The nested query's metadatamust describe a single column. For example:

SELECT * FROM foo WHERE (SELECT x FROM y WHERE z = 1) < ?

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 = (SELECT col2 FROM t2 WHERE col3 = ?)SELECT ... WHERE colname LIKE ?SELECT ... WHERE colname BETWEEN ? and ?SELECT ... WHERE colname IN (?, ?, ?)SELECT ... WHERE EXISTS(SELECT ... FROM T2 WHERE col1 < ?)

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, b, c, d FROM T1 AS A, T2 AS B WHERE A.a = ? AND B.b = ?

Isolation LevelsApache Cassandra does not support transactions. However, manual transactions can be handled to somedegree with the TransactionMode connection property. See TransactionMode on page 157 for details.

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:


Isolation Levels

• 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][Cassandra 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][Cassandra JDBC Driver][Cassandra]Invalid Object Name.

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

Large Object (LOB) SupportThe driver allows you to retrieve LONGVARBINARY data, using JDBC methods designed for Binary LargeObjects (BLOBs). When using these methods to update long data as BLOBs, the updates are made to thelocal copy of the data contained in the BLOB object.

Retrieving and updating long data using JDBC methods designed for BLOBs provides some of the samebenefits as retrieving and updating BLOBs, such as:

• Provides random access to data

• Allows searching for patterns in the data

To provide the benefits normally associated with BLOBs, data must be cached. Because data is cached, yourapplication will incur a performance penalty, particularly if data is read once sequentially. This performancepenalty can be severe if the size of the long data is larger than available memory.

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

• CachedRowSets

• FilteredRowSets

• WebRowSets

• JoinRowSets

• JDBCRowSets

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



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

Executing CQLThe driver supports new Native and Refresh escape sequences to embed CQL commands in SQL-92 statements.The Native escape sequence allows you to execute CQL directly through the client application. The Refreshescape sequence is then used to incorporate any changes introduced by the Native escape into the driver'srelational map of the data.

Note: The Native and Refresh escape sequences are mainly intended for the execution of DDL commands,such as ALTER, CREATE, and DROP. A returning clause for the Native escape is not currently supported bythe driver. Therefore, results cannot be retrieved using the Native escape sequence.

See alsoNative and Refresh Escape Sequences on page 208

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.

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.


Executing CQL

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.

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 Data Source ObjectThe following Java code example creates a Progress DataDirect data source object and registers it with a JNDInaming service.

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


Connection Pool Manager

//************************************************************************// 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 Progress DataDirect for JDBC Drivers.//// This data source registers its name as <jdbc/ConnectCassandra>.//// 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 Progress DataDirect for JDBC:import com.ddtek.jdbcx.cassandra.CassandraDataSource;import javax.sql.*;import java.sql.*;import javax.naming.*;import javax.naming.directory.*;import java.util.Hashtable;public class CassandraDataSourceRegisterJNDI{ public static void main(String argv[])

{try {// Set up data source reference data for naming context:// ----------------------------------------------------// Create a class instance that implements the interface// ConnectionPoolDataSourceCassandraDataSource ds = new CassandraDataSource();ds.setDescription("Cassandra Data Source");ds.setServerName("Server1");ds.setPortNumber(9042);ds.setKeyspaceName(MyKeyspace);ds.setUser("test");ds.setPassword("secret");// 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 servicectx.bind("jdbc/ConnectCassandra", ds);} catch (Exception e) {System.out.println(e);return;}

} // Main// class CassandraDataSourceRegisterJNDI

See alsoImplementing DataDirect Connection Pooling on page 73Creating the Connection Pool on page 74

Creating the Connection PoolAfter the Progress DataDirect data source object has been created and registered, you must create thePooledConnectionDataSource object and register it with a JNDI naming service as shown in the followingJava code example.



Note: The parameter of the DataSourceName method must be set to the JNDI name of a registered driverDataSource object. This specifies the driver DataSource object to be used by the connection pool. Thefollowing code example sets the parameter of the DataSourceName method to the JNDI name of the driverDataSource object created in the previous topic, "Creating a Driver DataSource Object."

//************************************************************************// 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// Progress DataDirect for JDBC driver DataSource object.//// This data source registers its name as <jdbc/PoolCassandra>.//// 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("Cassandra Data Source");

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

// 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 seconds



ds.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/PoolCassandra", ds);

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

}}

}

See alsoImplementing DataDirect Connection Pooling on page 73Creating a Driver Data Source Object on page 73

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 79

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 connection



for 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 80

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."

//********************************************************************// 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/PoolCassandra>//********************************************************************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 asthe command-line argument when you run the preceding application. For example, the following commandspecifies the driver DataSource object created in "Creating a Driver DataSource Object": javaTestDataSourceApp jdbc/ConnectCassandra.

See alsoCreating a Driver Data Source Object on page 73Creating the Connection Pool on page 74PooledConnectionDataSource on page 80

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 166

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 76

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()

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 ExtStatementPoolMonitorobject for the statement pool associated with the connection. This method is provided by the ExtConnectioninterface in the com.ddtek.jdbc.extensions package. If the connection does not have a statement pool,the method returns null.

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

See alsoMaxPooledStatements on page 145

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)

• 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 24: 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


Statement Pool Monitor

DescriptionValueParameter

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 howto generate a list of statements in the statement pool associated with the connection.

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.cassandra.CassandraDriver");con = DriverManager.getConnection(

"jdbc:datadirect:cassandra://MyServer:9042;" +"KeyspaceName=MyKS" +"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 poolregardless of statement type, result set cursor type, and concurrency type by specifying the value -1 for eachparameter as 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 the MaxPooled Statements propery, and the Statement Pool Monitor MBean must be registeredusing the RegisterStatementPoolMonitorMBean 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. Thefollowing code shows how to use the standard JMX API calls to return the state of all active statement poolsin 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 145RegisterStatementPoolMonitorMBean on page 150



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 the "Statement Pool Export File Example" topic for an example ofa statement pool 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:cassandra://MyServer:9042;KeyspaceName=MyKS;User=admin;Password=secret;ImportStatementPool=C:\\statement_pooling\\stmt_export.txt

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

ExtStatementPoolMonitor monitor =((ExtConnection) con).getStatementPoolMonitor().importStatements("C:\\statement_pooling\\stmt_export.txt");

See alsoStatement Pool Export File Example on page 170Generating a Statement Pool Export File on page 90

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 170

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()



DescriptionExtStatementPoolMonitorMBean Methods

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.

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


DataDirect Test

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:

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.


DataDirect Test



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.



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.


DataDirect Test

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:



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.


DataDirect Test

6. If you want to insert multiple records, repeat Step 3 on page 98 and Step 5 on page 99 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.



See alsoExecuting a Simple Select Statement on page 97

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.


DataDirect Test

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.



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.


DataDirect Test

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.



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.


DataDirect Test

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 105 through Step 4 on page 106 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.



See alsoExecuting a Simple Select Statement on page 97

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.


DataDirect Test

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.



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.


DataDirect Test

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.



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.


DataDirect Test

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.



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.


DataDirect Test

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

Inserting a Row









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



DataDirect Test

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.



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






DataDirect Test



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






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

10. Click Update Row.


12. Specify the statement that you want to execute.


DataDirect Test


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.






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


DataDirect Test

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

9. Change the data type to Clob.



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


DataDirect Test

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



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 163

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 DriverManagerThe SpyAttributes connection property allows you to specify a semi-colon separated list of DataDirect Spyattributes. The format for the value of the SpyAttributes property is:

(spy_attribute[;spy_attribute]...)

where spy_attribute is any valid DataDirect Spy attribute.

Windows ExampleClass.forName("com.ddtek.jdbc.cassandra.CassandraDriver");Connection conn = DriverManager.getConnection

("jdbc:datadirect:cassandra://MyServer:9042;KeyspaceName=MyKS;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_.


Tracking JDBC Calls with DataDirect Spy

Using this example, DataDirect Spy loads the driver and logs all JDBC activity to the spy_x.log file locatedin the C:\temp directory (log=(filePrefix)C:\\temp\\spy_), where x is an integer that increments by1 for each connection on which the prefix is specified. The spy_x.log file logs a maximum of 80 characterson each line (linelimit=80) and includes the name of the current thread (logTName=yes) and a timestampon each line in the log (timestamp=yes).

UNIX ExampleClass.forName("com.ddtek.jdbc.cassandra.CassandraDriver");Connection conn = DriverManager.getConnection

("jdbc:datadirect:cassandra://MyServer:9042;KeyspaceName=MyKS;SpyAttributes=(log=(filePrefix)/tmp/spy_;logTName=yes;timestamp=yes)");

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

See alsoDataDirect Spy Attributes on page 127SpyAttributes on page 156

Using Data SourcesYou can use DataDirect Spy to track JDBC calls made by a running application with either of these features:

• JNDI for Naming Databases

• Connection Pooling

The com.ddtek.jdbcx.cassandra.CassandraDataSource class supports setting a semi-colon-separatedlist of DataDirect Spy attributes.

Example on Windows:CassandraDataSource sds=new CassandraDataSource():sds.setServerName("MyServer");sds.setPortNumber(9042);sds.setKeyspaceName(MyKS);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 driver and log all JDBC activity to the spy.log file locatedin the C:\temp directory (log=(file)C:\\temp\\spy.log). In addition to regular JDBC activity, thespy.log file also logs activity on InputStream and Reader objects (logIS=yes). It also includes the name ofthe current thread (logTName=yes).

Example on UNIX:CassandraDataSource mds = new CassandraDataSource();mds.setServerName("MyServer");



mds.setPortNumber(9042);mds.setKeyspaceName(MyKS);mds.setSpyAttributes("log=(file)/tmp/spy.log;logTName=yes");Connection conn=mds.getConnection("TEST","secret");...

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

See alsoDataDirect Spy Attributes on page 127SpyAttributes on page 156

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

Table 25: 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

Directs logging to the file specified by filename.

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 named ForWindows, 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:file_prefixX.log

where:

X

For Windows, if coding a path to the log file inis an integer that incrementsby 1 for each connection on which the prefix is specified.

For example, if the attribute log=(filePrefix) C:\\temp\\spy_ is specifiedon multiple connections, 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


Tracking JDBC Calls with DataDirect Spy

DescriptionAttribute

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

Specifies whether DataDirect Spy logs activity on InputStream and Readerobjects.

When logIS=nosingleread, logging on InputStream and Reader objects isactive; however, logging of the single-byte read InputStream.read orsingle-character Reader.read is suppressed to prevent generating large log filesthat contain single-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}



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). Connection property names arecase-insensitive. For example, Password is the same as password.

Note: In a JDBC data source, string values must be enclosed in double quotation marks, for example,setKeyspaceName("MyKS").

Note: The data type listed in each of the connection property descriptions is the Java data type used for theproperty value in a JDBC data source.

The following table provides a summary of the connection properties supported by the driver, their correspondingdata source methods, and their default values.

Table 26: Driver Properties

Default ValueData Source MethodConnection String Property

userIdPasswordsetAuthenticationMethodAuthenticationMethod on page 132

notExistsetCreateMapCreateMap on page 133

noEncryptionsetEncryptionMethodEncryptionMethod on page 134

100 (rows)setFetchSizeFetchSize on page 135



Empty stringsetHostNameInCertificateHostNameInCertificate on page 136

No default valuesetImportStatementPoolImportStatementPool on page 137

No default valuesetInitializationStringInitializationString on page 138

2048 (KB)setInsensitiveResultSetBufferSizeInsensitiveResultSetBufferSize on page139

No default valuesetKeyPasswordKeyPassword on page 140

No default valuesetKeyspaceNameKeyspaceName on page 140

No default valuesetKeyStoreKeyStore on page 141

No default valuesetKeyStorePasswordKeyStorePassword on page 142

ddlogging.propertiessetLogConfigFileLogConfigFile on page 143

JDBC_DRIVER_01setLoginConfigNameLoginConfigName on page 143

0setLoginTimeoutLoginTimeout on page 144

0setMaxPooledStatementsMaxPooledStatements on page 145

10000 (rows)setNativeFetchSizeNativeFetchSize on page 146

No default valuesetPasswordPassword on page 147

9042setPortNumberPortNumber on page 148

quorumsetReadConsistencyReadConsistency on page 149

truesetReadOnlyReadOnly on page 150

falsesetRegisterStatementPoolMonitorMBeanRegisterStatementPoolMonitorMBeanon page 150

-1setResultMemorySizeResultMemorySize on page 151

For Windows:

application_data_folder\Local\Progress\DataDirect\Cassandra_Schema\servername.config

For UNIX/Linux:

˜/progress/datadirect/cassandra_schema/servername.config

setSchemaMapSchemaMap on page 153


Chapter 4: Connection Property Descriptions


No default valuesetServerNameServerName on page 154

Driver builds value based onenvironment

setServicePrincipalNameServicePrincipalName on page 155

No default valuesetSpyAttributesSpyAttributes on page 156

noTransactionssetTransactionModeTransactionMode on page 157

No default valuesetTrustStoreTrustStore on page 158

No default valuesetTrustStorePasswordTrustStorePassword on page 159

No default valuesetUserUser on page 159

No default valuesetValidateServerCertificateValidateServerCertificate on page 160

quorumsetWriteConsistencyWriteConsistency on page 161


• AuthenticationMethod

• CreateMap

• EncryptionMethod

• FetchSize

• HostNameInCertificate

• ImportStatementPool

• InitializationString

• InsensitiveResultSetBufferSize

• KeyPassword

• KeyspaceName

• KeyStore

• KeyStorePassword

• LogConfigFile

• LoginConfigName

• LoginTimeout

• MaxPooledStatements

• NativeFetchSize

• Password


• PortNumber

• ReadConsistency

• ReadOnly

• RegisterStatementPoolMonitorMBean

• ResultMemorySize

• SchemaMap

• ServerName

• ServicePrincipalName

• SpyAttributes

• TransactionMode

• TrustStore

• TrustStorePassword

• User

• ValidateServerCertificate

• WriteConsistency

AuthenticationMethodPurposeDetermines which authentication mechanism the driver uses when establishing a connection.

Valid Valuesnone | kerberos | userIdPassword

BehaviorIf set to none, the driver does not attempt to authenticate with the server.

If set to kerberos, the driver uses Kerberos authentication.

If set to userIdPassword, the driver uses SCRAM-SHA-1 user ID/password authentication. The User propertyprovides the user ID, and the Password property provides the password.

Notes• In a scenario where AuthenticationMethod has been set to userIdPassword but the server has not been

configured for user ID/password authentication, the driver will still connect to the database server.

• If authentication has not been enabled, client applications will have access to all keyspaces on the server.If authentication has been enabled, a client application will only have access to the keyspace specified bythe KeyspaceName property assuming it has the required permissions.



Data Source MethodsetAuthenticationMethod

DefaultuserIdPassword

Data TypeString

See also• Authentication on page 56

• Authentication Properties on page 51

CreateMapPurposeDetermines whether the driver creates the internal files required for a relational view of the native data whenestablishing a connection.

Valid ValuesforceNew | no | notExist

BehaviorIf set to forceNew, the driver deletes the group of internal files specified by SchemaMap and creates a newgroup of these files at the same location.

If set to no, the driver uses the current group of internal files specified by SchemaMap. If the files do not exist,the connection fails.

If set to notExist, the driver uses the current group of internal files specified by SchemaMap. If the files donot exist, the driver creates them.

Notes• The internal files share the same directory as the schema map's configuration file. This directory is specified

with the SchemaMap connection property.

• You can refresh the internal files related to an existing relational view of your data with the SQL extensionRefresh Map. Refresh Map runs a discovery against your native data and updates your internal filesaccordingly.

• CreateMap was formerly CreateDB.

Data Source MethodsetCreateMap


CreateMap

DefaultnotExist

Data TypeString

See also• SchemaMap on page 153

• Refresh Map (EXT) on page 180

• Mapping Properties on page 51

EncryptionMethodPurposeDetermines whether data is encrypted and decrypted when transmitted over the network between the driverand database server.

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.

NotesWhen SSL is enabled, the following properties also apply:

• 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 also• Data Encryption on page 64

• Performance Considerations on page 55

FetchSizePurposeSpecifies the number of rows that the driver processes before returning data to the application when executinga Select. This value provides a suggestion to the driver as to the number of rows it should internally processbefore returning control to the application. The driver may fetch fewer rows to conserve memory when processingexceptionally wide rows.

Valid Values0 | x

where:

x

is a positive integer indicating the number of rows that should be processed.

BehaviorIf set to 0, the driver processes all the rows of the result before returning control to the application. When largedata sets are being processed, setting FetchSize to 0 can diminish performance and increase the likelihoodof out-of-memory errors.

If set to x, the driver limits the number of rows that may be processed for each fetch request before returningcontrol to the application.

Notes• To optimize throughput and conserve memory, the driver uses an internal algorithm to determine how many

rows should be processed based on the width of rows in the result set. Therefore, the driver may processfewer rows than specified by FetchSize when the result set contains exceptionally wide rows. Alternatively,the driver processes the number of rows specified by FetchSize when the result set contains rows ofunexceptional width.

• FetchSize can be used to adjust the trade-off between throughput and response time. Smaller fetch sizescan improve the initial response time of the query. Larger fetch sizes can improve overall response timesat the cost of additional memory.

• You can use FetchSize to reduce demands on memory and decrease the likelihood of out-of-memory errors.Simply, decrease FetchSize to reduce the number of rows the driver is required to process before returningdata to the application.

• The ResultMemorySize connection property can also be used to reduce demands on memory and decreasethe likelihood of out-of-memory errors.


FetchSize

• FetchSize is related to, but different than, NativeFetchSize. NativeFetchSize specifies the number of rowsof raw data that the driver fetches from the native data source, while FetchSize specifies how many of theserows the driver processes before returning control to the application. Processing the data includes convertingnative data types to SQL data types used by the application. If FetchSize is greater than NativeFetchSize,the driver may make multiple round trips to the data source to get the requested number of rows beforereturning control to the application.

Data Source MethodsetFetchSize

Default100 (rows)

Data TypeInt

See also• Additional Properties on page 54


• NativeFetchSize on page 146

• ResultMemorySize on page 151

• Troubleshooting Out-of-Memory Errors on page 171

HostNameInCertificatePurposeSpecifies a host name for certificate validation when SSL encryption is enabled (EncryptionMethod=SSL) andvalidation is enabled (ValidateServerCertificate=true). This property is optional and provides additional securityagainst man-in-the-middle (MITM) attacks by ensuring that the server the driver is connecting to is the serverthat 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

See alsoData Encryption on page 64

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.

Valid Valuesstring

where:

string

is the path and file name of the file to be used to load the contents of the statement pool.


ImportStatementPool

NotesIf the driver cannot locate the specified file when establishing the connection, the connection fails and the driverthrows an exception.

Data Source MethodsetImportStatementPool

DefaultNo default value

Data TypeString

See also• Statement Pool Monitor on page 84

• Importing Statements into a Statement Pool on page 89

• Statement Pooling Properties on page 53

• MaxPooledStatements on page 145

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.

Data Source MethodsetInitializationString




Data TypeString

See alsoAdditional Properties on page 54

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 in KB.

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.

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 (KB)

Data TypeInt


InsensitiveResultSetBufferSize


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 property isuseful 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


KeyspaceNamePurposeSpecifies the default name of the Cassandra keyspace to which the driver connects. This value is used as thedefault qualifier for unqualified table names in SQL queries.

Valid Valueskeyspace_name

where:



keyspace_name

is the name of a valid CQL keyspace. If the driver cannot find the specified keyspace, the connectionfails.

Notes• A Cassandra keyspace is equivalent to a relational database.

• If KeyspaceName is not specified, Cassandra's internal keyspace name system will be used.

• If authentication has not been enabled, client applications will have access to all keyspaces on the server.If authentication has been enabled, a client application will only have access to the keyspace specified bythe KeyspaceName property assuming it has the required permissions.

Data Source MethodsetKeyspaceName


Data TypeString

See alsoRequired Properties on page 50

KeyStorePurposeSpecifies the directory of the keystore file to be used when SSL is enabled (EncryptionMethod=SSL) and SSLclient authentication is enabled on the database server. The keystore file contains the certificates that the clientsends to the server in response to the server’s certificate request.

Valid Valuesstring

where:

string

is a valid directory of a keystore file.

Notes• This value overrides the directory of the keystore file that is specified by the javax.net.ssl.keyStore Java

system property. If this property is not specified, the keystore directory is specified by thejavax.net.ssl.keyStore Java system property.

• The keystore and truststore files can be the same file.


KeyStore

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.

Valid Valuesstring

where:

string

is a valid password.

Notes• This value overrides the password of the keystore file that is specified by the javax.net.ssl.keyStorePassword

Java system property. If this property is not specified, the keystore password is specified by thejavax.net.ssl.keyStorePassword Java system property.

• The keystore and truststore files can be the same file.

Data Source MethodsetKeyStorePassword

DefaultNone

Data TypeString




LogConfigFilePurposeSpecifies the filename of the configuration file used to initialize driver logging. If the driver cannot locate thespecified file when establishing the connection, the connection fails and the driver returns an error.

Valid Valuesstring

where:

string

is the relative or fully qualified path of the configuration file used to initialize driver logging. If thespecified file does not exist, the driver continues searching for an appropriate configuration file asdescribed in "Using the Driver for Logging".

Data Source MethodsetLogConfigFile

Defaultddlogging.properties

Data TypeString


• Using the Driver for Logging on page 174

LoginConfigNamePurposeSpecifies the name of the entry in the JAAS login configuration file that contains the authentication technologyused by the driver to establish a Kerberos connection. The LoginModule-specific items found in the entry arepassed on to the LoginModule.

Valid Valuesentry_name


LogConfigFile

where:

entry_name

is the name of the entry that contains the authentication technology used with the driver.

ExampleIn the following example, JDBC_DRIVER_01 is the entry name while the authentication technology and relatedsettings are found in the brackets.


};

Data Source MethodsetLoginConfigName

DefaultJDBC_DRIVER_01

Data TypeString


• The JAAS Login Configuration File on page 61


LoginTimeoutPurposeThe amount of time, in seconds, that the driver waits for a connection to be established before timing out theconnection 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


MaxPooledStatementsPurposeSpecifies the maximum number of prepared statements to be pooled for each connection and enables thedriver’s internal prepared statement pooling when set to an integer greater than zero (0). The driver’s internalprepared statement pooling provides performance benefits when the driver is not running from within anapplication server or another application that provides its own statement pooling.

Valid Values0 | x

where:

x

is a positive integer that represents a number of prepared statements to be cached.

BehaviorIf set to 0, the driver’s internal prepared statement pooling is not enabled.

If set to x, the driver’s internal prepared statement pooling is enabled and the driver uses the specified valueto cache up to that many prepared statements created by an application. If the value set for this property isgreater than the number of prepared statements that are used by the application, all prepared statements thatare created by the application are cached. Because CallableStatement is a sub-class of PreparedStatement,CallableStatements also are cached.

NotesWhen you enable statement pooling, your applications can access the Statement Pool Monitor directly withDataDirect-specific methods. However, you can also enable the Statement Pool Monitor as a JMX MBean. Toenable the Statement Pool Monitor as an MBean, statement pooling must be enabled with MaxPooledStatementsand the Statement Pool Monitor MBean must be registered using the RegisterStatementPoolMonitorMBeanconnection property.


MaxPooledStatements

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




• RegisterStatementPoolMonitorMBean on page 150

NativeFetchSizePurposeSpecifies the number of rows of data the driver attempts to fetch from the native data source on each requestsubmitted to the server.

Valid Values0 | x

where:

x

is a positive integer that defines the number of rows.

BehaviorIf set to 0, the driver requests that the server return all rows for each request submitted to the server. Blockfetching is not used.

If set to x, the driver attempts to fetch up to a maximum of the specified number of rows on each requestsubmitted to the server.



NotesNativeFetchSize is related to, but different than, FetchSize. NativeFetchSize specifies the number of rows ofraw data that the driver fetches from the native data source, while FetchSize specifies how many of these rowsthe driver processes before returning control to the application. Processing the data includes converting nativedata types to SQL data types used by the application. If FetchSize is greater than NativeFetchSize, the drivermay make multiple round trips to the data source to get the requested number of rows before returning controlto the application.

Data Source MethodsetNativeFetchSize

Default10000 (rows)

Data TypeInt



• FetchSize on page 135

• ResultMemorySize on page 151


PasswordDescriptionSpecifies the password used to connect to your database for user ID/password authentication.

Important: Setting the password using a data source is not recommended. The data source persists allproperties, including Password, in clear text.

Valid Valuespassword

where:

password

is a valid password. The password is case-sensitive.

NotesWhen AuthenticationMethod=kerberos, the driver ignores the Password property.


Password

Data Source MethodsetPassword


Data TypeString



PortNumberPurposeSpecifies the port number of the server that is listening for connections to the Cassandra keyspace.

Valid Valuesport

where:

port

is the number port of the server listener.

Data Source MethodsetPortNumber

Default9042

Data TypeInt

See alsoRequired Properties on page 50



ReadConsistencyPurposeSpecifies how many replicas must respond to a read request before returning data to the client application.

Valid Valuesall | quorum | one | all | each_quorum | quorum | local_quorum | one | two | three | local_one |serial | local_serial

BehaviorIf set to all, data is returned to the application after all replicas have responded. This setting provides thehighest consistency and lowest availability.

(Cassandra 2.x only) If set to each_quorum, data is returned after a quorum of replicas in each data centerof the cluster has responded.

If set to quorum, data is returned after a quorum of replicas has responded from any data center.

If set to local_quorum, data is returned after a quorum of replicas in the same data center as the coordinatornode has responded. This setting voids latency of inter-data center communication.

If set to one, data is returned from the closest replica. This setting provides the highest availability, but increasesthe likelihood of stale data being read.

If set to two, data is returned from two of the closest replicas.

If set to three, data is returned from three of the closest replicas.

If set to local_one, data is returned from the closest replica in the local data center.

If set to serial, the data is read without proposing a new addition or update. Uncommitted transactions arecommitted as part of the read.

If set to local_serial, the data within a data center is read without proposing a new addition or update.Uncommitted transactions within the data center are committed as part of the read.

Notes• If the server does not support the ReadConsistency value specified, the connection attempt fails and the

driver returns a consistency level error.

• Refer to Apache Cassandra documentation for more information about configuring consistency levels,including usage scenarios.

• If you wish to specify a ReadConsistency value besides the values documented in this section, contactTechnical Support.

Data Source MethodsetReadConsistency

Defaultquorum


ReadConsistency


Data TypeString



• ReadOnly on page 150

• WriteConsistency on page 161

ReadOnlyPurposeSpecifies whether the connection supports read-only access to the data source.

Valid Valuestrue | false

BehaviorIf set to true, the connection supports read-only access.

If set to false, the connection supports read-write access.

Data Source MethodsetReadOnly

Defaulttrue

Data TypeBoolean


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 145

ResultMemorySizePurposeSpecifies the maximum size, in megabytes, of an intermediate result set that the driver holds in memory. Whenthis threshold is reached, the driver writes a portion of the result set to disk in temporary files.

Valid Values-1 | 0 | x

where:

x

is the maximum size, in MB, of an intermediate result set that the driver holds in memory.


ResultMemorySize

BehaviorIf set to -1, the maximum size of an intermediate result that the driver holds in memory is a percentage of themax Java heap size. When this threshold is reached, the driver writes a portion of the result set to disk.

If set to 0, the driver holds the entire intermediate result set in memory regardless of size. No portion of theresult set is written to disk. Setting ResultMemorySize to 0 can improve performance for result sets that easilyfit within the JVM's free heap space, but can diminish performance for result sets that barely fit within the JVM'sfree heap space.

If set to x, the driver holds intermediate results in memory that are no larger than the size specified. When thisthreshold is reached, the driver writes a portion of the result set to disk.

Notes• By default, ResultMemorySize is set to -1. When set to -1, the maximum size of an intermediate result

that the driver holds in memory is a percentage of the max Java heap size. When processing large sets ofdata, out-of-memory errors can occur when the size of the result set exceeds the available memory allocatedto the JVM. In this scenario, you can tune ResultMemorySize to suit your environment. To begin, setResultMemorySize equal to the max Java heap size divided by 4. Proceed by decreasing this value untilout-of-memory errors are eliminated. As a result, the maximum size of an intermediate result set the driverholds in memory will be reduced, and some portion of the result set will be written to disk. Be aware thatwhile writing to disk reduces the risk of out-of-memory errors, it also negatively impacts performance. Foroptimal performance, decrease this value only to a size necessary to avoid errors.

• You can also adjust the max Java heap size to address memory and performance concerns. By increasingthe max Java heap size, you increase the amount of data the driver accumulates in memory. This canreduce the likelihood of out-of-memory errors and improve performance by ensuring that result sets fit easilywithin the JVM's free heap space. In addition, when a limit is imposed by setting ResultMemorySize to -1,increasing the max Java heap size can improve performance by reducing the need to write to disk, orremoving it altogether.

• The FetchSize connection property can also be used to reduce demands on memory and decrease thelikelihood of out-of-memory errors.

Data Source MethodsetResultMemorySize

Default-1

Data TypeInt



• FetchSize on page 135




SchemaMapPurposeSpecifies the name and location of the configuration file used to create the relational map of native data. Thedriver looks for this file when connecting to the server. If the file does not exist, the driver creates one.

Valid Valuesstring

where:

string

is the absolute path and filename of the configuration file, including the .config extension. Forexample, if SchemaMap is set to a value ofC:\\Users\\Default\\AppData\\Local\\Progress\\DataDirect\\Cassandra_Schema\\MyServer.config,the driver either creates or looks for the configuration file MyServer.config in the directoryC:\Users\Default\AppData\Local\Progress\DataDirect\Cassandra_Schema\.

Notes• When connecting to a server, the driver looks for the SchemaMap configuration file. If the configuration file

does not exist, the driver creates a SchemaMap configuration file using the name and location you haveprovided. If you do not provide a name and location for a SchemaMap configuration file, the driver createsit using default values.

• The driver uses the path specified in this connection property to store additional internal files.

• You can refresh the internal files related to an existing relational view of your data by using the SQL extensionRefresh Map. Refresh Map runs a discovery against your native data and updates your internal filesaccordingly.

ExampleAs the following examples show, escapes are needed when specifying SchemaMap for a data source but arenot used when specifying SchemaMap in a Driver Manager connection URL.

Driver Manager Example

jdbc:datadirect:cassandra://MyServer:9042;KeyspaceName=MyKS;SchemaMap=C:\Users\Default\AppData\Local\Progress\DataDirect

\Cassandra_Schema\MyServer.config

Data Source Example

CassandraDataSource mds = new CassandraDataSource();mds.setDescription("My CassandraDataSource");mds.setServerName("MyServer");mds.setPortNumber(9042);mds.setKeyspaceName("MyKS");mds.setSchemaMap("C:\\Users\\Default\\AppData\\Local\\Progress

\\DataDirect\\Cassandra_Schema\\MyServer.config")

Data Source MethodsetSchemaMap


SchemaMap

Default• For Windows XP and Windows Server 2003

• userprofile\ApplicationData\Local\Progress\DataDirect\Cassandra_Schema\servername.config

• For other Windows platforms

• User data source:userprofile\AppData\Local\Progress\DataDirect\Cassandra_Schema\servername.config

• System data source:C:\Users\Default\AppData\Local\Progress\DataDirect\Cassandra_Schema\servername.config

• For UNIX/Linux

• ˜/progress/datadirect/cassandra_schema/servername.config

Data TypeString

See also• Complex Type Normalization on page 15

• Refresh Map (EXT) on page 180

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

Important: In a Kerberos configuration, an IP address cannot be used for the ServerName connection property.The value of the ServerName property must be the same as the fully qualified host name used in the Kerberosservice principal name.

Valid Valuesserver_name | IP_address

where:

server_name

is the name of the server to which you want to connect.

IP_address

is the IP address of the server to which you want to connect.

The IP address can be specified in either IPv4 or IPv6 format, or a combination of the two.



ExampleIf your network supports named servers, you can specify a server name such as MyServer, or you can specifyan IP address such as 199.226.224.34.

Data Source MethodsetServerName


Data TypeString

See also• Required Properties on page 50

• IP Addresses on page 67

ServicePrincipalNamePurposeSpecifies the three-part service principal name registered with the key distribution center (KDC) in a Kerberosconfiguration.

Valid ValuesService_Name/Fully_Qualified_Domain_Name@REALM_NAME

where:

Service_Name

is the name of the service hosting the instance. The default value is cassandra.

Fully_Qualified_Domain_Name

is the fully qualified domain name (FQDN) of the host machine. (The FQDN consists of a host nameand a domain name. For the example myserver.test.com, myserver is the host name andtest.com is the domain name.) The FQDN registered with the KDC must match the FQDN in yourconnection string.

REALM_NAME

is the Kerberos realm name. This part of the value must be specified in upper-case characters, forexample, EXAMPLE.COM. For Windows Active Directory, the Kerberos realm name is the Windowsdomain name.


ServicePrincipalName

Notes• If the ServicePrincipalName property is unspecified, the driver builds a service principal name in the following

manner.

• cassandra is used as the service name.

• The FQDN is obtained from the connection string.

• The default realm in the krb5.conf file is used as the realm name.

• You must specify a value for the ServicePrincipalName property if any of the following statements are valid.

• You are using a service name other than the default service name cassandra.

• The FQDN in your connection string is different from the FQDN registered with the KDC.

• You are using a Kerberos realm other than the default realm specified in the krb5.conf file.

• In a Kerberos configuration, an IP address cannot be used as a FQDN.

• If AuthenticationMethod is set to userIdPassword, the value of the ServicePrincipalName property isignored.

ExampleThe following is an example of a valid service principal name.

cassandra/[email protected]

DefaultDriver builds value based on environment



• The krb5.conf File on page 62

SpyAttributesPurposeEnables DataDirect Spy to log detailed information about calls that are issued by the driver on behalf of theapplication. DataDirect Spy is not enabled by default.

Valid Values( spy_attribute [; spy_attribute ]...)

where:

spy_attribute

is any valid DataDirect Spy attribute. See "DataDirect Spy Attributes" for a list of supported attributes.



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


Data TypeString

See also• Tracking JDBC Calls with DataDirect Spy on page 125

• DataDirect Spy Attributes on page 127

TransactionModePurposeSpecifies how the driver handles manual transactions.

Valid ValuesnoTransactions | ignore

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 return an error indicating that no transaction is started. Metadata indicatesthat the driver supports transactions and the ReadUncommitted 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.

Data Source MethodsetTransactionMode


TransactionMode

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.

Valid Valuesstring

where:

string

is the directory of the truststore file.

Notes• This value overrides the directory of the truststore file that is specified by the javax.net.ssl.trustStore Java

system property. If this property is not specified, the truststore directory is specified by thejavax.net.ssl.trustStore Java system property.

• This property is ignored if ValidateServerCertificate=false.

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.

Valid Valuesstring

where:

string

is a valid password for the truststore file.

Notes• This value overrides the password of the truststore file that is specified by the javax.net.ssl.trustStorePassword

Java system property. If this property is not specified, the truststore password is specified by thejavax.net.ssl.trustStorePassword Java system property.

• This property is ignored if ValidateServerCertificate=false.

Data Source MethodsetTrustStorePassword

DefaultNone

Data TypeString


UserPurposeSpecifies the user ID for user ID/password authentication or the user principal name for Kerberos authentication.

Valid Valuesuserid | user_principal_name

where:


TrustStorePassword

userid

is a valid user ID with permissions to access the keyspace using user ID/password authentication.

user_principal_name

is a valid Kerberos user principal name with permissions to access the keyspace using Kerberosauthentication.

NotesWhen AuthenticationMethod=kerberos, the User property does not have to be specified. The driveruses the user principal name in the Kerberos Ticket Granting Ticket (TGT) as the value for the User property.Any value specified must be a valid Kerberos user principal name used in the Kerberos authentication protocol.

Data Source MethodsetUser


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 by theserver must be issued by a trusted Certificate Authority (CA).


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.



Notes• Truststore information is specified using the TrustStore and TrustStorePassword properties or by using

Java system properties.

• Allowing the driver to trust any certificate that is returned from the server even if the issuer is not a trustedCA is useful in test environments because it eliminates the need to specify truststore information on eachclient in the test environment.

Data Source MethodsetValidateServerCertificate

Defaulttrue

Data Typeboolean


WriteConsistencyPurposeDetermines the number of replicas on which the write must succeed before returning an acknowledgment tothe client application.

Valid Valuesall | quorum | one | all | each_quorum | quorum | local_quorum | one | two | three | local_one |any | serial | local_serial

BehaviorIf set to all, a write must succeed on all replica nodes in the cluster for that partition key. This setting providesthe highest consistency and lowest availability.

If set to each_quorum, a write must succeed on a quorum of replica nodes across a data center.

If set to quorum, a write must succeed on a quorum of replica nodes.

If set to local_quorum, a write must succeed on a quorum of replica nodes in the same data center as thecoordinator node. This setting voids latency of inter-data center communication.

If set to one, a write must succeed on at least one replica node.

If set to two, a write must succeed on at least two replica nodes.

If set to three, a write must succeed on at least three replica nodes.

If set to local_one, a write must succeed on at least one replica node in the local data center.


WriteConsistency

If set to any, a write must succeed on at least one node. Even if all replica nodes for the given partition keyare down, the write can succeed after a hinted handoff has been written. This setting provides the lowestconsistency and highest availability.

If set to serial, the driver prevents unconditional updates to achieve linearizable consistency for lightweighttransactions.

If set to local_serial, the driver prevents unconditional updates to achieve linearizable consistency forlightweight transactions within the data center.

Notes• An update operation can result in a consistency level error if the server does not support the WriteConsistency

value specified.

• Refer to Apache Cassandra documentation for more information about configuring consistency levels,including usage scenarios.

• If you wish to specify a ReadConsistency value besides the values documented in this section, contactTechnical Support.

Data Source MethodsetWriteConsistency

Defaultquorum

Data TypeString



• ReadConsistency on page 149

• ReadOnly on page 150




5Troubleshooting

This section provides information that can help you troubleshoot problems when they occur.


• Troubleshooting your application

• Troubleshooting Connection Pooling

• Troubleshooting Statement Pooling

• Troubleshooting Out-of-Memory Errors

• Troubleshooting Operation Timeouts

• Using Java logging

• Contacting Technical Support

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 125

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 code shows how to turn off logging using setEnableLogging(false).

import com.ddtek.jdbc.extensions.*

// Get Database ConnectionConnection con = DriverManager.getConnection

("jdbc:datadirect:cassandra://MyServer:9042;KeyspaceName=MyKS;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 125

DataDirect Spy Log ExampleThis section provides information to help you understand the content of your own DataDirect Spy logs.

For example, suppose your application executes the following code and performs some operations:Class.forName("com.ddtek.jdbc.cassandra.CassandraDriver");DriverManager.getConnection("jdbc:datadirect:cassandra://MyServer:9042;keyspaceName=MyKS;fetchSize=50;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:cassandra://MyServer:9042;CONNECTIONRETRYCOUNT=5;ALTERNATESERVERS=;DATABASENAME=;INITIALIZATIONSTRING=;AUTHENTICATIONMETHOD=none;SPYATTRIBUTES=(log=(file)c:\temp\spy.log);TRANSACTIONMODE=noTransactions;JAVADOUBLETOSTRING=false;CONNECTIONRETRYDELAY=1;INSENSITIVERESULTSETBUFFERSIZE=2048;MAXPOOLEDSTATEMENTS=0;LOADBALANCING=false;CONVERTNULL=1; CREATEMAP=notExist;IMPORTSTATEMENTPOOL=;KEYSPACENAME=MyKS)10

spy>> DatabaseMetaData[1].getDriverName()spy>> OK (Cassandra)

10 The combination of the URL specified by the application and the default values of all connection properties not specified.


Chapter 5: Troubleshooting

spy>> DatabaseMetaData[1].getDriverVersion()spy>> OK (3.60.0 (000000.000000.000000))

spy>> DatabaseMetaData[1].getDatabaseProductName()spy>> OK (Cassandra)

spy>> DatabaseMetaData[1].getDatabaseProductVersion()spy>> OK (Cassandra - 2.1.0)

spy>> Connection Options :11

spy>> CONNECTIONRETRYCOUNT=5spy>> ALTERNATESERVERS=spy>> DATABASENAME=spy>> INITIALIZATIONSTRING=spy>> AUTHENTICATIONMETHOD=nonespy>> SPYATTRIBUTES=(log=(file)c:\temp\spy.log)spy>> JAVADOUBLETOSTRING=falsespy>> CONNECTIONRETRYDELAY=1spy>> INSENSITIVERESULTSETBUFFERSIZE=2048spy>> MAXPOOLEDSTATEMENTS=0spy>> LOADBALANCING=falsespy>> CONVERTNULL=1spy>> CREATEMAP=notExistspy>> IMPORTSTATEMENTPOOL=spy>> KEYSPACENAME=MyKSspy>> Driver Name = Cassandra12

spy>> Driver Version = 6.0.0 (000000.000000.000000)13

spy>> Database Name = Cassandra14

spy>> Database Version = Cassandra - 2.1.015

spy>> Connection[1].getWarnings()spy>> OK16spy>> 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])17

spy>> ResultSet[1].getMetaData()spy>> OK (ResultSetMetaData[1])18

spy>> ResultSetMetaData[1].getColumnCount()spy>> OK (3)19

spy>> ResultSetMetaData[1].getColumnLabel(int column)spy>> column = 1spy>> OK (EMPNO)20spy>> ResultSetMetaData[1].getColumnLabel(int column)spy>> column = 2spy>> OK (ENAME)21

spy>> ResultSetMetaData[1].getColumnLabel(int column)spy>> column = 3spy>> OK (JOB)22spy>> ResultSet[1].next()spy>> OK (true)23

spy>> ResultSet[1].getString(int columnIndex)spy>> columnIndex = 1spy>> OK (7369)24

spy>> ResultSet[1].getString(int columnIndex)

11 The combination of the connection properties specified by the application and the default values of all connection properties not specified.12 The name of the driver.13 The version of the driver.14 The name of the database server to which the driver connects.15 The version of the database to which the driver connects.16 The application checks to see if there are any warnings. In this example, no warnings are present.17

The statement select empno,ename,job from emp where empno=7369 is created.18 Some metadata is requested.19 Some metadata is requested.20 Some metadata is requested.21 Some metadata is requested.22 Some metadata is requested.23 The first row is retrieved and the application retrieves the result values.24 The first row is retrieved and the application retrieves the result values.


Troubleshooting your application

spy>> columnIndex = 2spy>> OK (SMITH)25

spy>> ResultSet[1].getString(int columnIndex)spy>> columnIndex = 3spy>> OK (CLERK)26

spy>> ResultSet[1].next()spy>> OK (false)27spy>> ResultSet[1].close()spy>> OK28

spy>> Connection[1].close()spy>> OK29

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 71

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.

Pool Manager Trace File ExampleThe following example shows a DataDirect Connection Pool Manager trace file. The footnotes provideexplanations for the referenced text to help you understand the content of your own Pool Manager trace files.

jdbc/CassandraNCMarkBPool: *** ConnectionPool Created(jdbc/CassandraNCMarkBPool,com.ddtek.jdbcx.cassandra.CassandraDataSource@1835282, 5, 5, 10, scott)30

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 application attempts to retrieve the next row, but only one row was returned for this query.28 After the application has completed retrieving result values, the result set is closed.29 The application finishes and disconnects.30 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/CassandraNCMarkBPool).

DataSource_class is the DataSource class associated with the connection pool (for examplecom.ddtek.jdbcx.cassandra.CassandraDataSource).

initial_pool_size is the number of physical connections created when the connection pool is initialized (for example, 5).



jdbc/CassandraNCMarkBPool: Number pooled connections = 0.jdbc/CassandraNCMarkBPool: Number free connections = 0.

jdbc/CassandraNCMarkBPool: Enforced minimum!31

NrFreeConnections was: 0jdbc/CassandraNCMarkBPool: Number pooled connections = 5.jdbc/CassandraNCMarkBPool: Number free connections = 5.

jdbc/CassandraNCMarkBPool: Reused free connection.32


jdbc/CassandraNCMarkBPool: Reused free connection.jdbc/CassandraNCMarkBPool: Number pooled connections = 5.jdbc/CassandraNCMarkBPool: Number free connections = 3.




jdbc/CassandraNCMarkBPool: Created new connection.33


jdbc/CassandraNCMarkBPool: Created new connection.jdbc/CassandraNCMarkBPool: Number pooled connections = 7.jdbc/CassandraNCMarkBPool: Number free connections = 0.





jdbc/CassandraNCMarkBPool: Connection was closed and added to the cache.34


jdbc/CassandraNCMarkBPool: Connection was closed and added to the cache.

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).31 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.32 The driver requests a connection from the connection pool. The driver retrieves an available connection.33 The driver requests a connection from the connection pool. Because a connection is unavailable, the Pool Manager creates a new connection

for the request.34 A connection is closed by the application and returned to the connection pool.


Troubleshooting Connection Pooling


jdbc/CassandraNCMarkBPool: Connection was closed and added to the cache.jdbc/CassandraNCMarkBPool: Number pooled connections = 11.jdbc/CassandraNCMarkBPool: Number free connections = 3.











jdbc/CassandraNCMarkBPool: Enforced maximum!36


jdbc/CassandraNCMarkBPool: Enforced minimum!NrFreeConnections was: 10jdbc/CassandraNCMarkBPool: Number pooled connections = 10.jdbc/CassandraNCMarkBPool: Number free connections = 10.

jdbc/CassandraNCMarkBPool: Enforced maximum!NrFreeConnections was: 10jdbc/CassandraNCMarkBPool: Number pooled connections = 10.jdbc/CassandraNCMarkBPool: Number free connections = 10.

jdbc/CassandraNCMarkBPool: Enforced minimum!NrFreeConnections was: 10jdbc/CassandraNCMarkBPool: Number pooled connections = 10.jdbc/CassandraNCMarkBPool: Number free connections = 10.

35 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.

36 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.




jdbc/CassandraNCMarkBPool: Dumped free connection.37


jdbc/CassandraNCMarkBPool: Dumped free connection.jdbc/CassandraNCMarkBPool: Number pooled connections = 8.jdbc/CassandraNCMarkBPool: Number free connections = 8.












jdbc/CassandraNCMarkBPool: Closing a pool of the groupjdbc/CassandraNCMarkBPool39


jdbc/CassandraNCMarkBPool: Pool closed40

37 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.

38 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.

39 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.

40 The Pool Manager closed all the pools in the pool group. The connection pool is closed.


Troubleshooting Connection Pooling


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 84

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]41

VERSION=142

[STMT_ENTRY]43

SQL_TEXT=[INSERT INTO emp(id, name) VALUES(?,?)

41 A string that identifies the file as a statement pool export file.42 The version of the export file.43 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.



]STATEMENT_TYPE=Prepared StatementRESULTSET_TYPE=Forward OnlyRESULTSET_CONCURRENCY=Read OnlyAUTOGENERATEDKEYSREQUESTED=falseREQUESTEDKEYCOLUMNS=

[STMT_ENTRY]44

SQL_TEXT=[INSERT INTO emp(id, name) VALUES(99,?)]STATEMENT_TYPE=Prepared StatementRESULTSET_TYPE=Forward OnlyRESULTSET_CONCURRENCY=Read OnlyAUTOGENERATEDKEYSREQUESTED=falseREQUESTEDKEYCOLUMNS=id,name

Troubleshooting Out-of-Memory ErrorsWhen processing large sets of data, out-of-memory errors can occur when the size of an intermediate resultexceeds the available memory allocated to the JVM. If you are encountering these errors, you can tuneFetchSize, ResultMemorySize, and the JVM heap size to fit your environment.

• Reduce FetchSize to reduce demands on memory. By lowering the number of rows as specified by FetchSize,you lower the number of rows the driver is required to process before returning data to the application. Thus,you reduce demands on memory and decrease the likelihood of out-of-memory errors.

• Decrease ResultMemorySize until out-of-memory errors are eliminated. Intermediate results larger than thevalue specified will be written to disk as opposed to held in memory. When configured correctly, this avoidsmemory limitations by not relying on memory to process larger intermediate results. Be aware that whilewriting to disk reduces the risk of out-of-memory errors, it also negatively impacts performance. For optimalperformance, decrease this value only to a size necessary to avoid errors. By default, ResultMemorySizeis set to -1, which sets the maximum size of intermediate results held in memory to a percentage of themax Java heap size. If you received errors using the default configuration, use the max Java heap sizedivided by 4 as a starting point when tuning this option.

• Increase the JVM heap size. By increasing the max Java heap size, you increase the amount of data thedriver can accumulate in memory and avoid out-of-memory errors.

See alsoFetchSize on page 135ResultMemorySize on page 151

Troubleshooting Operation TimeoutsCassandra imposes timeouts on read and write operations to prevent a given operation from negatively impactingthe performance of the cluster. If you encounter an operation timeout, you can take the following actions topromote operation success.

44 The next statement pool entry.


Troubleshooting Out-of-Memory Errors

• Adjust the ReadConsistency connection property. You can speed up a query by reducing the number ofreplicas required to respond to a read request. Therefore, you can reduce the likelihood of a timeout bysetting ReadConsistency to a value that requires fewer replicas to respond.

• Adjust the WriteConsistency connection property. You can speed up a write operation by reducing thenumber of replicas required to acknowledge success. Therefore, you can reduce the likelihood of a timeoutby setting WriteConsistency to a value that requires fewer replicas to acknowledge the execution of thewrite operation.

• Decrease the value of the NativeFetchSize connection property. By decreasing NativeFetchSize, you reducethe amount of data that must be transmitted between the driver and the native data source. For readoperations, the smaller the chunks of data requested, the faster the cluster can assemble results fortransmission to the driver. For write operations, smaller chunks of data allow the driver to communicatemore efficiently with the native data source and thus expedite write operations.

Note: Setting NativeFetchSize too low negatively impacts performance by requiring unnecessary roundtrips across the network.

• Optimize your query by taking one or more of the following actions.

1. Limit the number of results returned.

2. Add indexes to Cassandra tables and base operations on indexes as appropriate.

3. Use Where clause filtering that can be pushed down to Cassandra, allowing operations to be evaluatedand handled quickly. Refer to the following DataStax Web pages for more information about Whereclause functionality and limitations.

• A deep look at the CQL WHERE clause

• Filtering data using WHERE

• Adjust Cassandra network timeout settings in the cassandra.yml configuration file. These settings canbe adjusted to promote read operation success by increasing the size of the timeout window. Refer to yourApache Cassandra documentation for details.

See alsoReadConsistency on page 149WriteConsistency on page 161NativeFetchSize on page 146Where Clause on page 185

Using Java loggingThe driver provides a flexible and comprehensive logging mechanism that allows logging to be incorporatedseamlessly with the logging of your own application or allows logging to be enabled and configured independentlyfrom the application. The logging mechanism can be instrumental in investigating and diagnosing issues. Italso provides valuable insight into the type and number of operations requested by the application from thedriver and requested by the driver from the remote data source. This information can help you tune and optimizeyour application.



http://www.datastax.com/dev/blog/a-deep-look-to-the-cql-where-clause

http://docs.datastax.com/en/cql/3.1/cql/cql_reference/select_r.html?scroll=reference_ds_d35_v2q_xj__filtering-data-using-where

Logging ComponentsThe driver uses the Java Logging API to configure the loggers (individual logging components) used by thedriver. The Java Logging API is built into the JVM.

The Java Logging API allows applications or components to define one or more named loggers. Messageswritten to the loggers can be given different levels of importance. For example, errors that occur in the drivercan be written to a logger at the CONFIG level, while progress or flow information may be written to a loggerat the FINE or FINER level. Each logger used by the driver can be configured independently. The configurationfor a logger includes what level of log messages are written, the location to which they are written, and theformat of the log message.

The Java Logging API defines the following levels:

• SEVERE

• WARNING

• INFO

• CONFIG

• FINE

• FINER

• FINEST

Note: Log messages logged by the driver only use the CONFIG, FINE, FINER, and FINEST logging levels.

Setting the log threshold of a logger to a particular level causes the logger to write log messages of that leveland higher to the log. For example, if the threshold is set to FINE, the logger writes messages of levels FINE,CONFIG, INFO, WARNING, and SEVERE to its log. Messages of level FINER or FINEST are not written tothe log.

The driver exposes loggers for the following functional areas:

• JDBC API

• SQL Engine

JDBC API logger

Namedatadirect.jdbc.cloud.level

PurposeLogs the JDBC calls made by the application to the driver and the responses from the driver back to theapplication. DataDirect Spy is used to log the JDBC calls.

Message LevelsFINER - Calls to the JDBC methods are logged at the FINER level. The value of all input parameters passedto these methods and the return values passed from them are also logged, except that input parameter orresult data contained in InputStream, Reader, Blob, or Clob objects are not written at this level.


Using Java logging

FINEST - In addition to the same information logged by the FINER level, input parameter values and returnvalues contained in InputStream, Reader, Blob and Clob objects are written at this level.

OFF - Calls to the JDBC methods are not logged.

SQL Engine logger

Namedatadirect.cloud.sql.level

PurposeLogs the operations that the SQL engine performs while executing a query. Operations include preparing astatement to be executed, executing the statement, and (if needed) fetching the data. These are internaloperations that do not necessarily directly correlate calls made to the data source.

Message LevelsCONFIG - Any errors or warnings detected by the SQL engine are written at this level.

FINE - In addition to the same information logged by the CONFIG level, SQL engine operations are logged atthis level. In particular, the SQL statement that is being executed is written at this level.

FINER - In addition to the same information logged by the CONFIG and FINE levels, data sent or received inthe process of performing an operation is written at this level.

Configuring LoggingYou can configure logging by using the properties file that shipped with your JVM or by using the driver.

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.

Using the Driver for LoggingIf you want to configure logging using the driver, you can use either of the following approaches:

• Use a single properties file for all Cassandra connections.

• Use a different properties file for each relational map of your native Cassandra data. For example, if youhave two configuration files, such asC:\data\db\mydb1.config and C:\data\db\mydb2.config,



you can load one properties file for the mydb1.config schema map and load another properties file forthe mydb2.config schema map.

Note: You must specify the name and path of the relational map using the SchemaMap property.

If a properties file is specified for the LogConfigFile connection property, the driver uses the following processto determine which file to load:

1. The driver looks for the file specified by the LogConfigFile property.

2. If the driver cannot find the file in Step 1 on page 175, it looks for a properties file namedschema_name.logging.properties in the directory containing the schema map configuration file,where schema_name is the name of the schema map configuration file.

3. If the driver cannot find the file in Step 2 on page 175, it looks for a properties file namedddlogging.properties in the current working directory.

4. If the driver cannot find the file in Step 3 on page 175 , it abandons its attempt to load a properties file.

If any of these files exist, but the logging initialization fails for some reason while using that file, the driver writesa warning to the standard output (System.out), specifying the name of the properties file being used.

A sample properties file is installed in the install_dir/testforjdbc.

See alsoSchemaMap on page 153LogConfigFile on page 143

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:


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.

• 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 so


Contacting Technical Support


on. 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.



6Supported SQL Functionality

The driver provides support for SQL statements and extensions described in this section. SQL extensions aredenoted by an (EXT) in the topic title.


• Data Definition Language (DDL)

• Delete

• Insert

• Refresh Map (EXT)

• Select

• Update

• SQL Expressions

• Subqueries

Data Definition Language (DDL)The driver supports data store-specific DDL through the Native and Refresh escape sequences. See "Nativeand Refresh Escape Sequences" for details.

See alsoNative and Refresh Escape Sequences on page 208


DeletePurposeThe Delete statement is used to delete rows from a table.

SyntaxDELETE FROM table_name [WHERE search_condition]

where:

table_name

specifies the name of the table from which you want to delete rows.

search_condition

is an expression that identifies which rows to delete from the table.

Notes• The Where clause determines which rows are to be deleted. Without a Where clause, all rows of the table

are deleted, but the table is left intact. See Where Clause on page 185 for information about the syntax ofWhere clauses. Where clauses can contain subqueries.

Example AThis example shows a Delete statement on the emp table.

DELETE FROM emp WHERE emp_id = 'E10001'

Each Delete statement removes every record that meets the conditions in the Where clause. In this case, everyrecord having the employee ID E10001 is deleted. Because employee IDs are unique in the employee table,at most, one record is deleted.

Example BThis example shows using a subquery in a Delete clause.

DELETE FROM emp WHERE dept_id = (SELECT dept_id FROM dept WHERE dept_name ='Marketing')

The records of all employees who belong to the department named Marketing are deleted.

Notes• Delete is supported for primitive types and non-nested complex types. See "Complex Type Normalization"

for details.

• To enable Insert, Update, and Delete, set the ReadOnly connection property to false.

• A Where clause can be used to restrict which rows are deleted.



Chapter 6: Supported SQL Functionality

InsertPurposeThe Insert statement is used to add new rows to a local table. You can specify either of the following options:

• List of values to be inserted as a new row

• Select statement that copies data from another table to be inserted as a set of new rows

In Cassandra, Inserts are in effect Upserts. When an Insert is performed on a row that already exists, the rowwill be updated.

SyntaxINSERT INTO table_name [(column_name[,column_name]...)] {VALUES (expression[,expression]...) | select_statement}

table_name

is the name of the table in which you want to insert rows.

column_name

is optional and specifies an existing column. Multiple column names (a column list) must be separatedby commas. A column list provides the name and order of the columns, the values of which arespecified in the Values clause. If you omit a column_name or a column list, the value expressionsmust provide values for all columns defined in the table and must be in the same order that thecolumns are defined for the table. Table columns that do not appear in the column list are populatedwith the default value, or with NULL if no default value is specified.

expression

is the list of expressions that provides the values for the columns of the new record. Typically, theexpressions are constant values for the columns. Character string values must be enclosed in singlequotation marks (’). See Literals on page 193 for more information.

select_statement

is a query that returns values for each column_name value specified in the column list. Using aSelect statement instead of a list of value expressions lets you select a set of rows from one tableand insert it into another table using a single Insert statement. The Select statement is evaluatedbefore any values are inserted. This query cannot be made on the table into which values are inserted.See Select on page 180 for information about Select statements.

Notes• Insert is supported for primitive types and non-nested complex types. See "Complex Type Normalization"

for details.

• The driver supports an insert on a child table prior to an insert on a parent table, circumventing referentialintegrity constraints associated with traditional RDBMS. To maintain integrity between parent and childtables, it is recommended that an insert be performed on the parent table for each foreign key value addedto the child. If such an insert is not first performed, the driver automatically inserts a row into the parenttables that contains only the primary key values and NULL values for all non-primary key columns. See"Complex Type Normalization" for details.


Insert



Refresh Map (EXT)PurposeThe REFRESH MAP statement adds newly discovered objects to your relational view of native data. It alsoincorporates any configuration changes made to your relational view by reloading the schema map configurationfile.

SyntaxREFRESH MAP

NotesREFRESH MAP is an expensive query since it involves the discovery of native data.

SelectPurposeUse the Select statement to fetch results from one or more tables.

SyntaxSELECT select_clausefrom_clause[where_clause][groupby_clause][having_clause][{UNION [ALL | DISTINCT] |{MINUS [DISTINCT] | EXCEPT [DISTINCT]} |INTERSECT [DISTINCT]} select_statement][limit_clause]

where:

select_clause

specifies the columns from which results are to be returned by the query. See Select Clause on page181 for a complete explanation.

from_clause

specifies one or more tables on which the other clauses in the query operate. See From Clause onpage 183 for a complete explanation.



where_clause

is optional and restricts the results that are returned by the query. See Where Clause on page 185for a complete explanation.

groupby_clause

is optional and allows query results to be aggregated in terms of groups. See Group By Clause onpage 186 for a complete explanation.

having_clause

is optional and specifies conditions for groups of rows (for example, display only the departmentsthat have salaries totaling more than $200,000). See Having Clause on page 187 for a completeexplanation.

UNION

is an optional operator that combines the results of the left and right Select statements into a singleresult. See Union Operator on page 187 for a complete explanation.

INTERSECT

is an optional operator that returns a single result by keeping any distinct values from the results ofthe left and right Select statements. See Intersect Operator on page 188 for a complete explanation.

EXCEPT | MINUS

are synonymous optional operators that returns a single result by taking the results of the left Selectstatement and removing the results of the right Select statement. See Except and Minus Operatorson page 189 for a complete explanation.

orderby_clause

is optional and sorts the results that are returned by the query. See Order By Clause on page 190 fora complete explanation.

limit_clause

is optional and places an upper bound on the number of rows returned in the result. See Limit Clauseon page 190 for a complete explanation.

Select Clause

PurposeUse the Select clause to specify with a list of column expressions that identify columns of values that you wantto retrieve or an asterisk (*) to retrieve the value of all columns.

SyntaxSELECT [{LIMIT offset number | TOP number}] [ALL | DISTINCT] {* | column_expression[[AS] column_alias] [,column_expression [[AS] column_alias], ...]}

where:


Select

LIMIT offset number

creates the result set for the Select statement first and then discards the first number of rows specifiedby offset and returns the number of remaining rows specified by number. To not discard any ofthe rows, specify 0 for offset, for example, LIMIT 0 number. To discard the first offset numberof rows and return all the remaining rows, specify 0 for number, for example, LIMIT offset0.

TOP number

is equivalent to LIMIT 0number.

column_expression

can be simply a column name (for example, last_name). More complex expressions may includemathematical operations or string manipulation (for example, salary * 1.05). See SQL Expressionson page 193 for details. column_expression can also include aggregate functions. See AggregateFunctions on page 182 for details.

column_alias

can be used to give the column a descriptive name. For example, to assign the alias department tothe column dep:

SELECT dep AS department FROM emp

DISTINCT

eliminates duplicate rows from the result of a query. This operator can precede the first columnexpression. For example:

SELECT DISTINCT dep FROM emp

Notes• Separate multiple column expressions with commas (for example, SELECT last_name, first_name,

hire_date).

• Column names can be prefixed with the table name or table alias. For example, SELECT emp.last_nameor e.last_name, where e is the alias for the table emp.

• NULL values are not treated as distinct from each other. The default behavior is that all result rows bereturned, which can be made explicit with the keyword ALL.

Aggregate FunctionsAggregate functions can also be a part of a Select clause. Aggregate functions return a single value from a setof rows. An aggregate can be used with a column name (for example, AVG(salary)) or in combination witha more complex column expression (for example, AVG(salary * 1.07)). The column expression can bepreceded by the DISTINCT operator. The DISTINCT operator eliminates duplicate values from an aggregateexpression.

The following table lists supported aggregate functions.

Table 27: Aggregate Functions

ReturnsAggregate



The average of the values in a numeric column expression. For example, AVG(salary)returns the average of all salary column values.

AVG

The number of values in any field expression. For example, COUNT(name) returns thenumber of name values. When using COUNT with a field name, COUNT returns thenumber of non-NULL column values. A special example is COUNT(*), which returnsthe number of rows in the set, including rows with NULL values.

COUNT

The maximum value in any column expression. For example, MAX(salary) returnsthe maximum salary column value.

MAX

The minimum value in any column expression. For example, MIN(salary) returnsthe minimum salary column value.

MIN

The total of the values in a numeric column expression. For example, SUM(salary)returns the sum of all salary column values.

SUM

Example AIn the following example, only distinct last name values are counted. The default behavior is that all duplicatevalues be returned, which can be made explicit with ALL.

COUNT (DISTINCT last_name)

Example BThe following example uses the COUNT, MAX, and AVG aggregate functions:

SELECTCOUNT(amount) AS numOpportunities,MAX(amount) AS maxAmount,AVG(amount) AS avgAmount

FROM opportunity o INNER JOIN user uON o.ownerId = u.id

WHERE o.isClosed = 'false' ANDu.name = 'MyName'

From Clause

PurposeThe From clause indicates the tables to be used in the Select statement.

SyntaxFROM table_name [table_alias] [,...]

where:

table_name

is the name of a table or a subquery. Multiple tables define an implicit inner join among those tables.Multiple table names must be separated by a comma. For example:

SELECT * FROM emp, dep


Select

Subqueries can be used instead of table names. Subqueries must be enclosed in parentheses. SeeSubquery in a From Clause on page 185 for an example.

table_alias

is a name used to refer to a table in the rest of the Select statement. When you specify an alias fora table, you can prefix all column names of that table with the table alias.

ExampleThe following example specifies two table aliases, e for emp and d for dep:

SELECT e.name, d.deptNameFROM emp e, dep dWHERE e.deptId = d.id

table_alias is a name used to refer to a table in the rest of the Select statement. When you specify an aliasfor a table, you can prefix all column names of that table with the table alias. For example, given the tablespecification:

FROM emp E

you may refer to the last_name field as E.last_name. Table aliases must be used if the Select statement joinsa table to itself. For example:

SELECT * FROM emp E, emp F WHERE E.mgr_id = F.emp_id

The equal sign (=) includes only matching rows in the results.

Outer Join Escape Sequences

PurposeThe SQL-92 left, right, and full outer join syntax is supported.

Syntax{oj outer-join}

where outer-join is

table-reference {LEFT | RIGHT | FULL} OUTER JOIN {table-reference | outer-join} ONsearch-condition

where table-reference is a database table name, and search-condition is the join condition you wantto use for the tables.

Example: SELECT Customers.CustID, Customers.Name, Orders.OrderID, Orders.Status FROM {ojCustomers LEFT OUTER JOIN Orders ON Customers.CustID=Orders.CustID} WHEREOrders.Status='OPEN'

The following outer join escape sequences are supported:

• Left outer joins

• Right outer joins

• Full outer joins

• Nested outer joins



Join in a From Clause

PurposeYou can use a Join as a way to associate multiple tables within a Select statement. Joins may be either explicitor implicit. For example, the following is the example from the previous section restated as an explicit innerjoin:

SELECT * FROM emp INNER JOIN dep ON id=empIdSELECT e.name, d.deptNameFROM emp e INNER JOIN dep d ON e.deptId = d.id;

whereas the following is the same statement as an implicit inner join:

SELECT * FROM emp, dep WHERE emp.deptID=dep.id

Syntax

FROM table_name {RIGHT OUTER | INNER | LEFT OUTER | CROSS | FULL OUTER} JOIN table.keyON search-condition

ExampleIn this example, two tables are joined using LEFT OUTER JOIN. T1, the first table named includes nonmatchingrows.

SELECT * FROM T1 LEFT OUTER JOIN T2 ON T1.key = T2.key

If you use a CROSS JOIN, no ON expression is allowed for the join.

Subquery in a From ClauseSubqueries can be used in the From clause in place of table references (table_name).

ExampleSELECT * FROM (SELECT * FROM emp WHERE sal > 10000) new_emp, dept WHEREnew_emp.deptno = dept.deptno

See alsoFor more information about subqueries, see Subqueries on page 200.

Where Clause

PurposeSpecifies the conditions that rows must meet to be retrieved.

SyntaxWHERE expr1rel_operatorexpr2

where:


Select

expr1

is either a column name, literal, or expression.

expr2

is either a column name, literal, expression, or subquery. Subqueries must be enclosed in parentheses.

rel_operator

is the relational operator that links the two expressions.

ExampleThe following Select statement retrieves the first and last names of employees that make at least $20,000.

SELECT last_name, first_name FROM emp WHERE salary >= 20000

See also• SQL Expressions on page 193

• Subqueries on page 200

• Troubleshooting Operation Timeouts on page 171

Group By Clause

PurposeSpecifies the names of one or more columns by which the returned values are grouped. This clause is usedto return a set of aggregate values.

SyntaxGROUP BY column_expression [,...]

where:

column_expression

is either a column name or a SQL expression. Multiple values must be separated by a comma. Ifcolumn_expression is a column name, it must match one of the column names specified in the Selectclause. Also, the Group By clause must include all non-aggregate columns specified in the Selectlist.

ExampleThe following example totals the salaries in each department:

SELECT dept_id, sum(salary) FROM emp GROUP BY dept_id

This statement returns one row for each distinct department ID. Each row contains the department ID and thesum of the salaries of the employees in the department.





Having Clause

PurposeSpecifies conditions for groups of rows (for example, display only the departments that have salaries totalingmore than $200,000). This clause is valid only if you have already defined a Group By clause.

SyntaxHAVING expr1rel_operatorexpr2

where:

expr1 | expr2

can be column names, constant values, or expressions. These expressions do not have to match acolumn expression in the Select clause. See SQL Expressions on page 193 for details regarding SQLexpressions.

rel_operator

is the relational operator that links the two expressions.

ExampleThe following example returns only the departments that have salaries totaling more than $200,000:

SELECT dept_id, sum(salary) FROM emp GROUP BY dept_id HAVING sum(salary) > 200000



Union Operator

PurposeCombines the results of two Select statements into a single result. The single result is all the returned rowsfrom both Select statements. By default, duplicate rows are not returned. To return duplicate rows, use the Allkeyword (UNION ALL).

Syntaxselect_statementUNION [ALL | DISTINCT] | {MINUS [DISTINCT] | EXCEPT [DISTINCT]} | INTERSECT[DISTINCT]select_statement

Notes• When using the Union operator, the Select lists for each Select statement must have the same number of

column expressions with the same data types and must be specified in the same order.


Select

Example AThe following example has the same number of column expressions, and each column expression, in order,has the same data type.

SELECT last_name, salary, hire_date FROM empUNIONSELECT name, pay, birth_date FROM person

Example BThe following example is not valid because the data types of the column expressions are different (salaryFROM emp has a different data type than last_name FROM raises). This example does have the samenumber of column expressions in each Select statement but the expressions are not in the same order by datatype.

SELECT last_name, salary FROM empUNIONSELECT salary, last_name FROM raises

Intersect Operator

PurposeIntersect operator returns a single result set. The result set contains rows that are returned by both Selectstatements. Duplicates are returned unless the Distinct operator is added.

Syntaxselect_statementINTERSECT [DISTINCT]select_statement

where:

DISTINCT

eliminates duplicate rows from the results.

Notes• When using the Intersect operator, the Select lists for each Select statement must have the same number

of column expressions with the same data types and must be specified in the same order.


SELECT last_name, salary, hire_date FROM empINTERSECT [DISTINCT]SELECT name, pay, birth_date FROM person




SELECT last_name, salary FROM empINTERSECTSELECT salary, last_name FROM raises

Except and Minus Operators

PurposeReturn the rows from the left Select statement that are not included in the result of the right Select statement.

Syntaxselect_statement{EXCEPT [DISTINCT] | MINUS [DISTINCT]}select_statement

where:

DISTINCT

eliminates duplicate rows from the results.

Notes• When using one of these operators, the Select lists for each Select statement must have the same number

of column expressions with the same data types and must be specified in the same order.


SELECT last_name, salary, hire_date FROM empEXCEPTSELECT name, pay, birth_date FROM person


SELECT last_name, salary FROM empEXCEPTSELECT salary, last_name FROM raises


Select

Order By Clause

PurposeThe Order By clause specifies how the rows are to be sorted.

SyntaxORDER BY sort_expression [DESC | ASC] [,...]

where:

sort_expression

is either the name of a column, a column alias, a SQL expression, or the positioned number of thecolumn or expression in the select list to use.

The default is to perform an ascending (ASC) sort.

ExampleTo sort by last_name and then by first_name, you could use either of the following Select statements:

SELECT emp_id, last_name, first_name FROM emp

ORDER BY last_name, first_name

or

SELECT emp_id, last_name, first_name FROM emp

ORDER BY 2,3

In the second example, last_name is the second item in the Select list, so ORDER BY 2,3 sorts by last_nameand then by first_name.

See alsoSQL Expressions on page 193

Limit Clause

PurposePlaces an upper bound on the number of rows returned in the result.

SyntaxLIMIT number_of_rows [OFFSET offset_number]

where:

number_of_rows

specifies a maximum number of rows in the result. A negative number indicates no upper bound.



OFFSET

specifies how many rows to skip at the beginning of the result set. offset_number is the numberof rows to skip.

Notes• In a compound query, the Limit clause can appear only on the final Select statement. The limit is applied

to the entire query, not to the individual Select statement to which it is attached.

ExampleThe following example returns a maximum of 20 rows.

SELECT last_name, first_name FROM emp WHERE salary > 20000 ORDER BY dept_idc LIMIT20

UpdatePurposeAn Update statement changes the value of columns in the selected rows of a table.

In Cassandra, Updates are in effect Upserts. When an Update is performed on a row that does not exist, therow will be inserted.

SyntaxUPDATE table_name SET column_name = expression

[, column_name = expression] [WHERE conditions]

table_name

is the name of the table for which you want to update values.

column_name

is the name of a column, the value of which is to be changed. Multiple column values can be changedin a single statement.

expression

is the new value for the column. The expression can be a constant value or a subquery that returnsa single value. Subqueries must be enclosed in parentheses.

Example AThe following example changes every record that meets the conditions in the Where clause. In this case, thesalary and exempt status are changed for all employees having the employee ID E10001. Because employeeIDs are unique in the emp table, only one record is updated.

UPDATE emp SET salary=32000, exempt=1

WHERE emp_id = 'E10001'


Update

Example BThe following example uses a subquery. In this example, the salary is changed to the average salary in thecompany for the employee having employee ID E10001.

UPDATE emp SET salary = (SELECT avg(salary) FROM emp)

WHERE emp_id = 'E10001'

Notes• Update is supported for primitive types, non-nested Tuple types, and non-nested user-defined types. Update

is also supported for values in non-nested Map types. The driver does not support updates on List types,Set types, or keys in Map types because the values in each are part of the primary key of their respectivechild tables and primary key columns cannot be updated. If an Update is attempted when not allowed, thedriver issues the following error message:

[DataDirect][Cassandra JDBC Driver][Cassandra]syntax error or access ruleviolation: UPDATE not permitted for column: column_name

See "Complex Type Normalization" for details.

• Update is supported for Counter columns when all the other columns in the row comprise that row’s primarykey. The Counter column itself is the only updatable field in the row. When updating a Counter column onan existing row, the Counter column is updated according to the increment (or decrement) specified in theSQL statement. When updating a Counter column for which there is no existing row, the values of thecolumns that comprise the row’s primary key are inserted into the table alongside the value of the Countercolumn.

For example, consider the following table.

CREATE TABLE page_view_counts (counter_value counter,url_name varchar,page_name varchar,PRIMARYKEY (url_name, page_name));

The following Update can be performed on the page_view_counts table.

UPDATE page_view_countsSET counter_value=counter_value + 1WHERE url_name = 'www.progress.com' AND page_name = 'home'

This Update would provide the following output.

Note: Cassandra initially assigns a value of 0 (zero) to Counter columns. An increment or decrement canbe specified in the SQL statement.

url_name | page_name | counter_value------------------+-----------+---------------www.progress.com | home | 1

• A Where clause can be used to restrict which rows are updated.


See also• Where Clause on page 185




• Complex Type Normalization on page 15

• Native and Refresh Escape Sequences on page 208

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 of Select statements; and in the Set clauses of Updatestatements.

Expressions enable you to use mathematical operations as well as character string manipulation operators toform complex queries.

The driver supports both unquoted and quoted identifiers. An unquoted identifier must start with an ASCII alphacharacter and can be followed by zero or more ASCII alphanumeric characters. Unquoted identifiers areconverted to uppercase before being used.

Quoted identifiers must be enclosed in double quotation marks (""). A quoted identifier can contain any Unicodecharacter including the space character. The driver recognizes the Unicode escape sequence \uxxxx as aUnicode character. You can specify a double quotation mark in a quoted identifier by escaping it with a doublequotation mark.

The maximum length of both quoted and unquoted identifiers is 128 characters.

Valid expression elements are:

• Column names

• Literals

• Operators

• Functions

Column NamesThe most common expression is a simple column name. You can combine a column name with other expressionelements.

LiteralsLiterals are fixed data values. For example, in the expression PRICE * 1.05, the value 1.05 is a constant.Literals are classified into types, including the following:

• Binary

• Character string

• Date

• Floating point

• Integer

• Numeric

• Time


SQL Expressions

• Timestamp

The following table describes the literal format for supported SQL data types.

Table 28: Literal Syntax Examples

ExampleLiteral SyntaxSQL Type

12 or -34 or 0n

wheren is any valid integer value in the range of theINTEGER data type

BIGINT

0

1

Min Value: 0

Max Value: 1

BOOLEAN

'2010-05-21'DATE'date'DATE

'2010-05-2118:33:05.025'

TIMESTAMP'ts'DATETIME

0.25

3.1415

-7.48

n.f

where:

n

is the integral part

f

is the fractional part

DECIMAL

1.2E0 or 2.5E40 or -3.45E2or 5.67E-4

n.fEx

where:

n is the integral part

f is the fractional part

x is the exponent

DOUBLE

12 or -34 or 0n

where n is a valid integer value in the rangeof the INTEGER data type

INTEGER

'000482ff'X'hex_value'LONGVARBINARY

'This is a stringliteral'

'value'LONGVARCHAR

'2010-05-2118:33:05.025'

TIME'time'TIME

'This is a stringliteral'

'value'VARCHAR



Character String LiteralsText specifies a character string literal. A character string literal must be enclosed in single quotation marks.To represent one single quotation mark within a literal, you must enter two single quotation marks. When thedata in the fields is returned to the client, trailing blanks are stripped.

A character string literal can have a maximum length of 32 KB, that is, (32*1024) bytes.

Example

'Hello''Jim''s friend is Joe'

Numeric LiteralsUnquoted numeric values are treated as numeric literals. If the unquoted numeric value contains a decimalpoint or exponent, it is treated as a real literal; otherwise, it is treated as an integer literal.

Example+1894.1204

Binary LiteralsBinary literals are represented with single quotation marks. The valid characters in a binary literal are 0-9, a-f,and A-F.

Example'00af123d'

Date/Time LiteralsDate and time literal values are enclosed in single quotion marks ('value').

• The format for a Date literal is DATE'date'.

• The format for a Time literal is TIME'time'.

• The format for a Timestamp literal is TIMESTAMP'ts'.

Integer LiteralsInteger literals are represented by a string of numbers that are not enclosed in quotation marks and do notcontain decimal points.

Notes• Integer constants must be whole numbers; they cannot contain decimals.

• Integer literals can start with sign characters (+/-).

Example1994 or -2


SQL Expressions

OperatorsThis section describes the operators that can be used in SQL expressions.

Unary OperatorA unary operator operates on only one operand.operator operand

Binary OperatorA binary operator operates on two operands.operand1 operator operand2

If an operator is given a null operand, the result is always null. The only operator that does not follow this ruleis concatenation (||).

Arithmetic OperatorsYou can use an arithmetic operator in an expression to negate, add, subtract, multiply, and divide numericvalues. The result of this operation is also a numeric value. The + and - operators are also supported in date/timefields to allow date arithmetic. The following table lists the supported arithmetic operators.

Table 29: Arithmetic Operators

ExamplePurposeOperator

SELECT * FROM emp WHERE comm = -1Denotes a positive or negative expression. Theseare unary operators.

+ -

UPDATE emp SET sal = sal + sal *0.10

Multiplies, divides. These are binary operators.* /

SELECT sal + comm FROM emp WHEREempno > 100

Adds, subtracts. These are binary operators.+ -

Concatenation OperatorThe concatenation operator manipulates character strings. The following table lists the only supportedconcatenation operator.

Table 30: Concatenation Operator


SELECT 'Name is' || ename FROM empConcatenates character strings.||

The result of concatenating two character strings is the data type VARCHAR.



Comparison OperatorsComparison operators compare one expression to another. The result of such a comparison can be TRUE,FALSE, or UNKNOWN (if one of the operands is NULL). The driver considers the UNKNOWN result as FALSE.

The following table lists the supported comparison operators.

Table 31: Comparison Operators


SELECT * FROM emp WHERE sal =1500

Equality test.=

SELECT * FROM emp WHERE sal !=1500

Inequality test.!=<>

SELECT * FROM emp WHERE sal >1500 SELECT * FROM emp WHEREsal < 1500

“Greater than" and "less than"tests.

><

SELECT * FROM emp WHERE sal >=1500 SELECT * FROM emp WHEREsal <= 1500

“Greater than or equal to" and "lessthan or equal to" tests.

>=<=

SELECT * FROM emp WHERE ENAMELIKE 'J%\_%' ESCAPE '\'

This matches all records with names thatstart with letter 'J' and have the '_'character in them.

The Escape clause is supported inthe LIKE predicate to indicate theescape character. Escapecharacters are used in the patternstring to indicate that any wildcardcharacter that is after the escape

ESCAPE clause in LIKEoperator

LIKE ’pattern string’ ESCAPE’c’

SELECT * FROM emp WHERE ENAMELIKE 'JOE\_JOHN' ESCAPE '\'

character in the pattern stringshould be treated as a regularcharacter.

The default escape character isbackslash (\).

This matches only records with name’JOE_JOHN’.

SELECT * FROM emp WHERE job IN('CLERK','ANALYST') SELECT *FROM emp WHERE sal IN (SELECTsal FROM emp WHERE deptno =30)

“Equal to any member of" test.[NOT] IN

SELECT * FROM emp WHERE salBETWEEN 2000 AND 3000

"Greater than or equal to x" and"less than or equal to y."

[NOT] BETWEEN x AND y


SQL Expressions


SELECT empno, ename, deptnoFROM emp e WHERE EXISTS(SELECT deptno FROM dept WHEREe.deptno = dept.deptno)

Tests for existence of rows in asubquery.

EXISTS

SELECT * FROM emp WHERE enameIS NOT NULL SELECT * FROM empWHERE ename IS NULL

Tests whether the value of thecolumn or expression is NULL.

IS [NOT] NULL

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 32: Logical Operators


SELECT * FROM emp WHERE NOT (jobIS NULL)SELECT * FROM emp WHERE NOT (salBETWEEN 1000 AND 2000)

Returns TRUE if the following condition isFALSE. Returns FALSE if it is TRUE. If it isUNKNOWN, it remains UNKNOWN.

NOT

SELECT * FROM emp WHERE job ='CLERK' AND deptno = 10

Returns TRUE if both component conditions areTRUE. Returns FALSE if either is FALSE;otherwise, returns UNKNOWN.

AND

SELECT * FROM emp WHERE job ='CLERK' OR deptno = 10

Returns TRUE if either component condition isTRUE. Returns FALSE if both are FALSE;otherwise, returns UNKNOWN.

OR

ExampleIn the Where clause of the following Select statement, the AND logical operator is used to ensure that managersearning more than $1000 a month are returned in the result:

SELECT * FROM emp WHERE jobtitle = manager AND sal > 1000

Operator PrecedenceAs expressions become more complex, the order in which the expressions are evaluated becomes important.The following table shows the order in which the operators are evaluated. The operators in the first line areevaluated first, then those in the second line, and so on. Operators in the same line are evaluated left to rightin the expression.You can change the order of precedence by using parentheses. Enclosing expressions inparentheses forces them to be evaluated together.



Table 33: Operator Precedence

OperatorPrecedence

+ (Positive), - (Negative)1

*(Multiply), / (Division)2

+ (Add), - (Subtract)3

|| (Concatenate)4

=, >, <, >=, <=, <>, != (Comparison operators)5

NOT, IN, LIKE6

AND7

OR8

Example AThe query in the following example returns employee records for which the department number is 1 or 2 andthe salary is greater than $1000:

SELECT * FROM emp WHERE (deptno = 1 OR deptno = 2) AND sal > 1000

Because parenthetical expressions are forced to be evaluated first, the OR operation takes precedence overAND.

Example BIn the following example, the query returns records for all the employees in department 1, but only employeeswhose salary is greater than $1000 in department 2.

SELECT * FROM emp WHERE deptno = 1 OR deptno = 2 AND sal > 1000

The AND operator takes precedence over OR, so that the search condition in the example is equivalent to theexpression deptno = 1 OR (deptno = 2 AND sal > 1000).

FunctionsThe driver supports a number of functions that you can use in expressions, as listed and described in ScalarFunctions on page 206.

ConditionsA condition specifies a combination of one or more expressions and logical operators that evaluates to eitherTRUE, FALSE, or UNKNOWN. You can use a condition in the Where clause of the Delete, Select, and Updatestatements; and in the Having clauses of Select statements. The following describes supported conditions.


SQL Expressions

Table 34: Conditions

DescriptionCondition

Specifies a comparison with expressions or subquery results.

= , !=, <>, < , >, <=, <=

Simple comparison

Specifies a comparison with any or all members in a list orsubquery.

[= , !=, <>, < , >, <=, <=] [ANY, ALL, SOME]

Group comparison

Tests for membership in a list or subquery.

[NOT] IN

Membership

Tests for inclusion in a range.

[NOT] BETWEEN

Range

Tests for nulls.

IS NULL, IS NOT NULL

NULL

Tests for existence of rows in a subquery.

[NOT] EXISTS

EXISTS

Specifies a test involving pattern matching.

[NOT] LIKE

LIKE

Specifies a combination of other conditions.

CONDITION [AND/OR] CONDITION

Compound

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.

A subquery is a query expression that appears in the body of another expression such as a Select, an Update,or a Delete statement. In the following example, the second Select statement is a subquery:

SELECT * FROM emp WHERE deptno IN (SELECT deptno FROM dept)



IN Predicate

PurposeThe In predicate specifies a set of values against which to compare a result set. If the values are being comparedagainst a subquery, only a single column result set is returned.

Syntaxvalue [NOT] IN (value1, value2,...)

OR

value [NOT] IN (subquery)

ExampleSELECT * FROM emp WHERE deptno IN

(SELECT deptno FROM dept WHERE dname <> 'Sales')

EXISTS Predicate

PurposeThe Exists predicate is true only if the cardinality of the subquery is greater than 0; otherwise, it is false.

SyntaxEXISTS (subquery)

Example

SELECT empno, ename, deptno FROM emp e WHERE EXISTS(SELECT deptno FROM dept WHERE e.deptno = dept.deptno)

UNIQUE Predicate

PurposeThe Unique predicate is used to determine whether duplicate rows exist in a virtual table (one returned from asubquery).

SyntaxUNIQUE (subquery)

Example

SELECT * FROM dept d WHERE UNIQUE(SELECT deptno FROM emp e WHERE e.deptno = d.deptno)


Subqueries

Correlated Subqueries

PurposeA correlated subquery is a subquery that references a column from a table referred to in the parent statement.A correlated subquery is evaluated once for each row processed by the parent statement. The parent statementcan be a Select, Update, or Delete statement.

A correlated subquery answers a multiple-part question in which the answer depends on the value in each rowprocessed by the parent statement. For example, you can use a correlated subquery to determine whichemployees earn more than the average salaries for their departments. In this case, the correlated subqueryspecifically computes the average salary for each department.

SyntaxSELECT select_list

FROM table1 t_alias1WHERE expr rel_operator(SELECT column_list

FROM table2 t_alias2WHERE t_alias1.columnrel_operatort_alias2.column)

UPDATE table1 t_alias1SET column =(SELECT expr

FROM table2 t_alias2WHERE t_alias1.column = t_alias2.column)

DELETE FROM table1 t_alias1WHERE column rel_operator(SELECT expr

FROM table2 t_alias2WHERE t_alias1.column = t_alias2.column)

Notes• Correlated column names in correlated subqueries must be explicitly qualified with the table name of the

parent.

Example AThe following statement returns data about employees whose salaries exceed their department average. Thisstatement assigns an alias to emp, the table containing the salary information, and then uses the alias in acorrelated subquery:

SELECT deptno, ename, sal FROM emp x WHERE sal >(SELECT AVG(sal) FROM emp WHERE x.deptno = deptno)ORDER BY deptno

Example BThis is an example of a correlated subquery that returns row values:

SELECT * FROM dept "outer" WHERE 'manager' IN(SELECT managername FROM empWHERE "outer".deptno = emp.deptno)



Example CThis is an example of finding the department number (deptno) with multiple employees:

SELECT * FROM dept main WHERE 1 <(SELECT COUNT(*) FROM emp WHERE deptno = main.deptno)

Example DThis is an example of correlating a table with itself:

SELECT deptno, ename, sal FROM emp x WHERE sal >(SELECT AVG(sal) FROM emp WHERE x.deptno = deptno)


Subqueries

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

• Native and Refresh escape sequences

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

• Native and Refresh 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 drivers, as listed in the following table.

Example:

SELECT id, name FROM emp WHERE name LIKE {fn UCASE('Smith')}

Table 35: Supported Scalar Functions

System FunctionsTimedate FunctionsNumeric FunctionsString Functions

CURSESSIONIDCURDATEABSASCII

DATABASECURTIMEACOSBIT_LENGTH

IDENTITYDATEDIFFASINCHAR

DAYATANCHAR_LENGTH USER

DAYNAMEATAN2CHARACTER_LENGTH


Chapter 7: SQL Escape Sequences for JDBC

System FunctionsTimedate FunctionsNumeric FunctionsString Functions

DAYOFMONTHBITANDCONCAT

DAYOFWEEKBITORDIFFERENCE

DAYOFYEARBITXORHEXTORAW

EXTRACTCEILINGINSERT

HOURCOSLCASE

MINUTECOTLEFT

MONTHDEGREESLENGTH

MONTHNAMEEXPLOCATE

NOWFLOORLOCATE_2

QUARTERLOGLOWER

SECONDLOG10LTRIM

SECONDS_SINCE_MIDNIGHTMODOCTET_LENGTH

TIMESTAMPADDPIRAWTOHEX

TIMESTAMPDIFFPOWERREPEAT

TO_CHARRADIANSREPLACE

WEEKRANDRIGHT

ROUNDRTRIM YEAR

ROUNDMAGICSOUNDEX

SIGNSPACE

SINSUBSTR

SQRTSUBSTRING

TANUCASE

TRUNCATEUPPER

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.


Outer Join Escape Sequences

search-condition

is the join condition you want to use for the tables.

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

• Nested outer join

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 '*'}

Native and Refresh Escape SequencesThe driver supports the Native and Refresh escape sequences to embed data store-specific commands inSQL-92 statements. The Native escape sequence allows you to execute native commands directly throughthe client application, while the Refresh escape sequence is used to incorporate any changes introduced bythe Native escape into the driver's relational map of the data.

Note: The Native and Refresh escape sequences are mainly intended for the execution of DDL commands,such as ALTER, CREATE, and DROP. A returning clause for the Native escape is not currently supported bythe driver. Therefore, results cannot be retrieved using the Native escape sequence.

The Native escape sequences can be used with the following syntax:

{native(command_text)}

where:



command_text

is a data store-specific command.

The Refresh escape sequence has no additional argument and takes the form:

{refresh}

The following example shows the execution of two data store-specific commands with a refresh of the driver'srelational map of the data. Note that each Native escape sequence must have its own execute method. TheRefresh escape, however, can be used in the same execute statement as the Native escape.

stmt.executeUpdate ("{native (CREATE TABLE emp (empid int, title varchar))}");stmt.executeUpdate ("{native (CREATE TABLE dept (deptid int, city varchar))}{refresh}");

See alsoSupported SQL Functionality on page 177


Native and Refresh Escape Sequences

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 SQL45,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.

45 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 36: 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 37: 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 284

Reduce network traffic.Network communication is slow.

Using Database Metadata Methods onpage 284

Selecting JDBC Objects and Methodson page 288

Simplify queries.Evaluation of complex SQL queries onthe database server is slow and canreduce concurrency.


See guidelines in…SolutionProblem

Returning Data on page 286

Selecting JDBC Objects and Methodson page 288

Optimize application-to-driverinteraction.

Excessive calls from the application tothe driver slow performance.

Managing Connections and Updateson page 291

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 87addresses

IPv4/IPv6 67aggregate functions 182application

connecting with driver 44troubleshooting 163

arithmetic operators 196Array interface, methods 212ASCII

encoding 69authentication

client 66Kerberos 56server (SSL) 65SSL 66user ID/password 56

Authenticationuser ID/password 51

AuthenticationMethod 132auto generated keys

example, retrieving 291performance optimization 291

Autocommit mode 292

Bbatch inserts and updates

batch execution on a prepared statement withDataDirect Test 105using instead of prepared statements 289

binaryliterals 195operators 196

BLOBreturning long data 70

Blob interface, methods 212Blobs

retrieving with DataDirect Test 120

CCallableStatement interface, methods 213certificate

validation 160Certificate Authority (CA)

SSL 65changing the maximum pool size behavior 76character string literals 195

classesdata source and driver 13, 35, 44

CLASSPATHsetting 36, 45

clearing statements in the statement pool 89client authentication

SSL 66Clob interface, methods 225Clobs

retrieving with DataDirect Test 120closing the connection pool 78collection types 15column

names 193committing transactions 292comparison operators 197complex types

normalization 15support 15

concatenation operator 196conditions 199connecting

connection URL 37, 45DataDirect Test

using a data source 95using driver/database selection 96

using connection pool 77using DataDirect Test 95with data sources 40–41, 48–49

connectiontesting 37, 46

Connection interface, methods 226connection management 292Connection object

managing connections 292transaction model 293

Connection Pool Managerversion information 79

connection poolingconfiguring 76connection pool

closing 78connecting using 77

DataDirect Connection Pool Manager trace file 166javax.sql.ConnectionPoolDataSource interface 41, 49performance optimization 292using 71

connection propertiesadditional 54AuthenticationMethod 132


Index

connection properties (continued)CreateMap 133data encryption 52EncryptionMethod 134FetchSize 55, 135HostNameInCertificate 136ImportStatementPool 137InitializationString 138InsensitiveResultSetBufferSize 55, 139KeyPassword 140KeyspaceName 140KeyStore 141KeyStorePassword 142LogConfigFile 143LoginConfigName 143LoginTimeout 144MaxPooledStatements 55, 145NativeFetchSize 55, 146overview 50Password 147PortNumber 148ReadConsistency 149ReadOnly 150RegisterStatementPoolMonitorMBean 150required 50ResultMemorySize 55, 151SchemaMap 153ServerName 154ServicePrincipalName 155SpyAttributes 125, 127, 156statement pooling 53TransactionMode 157TrustStore 158TrustStorePassword 159User 159ValidateServerCertificate 160WriteConsistency 161

connection property descriptions 129connection URL

overview 37, 45ConnectionEventListener interface, methods 231ConnectionPoolDataSource interface, methods 231ConnectionPoolMonitor

interface 83copyrightcorrelated subqueries 202Counter data type 191, 208CQL

executing 71CreateMap 133cursors

choosing 290

DData Definition Language (DDL) 177, 208

data encryptionconfiguring 64SSL 52, 64

data source class 13, 35, 44data source methods 129data sources

calling in an application 41, 49connecting with 40, 44, 48connection pooling 71creating 41, 49, 73–74implementing 41, 49specifying SpyAttributes 125

data typescomplex 15, 21getTypeInfo() results 24mapping 22

data types, choosing for performance 287database

table characteristics, using dummy query todetermine 285

database metadataretrieving with DataDirect Test 101

DatabaseMetaData interface 268DatabaseMetaData interface, methods 232DataDirect Connection Pool Manager

trace file 166tracing, enabling 79, 166version information 79

DataDirect Spyattributes 127enabling 125logging 163–164overview 125setEnableLogging() method 164SpyAttributes connection property 156troubleshooting 163

DataDirect Spy, enabling 126DataDirect Statement Pool Monitor

accessingusing the JMX API 87

classes and interfaces 90DataDirect Test

batch execution 105configuring 93connecting with 95database metadata, retrieving 101deleting rows 111executing

Select statement 97executing prepared statement 98inserting rows 111, 114LOB support 120ParameterMetaData, returning 107result set, scrolling through 103savepoints, establishing 108starting 94


Index

DataDirect Test (continued)testing a connection 37, 46tutorial 92–93updatable result sets 111updating rows 111, 117using 92

DataSourceconnecting with 35connection pooling 73–74

DataSource interface, methods 240date

escape sequence 206date/time literals 195DDBulkLoad interface, methods 269DDL (Data Definition Language) 177, 208delegation of credentials for Kerberos 63Delete statement 178deleting rows

with DataDirect Test 111driver class 13, 35, 44Driver interface, methods 241driver overview 11Driver Version string

format 14DriverManager

connecting with 35–36, 44specifying SpyAttribute 125specifying SpyAttributes 125

dummy query, using to determine table characteristics285

Eencryption

configuring 64SSL 64

EncryptionMethod 55, 134error handling

format 69escape sequences

date, time, and timestamp 206LIKE escape character for wildcards 208native 208outer join 207refresh 208

exampleouter join escape sequence 207scalar functions 206

Except operator 189EXISTS predicate 201export file for statement pool

example 170generating 90

ExtConnection interface, methods 276ExtDatabaseMetaData interface, methods 281

extensions packagedatadirect.jdbc.extensions package 267

ExtLogControl class, methods 281ExtLogControl interface 164ExtStatementPoolMonitor class 91ExtStatementPoolMonitorMBean interface 91

FFetchSize 55, 135, 171forward-only cursor

performance implications 290freezing the statement pool 90From clause

Outer Join Escape Sequences 184functions 199

GgetBestRowIdentifier() method 293getBlob() method 286getClob() method 286getObject() method 290getTypeInfo()

results 24Group By clause 186

HHaving clause 187help, online 32, 175HostNameInCertificate 136

Iidentifiers 67importing statements into the statement pool 89ImportStatementPool 137IN predicate 201initial pool size 76InitializationString 138InputStream object, DataDirect Spy 126insensitive cursors

performance implications 290InsensitiveResultSetBufferSize 55, 139Insert statement 179inserting rows

with DataDirect Test 114Inserts

parameter metadata 68integer literals 195Interfaces, JDBC 211Intersect operator 188IP addresses

IPv4/IPv6 support 67


Index

isolation levelssupport 69

JJAAS (Java Authentication and Authorization Service)

login configuration file 61Java Authentication and Authorization Service (JAAS)

login configuration file 61Java Authentication and Authorization Service (JAAS)login module 57Java logging

components 173JDBC API logger 173SQL engine logger 174using 172

Java Naming Directory Interface (JNDI)connecting with 35, 44data sources 40, 48initializing environment 41, 49

Java SErequirements 13

javax.security.auth.Subject 63JDBC

functionality supported 211interfaces 211JVM compatibility 211methods supported 211SQL escape sequences 205versions supported 211

JDBC API logger 173JDBC data source, specifying SpyAttributes 126JDBC data sources

connecting with 40, 48JDBC data types

mapping 22JDBC Driver Manager

connecting with 44JDBC DriverManager

connecting with 36, 44specifying SpyAttribute 125

JDBC extensionsintroduction 267wrapper methods to access 268

JNDI Provider for LDAPsaving JDBC data source 41, 49

join in a From clause 185JSR 114 Rowsets

requirements 13JSR 114, Rowsets 70JTA support

transactionmodel, choosing for performance 293

JTA transaction supportmanaging commits 292

JVMJDBC compatibility 211properties file 174

JVM Heap Size 55

KKerberos

JAAS login configuration file 61krb5.conf 62

Kerberos authenticationconfiguration file 57delegation of credentials 63javax.security.auth.Subject 63kinit command (UNIX and Linux) 64product requirements 60Ticket Granting Ticket (TGT) 64user credentials, specifying 63

Kerberos Key Distribution Center (KDC) 57KeyPassword 140keyset-driven cursors, performance implications 290KeyspaceName 140keystore

SSL 66KeyStore 141KeyStorePassword 142kinit command, Kerberos authentication 64krb5.conf file

Kerberos authentication 62

Llarge object (LOB) support 70LDAP Directory

saving JDBC data source 41, 49LIKE escape character for wildcards escape sequence208Limit clause 190list type 15literals

about 193arguments, using parameter markers 288binary 195character string 195date 206date/time 195integer 195numeric 195time 206timestamp 206

LOBs supportexecuting a query with DataDirect Test 120

local tabledeleting rows 178

LogConfigFile 143


Index

loggingDataDirect Spy 164JVM properties file 174with DataDirect Spy 125

logging, Javacomponents 173JDBC API logger 173SQL engine logger 174using 172

logical operators 198LoginConfigName 143LoginTimeout 144long data

BLOB 70long data, retrieving and performance 286

Mmap type 15mapping

connection properties 51data types 22

maximum idle time 76maximum pool size 76maximum pool size behavior 76MaxPooledStatements 55, 145MBean name, registering 87memory usage, tuning

InsensitiveResultSetBufferSize 139metadata

JDBC extensions 268metadata methods, minimizing use of 284methods

Array interface 212Blob interface 212CallableStatement interface 213Clob interface 225Connection interface 226ConnectionEventListener interface 231ConnectionPoolDataSource interface 231DatabaseMetaData interface 232DataSource interface 240DDBulkLoad interface 269Driver interface 241ExtConnection interface 276ExtDatabaseMetaData interface 281ExtLogControl class 281ParameterMetaData interface 241PooledConnection interface 242PreparedStatement interface 243Ref interface 248ResultSet interface 248ResultSetMetaData interface 259RowSet interface 260SavePoint interface 260Statement interface 260

methods (continued)StatementEventListener interface 264Struct interface 264XAConnection interface 265XADataSource interface 265XAResource interface 265

minimum pool size 76Minus operator 189MIT Kerberos 56multilingual applications

development 69

Nnaming conflicts

identifiers 67native CQL

executing 71native escape sequence 208NativeFetchSize 55, 146, 171nested complex types 21normalization

identifiers 67numeric literals 195

Oobject

Connectionmanaging connections 292transaction model 293

Long (DB2) 251PooledConnectionDataSource

connecting with 77PreparedStatement

using Statement object instead of 288ResultSet

database metadata 284generating 284updating data 293

Statementusing instead of PreparedStatement object 288using multiple 292

using addBatch() instead of PreparedStatement 289operation timeouts

troubleshooting 171operators

arithmetic 196comparison 197concatenation 196logical 198precedence 198

Order By clause 190out-of-memory errors

troubleshooting 171outer join escape sequence, example 207


Index

Outer Join Escape Sequences 184overview

driver 11

Pparameter markers, using as arguments to storedprocedures 288parameter metadata

returning 68returning with DataDirect Test 107

ParameterMetaData interface, methods 241Password 147performance considerations 55performance optimization

auto generated keys, retrieving 291batches, using instead of prepared statements 289commits, managing 292connection

management 292pooling 292

database metadata methods 284designing JDBC applications 291get methods, using effectively 290getBestRowIdentifier() 293result sets, retrieving 287retrieving long data 286scrollable cursors 287selecting JDBC objects and methods 288transaction model, choosing 293update methods of the ResultSet object 293updating data 293

PooledConnection interface, methods 242PooledConnectionDataSource

interface 80PooledConnectionDataSource object

connecting with 77creating 73–74, 80

PooledConnectionDataSourceFactoryinterface 80

poolEntries() method 85PortNumber 148predicate

EXISTS 201IN 201UNIQUE 201

prepared statement pooling, performance optimization292prepared statement, executing with DataDirect Test 98prepared statements

using batches instead of 289PreparedStatement interface, methods 243PreparedStatement object

performanceimplications of using Statement object instead288

PreparedStatement object (continued)performance (continued)

of prepared statement pool 292prepared statement pooling 292using Statement object instead of 288

product requirementsKerberos authentication 60

properties file for Java logging 174

RRead Committed

isolation level 69Read Uncommitted

isolation level 69ReadConsistency 149, 171Reader object, DataDirect Spy 126ReadOnly 150Ref interface, methods 248Reference object

creating PooledConnectionDataSource object 80refresh escape sequence 208Refresh Map (EXT) 180registering MBean name 87RegisterStatementPoolMonitorMBean 150relational mapping

connection properties 51Repeatable Read

isolation level 69requirements

Java SE 13JSR 114 Rowsets 13SSL 13

result setsdeleting rows with DataDirect Test 111inserting rows with DataDirect Test 111scrolling through a result set with DataDirect Test103updating rows with DataDirect Test 111

result sets, scrollableperformance optimization 287

ResultMemorySize 55, 151, 171ResultSet interface, methods 248ResultSet object

database metadata 284generating 284updating data 293

ResultSetMetaData interface, methods 259RowSet interface, methods 260Rowsets 70

SSavePoint interface, methods 260savepoints

establishing with DataDirect Test 108


Index

scalar functions 206SchemaMap 153search patterns, avoiding 285security

data encryption 64SSL 52

Securityauthentication 51

Select clause 181Select statement

executing with DataDirect Test 97selects

parameter metadata 68sensitive cursors

performance implications 290Serializable

isolation level 69server authentication

configuring 65server-side RPCs 288ServerName 154ServicePrincipalName 155set type 15setEnableLogging() 164SpyAttributes 125, 127, 156SQL

expressions 193SQL engine logger 174SQL escape sequences

date, time, and timestamp 206LIKE escape character for wildcards 208native 208outer join 207refresh 208scalar functions 206

SQL statement support 177SQL statements

Insert 179Update 191, 208

SQLExceptionsreporting 69

SSLCertificate Authority (CA) 65client authentication 66configuring 64data encryption properties 52keystore 66requirements 13server authentication 65truststore 65

Statement interface, methods 260Statement object

Connection object association 292using instead of PreparedStatement object 288using multiple 292when to use 288

statement poolclearing statements 89export file, generating 90freezing and unfreezing 90importing statements to 89

statement pool export fileexample 170generating 170

Statement Pool Monitoraccessing with DataDirect-specific methods 85classes and interfaces 90poolEntries() method 85

statement poolingconnection properties 53ImportStatementPool 137MaxPooledStatements 145registering JMX MBean 150RegisterStatementPoolMonitorMBean 150statement pool export file 170troubleshooting problems 170

StatementEventListener interface, methods 264stored procedures

parameter markers as arguments, using 288Struct interface, methods 264subqueries

correlated 202overview 200

subquery in a From clause 185support

online help 32, 175technical support 32, 175

syntaxconnection URL 37, 45

TTechnical Support 32, 175testing a connection

instructions 37, 46Ticket Granting Ticket (TGT), Kerberos authentication64time literal

escape sequence 206timeout, connection 144timeouts, operation

troubleshooting 171timestamp literal

escape sequence 206tracing, enabling for Pool Manager 79TransactionMode 157transactions , See JTA supporttroubleshooting

connection pooling problems 166operation timeouts 171out-of-memory errors 171statement pooling problems 170


Index

troubleshooting (continued)your application 163

truststoreSSL 65

TrustStore 158TrustStorePassword 159tuple type 18

Uunary operator 196understanding the maximum pool size 76unfreezing the statement pool 90Unicode support 69Union operator 187UNIQUE predicate 201UNIX CLASSPATH

setting 36, 45updatable result sets, DataDirect Test 111Update statement 191, 208Updates

parameter metadata 68updating rows

with DataDirect Test 117URL

connecting with 36, 44User connection property 159user credentials, specifying 63user ID/password authentication

configuring 56

user-defined types 18using

JMX API 87UTF-16

conversion 69encoding 69

VValidateServerCertificate 160Version string information

format 14

WWhere clause 171, 185Windows Active Directory Kerberos 56Windows CLASSPATH

setting 36, 45Wrapper methods

to access JDBC Extensions 268WriteConsistency 161, 171

XXAConnection interface, methods 265XADataSource interface, methods 265XAResource interface, methods 265


Index

progress datadirect for jdbc forapache cassandra · 2016-01-10 li kumar jones home: 2855551122...

Documents