Progress® DataDirect® for JDBC™ for MongoDB™ Driver User's ...€¦ · • The driver has been enhanced to suppor t the native Decimal128 data type, which maps to the Decimal

Progress® DataDirect® forJDBC™ for MongoDB™ DriverUser's Guide

Release 6.0.2

Copyright

For details, see the following topics:

• Copyright

Copyright

© 2020 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 inthese materials to specific platforms supported are subject to change.

Corticon, DataDirect (and design), DataDirect Cloud, DataDirect Connect, DataDirect Connect64, DataDirectXML Converters, DataDirect XQuery, DataRPM, Defrag This, Deliver More Than Expected, Icenium, Ipswitch,iMacros, Kendo UI, Kinvey, MessageWay, MOVEit, NativeChat, NativeScript, OpenEdge, Powered by Progress,Progress, Progress Software Developers Network, SequeLink, Sitefinity (and Design), Sitefinity, SpeedScript,Stylus Studio, TeamPulse, Telerik, Telerik (and Design), Test Studio, WebSpeed, WhatsConfigured,WhatsConnected, WhatsUp, and WS_FTP are registered trademarks of Progress Software Corporation or oneof its affiliates or subsidiaries in the U.S. and/or other countries. Analytics360, AppServer, BusinessEdge,DataDirect Autonomous REST Connector, DataDirect Spy, SupportLink, DevCraft, Fiddler, iMail, JustAssembly,JustDecompile, JustMock, NativeScript Sidekick, OpenAccess, ProDataSet, Progress Results, ProgressSoftware, ProVision, PSE Pro, SmartBrowser, SmartComponent, SmartDataBrowser, SmartDataObjects,SmartDataView, SmartDialog, SmartFolder, SmartFrame, SmartObjects, SmartPanel, SmartQuery, SmartViewer,SmartWindow, and WebClient are trademarks or service marks of Progress Software Corporation and/or itssubsidiaries or affiliates in the U.S. and other countries. Java is a registered trademark of Oracle and/or itsaffiliates. Any other marks contained herein may be trademarks of their respective owners.

Updated: 2020/03/02

3Progress® DataDirect® for JDBC™ for MongoDB™ Driver: User's Guide: Version 6.0.2

Progress® DataDirect® for JDBC™ for MongoDB™ Driver: User's Guide: Version 6.0.24

Copyright

Table of Contents

Welcome to the Progress DataDirect for JDBC for MongoDB Driver.....11What's New in this Release?................................................................................................................12

Requirements.......................................................................................................................................15

Data Source and Driver Classes..........................................................................................................15

Version String Information....................................................................................................................16

Connection Properties..........................................................................................................................16

Mapping Objects to Tables...................................................................................................................16

Normalizing Native Data............................................................................................................17

Mapping Nested Complex Types...............................................................................................18

Flattening Native Data...............................................................................................................24

Data Types............................................................................................................................................24

Default Mapping of Columns with Inconsistent Native Data Types............................................26

getTypeInfo()..............................................................................................................................26

Contacting Technical Support...............................................................................................................31

Getting Started.............................................................................................33Data Source and Driver Classes..........................................................................................................33

Connecting Using the JDBC Driver Manager.......................................................................................34

Setting the Classpath ................................................................................................................34

Passing Connection URLs.........................................................................................................34

Testing the Connection..............................................................................................................35

Connecting Using Data Sources..........................................................................................................38

How Data Sources Are Implemented........................................................................................38

Creating Data Sources..............................................................................................................39

Calling a Data Source in an Application....................................................................................39

Using the driver............................................................................................41Connecting from an Application............................................................................................................42

Data Source and Driver Classes...............................................................................................42

Connecting Using the JDBC Driver Manager............................................................................42

Connecting Using Data Sources................................................................................................47

Creating and Customizing Schemas Using the DataDirect Schema Tool ...........................................48

Starting the Schema Tool...........................................................................................................49

Creating a Schema with the Table Wizard.................................................................................63

Customizing Your Schema.........................................................................................................70

Restarting the Wizard................................................................................................................90

Using Connection Properties................................................................................................................90

Required Properties...................................................................................................................91


Contents

Mapping Properties...................................................................................................................91

Authentication Properties...........................................................................................................92

Data Encryption Properties........................................................................................................93

Statement Pooling Properties....................................................................................................94

Additional Properties.................................................................................................................95

Performance Considerations................................................................................................................96

Data Encryption....................................................................................................................................97

Configuring SSL Encryption......................................................................................................97

Configuring SSL Server Authentication.....................................................................................98

Configuring SSL Client Authentication.......................................................................................99

Authentication.....................................................................................................................................100

Configuring User ID/Password Authentication.........................................................................100

Configuring the Driver for Kerberos Authentication..................................................................101

MongoDB Sharding............................................................................................................................105

Identifiers............................................................................................................................................105

IP Addresses......................................................................................................................................107

Parameter Metadata...........................................................................................................................108

Insert and Update Statements.................................................................................................108

Select Statements....................................................................................................................108

Views and Remote/Local Tables.........................................................................................................109

Isolation Levels...................................................................................................................................109

Unicode support.................................................................................................................................109

Error Handling....................................................................................................................................109

Connection Pool Manager..................................................................................................................110

How connection pooling works................................................................................................110

Implementing DataDirect connection pooling..........................................................................112

Configuring the connection pool..............................................................................................115

Connecting using a connection pool........................................................................................116

Closing the connection pool.....................................................................................................118

Checking the Pool Manager version........................................................................................118

Enabling Pool Manager tracing................................................................................................118

Connection Pool Manager interfaces.......................................................................................119

Statement Pool Monitor......................................................................................................................124

Using DataDirect-Specific Methods to Access the Statement Pool Monitor............................124

Using JMX to Access the Statement Pool Monitor..................................................................127

Importing Statements into a Statement Pool...........................................................................128

Clearing all statements in a statement pool.............................................................................129

Freezing and unfreezing the statement pool............................................................................129

Generating a statement pool export file...................................................................................129

DataDirect Statement Pool Monitor interfaces and classes.....................................................130

DataDirect Test...................................................................................................................................132

DataDirect Test tutorial.............................................................................................................132

Tracking JDBC calls with DataDirect Spy...........................................................................................165

Enabling DataDirect Spy..........................................................................................................165


Contents

Connection Property Descriptions...........................................................169AuthenticationDatabase......................................................................................................................172

AuthenticationMethod.........................................................................................................................173

ConfigOptions.....................................................................................................................................173

ColumnDiscoverySampleSize (Configuration Option).............................................................175

DefaultVarcharSize (Configuration Option)..............................................................................175

KeywordConflictSuffix (Configuration Option)..........................................................................177

LeadingUnderscoreReplacement (Configuration Option)........................................................177

MaxVarcharSize (Configuration Option)..................................................................................178

MinVarcharSize (Configuration Option)...................................................................................179

SchemaFilter (Configuration Option).......................................................................................180

UppercaseIdentifiers (Configuration Option)...........................................................................181

CreateDB............................................................................................................................................182

DatabaseName...................................................................................................................................183

EncryptionMethod..............................................................................................................................184

FetchSize............................................................................................................................................185

HostName...........................................................................................................................................186

HostNameInCertificate.......................................................................................................................187

ImportStatementPool..........................................................................................................................188

InitializationString...............................................................................................................................188

KeyPassword......................................................................................................................................189

KeyStore.............................................................................................................................................190

KeyStorePassword..............................................................................................................................190

LogConfigFile.....................................................................................................................................191

LoginConfigName...............................................................................................................................192

LoginTimeout......................................................................................................................................193

MaxPooledStatements........................................................................................................................193

Password............................................................................................................................................194

PortNumber........................................................................................................................................195

ReadOnly............................................................................................................................................196

ReadPreference .................................................................................................................................197

RegisterStatementPoolMonitorMBean...............................................................................................198

ResultMemorySize.............................................................................................................................198

SchemaMap.......................................................................................................................................200

ServicePrincipalName........................................................................................................................201

SpyAttributes......................................................................................................................................202

TransactionMode................................................................................................................................203

TrustStore...........................................................................................................................................203

TrustStorePassword............................................................................................................................204

User....................................................................................................................................................205

ValidateServerCertificate....................................................................................................................206


Contents

Troubleshooting.........................................................................................207Troubleshooting your application........................................................................................................207

Turning on and off DataDirect Spy logging..............................................................................208

DataDirect Spy log example....................................................................................................208

Troubleshooting connection pooling...................................................................................................210

Enabling tracing with the setTracing method...........................................................................210

Pool Manager trace file example..............................................................................................211

Troubleshooting statement pooling.....................................................................................................214

Generating an export file with the exportStatement method....................................................215

Statement pool export file example.........................................................................................215

Troubleshooting Out-of-Memory Errors..............................................................................................215

Using Java logging.............................................................................................................................216

Logging Components...............................................................................................................216

Configuring Logging.................................................................................................................217

Contacting Technical Support.............................................................................................................218

Supported SQL Functionality...................................................................221Delete.................................................................................................................................................221

Insert..................................................................................................................................................222

Refresh Map (EXT).............................................................................................................................223

Reload Map (EXT)..............................................................................................................................224

Select..................................................................................................................................................224

Select Clause...........................................................................................................................226

Update................................................................................................................................................236

SQL Expressions................................................................................................................................237

Column Names........................................................................................................................237

Literals.....................................................................................................................................237

Operators.................................................................................................................................240

Functions.................................................................................................................................243

Conditions................................................................................................................................243

Subqueries.........................................................................................................................................244

IN Predicate.............................................................................................................................245

EXISTS Predicate....................................................................................................................245

UNIQUE Predicate...................................................................................................................245

Correlated Subqueries.............................................................................................................246

SQL escape sequences for JDBC............................................................249Date, time, and timestamp escape sequences...................................................................................250

Scalar functions..................................................................................................................................250

Outer join escape sequences.............................................................................................................251

LIKE escape character sequence for wildcards..................................................................................252

CAST_TO_NATIVE function escape..................................................................................................252


Contents

JDBC support.............................................................................................255JDBC and JVM compatibility..............................................................................................................255

Supported functionality.......................................................................................................................255

Array........................................................................................................................................256

Blob..........................................................................................................................................256

CallableStatement...................................................................................................................257

Clob.........................................................................................................................................269

Connection...............................................................................................................................271

ConnectionEventListener.........................................................................................................276

ConnectionPoolDataSource.....................................................................................................276

DatabaseMetaData..................................................................................................................276

DataSource..............................................................................................................................285

Driver.......................................................................................................................................285

ParameterMetaData.................................................................................................................286

PooledConnection....................................................................................................................287

PreparedStatement..................................................................................................................287

Ref...........................................................................................................................................292

ResultSet.................................................................................................................................292

ResultSetMetaData..................................................................................................................303

RowSet....................................................................................................................................304

SavePoint.................................................................................................................................304

Statement................................................................................................................................304

StatementEventListener...........................................................................................................308

Struct.......................................................................................................................................309

XAConnection..........................................................................................................................309

XADataSource.........................................................................................................................309

XAResource.............................................................................................................................309

JDBC extensions.......................................................................................311Using JDBC wrapper methods to access JDBC extensions...............................................................312

DatabaseMetaData interface..............................................................................................................313

DDBulkLoad interface.........................................................................................................................313

ExtConnection interface......................................................................................................................320

ExtDatabaseMetaData interface.........................................................................................................325

ExtLogControl class............................................................................................................................325

Designing JDBC applications for performance optimization................327Using database metadata methods....................................................................................................328

Minimizing the use of database metadata methods................................................................328

Avoiding search patterns.........................................................................................................329

Using a dummy query to determine table characteristics........................................................329

Returning data....................................................................................................................................330


Contents

Returning long data.................................................................................................................330

Reducing the size of returned data..........................................................................................331

Choosing the right data type....................................................................................................331

Retrieving result sets...............................................................................................................331

Selecting JDBC objects and methods ...............................................................................................332

Using parameter markers as arguments to stored procedures...............................................332

Using the statement object instead of the PreparedStatement object.....................................332

Using batches instead of prepared statements.......................................................................333

Choosing the right cursor.........................................................................................................334

Using get methods effectively..................................................................................................334

Retrieving auto-generated keys...............................................................................................335

Managing connections and updates...................................................................................................335

Managing connections.............................................................................................................336

Managing commits in transactions..........................................................................................336

Choosing the right transaction model......................................................................................337

Using updateXXX methods......................................................................................................337

Using getBestRowIdentifier.....................................................................................................337

Glossary.......................................................................................................339

Index............................................................................................................343


Contents

1Welcome to the Progress DataDirect forJDBC for MongoDB Driver

The Progress®

DataDirect®

for JDBC™

for MongoDB™

driver supports SQL to select data from MongoDB 2.2 andhigher. Some insert, update, and delete capabilities are also supported.The driver translates the SQL statementsprovided by an application, enabling you to leverage your knowledge of SQL. Additionally, the driver createsa relational schema of your native MongoDB data to support SQL access to MongoDB's flexible schema datamodel. The relational schema created by the driver is written to a configuration file that can be shared amongclient machines accessing a common data store. The configuration file can be modified subsequently usingthe DataDirect Schema Tool.

The DataDirect Schema Tool is included with the driver. The Schema Tool enables you to customize andperfect the relational schema used to access your MongoDB data. The Schema Tool provides metadata,statistics, and a hierarchical view of your data, as it guides you through the mapping process.You can use theSchema Tool's Table Wizard to expose tabular relationships among your MongoDB data collections. Usingthe Schema Tool, you can create new relational views of your data with options to flatten, normalize, or customizeyour MongoDB data. In turn, the Schema Tool allows you to define data types consistently within columns, acritical step in ensuring data integrity.

Once you have an established relational schema, the relationships among objects can be reported throughthe following metadata methods: getColumns, getImportedKeys, getExportedKeys, getPrimaryKeys, getTypeInfo,getCrossReference, getBestRowIdentifier, getIndexInfo, getSchemas, getCatalogs, and getTables. Furthermore,when performing joins, the driver leverages data relationships in MongoDB collections, minimizing the amountof data that needs to be fetched over the network.


• What's New in this Release?

• Requirements


• Data Source and Driver Classes

• Version String Information

• Connection Properties

• Mapping Objects to Tables

• Data Types

• Contacting Technical Support

What's New in this Release?

Support and certificationVisit the following web pages for the latest support and certification information.

• Release Notes

• Supported Configurations

• DataDirect Support Matrices

Changes since the 6.0.2 Release

• Driver Enhancements

• The new SchemaFilter config option allows you to specify the database and collections pairs for whichyou want the driver to fetch metadata. Using this option can provide can significantly improve connectiontimes by limiting the collections for which metadata is fetched to only those that are required by yourapplication. See SchemaFilter (Configuration Option) on page 180 for details.

• The driver and schema tool have been enhanced to allow you to limit sampling to only new collectionswhen refreshing the schema map. This provides for quicker processing times if you only want to mapnew collections or if existing collections are unchanged.You can specify the sampling behavior usingthe following methods:

• The Schema Tool: At connection, the Schema Tool prompts you to select the sampling behavior forthe session. See Launching the Schema Tool with User/ID Password Authentication or NoAuthentication on page 49 or Launching the Schema Tool with Kerberos Authentication on page 55for details.

• The Refresh Map SQL extension: When executing the Refresh Map SQL extension, you can specifythe NEW option in the statement to limit sampling to only new collections. See Refresh Map (EXT) onpage 223 for details.

• The driver has been enhanced to support the native Decimal128 data type, which maps to the DecimalJDBC type by default. See Data Types on page 24 for details.

• The CAST_TO_NATIVE function escape has been introduced to select or insert a value of a specificnative type. This can be particularly useful when MongoDB has inconsistent native types for a givenfield. Currently, CAST_TO_NATIVE can only be used with the ObjectID type in SELECT statement filtersand literal INSERT values. See Default Mapping of Columns with Inconsistent Native Data Types onpage 26 and CAST_TO_NATIVE function escape on page 252 for details.


Chapter 1: Welcome to the Progress DataDirect for JDBC for MongoDB Driver

https://www.progress.com/jdbc/release-history/mongodb-jdbc

https://www.progress.com/supported-configurations/datadirect?ds=mongodb

https://www.progress.com/matrices/datadirect

Changes for the 6.0.2 Release


• The driver has been enhanced to support Kerberos authentication. See Authentication on page 100 fordetails.

• Changed Behavior

• The SchemaMap connection property has been created to replace the SchemaDefinition connectionproperty. The SchemaMap property should now be used to specify the path of the configuration filewhere the relational map of native data is written. See SchemaMap on page 200 for details.



• The driver has been enhanced to resolve naming conflicts that can occur when exposing native objectsusing unquoted, uppercase identifiers (the default behavior). To avoid conflicts, the driver appends anunderscore separator and integer (for example, _1) to identifiers that differ only by case. See Identifierson page 105 and Naming Conflicts on page 89 for details.

• The DefaultVarcharSize configuration option has been enhanced to generate dynamic default lengthsfor VARCHAR columns when specifying a multiplier value (for example, 2x) for the option.When specifyinga multiplier value, the default length for a VARCHAR column is determined by multiplying the valuespecified by the size of the largest value detected in that column. This results in a default length that isproportionate to the size of the data within the column, which can improve the memory efficiency withinthe driver and application. The default value for this option has been updated to 1.5x.

In addition, you can further define the default length for VARCHAR columns by tuning the newMaxVarcharSize and MinVarcharSize configuration options.These options allow you to specify maximumand minimum size limits for the default length generated by the DefaultVarcharSize configuration option.When tuned for your data, MaxVarcharSize and MinVarcharSize can improve memory efficiency andavoid the undesired truncation of VARCHAR values.

See DefaultVarcharSize (Configuration Option) on page 175, MaxVarcharSize (Configuration Option) onpage 178, and MinVarcharSize (Configuration Option) on page 179 for details.

• The new KeywordConflictSuffix configuration option allows you to specify the suffix that is appended toobject and field names that conflict with SQL engine keywords. See KeywordConflictSuffix (ConfigurationOption) on page 177 for details.

• The driver has been enhanced to use the MongoDB aggregation framework to improve performance inthe execution of SQL queries using LIMIT, ORDER BY, and TOP clauses.

• The following new SQL extensions have been added to the driver:

• Refresh Map: REFRESH MAP discovers native objects that have been added to the native datastore since connection or since the last refresh and maps the objects into your relational view ofnative data. It also incorporates any configuration changes made to your relational view by reloadingthe schema map and associated files. See Refresh Map (EXT) on page 223 for details.

• Reload Map: RELOAD MAP reloads the schema map and associated files, allowing you to updateyour relational view of native data while the driver is connected to the data store. See Reload Map(EXT) on page 224 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 configuration of the FetchSize connection property and the introductionof the ResultMemorySize connection property. See FetchSize on page 185 and ResultMemorySize onpage 198 for more information.


What's New in this Release?

• The driver has been enhanced to further ensure data integrity when mapping inconsistent data types toa relational schema. See Default Mapping of Columns with Inconsistent Native Data Types on page 26for details.


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



• When first connecting to a MongoDB server, the driver automatically creates a normalized schema ofthe data and generates a SchemaMap (formerly, SchemaDefinition) for housing and sharing thenormalized schema. See Normalizing Native Data on page 17 and SchemaMap on page 200 for details.

• Native MongoDB data is fully normalized during the normalization process, regardless of the depth ofnested arrays, documents, and objects. See Normalizing Native Data on page 17 and Generating aNormalized View on page 63 for details.

• The driver uses the MongoDB aggregation framework to improve performance in the execution of SQLqueries using aggregates, GROUP BY clauses, or HAVING clauses.

• Schema Tool Enhancements

• The new Restart Wizard feature allows you to reset the relational view of your data from the Table Wizardmenu. See Restarting the Wizard on page 90 for details.

• The new Update Schema feature allows you to map all new native objects to your schema map with asingle click. See Mapping Newly Detected Objects on page 81 for details.

• Support for selecting multiple objects in the Table Wizard for improved object management whencustomizing your schema.


• The driver no longer supports in-memory tables (also referred to as "local tables").

• The 6.0 driver pushes down SQL queries to MongoDB whenever possible. Queries that cannot be pusheddown to MongoDB in the 6.0 driver may be slower than comparable queries made with previous versionsof the driver because data may be paged to disk while completing an operation. If you experience slowperformance, please contact Technical Support. Our team will quickly address any performance issuesyou encounter.

• The Normalization Depth option is no longer available in the Schema Tool because native MongoDBdata is now fully normalized, regardless of depth, during the normalization process. See Generating aNormalized View on page 63 for details.

• The 6.0 driver and Schema Tool do not support schema maps (formerly, schema definitions) createdwith previous versions of the product. Therefore, you should reproduce your 5.1.x schema maps withthe 6.0 driver or Schema Tool.



https://www.progress.com/support-and-services

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 Virtual Machine (JVM) that is Java SE 8 or higher,including Oracle JDK, OpenJDK, and IBM SDK (Java)distributions.

JDBC 4.0 API


JDBC 3.0 API


JSR 114 Rowsets


JDBC 1.22 API

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

Data Source and Driver ClassesThe driver class is:

com.ddtek.jdbc.mongodb.MongoDBDriver

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

Table 2: Choosing a Data Source Class

Data Source ClassIf your application requires...

com.ddtek.jdbcx.mongodb.MongoDBDataSource40JDBC 4.0 functionality and higher

com.ddtek.jdbcx.mongodb.MongoDBDataSourceJDBC 3.x functionality and earlierspecifications


Requirements

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.1.000002(C0003.F000001.U000002) |____| |___| |_____| |_____| Driver Cloud Frame Utl

Connection PropertiesYou can use connection properties to customize the driver for your environment. Connection properties canbe used to accomplish different tasks, such as implementing driver functionality and optimizing performance.You can specify connection properties in a connection URL or within a JDBC data source object.

See Using Connection Properties on page 90 and Connection Property Descriptions on page 169 for moreinformation.

Mapping Objects to TablesData mapping describes how elements are mapped between two distinct data models.To support SQL accessto a MongoDB database, the MongoDB database must be mapped to a relational schema. Native MongoDBdata can be either normalized or flattened to create a relational schema.

Normalization takes place upon initial connection with the driver or when creating a new schema map usingthe Schema Tool. During the normalization process, MongoDB collections are normalized into sets of parent-childtables. The child tables correspond to complex types, such as arrays and embedded documents (orsubdocuments), and have a foreign key relationship to the parent table.

Flattening can only take place by creating a schema map using the Schema Tool. When flattening data withthe Schema Tool, MongoDB collections are flattened into single, relational tables. All fields, including thosethat may comprise complex types, are organized as columns within the relational table.



Whether you normalize or flatten your native data, the relational schema is written to the schema mapconfiguration file. This configuration file is an XML file that may be shared across servers. The configurationfile can be subsequently modified using the Schema Tool.

See alsoSchemaMap on page 200Creating and Customizing Schemas Using the DataDirect Schema Tool on page 48

Normalizing Native Data

When you first connect to a MongoDB server, the driver automatically generates a normalized view of yourdata.You can also use the Schema Tool to normalize your native MongoDB data. When your native data isnormalized, each MongoDB collection is decompounded into a set of parent-child tables. Fields containingsimple types are mapped as columns in a parent table, while complex types, such as subdocuments and arrays,are mapped as child tables. Child tables share a foreign key relationship with their parent table.

Note: Child tables are only extracted from arrays if all the sampled rows in the column have the native Arraydata type. See ConfigOptions on page 173 for information on setting the sample size.

For example, the collection residents contains the array vehicles and subdocuments in the addressdocument (or object). The collection's JSON structure can be rendered as follows:

{"_id": "ajx363", "name": "Sydney Smith", "address": {"street": "101 Main Street", "city": "Raleigh", "state": "NC"}, "county": "Wake", "vehicles: ["car", "boat", "bicycle"]}

{"_id": "tzn525", "name": "Cora Welch", "address": {"street": "191 First Street", "city": "Chapel Hill", "state": "NC"}, "county": "Orange", "vehicles": ["scooter", "truck", "bicycle"]}

The collection has been decompounded into separate but related tables.The normalization of the residentscollection yields one parent table and two child tables. In the parent table, the _id field is mapped as a primarykey column, and fields with other simple types are mapped as relational columns. The parent table adopts thename RESIDENTS and takes the following form:

COUNTYNAME_ID (PK)

WakeSydney Smithajx363

OrangeCora Welchtzn525

The information in the vehicles array maps to a RESIDENTS_VEHICLES child table. In this table, a columnwhich refers back to the parent table is mapped as a concatenation of the parent table and the _id field:RESIDENTS_ID. (This column establishes a foreign key relationship to the parent table based on the _idfield.) The vehicles array is mapped to the column VEHICLES. Each value in the VEHICLES columncorresponds to an element in the vehicles array. In addition, the driver generates a third column to establisha primary key for the child table: VEHICLES_GENERATED_ID. (This automatically generated column enablesthe driver to normalize nested arrays to any depth. The format of the unique keys are internal to the driver.)This child table would take the following form:


Mapping Objects to Tables

VEHICLES_GENERATED_ID (PK)VEHICLESRESIDENTS_ID (FK)

unique keycarajx363

unique keyboatajx363

unique keybicycleajx363

unique keybicycletzn525

unique keyscootertzn525

unique keytrucktzn525

The information in the address object maps to a RESIDENTS_ADDRESS child table. In this table, a columnwhich refers back to the parent table is mapped as a concatenation of the parent name and the _id field:RESIDENTS_ID. (This column establishes a foreign key relationship to the parent table and functions as aprimary key within the child table.) Each subdocument found in the address object is mapped as a column.This table would take the following form:

STATECITYSTREETRESIDENTS_ID (PK &FK)

NCRaleigh101 Main Streetajx363

NCChapel Hill191 First Streettzn525

Mapping Nested Complex Types

The following examples illustrate several ways the normalization of complex types are handled.

A Subdocument Nested in a SubdocumentIn this example, the subdocument location contains the subdocuments city and state in the employeecollection:

{"_id": pdn313, "name": "Charlotte", "manager": {"name": "Robert", "department": "Development", "location": {"city": "Tulsa", "state": "OK"}}}

{"_id": gkx136, "name": "Benjamin", "manager": {"name": "Michael", "department": "Quality Assurance", "location": {"city": "Dallas", "state": "TX"}}}

First, the EMPLOYEE parent table would be derived from the simple types _id and name as follows:



NAME_ID

Charlottepdn313

Benjamingkx136

Second, the EMPLOYEE_MANAGER child table would be derived from the manager object. The id_ field ismapped as EMPLOYEE_ID. (This column establishes a foreign key relationship to the parent table and functionsas a primary key within the child table.) In turn, the name and department subdocuments are mapped ascolumns. The resulting table would take the following form:

DEPARTMENTNAMEEMPLOYEE_ID (PK & FK)

DevelopmentRobertpdn313

Quality AssuranceMichaelgkx136

Third, an EMPLOYEE_MANAGER_LOCATION child table would be derived from the location object. The id_field is mapped as EMPLOYEE_MANAGER_ID. (As in the previous table, this column establishes a foreign keyrelationship to the parent table and functions as a primary key within the child table.) The city and statesubdocuments, which indicate the location of an employee's manager, are mapped as CITY and STATEcolumns. The resulting table would take the following form:

STATECITYEMPLOYEE_MANAGER_ID (PK& FK)

OKTulsapdn313

TXDallasgkx136

Subdocuments Nested in an ArrayIn the collection employee, the addresses array contains the subdocuments: label, street, city, andstate.

{"_id": ajx456, "name": "Andrea", "addresses": [ {"label": "Home", "street": "101 Main St", "city": "Raleigh", "state": "NC"}, {"label": "Work", "street": "303 Main St", "city": "Morrisville", "state": "NC"} ]}

First, the EMPLOYEE parent table is derived from the simple types _id and name as follows:

NAME_ID

Andreaajx456



Second, the EMPLOYEE_ADDRESSES child table would be derived from the addresses array. In this scenario,the id_ field is mapped as EMPLOYEE_ID and retains a foreign key column relationship to the parent table.Next, each of the subdocuments in the array are mapped as columns. The driver also generates an additionalcolumn to establish a primary key for the child table:ADDRESSES_GENERATED_ID.This automatically generatedcolumn enables the driver to normalize nested arrays to any depth. The unique keys are internal to the driver.The resulting table takes the following form:

ADDRESSES_

GENERATED_ID

(PK)

STATECITYSTREETLABELEMPLOYEE_ID(FK)

unique keyNCRaleigh101 Main StHomeajx456

unique keyNCMorrisville303 Main StWorkajx456

An Array Nested in a DocumentIn a separate scenario, the manager document contains the emails array in the employee collection. Thecollection has the following JSON structure:

{"_id": ajp211, "name": "Mark", "manager": {"name": "Cynthia", "emails": ["[email protected]", "[email protected]"]}}{"_id": mpc393, "name": "Deborah", "manager": {"name": "Cynthia", "emails": ["[email protected]", "[email protected]"]}}{"_id": dlm215, "name": "Jason", "manager": {"name": "Chris", "emails": ["[email protected]", "[email protected]"]}}

Again, the EMPLOYEE parent table would be derived from the simple types _id and name as follows:

NAME_ID

Markajp211

Deborahmpc393

Jasondlm215

Next, the EMPLOYEE_MANAGER child table would be derived from the manager object. As in previous examples,the id_ field is mapped as EMPLOYEE_ID and retains a foreign key relationship to the parent table. In turn,the nested name subdocument (the name of the manager) is mapped as a column. Next, the emails array ismapped to the column EMAILS. Each value in the EMAILS column corresponds to an element in the emailsarray. The driver also generates an additional column to establish a primary key for the child table:MANAGER_GENERATED_ID. Note that the names and emails in the following this child table are those of themanagers but are linked to the employee identification number.



MANAGER_

GENERATED_ID

(PK)

EMAILSNAMEEMPLOYEE_ID (FK)

unique [email protected]






An Array Nested in an ArrayIn the collection offices, the departments array contains an employees array.

{"_id": au32, "city": "Bedford", "departments": [{"name": "Development", "employees": [ {"first": "Leslie", "last": "Jacobs"}, {"first": "Emma", "last": "Alves"}, {"first": "Brad", "last": "Jones"} ] }, {"name": "Human Resources", "employees": [ {"first": "Joseph", "last": "Lu"}, {"first": "Margaret", "last": "Baker"}, {"first": "Chetna", "last": "Campbell"} ] }, {"name": "IT", "employees": [ {"first": "Caroline", "last": "Evans"}, {"first": "Markus", "last": "Campanella"}, {"first": "Jennifer", "last": "Bradley"} ] }] },{"_id": xn44, "city": "Morrisville", "departments": [{"name": "Development", "employees": [ {"first": "Charles", "last": "Scott"}, {"first": "Mary", "last": "Gonzales"}, {"first": "Phil", "last": "McEnroe"} ] }, {"name": "Operations", "employees": [ {"first": "Rachel", "last": "Cullingford"}, {"first": "Lance", "last": "Friedman"}, {"first": "Amanda", "last": "Giachetti"} ] },



{"name": "IT", "employees": [ {"first": "Ingrid", "last": "Burkis"}, {"first": "Catherine", "last": "Wheeler"}, {"first": "Jacob", "last": "Williams"} ] }]}

First, an OFFICES parent table is derived from the _id and city simple types. The _id field is mapped asthe primary key column _ID, and the city field is mapped as the relational column CITY.

CITY_ID (PK)

Bedfordau32

Morrisvillexn44

Next, an OFFICES_DEPARTMENTS child table is derived from the departments array. The OFFICES_IDcolumn is generated to establish a foreign key relationship to the parent table based on the _id field. Thedepartments array is mapped to the column DEPARTMENTS. Each value in the DEPARTMENTS columncorresponds to an element in the departments array.The DEPARTMENTS_GENERATED_ID column is generatedto establish a primary key for the child table. (The unique keys are internal to the driver.)

DEPARTMENTS_GENERATED_ID(PK)

DEPARTMENTSOFFICES_ID (FK)

unique keyDevelopmentau32

unique keyHuman Resourcesau32

unique keyITau32

unique keyDevelopmentxn44

unique keyOperationsxn44

unique keyITxn44

The employees array nested in the departments array is mapped as anOFFICES_DEPARTMENTS_EMPLOYEES child table. (This table is the child of the OFFICES_DEPARTMENTStable and the grandchild of the OFFICES table.) The OFFICES_DEPARTMENTS_ID column establishes a foreignkey relationship to the parent array based on the automatically generated primary key from theOFFICES_DEPARTMENTS table. The FIRST and LAST columns are derived from the first and last fieldscontained in each employees array. The EMPLOYEES_GENERATED_ID column is generated to establish aprimary key for the child table.



EMPLOYEES_

GENERATED_ID

(PK)

LASTFIRSTOFFICES_

DEPARTMENTS_ID

(FK)

unique keyJacobsLeslieauto-generated key fromthe parent array

unique keyAlvesEmmaauto-generated key fromthe parent array

unique keyJonesBradauto-generated key fromthe parent array

unique keyLuJosephauto-generated key fromthe parent array

unique keyBakerMargaretauto-generated key fromthe parent array

unique keyCampbellChetnaauto-generated key fromthe parent array

unique keyEvansCarolineauto-generated key fromthe parent array

unique keyCampanellaMarkusauto-generated key fromthe parent array

unique keyBradleyJenniferauto-generated key fromthe parent array

unique keyScottCharlesauto-generated key fromthe parent array

unique keyGonzalesMaryauto-generated key fromthe parent array

unique keyMcEnroePhilauto-generated key fromthe parent array

unique keyCullingfordRachelauto-generated key fromthe parent array

unique keyFriedmanLanceauto-generated key fromthe parent array

unique keyGiachettiAmandaauto-generated key fromthe parent array

unique keyBurkisIngridauto-generated key fromthe parent array



EMPLOYEES_

GENERATED_ID

(PK)

LASTFIRSTOFFICES_

DEPARTMENTS_ID

(FK)

unique keyWheelerCatherineauto-generated key fromthe parent array

unique keyWilliamsJacobauto-generated key fromthe parent array

Flattening Native Data

You can use the Schema Tool to flatten MongoDB collections into relational tables. The following exampleshows how the source data is flattened.

A data source has a collection called employee with the following structure:

{"_id": pdn313, "name": "Charlotte", "manager": {"name": "Robert", "emails": ["[email protected]", "[email protected]"] }}

The employee collection would be flattened into a relational table with the following structure:

MANAGER_EMAILS_1MANAGER_EMAILS_0MANAGER_NAMENAME_ID

[email protected]@email.comRobertCharlottepdn313

All fields are retained as separate columns in the resulting relational table. Simple types such as _id and namecorrespond directly to columns. In turn, subdocuments are flattened into columns using the<objectname>_<fieldname> pattern. Next, the emails array is flattened into two columns, using anextended version of the <arrayname>_<arrayindex> pattern:<objectname>_<arrayname>_<arrayindex>.

Note: As subdocuments or arrays are discovered at deeper and deeper levels, the<objectname>_<fieldname> or <arrayname>_<arrayindex> pattern is extended, for example,<objectname>_<objectname>_<fieldname>.

Data TypesThe following table shows how data types supported by the driver map to JDBC data types.

Note: Default mappings can be overridden using the Schema Tool. See "Defining Columns" for additionalinformation.



Table 3: Default Mapping for MongoDB Data Types

JDBC Data TypeMongoDB Data Type

LONGVARCHAR (-1)Array1

BIGINT (-5)Bigint

VARBINARY (-3)Bindata

BOOLEAN (16)Boolean

TIMESTAMP (93)Date

DECIMAL (3)Decimal1282

DOUBLE (8)Double

INTEGER (4)Integer

LONGVARCHAR (-1)Object1

VARCHAR (12)ObjectID3

CHAR (1), VARCHAR (12), or LONGVARCHAR (-1)String4, 5, 6

See alsoDefining Columns on page 86CAST_TO_NATIVE function escape on page 252DefaultVarcharSize (Configuration Option) on page 175Creating and Customizing Schemas Using the DataDirect Schema Tool on page 48

1 Complex data types can be returned as strings in the JSON format, or can be normalized such that nested elements are returnedas columns in a relational table.

2 The driver reports a precision of 68 digits for this type; however, the native type limits the maximum number of digits before orafter the decimal to 34 digits.

3 The CAST_TO_NATIVE function escape may be needed to select or insert a value of the ObjectID type when MongoDB hasinconsistent native types for a given field. See "Default Mapping of Columns with Inconsistent Native Data Types" and"CAST_TO_NATIVE Function Escape" for details.

4 When the driver discovers a column with a String size less than or equal to 4000 characters, String is mapped as VARCHARand the precision is 4000 characters. When a column with a String size greater than 4000 characters is discovered, String ismapped as LONGVARCHAR and precision is 16 MB.

5 During the initial discovery and normalization process, you can use the DefaultVarcharSize configuration option to specify thedefault length of fields that are discovered and mapped as Varchar by the driver. If the driver discovers a field with String dataof a greater length, the String data is truncated to the length of the specified value. See "DefaultVarcharSize (ConfigurationOption" for details.

6 You can map String to CHAR, VARCHAR, or LONGVARCHAR, regardless of the column size, using the Schema Tool. See"Creating and Customizing Schemas Using the DataDirect Schema Tool" and "Defining Columns" for details.


Data Types

Default Mapping of Columns with Inconsistent Native Data Types

Due to the flexibility of the MongoDB schema data model, your native data sources may not enforce consistentdata types. To ensure data integrity when mapping to a relational model, the driver describes columns withinconsistent native data types as a single SQL data type. The driver determines which SQL type to use basedon the combination of native types detected when sampling data. The following table lists combinations ofMongoDB data types and their default mapping for JDBC. If you need to change the JDBC data type, defaultmappings can be overridden using the Schema Tool. See "Defining Columns" for additional information.

Note: In some cases, a value with a specific native type can be concealed or obscured because the driverdescribes a field with inconsistent native types as a column with a single SQL type. The CAST_TO_NATIVEfunction escape allows users to send a value as it is defined in the MongoDB database, rather than how it isdescribed in the relational model of the data. Currently, CAST_TO_NATIVE can only be used with the ObjectIDtype in SELECT statement filters and literal INSERT values. See "CAST_TO_NATIVE Function Escape" fordetails.

Table 4: Default Mapping for Columns Containing Inconsistent MongoDB Data Types

JDBC Data TypeMongoDB Data Types

BIGINT (-5)Bigint and Integer

DOUBLE (8)Double and Integer

VARCHAR (12) or LONGVARCHAR (-1)7All other combinations

See alsoDefining Columns on page 86CAST_TO_NATIVE function escape on page 252Creating and Customizing Schemas Using the DataDirect Schema Tool on page 48

getTypeInfo()

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

7 When the driver discovers a column with 4000 characters or less, the column is mapped as VARCHAR and the precision is4000 characters.When the driver discovers a column with more than 4000 characters, the column is mapped as LONGVARCHARand precision is 16 MB.You can map columns to any supported data type, regardless of the size, using the Schema Tool. See"Creating and Customizing Schemas Using the DataDirect Schema Tool" and "Defining Columns" for details



Table 5: getTypeInfo() Results

MINIMUM_SCALE = 0

NULLABLE = 1 (Type allows null values)

NUM_PREC_RADIX = NULL

PRECISION = 16777204

SEARCHABLE = 0 (No support)

SQL_DATA_TYPE = NULL

SQL_DATETIME_SUB = NULL

UNSIGNED_ATTRIBUTE = NULL

TYPE_NAME = ARRAY 8

AUTO_INCREMENT = NULL

CASE_SENSITIVE = true

CREATE_PARAMS = NULL

DATA_TYPE = -1 (LONGVARCHAR)

FIXED_PREC_SCALE = false

LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = ARRAY

MAXIMUM_SCALE = NULL

MINIMUM_SCALE = 0


NUM_PREC_RADIX = 10

PRECISION = 19

SEARCHABLE = 3 (Supported for all WHERE clauses)



UNSIGNED_ATTRIBUTE = false

TYPE_NAME = BIGINT


CASE_SENSITIVE = false


DATA_TYPE = -5 (BIGINT)


LITERAL_PREFIX = NULL

LITERAL_SUFFIX = NULL

LOCAL_TYPE_NAME = BIGINT

MAXIMUM_SCALE = 0

MINIMUM_SCALE = NULL



PRECISION = 8000





TYPE_NAME = BINDATA




DATA_TYPE = -3 (VARBINARY)


LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = BINDATA

MAXIMUM_SCALE = 0

8 Complex data types can be returned as strings in the JSON format, or can be normalized such that nested elements are returnedas columns in a relational table.


Data Types




PRECISION = 1





TYPE_NAME = BOOLEAN




DATA_TYPE = 16 (BOOLEAN)




LOCAL_TYPE_NAME = BOOLEAN

MAXIMUM_SCALE = 0

MINIMUM_SCALE = 0



PRECISION = 23





TYPE_NAME = DATE




DATA_TYPE = 93 (TIMESTAMP)


LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = DATE

MAXIMUM_SCALE = 3

MINIMUM_SCALE = 0


NUM_PREC_RADIX = 10

PRECISION = 689





TYPE_NAME = DECIMAL128

AUTO_INCREMENT = false



DATA_TYPE = 3 (DECIMAL)




LOCAL_TYPE_NAME = DECIMAL128

MAXIMUM_SCALE = 34

9 The driver reports a precision of 68 digits for this type; however, the native type limits the maximum number of digits before orafter the decimal to 34 digits.



MINIMUM_SCALE = 0


NUM_PREC_RADIX = 10

PRECISION = 15





TYPE_NAME = DOUBLE




DATA_TYPE = 8 (DOUBLE)




LOCAL_TYPE_NAME = DOUBLE

MAXIMUM_SCALE = 0

MINIMUM_SCALE = 0


NUM_PREC_RADIX = 10

PRECISION = 10





TYPE_NAME =INTEGER




DATA_TYPE = 4 (INTEGER)




LOCAL_TYPE_NAME = INTEGER

MAXIMUM_SCALE = 0




PRECISION = 16777204

SEARCHABLE = 0 (No support)




TYPE_NAME =OBJECT 8




DATA_TYPE = -1 (LONGVARCHAR)


LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = OBJECT

MAXIMUM_SCALE = 0


Data Types




PRECISION = 24





TYPE_NAME = OBJECTID10




DATA_TYPE = 12 (VARCHAR)


LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = OBJECTID

MAXIMUM_SCALE = 0




PRECISION = 8000





TYPE_NAME = STRING




DATA_TYPE = 12 (VARCHAR) or -1 (LONGVARCHAR)11, 12, 13


LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = STRING

MAXIMUM_SCALE = 0

See alsoDefault Mapping of Columns with Inconsistent Native Data Types on page 26CAST_TO_NATIVE function escape on page 252DefaultVarcharSize (Configuration Option) on page 175Creating and Customizing Schemas Using the DataDirect Schema Tool on page 48Defining Columns on page 86

10 The CAST_TO_NATIVE function escape may be needed to select or insert a value of the ObjectID type when MongoDB hasinconsistent native types for a given field. See "Default Mapping of Columns with Inconsistent Native Data Types" and"CAST_TO_NATIVE Function Escape" for details.

11 When the driver discovers a column with a String size less than or equal to 4000 characters, String is mapped as VARCHARand the precision is 4000 characters. When a column with a String size greater than 4000 characters is discovered, String ismapped as LONGVARCHAR and precision is 16 MB.

12 During the initial discovery and normalization process, you can use the DefaultVarcharSize configuration option to specify thedefault length of fields that are discovered and mapped as Varchar by the driver. If the driver discovers a field with String dataof a greater length, the String data is truncated to the length of the specified value. See "DefaultVarcharSize (ConfigurationOption" for details.

13 You can map String to CHAR, VARCHAR, or LONGVARCHAR, regardless of the column size, using the Schema Tool. See"Creating and Customizing Schemas Using the DataDirect Schema Tool" and "Defining Columns" for details.



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

Once the driver is installed and configured, you can connect from your application to your database in eitherof the following ways.

• Using the JDBC DriverManager, 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).


• Data Source and Driver Classes

• Connecting Using the JDBC Driver Manager

• Connecting Using Data Sources

Data Source and Driver ClassesThe driver class is:








Connecting Using the JDBC Driver ManagerOne way to connect to a database is by using the JDBC DriverManager.getConnection() method. Asthe following example shows, this method specifies a string containing a connection URL.

Connection conn = DriverManager.getConnection("jdbc:datadirect:mongodb://MyServer:27017;DatabaseName=Test;SchemaMap=MyUserProfile\\AppData\\Local\\Progress\\DataDirect\\MongoDB_Schema\\MyServer.config;UserName=admin;Password=adminpass");

Setting the Classpath

The driver must be defined in your CLASSPATH variable before you can connect. The CLASSPATH is thesearch string your Java Virtual Machine (JVM) uses to locate JDBC drivers on your computer. If the driver isnot defined on your CLASSPATH, you will receive a class not found exception when trying to load thedriver. Set your system CLASSPATH to include the mongodb.jar file as shown, where install_dir is thepath to your product installation directory:

install_dir/lib/mongodb.jar

Windows Example

CLASSPATH=.;C:\Program Files\Progress\DataDirect\JDBC_60\lib\mongodb.jar

UNIX Example

CLASSPATH=.:/opt/Progress/DataDirect/JDBC_60/lib/mongodb.jar

Passing Connection URLs

This section shows the correct format for specifying a connection URL.

Syntax

jdbc:datadirect:mongodb://host:port;DatabaseName=database;SchemaMap=schema;[property=value[;...]]

where:

host

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


Chapter 2: Getting Started

port

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

DatabaseName

specifies the name of the database to which you want to connect. This value is used as the defaultqualifier for unqualified table names in SQL queries. Required for User/ID password authentication.

Important: This value is case-insensitive if you have access privileges to query the list of databases on theserver. If you do not have access, this value is case-sensitive.

SchemaMap

specifies the fully qualified path of the configuration file where the relational map of native data iswritten. The driver looks for this file when connecting to a MongoDB server. If the file does not exist,the driver creates one. See SchemaMap on page 200 for further details.

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

This example shows how to establish a connection to a MongoDB data store with user ID/passwordauthentication:

Connection conn = DriverManager.getConnection("jdbc:datadirect:mongodb://MyServer:27017;DatabaseName=Test;SchemaMap=C:\\Users\\MyUserProfile\\AppData\\Local\\Progress\\DataDirect\\MongoDB_Schema\\MyServer.config;UserName=admin;Password=adminpass");

Testing the Connection

You can also use DataDirect Test™ to establish and test a DriverManager connection. The screen shots inthis section 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:


Connecting Using the JDBC Driver Manager

3. Click Press Here to Continue.

The main dialog appears:



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

The Select A Database dialog appears:

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

6. In the Database field, specify all required connection properties.

For example:

jdbc:datadirect:mongodb://MyServer:27017;DatabaseName=Test;SchemaMap=MyUserProfile\AppData\Local\Progress\DataDirect\MongoDB_Schema\MyServer.config

7. If you did not specify your user name and password in the connection URL, enter this information in thecorresponding fields.

8. Click Connect.

If the connection information is entered correctly, the JDBC/Database Output window 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 132.

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 Implemented

Data sources are implemented through a data source class. A data source class implements the followinginterfaces.

• javax.sql.DataSource

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



See Data Source and Driver Classes on page 15 for data source class information.

Creating Data Sources

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

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 Application

Applications 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. Finally, theDataSource.getConnection() method is called to establish a connection.


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



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

• Creating and Customizing Schemas Using the DataDirect Schema Tool

• Using Connection Properties

• Performance Considerations

• Data Encryption

• Authentication

• MongoDB Sharding

• Identifiers

• IP Addresses

• Parameter Metadata

• Views and Remote/Local Tables

• Isolation Levels

• Unicode support

• Error Handling


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

Data Source and Driver Classes

The driver class is:








One way to connect to a database is by using the JDBC DriverManager.getConnection() method. Asthe following example shows, this method specifies a string containing a connection URL.

Connection conn = DriverManager.getConnection("jdbc:datadirect:mongodb://MyServer:27017;DatabaseName=Test;SchemaMap=MyUserProfile\\AppData\\Local\\Progress\\DataDirect\\MongoDB_Schema\\MyServer.config;UserName=admin;Password=adminpass");


Chapter 3: Using the driver

Setting the ClasspathThe driver must be defined in your CLASSPATH variable before you can connect. The CLASSPATH is thesearch string your Java Virtual Machine (JVM) uses to locate JDBC drivers on your computer. If the driver isnot defined on your CLASSPATH, you will receive a class not found exception when trying to load thedriver. Set your system CLASSPATH to include the mongodb.jar file as shown, where install_dir is thepath to your product installation directory:

install_dir/lib/mongodb.jar

Windows Example

CLASSPATH=.;C:\Program Files\Progress\DataDirect\JDBC_60\lib\mongodb.jar

UNIX Example

CLASSPATH=.:/opt/Progress/DataDirect/JDBC_60/lib/mongodb.jar

Passing Connection URLsThis section shows the correct format for specifying a connection URL.

Syntax

jdbc:datadirect:mongodb://host:port;DatabaseName=database;SchemaMap=schema;[property=value[;...]]

where:

host

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

port

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

DatabaseName

specifies the name of the database to which you want to connect. This value is used as the defaultqualifier for unqualified table names in SQL queries. Required for User/ID password authentication.


SchemaMap

specifies the fully qualified path of the configuration file where the relational map of native data iswritten. The driver looks for this file when connecting to a MongoDB server. If the file does not exist,the driver creates one. See SchemaMap on page 200 for further details.

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


Connecting from an Application

This example shows how to establish a connection to a MongoDB data store with user ID/passwordauthentication:

Connection conn = DriverManager.getConnection("jdbc:datadirect:mongodb://MyServer:27017;DatabaseName=Test;SchemaMap=C:\\Users\\MyUserProfile\\AppData\\Local\\Progress\\DataDirect\\MongoDB_Schema\\MyServer.config;UserName=admin;Password=adminpass");

Testing the ConnectionYou can also use DataDirect Test™ to establish and test a DriverManager connection. The screen shots inthis section 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 the Database field, specify all required connection properties.

For example:

jdbc:datadirect:mongodb://MyServer:27017;DatabaseName=Test;SchemaMap=MyUserProfile\AppData\Local\Progress\DataDirect\MongoDB_Schema\MyServer.config

7. If you did not specify your user name and password in the connection URL, enter this information in thecorresponding fields.

8. Click Connect.

If the connection information is entered correctly, the JDBC/Database Output window 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 132.

Connecting Using Data Sources

A 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 Data Source and Driver Classes on page 15 for data source class information.



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.

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. Finally, theDataSource.getConnection() method is called to establish a connection.

Creating and Customizing Schemas Using theDataDirect Schema Tool

After installation, you can create and define your schema map using the DataDirect Schema Tool.The SchemaTool allows you to map your NoSQL data model to a relational model that exposes your data to relational,SQL-based applications. Using the Schema Tool's Table Wizard, you decide whether to extract your nativedata into flattened, normalized, or customized relational views. Once you select a relational model, you canfurther customize your schema by defining column data types and the order in which columns appear. Theschema maps created by the Schema Tool are stored in configuration files that allow them to be shared acrossservers.




Starting the Schema Tool

The DataDirect Schema Tool allows you to create a schema map or modify an existing one. When you createa schema map using the Schema Tool, it is written to a configuration file in a directory that you specify. Becauseschema maps are stored separately from the tool, they can be shared across networks and modified as needed.

During product installation, the Schema Tool is installed in the following default location.

• Windows systems: Program Files\Progress\DataDirect\JDBC_60\Tools\schematool.jar

• UNIX and Linux systems: /opt/Progress/DataDirect/JDBC_60/Tools/schematool.jar

The Schema Tool can be used with user/ID password authentication, Kerberos authentication, or noauthentication. For instructions on starting the Schema Tool, see "Launching the Schema Tool with User/IDPassword Authentication or No Authentication" or "Launching the Schema Tool in a Kerberos Environment."

Note: The Schema Tool is only offered as a GUI application. If your system does not support GUI applications,you will receive an error when opening the Schema Tool.

See alsoLaunching the Schema Tool with User/ID Password Authentication or No Authentication on page 49Launching the Schema Tool with Kerberos Authentication on page 55

Launching the Schema Tool with User/ID Password Authentication or NoAuthenticationTake the following steps to use the Schema Tool with user/ID password authentication or no authentication.

1. Start the Schema Tool jar file. The jar file is installed in the following default locations.

• Windows systems: Program Files\Progress\DataDirect\JDBC_60\Tools\schematool.jar


The Open Schema Map window appears.


Creating and Customizing Schemas Using the DataDirect Schema Tool

Note: If you are opening an existing schema map, you can reopen it either by choosing Recent SchemaMap and selecting the configuration file of the schema map you want to open, or by choosing Browse toSchema Map and navigating to the configuration file of the schema map that you want to open. When anexisting schema is opened, the Schema Tool automatically compares the content of the schema configurationfile to a snapshot of the data on the wire.When new native objects are discovered, the Schema Tool displaysthem in a specialized, hierarchical view of the data and allows you to update your schema accordingly. SeeMapping Newly Detected Objects on page 81 for more information.

2. Select an existing schema map or create a new one (refer to the "SchemaMap" connection property topicin your driver documentation for details):

• Selecting an existing map: Select a schema map from the Recent Schema Map field or click Browseto navigate to your schema map.

• Creating a map: Click Create. Specify the schema map path by navigating to the directory where youwant to store the configuration file. Type the name for the configuration file (for example,MySchema.config) in the File Name field. Click Create New Schema Map.You are returned to theOpen Schema Map window where the Schema Map Location field has been populated with the pathand file name of the schema map's configuration file.

3. In the fields provided, enter values for each of the connection properties described in the following table.



Table 8: Connection Properties

CharacteristicProperty

Specifies the name or the IP address of the server to which you wantto connect.

Important: In a Kerberos configuration, an IP address cannot beused, and the host name must be the same as the host name usedin the Kerberos service principal name.

Host Name

Specifies the port number of the server listener.The default is 27017.Port Number

4. From the Authentication Method drop-down menu, select the form of authentication appropriate to yourenvironment.

Note: For Kerberos authentication, see "Launching the Schema Tool with Kerberos Authentication."

• Select None if you are not using either user ID/password or Kerberos authentication. Then skip to Step6.

• Select User Name / Password to enable user ID/password authentication. Proceed to Step 5.

5. For user ID/password authentication, enter values for the authentication connection properties in the fieldsprovided. These properties are described in the following table.

Note: It is recommended that privileges for generating the schema map be equivalent to the accessprivileges for an application using the driver.Your authentication settings determine for which databasesthe Schema Tool retrieves metadata. If authentication is not used, the Schema Tool retrieves metadata forall databases on the server. If authentication is used, the Schema Tool returns only the metadata for thedatabase specified in the DatabaseName property. However, if you are assigned the clusterAdmin role, theSchema Tool returns metadata for all the databases on the server for which you have read privileges.

Table 9: User ID/Password Authentication Properties


Specifies the name of the database to which you want to connect.Database Name

Specifies the user ID that is used to connect to your database.User Name

Specifies the password that is used to connect to your database.Password

Note: If the values you specify for authentication properties do not match the actual values of theseproperties, a pop-up window appears and allows you to enter the correct values.



6. Optionally, specify configuration options to determine how native data is mapped to the relational schema.In the Configuration Options field, enter a semicolon-separated list of configuration options and theirvalues. For example, columnDiscoverySampleSize=1000;UppercaseIdentifiers=true;.Configuration options are described in the following table. For more detail, refer to the "ConfigOptions" topicin the driver documentation.

Table 10: Schema Tool Config Options

CharacteristicOption

Specifies the number of rows the driver fetches per collection whensampling data to detect columns and gather column statistics. Theinformation collected in these samples is used when defining a schemamap with the DataDirect Schema Tool. Larger fetch sizes returnsamples that are more representative of your data, but at the expenseof slower performance. See About Column Information and Statisticson page 74 for additional information on how sampling is used forstatistics.

The default is 1000.

ColumnDiscoverySampleSize

Determines the default length of fields that are mapped as VARCHAR.

The default is 1.5x.DefaultVarcharSize

Specifies a string of up to five alphanumeric characters that the driverappends to any object or field name that conflicts with a SQL enginekeyword. For example, if you specify KeywordConflictSuffix=TAB,the driver maps the Case object to CASETAB.

KeywordConflictSuffix

Specifies the string of characters that replace leading underscoresused in identifiers for collections, documents, and arrays.

LeadingUnderscoreReplacement

Specifies the maximum default length of fields that are mapped asVARCHAR when a multiplier is specified for the DefaultVarcharSizeconfiguration option (DefaultVarcharSize=multiplier).

MaxVarcharSize

Specifies the minimum default length, in characters, of fields that aremapped as VARCHAR when a multiplier value is specified for theDefaultVarcharSize configuration option(DefaultVarcharSize=multiplier).

MinVarcharSize




Specifies a comma-separated list of database and collection pairs forwhich you want the driver to fetch metadata. SchemaFilter cansignificantly improve connection times by limiting the collections forwhich metadata is fetched to only those that are required by yourapplication. This value takes the following form:

SchemaFilter=database_name:collection_name[[,database_name:collection_name]...]

See "SchemaFilter (Config Option)" for detailed list of supported values.

SchemaFilter

Specifies whether the driver maps all identifier names to uppercase.By default, the driver maps all identifier names to uppercase.

If set to true, the driver maps identifiers to uppercase.

If set to false, the driver maps identifiers to the mixed case name ofthe object being mapped. If mixed case identifiers are used, SQLstatements must enclose those identifiers in double quotation marks,and the case of the identifier must exactly match the case of theidentifier name.

See Naming Conflicts on page 89 for additional information aboutusing identifiers.

The default is true.

UppercaseIdentifiers

7. To configure SSL, specify connection property values in the Connection Options field assemicolon-separated key value pairs. For example,EncryptionMethod=SSL;ValidateServerCertificate=true;HostNameInCertificate=Server3.(Only connection properties related to Kerberos and SSL can be specified in the Connection Optionsfield.)

Note: To fully implement SSL, you must also specify SSL connection property values in the connectionstring used by your JDBC application. The connection property values in the Connection Options fieldmust match the values you specify in the connection URL used by your JDBC application.

Note: When creating or opening a schema map, the Schema Tool accesses data from the server for thepurpose of object mapping and generating column statistics. This process requires data to be transferredover networks, which can make data vulnerable to interception by unauthorized parties. To provide moresecure transmission of data, you should consider enabling SSL.

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




Specifies a host name for certificate validation when SSL encryption isenabled (EncryptionMethod=SSL) and validation is enabled(ValidateServerCertificate=true). This property is optional andprovides additional security against man-in-the-middle (MITM) attacks byensuring that the server the driver is connecting to is the server that wasrequested.

HostNameInCertificate

Specifies the password that is used to access the individual keys in thekeystore file when SSL is enabled (EncryptionMethod=SSL) and SSLclient authentication is enabled on the database server. This property isuseful when individual keys in the keystore file have a different passwordthan the keystore file.

KeyPassword

Specifies the directory of the keystore file to be used when SSL is enabled(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.

KeyStore

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

KeyStorePassword

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

TrustStore

Specifies the password that is used to access the truststore file when SSLis enabled (EncryptionMethod=SSL) and server authentication is used.The truststore file contains a list of the Certificate Authorities (CAs) that theclient trusts.

TrustStorePassword

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, anycertificate that is sent by the server must be issued by a trusted CertificateAuthority (CA).


ValidateServerCertificate

8. To create a new schema map, click Open Schema Map and proceed to Creating a Schema with the TableWizard on page 63.

9. If you are using an existing schema map, choose one of the following sampling behaviors to execute atconnection:



• All Collections: The driver samples all new and existing collections to detect changes. This providesthe most accurate view of your data, but, depending on the number and size of your collections, cantake a long time to process.

• Only New Collections:The driver samples only newly discovered collections.This provides the quickestprocessing time, allowing you to begin using the tool faster. If you only want to map new collections, orif your existing collections are unchanged, this method is recommended.

See alsoLaunching the Schema Tool with Kerberos Authentication on page 55

Launching the Schema Tool with Kerberos AuthenticationYour Kerberos environment should be fully configured before you launch the Schema Tool.You should referto your MongoDB and Java documentation for instructions on configuring Kerberos. For a Windows ActiveDirectory implementation, you should also consult your Windows documentation. For a non-Active Directoryimplementation (on a Windows or non-Windows operating system), you should consult MIT Kerberosdocumentation.

Important: A properly configured Kerberos environment must include a means of obtaining a Kerberos TicketGranting Ticket (TGT). For a Windows Active Directory implementation, Active Directory automatically obtainsthe TGT. However, for a non-Active Directory implementation, the means of obtaining the TGT must beautomated or handled manually.

Once your Kerberos environment has been configured, take the following steps to launch the Schema Tool.

1. Ensure your JAAS login configuration file includes an entry with authentication technology that the drivercan use to establish a Kerberos connection. (See "The JAAS Login Configuration File" for details.)

Note: The JAAS login configuration file installed with the driver(install_dir/lib/JDBCDriverLogin.conf) includes a default entry with the name JDBC_DRIVER_01.This entry specifies the Kerberos authentication technology used with an Oracle JVM.

The following examples show that the authentication technology used in a Kerberos environment dependson your JVM.

Oracle JVM

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

IBM JVM

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

2. Use one of the following methods to integrate the JAAS configuration file into your Kerberos environment,and then start the Schema Tool. (See "The JAAS Login Configuration File" for details.)

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.



Note: Regardless of operating system, forward slashes must be used when designating the path of theJAAS login configuration file.

Option 1. Set up a default configuration, and then start the Schema Tool. Modify the Java security propertiesfile to indicate the URL of the login configuration file with the login.config.url.n property where n isan integer connoting separate, consecutive login configuration files.When more than one login configurationfile is specified, then the files are 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

d) Start the Schema Tool jar file. The jar file is installed in the following default locations.

• Windows systems: ProgramFiles\Progress\DataDirect\JDBC_60\Tools\schematool.jar


Option 2. If your Kerberos environment does not include a default configuration as described in Option 1,you must use a JVM argument to specify the JAAS login configuration file and start the Schema Tool. Asthe following example shows, the JVM argument must specify the location of the JAAS login configurationfile with the java.security.auth.login.config system property as well as the location of the SchemaTool jar file.

java -Djava.security.auth.login.config=/home/users/test/driver.conf install_dir/Tools/schematool.jar

The Open Schema Map window appears.



Note: If you are opening an existing schema map, you can reopen it either by choosing Recent SchemaMap and selecting the configuration file of the schema map you want to open, or by choosing Browse toSchema Map and navigating to the configuration file of the schema map that you want to open. When anexisting schema is opened, the Schema Tool automatically compares the content of the schema configurationfile to a snapshot of the data on the wire.When new native objects are discovered, the Schema Tool displaysthem in a specialized, hierarchical view of the data and allows you to update your schema accordingly. SeeMapping Newly Detected Objects on page 81 for more information.

3. Select an existing schema map or create a new one (refer to the "SchemaMap" connection property topicin your driver documentation for details):

• Selecting an existing map: Select a schema map from the Recent Schema Map field or click Browseto navigate to your schema map.

• Creating a map: Click Create. Specify the schema map path by navigating to the directory where youwant to store the configuration file. Type the name for the configuration file (for example,MySchema.config) in the File Name field. Click Create New Schema Map.You are returned to theOpen Schema Map window where the Schema Map Location field has been populated with the pathand file name of the schema map's configuration file.

4. In the fields provided, enter values for each of the connection properties described in the following table.



Table 12: Connection Properties


Specifies the name or the IP address of the server to which you wantto connect.

Important: In a Kerberos configuration, the value of the HostNameproperty must match the fully qualified domain name (FQDN)registered with the KDC. In addition, an IP address cannot be usedfor the HostName connection property.

Host Name

Specifies the port number of the server listener.The default is 27017.Port Number

5. From the Authentication Method drop-down menu, select Kerberos to enable Kerberos authentication.

6. Complete the following two part process.

Note: It is recommended that privileges for generating the schema map be equivalent to the accessprivileges for an application using the driver.Your authentication settings determine for which databasesthe Schema Tool retrieves metadata. If authentication is not used, the Schema Tool retrieves metadata forall databases on the server. If authentication is used, the Schema Tool returns only the metadata for thedatabase specified in the DatabaseName property. However, if you are assigned the clusterAdmin role, theSchema Tool returns metadata for all the databases on the server for which you have read privileges.

Part 1. Enter values for the authentication connection properties in the fields provided. These propertiesare described in the following table.

Table 13: Kerberos Authentication Properties (Part 1)


Specifies the name of the database to which you want to connect.Database Name

Optional. Specifies the Kerberos user principal name. When this fieldis left blank, the Schema Tool uses the user principal name in theKerberos Ticket Granting Ticket (TGT).

User Name

Part 2. As appropriate, specify values for the AuthenticationDatabase, LoginConfigName, andServicePrincipalName connection properties in the Connection Options field in accordance with thefollowing guide lines. (Only connection properties related to Kerberos and SSL can be specified in theConnection Options field.)

Note: Values for these properties must be entered as semicolon-separated key value pairs. For example,AuthenticationDatabase=kerbuserpals;LoginConfigName=IBM_ENTRY;ServicePrincipalName=mydb/[email protected]

• Set the ServicePrincipalName connection property if the default value built by the driver does not matchthe service principal name registered with the KDC.



By default, the driver builds the ServicePrincipalName by concatenating the service name mongodb,the fully qualified domain name (FQDN) as specified in the Host Name field, and the default realm nameas specified in the Kerberos configuration file. If this value does not match the service principal nameregistered with the KDC, then the value of the service principal name registered with the KDC shouldbe specified for the ServicePrincipalName property.

The ServicePrincipalName takes the following form.

Service_Name/Fully_Qualified_Domain_Name@REALM_NAME

See "ServicePrincipalName" for details on the composition of the service principal name.

• Set the AuthenticationDatabase connection property if user principal names stored by MongoDB arestored in a database other than the default $external database. (See "AuthenticationDatabase" fordetails.)

• Set the LoginConfigName connection property if the name of the JAAS login configuration file entry isdifferent from the driver default JDBC_DRIVER_01. (See "The JAAS Login Configuration File" and"LoginConfigName" for details.)

JDBC_DRIVER_01 is the default entry name for the JAAS login configuration file(JDBCDriverLogin.conf) installed with the driver. When configuring your Kerberos environment,your network or system administrator may have used a different entry name. Check with your administratorto verify the correct entry name.

Table 14: Kerberos Authentication Properties (Part 2)


Specifies the database on the MongoDB server where user principal namesare stored for Kerberos authentication. The default is $external.AuthenticationDatabase

Specifies the name of the entry in the JAAS login configuration file thatcontains the authentication technology used by the driver or Schema Toolto establish a Kerberos connection.

LoginConfigName

Specifies the three-part service principal name registered with the keydistribution center (KDC) in a Kerberos configuration.ServicePrincipalName

7. Optionally, specify configuration options to determine how native data is mapped to the relational schema.In the Configuration Options field, enter a semicolon-separated list of configuration options and theirvalues. For example, columnDiscoverySampleSize=1000;UppercaseIdentifiers=true;.Configuration options are described in the following table. For more detail, refer to the "ConfigOptions" topicin the driver documentation.



Table 15: Schema Tool Config Options


Specifies the number of rows the driver fetches per collection whensampling data to detect columns and gather column statistics. Theinformation collected in these samples is used when defining a schemamap with the DataDirect Schema Tool. Larger fetch sizes returnsamples that are more representative of your data, but at the expenseof slower performance. See About Column Information and Statisticson page 74 for additional information on how sampling is used forstatistics.

The default is 1000.

ColumnDiscoverySampleSize

Determines the default length of fields that are mapped as VARCHAR.

The default is 1.5x.DefaultVarcharSize

Specifies a string of up to five alphanumeric characters that the driverappends to any object or field name that conflicts with a SQL enginekeyword. For example, if you specify KeywordConflictSuffix=TAB,the driver maps the Case object to CASETAB.

KeywordConflictSuffix

Specifies the string of characters that replace leading underscoresused in identifiers for collections, documents, and arrays.

LeadingUnderscoreReplacement

Specifies the maximum default length of fields that are mapped asVARCHAR when a multiplier is specified for the DefaultVarcharSizeconfiguration option (DefaultVarcharSize=multiplier).

MaxVarcharSize

Specifies the minimum default length, in characters, of fields that aremapped as VARCHAR when a multiplier value is specified for theDefaultVarcharSize configuration option(DefaultVarcharSize=multiplier).

MinVarcharSize




Specifies a comma-separated list of database and collection pairs forwhich you want the driver to fetch metadata. SchemaFilter cansignificantly improve connection times by limiting the collections forwhich metadata is fetched to only those that are required by yourapplication. This value takes the following form:

SchemaFilter=database_name:collection_name[[,database_name:collection_name]...]

See "SchemaFilter (Config Option)" for detailed list of supported values.

SchemaFilter

Specifies whether the driver maps all identifier names to uppercase.By default, the driver maps all identifier names to uppercase.

If set to true, the driver maps identifiers to uppercase.

If set to false, the driver maps identifiers to the mixed case name ofthe object being mapped. If mixed case identifiers are used, SQLstatements must enclose those identifiers in double quotation marks,and the case of the identifier must exactly match the case of theidentifier name.

See Naming Conflicts on page 89 for additional information aboutusing identifiers.


UppercaseIdentifiers

8. To configure SSL, specify connection property values in the Connection Options field assemicolon-separated key value pairs. For example,EncryptionMethod=SSL;ValidateServerCertificate=true;HostNameInCertificate=Server3.(Only connection properties related to Kerberos and SSL can be specified in the Connection Optionsfield.)

Note: To fully implement SSL, you must also specify SSL connection property values in the connectionstring used by your JDBC application. The connection property values in the Connection Options fieldmust match the values you specify in the connection URL used by your JDBC application.

Note: When creating or opening a schema map, the Schema Tool accesses data from the server for thepurpose of object mapping and generating column statistics. This process requires data to be transferredover networks, which can make data vulnerable to interception by unauthorized parties. To provide moresecure transmission of data, you should consider enabling SSL.






EncryptionMethod




Specifies a host name for certificate validation when SSL encryption isenabled (EncryptionMethod=SSL) and validation is enabled(ValidateServerCertificate=true). This property is optional andprovides additional security against man-in-the-middle (MITM) attacks byensuring that the server the driver is connecting to is the server that wasrequested.


Specifies the password that is used to access the individual keys in thekeystore file when SSL is enabled (EncryptionMethod=SSL) and SSLclient authentication is enabled on the database server. This property isuseful when individual keys in the keystore file have a different passwordthan the keystore file.

KeyPassword

Specifies the directory of the keystore file to be used when SSL is enabled(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.

KeyStore

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

KeyStorePassword


TrustStore

Specifies the password that is used to access the truststore file when SSLis enabled (EncryptionMethod=SSL) and server authentication is used.The truststore file contains a list of the Certificate Authorities (CAs) that theclient trusts.

TrustStorePassword

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, anycertificate that is sent by the server must be issued by a trusted CertificateAuthority (CA).



9. To create a new schema map, click Open Schema Map and proceed to Creating a Schema with the TableWizard on page 63.

10. If you are using an existing schema map, choose one of the following sampling behaviors to execute atconnection:



• All Collections: The driver samples all new and existing collections to detect changes. This providesthe most accurate view of your data, but, depending on the number and size of your collections, cantake a long time to process.

• Only New Collections:The driver samples only newly discovered collections.This provides the quickestprocessing time, allowing you to begin using the tool faster. If you only want to map new collections, orif existing collections are unchanged, this method is recommended.

Creating a Schema with the Table Wizard

It is recommended that you create a relational schema before you connect to a server. This process beginswith the DataDirect Schema Tool Table Wizard. Once you open the Table Wizard according to the instructionsdescribed in Starting the Schema Tool on page 49, the Table Wizard prompts you to select one of the followinginitial views to begin the process of creating a relational schema:

• Normalized View which presents your data in a relational format, mapping subdocuments and arrays aschild tables with foreign key relationship to a parent table. For instructions on how to generate a normalizedview of your data, see Generating a Normalized View on page 63.

• Flattened View which presents your data in a relational format, mapping subdocuments and arrays ascolumns within a comprehensive relational table. For instructions on how to generate a flattened view ofyour data, see Generating a Flattened View on page 65.

• Custom View which allows you to choose the native data you want to map to a relational schema. Forinstructions on how to begin the customization process with Custom View, see Starting with Custom Viewon page 67.

Generating a Normalized ViewAfter you open the Table Wizard according to the instructions in Starting the Schema Tool on page 49, youcan generate a normalized view of your data by taking the following steps:

1. Select Normalized View under Select an initial view for your data in the Table Wizard window.

The Table Wizard displays a graphic which shows how objects, such as embedded documents and arrays,are normalized into a relational structure.



2. Click OK to generate the normalized schema.

The Schema Tool's main display appears with a normalized view of your data in the left-hand panel.

Note: If you want to change the initial view of your data later, select File>Restart Wizard from the TableWizard dialog. Be aware that restarting the wizard will also overwrite any customizations you have madeto your schema map. See Restarting the Wizard on page 90 for more information.

3. Click the Save button to save the schema.

4. Click database and table nodes to tour the normalized schema structure.

A normalized view of your data has been generated and saved.



The Table Wizard has decomposed each collection into a parent table with multiple child tables. In the parent

table, the _id field is mapped as a primary key column and is denoted with the ID icon . The parent tablealso contains any columns derived from simple types (in contrast to subdocuments and arrays). In turn, childtables are derived from any complex types discovered in the source data. The child tables share a foreign keyrelationship with the parent table.When a subdocument is normalized into a child table, the primary key column

and the foreign key column are one and the same. Such a column is denoted with the ID/FK icon . Whenan array is normalized into a child table, the primary key column and foreign key column are distinct columns.

The primary key column is denoted with the ID icon , while the foreign key column is denoted with the FK

icon . For more information on relational mapping, refer to "Mapping Objects to Tables" in your driverdocumentation.

Depending on your work flow, you can now proceed with customizing the schema. See Customizing YourSchema on page 70 for details.

Generating a Flattened ViewAfter you open the Table Wizard according to the instructions in Starting the Schema Tool on page 49, youcan generate a flattened view of your database by taking the following steps:

1. Select Flattened View under Select an initial view for your data in the Table Wizard window.

The Table Wizard presents a graphic which shows how objects, such as subdocuments and arrays, areflattened into a relational structure.



2. Click OK to generate the flattened schema.

The Schema Tool's main display appears with the flattened view of your data in the left-hand panel.

Note: If you want to change the initial view of your data later, select File>Restart Wizard from the TableWizard dialog. Be aware that restarting the wizard overwrites any customizations you have made to yourschema map. See Restarting the Wizard on page 90 for more information.

3. Click the Save button to save the schema.

4. Click database and table nodes to tour the flattened schema structure.

A flattened view of your data has been generated and saved. The Schema Tool's main display appears witha flattened view of your data in the left-hand panel:



The Table Wizard has decomposed each collection into a relational table.The _id field is mapped as a primary

key column and denoted with the icon. Fields with simple types, such as address and name, are mappedas the corresponding columns ADDRESS and NAME. Subdocuments are flattened into columns using the<objectname>_<fieldname> pattern, and nested arrays are flattened into columns using the<arrayname>_<arrayindex> pattern. For more information on relational mapping, refer to "Mapping Objectsto Tables" in the driver documentation.

Depending on your work flow, you can now proceed with customizing the schema. See Customizing YourSchema on page 70 for details.

Starting with Custom ViewInstead of generating a normalized or flattened view of your data first, you can begin the process of customizingthe relational view of your data by selecting Custom View in the Table Wizard. Take the following steps tostart the customization process with the Table Wizard:

1. Open the Table Wizard according to the instructions in Starting the Schema Tool on page 49:



2. Select Custom View under Select an initial view for your data in the Table Wizard window.

3. Click OK.

Note: If you want to change the initial view of your data later, select File>Restart Wizard from the TableWizard dialog. Be aware that restarting the wizard will also overwrite any customizations you have madeto your schema map. See Restarting the Wizard on page 90 for more information.

The Schema Tool's main display appears:



4. From the main display, click the Add Table(s) button .

The Schema Tool Native View window appears:



From the Schema Tool Native View, you can begin customizing your relational schema in either of the followingways:

• By selecting objects one at a time from the Single Add tab (see Extracting a New Table on page 82)

• By selecting multiple objects at a time from the Bulk Add tab (see Mapping Native Objects on page 76)

See Customizing Your Schema on page 70 for details.

Customizing Your Schema

Depending on your work flow, you can either customize your database schema when you first create it or returnto a schema you have already created and modify it as the need arises. In either case, the DataDirect SchemaTool helps you accomplish several key tasks. See the following topics for details.



• Viewing Information and Statistics on page 71

• Mapping Native Objects in a Schema on page 76

• Adding Columns on page 84

• Removing Objects from a Schema on page 84

• Removing Columns on page 86

• Defining Columns on page 86

• Designating a Primary Key on page 87

• Naming Conflicts on page 89

Viewing Information and StatisticsThe Schema Tool provides information and statistics about your data that you can use to modify your schemamaps. Column information and statistics are affected by the Schema Tool's configuration (see About ColumnInformation and Statistics on page 74 for details). The following steps demonstrate how you can accessinformation and statistics.

1. To view database and table information, select the database you want to investigate from the left panel inthe main display.

Available database and table information is displayed in the panel to the right. In addition to other information,table names and whether they are visible in your relational schema are provided.



2. To view table and column information, select the table you want to investigate.

Available information is displayed in the panel to the right, including the position of the column, the columndata type, and (if applicable) column parameters.

Note: The Column Information pane is interactive. From this pane, in the main display, you can add columns,rename columns, change a column's data type, change data type parameters, and change the order inwhich columns appear in a table. See Defining Columns on page 86 for details.

3. For column statistics, select a column in either the right or left panel.

Note: Column information and statistics are affected by the Schema Tool's configuration. See About ColumnInformation and Statistics on page 74 for details.

When you select a column from the right panel, column statistics are displayed in the following way.



When you select the column from the left panel, column statistics are displayed in the following way.



About Column Information and Statistics

Column information and statistics are based on the number of rows sampled. The default sample size is setto 1000 rows.You can adjust the sample size by specifying a different number of rows for theColumnDiscoverySampleSize value in the ConfigOptions connection property. Refer to "Connection PropertyDescriptions" in your driver documentation for details on setting this and other options.

When the sample size is less than the total number of rows in a table, statistics are based on the sample andnot all the values in the table. For example, the table RESIDENTS has 20,000 rows of data. If the sample sizeis 5000 rows, statistics are based on the first 5000 rows of data returned. Statistics are not collected on theremaining 15,000 rows of data. In turn, when the sample size is equal to or greater than the number of rowsin a table, statistics are based on all the rows within the table.



Information and Statistics Displayed in the Column Information PaneWhen you select a column (or field) from the Column Information pane, you receive the following informationon the data types found in the column:

• Data Type is the name of the native data type. (Refer to "Data Types" in the driver documentation forinformation on supported data types.)

• Max Display Length is the longest value found in a column within the sample. For example, in a sample ofthe column LAKES, the values Jordan and Durgam Cheruvu are found. In this scenario, the maximumdisplay length would be 14.

• Min Array Size is the minimum number of elements found in an array. For example, in a sample of thecolumn EMAIL, the Schema Tool finds 2 email addresses in one row and 5 email addresses in another.The Min Array Size would be 2.

• Max Array Size is the maximum number of elements found in an array. For example, in a sample of thecolumn EMAIL, the Schema Tool finds 2 email addresses in one row and 5 email addresses in another.The Max Array Size would be 5.

• Occurrences/Density displays:

1. The number of rows within the sample size containing a column value as the given data type (occurrences)

2. The percentage of rows within the sample size containing the column as a given data type (density)

How Sample Size Affects Occurrences/DensityThe following examples show how sample size affects the Occurrences/Density values.

• In a scenario where the sample size has been set to 5000, the first 5000 rows of the column EMAIL contain1000 occurrences of the Array data type and 3000 occurrences of the String data type. When the EMAILcolumn is selected, the Density/Occurrences values for ARRAY would appear as 1000 (20.00%) whilethe values for STRING would appear as 3000 (60.00%).

• In a scenario where the sample size has been set to 10000 rows, the column NAMES is selected from atable with 8000 rows. In this case, column statistics are based on all the data in the column. If 2000 Stringdata types are discovered, the Occurrences/Density values would appear as 2000 (25.00%). In turn, if4000 Object data types are discovered, the Occurrences/Density values would appear as 4000 (50.00%).

How Sample Size Affects MappingSample size affects column information as well as column statistics. For example, if the Schema Tool discoversthat all the sampled rows in a column have the Double data type, that data type is mapped as Double in therelational view of the table. In contrast, if the Schema Tool discovers a column with multiple data types withinthe sampled rows, the SQL type is determined by the combination of data types detected within the column.For details, see "Default Mapping of Columns with Inconsistent Native Data Types."

Column Size for VarcharFor columns mapped to Varchar, the driver truncates values that exceed the column size defined for the columnwhen constructing the relational map of your data. For example, if you have a column with a defined columnsize of 150 that contains a value with 200 characters, the driver returns only the first 150 characters of thatvalue.

During the initial discovery and normalization process, you can use the DefaultVarcharSize configuration optionto specify the default length of fields that are discovered and mapped as Varchar by the driver. If the driverdiscovers a field with String data of a greater length, the String data is truncated to the length of the specifiedvalue.



After the initial discovery and normalization process, you can define the column size of individual columns fromthe main display of the Schema Tool. In the main display, select the table from the Available Schemas pane.In the Column Information pane, you can specify a new column size in the VARCHAR Size field.

If you merely want to find out the size of a Varchar column, you can execute the getColumns function. Thecolumn size defined will be the value of the COLUMN_SIZE column.

Column Size for VarbinaryFor columns mapped to Varbinary, the driver truncates values that exceed the column size defined for thecolumn when constructing the relational map of your data. For example, if you have a column with a definedcolumn size of 8000 that contains a value with 9000 bytes, the driver will return only the first 8000 bytes of thatvalue. The default maximum size of Varbinary columns is set 8000 bytes.

After the initial discovery and normalization process, you can define the column size of individual columns fromthe main display of the Schema Tool. In the main display, select the table from the Available Schemas pane.In the Column Information pane, you can specify a new column size in the VARCHAR Size field.

If you merely want to find out the size of the Varbinary column, you can execute the getColumns function. Thecolumn size defined will be the value of the COLUMN_SIZE column.

Mapping Native Objects in a SchemaAfter selecting an initial relational view of your data, you may want to map additional native objects to yourschema map. To map native objects in a schema, see the following topics:

• Mapping Native Objects on page 76

• Mapping Newly Detected Objects on page 81

Mapping Native Objects

You can map native objects in your relational schema when you first create a schema map or after you havealready created one. In either case, this process is carried out through the Schema Tool Native View dialog.

1. From the Schema Tool's main display, click Add Table(s) button to open the Schema Tool Native Viewdialog.

A hierarchical view of your native data appears in the window.You can click on nodes to see how objectsare nested.



2. Select either Flatten or Normalize. Then select the objects you want to include in your schema.

Flatten has been selected in the following example. A native view of the data is presented. residentscorresponds to the native residents collection, address corresponds to an embedded document in thecollection, vehicles corresponds to an array in the collection, and so forth.



Normalize has been selected in the following example. Because the Schema Tool handles normalizationof objects more than one level deep, you can only select tables when Normalize is selected. However, youcan tailor these tables by excluding columns once they have been added to your schema (see RemovingObjects from a Schema on page 84 for details).



3. Click OK.

The Schema Tool's main display appears.

4. Click the Save button to save your modification of the schema map.

This following example shows how the residents collection has been flattened into the relational RESIDENTStable.

Note: Refer to "Mapping Objects to Tables" in the driver documentation for details on how the Schema Toolflattens data.



This following example shows how the residents collection has been normalized into a set of parent-childtables.

Note: Refer to "Mapping Objects to Tables" in the driver documentation for details on how the Schema Toolnormalizes data.



Mapping Newly Detected Objects

When you open an existing schema with the Schema Tool, the Schema Tool automatically compares thecontent of the schema configuration file to a new sample of the data from the server. When new native objectsare detected, the Schema Tool identifies the newly detected objects by highlighting the objects in a hierarchicalview of the native data. This information is displayed in the New Native Objects window which opens over theSchema Tool's main display window. In the following example, a number of new objects have been discovered:



If you want to include all the new objects in your schema, click the Update Schema button. All new objects inthe view will be added using the same relational view as the initial view you selected for your schema in Creatinga Schema with the Table Wizard on page 63. For example, if you selected a normalized initial view, the objectswill be normalized when they are added to the schema. For schema maps with a custom initial view, newobjects are added using a normalized view.

Alternatively, you can add new objects manually as described in Mapping Native Objects on page 76. Bymanually adding the objects, you can choose which new objects are added to your schema as well as customizehow they map to the relational view, including whether they are flattened or normalized.You can leave theNew Native Objects window open as a reference while you modify your schema. Keep in mind that this windowis a partial view of the native data: it highlights new objects and displays the parents of new objects to showwhere they are located.

After you are done reviewing the new native objects view, you can close the window. This view will remainavailable until you save your schema. Once you save, any new objects not added to the schema will be removed

from the view. To reopen the window, click the New Native Objects button .

Note: You can map new native objects without using the Schema Tool by executing the REFRESH MAPstatement. See the "Refresh Map (EXT)" topic for details.

Extracting a New TableYou can map a single object multiple times by extracting a new table from an existing relational table. In effect,you are adding the same table to your schema under a new name. Any subsequently named table will refer tothe same native object as the original table.

Note: For instructions on how to add columns, see Adding Columns on page 84 for details.



Take the following steps to extract a new table:

1. Navigate to the Schema Tool's main display.

2. In the Available Schemas panel, right-click the table you want to add to your schema under a new name,and select Extract New Table.

The Schema Tool Native View window appears. In the Column Information pane, you can view the columnsassociated with the table you are adding to the schema.

3. If you want to remove a column from your new table, select the column in the Column Information pane;

then, click the Remove Column button . Repeat this step for any additional columns you would like toremove.

4. Optionally, define your columns in the Column Information pane. From this pane, you can rename columns,change a column's data type, change data type parameters (if applicable), and change the order in whichcolumns appear in a table. See Defining Columns on page 86 for details.

5. In the New Table Name field, type a unique name for the table. Then click OK. A confirmation message willbe displayed. Click OK again.

6. In the left-hand panel, check the schema to ensure that the new table has been added. To save your work,

click the Save button or select File > Save.



A table has been added to your relational schema, and the modified schema has been saved.Your SQL-basedapplications can use the name of the newly mapped table when running queries against the modified schema.

Adding ColumnsWhen you add a column to a table, you are mapping the field of the native data source to your relational schema.The functionality described here is intended to be used when you want to map a field that does not appear inyour relational schema. (It should not be used for duplicating or renaming a column that is already present inyour schema.) Take the following steps to add a new column to your schema.

Note: You can map or add objects, including columns, to your relational schema in other ways. See MappingNative Objects in a Schema on page 76 for details.

1. Open the Add Column window in either of the following ways:

• From the Available Schemas panel, right-click the table and select Add Column.

• If you have the table you are modifying selected, you can click the Add Column button .

The Add Column window appears.

2. Enter the name of the native field you want to add as a column, or select it from the drop-down list. Thename of the native field is case-sensitive.

Note: You can add fields that were not initially discovered by the Schema Tool. In this scenario, the nameof the native field will not be available in the drop-down list, and you will have to enter the correct name inthe Source Column Name field. When adding array elements, you will need to add not only the name ofthe element but also its index value. When indexing array elements, the element in the first position isindexed as 0, the element in the second position as 1, the element in the third position as 2, and so on. Forexample, the object Coordinates is an array in which the first element is the longitude and the secondelement is the latitude. In this case, you could specify Coordinates.0 as the source column whose columnname is Longitude, and you could map Coordinates.1 to a column name of Latitude.

3. Enter a name for the column and click Add.

The Schema Tool returns to the main display. The native field now appears as a column in the table.

4. Click the Save button or select File>Save to save the modified schema.

Removing Objects from a SchemaWhen you remove an object, you are hiding it from the relational view of your data and, by extension, fromyour SQL-based applications. The native data itself is not changed in any way. Because the native object



persists, objects that have been removed can be added back to your relational schema (see Mapping NativeObjects in a Schema on page 76).

The following instructions illustrate how you can remove or hide any object that appears in the Schema Tool'sAvailable Schemas panel.

Note: You can also remove columns from the Column Information pane. See Removing Columns on page86 for details.

1. Navigate to the Schema Tool's main display.

2. Select the object(s) you want to remove in the Available Schemas pane.

Note: You can select any combination of databases, tables, or columns to be hidden. However, becausenormalized child tables have a foreign key relationship to a parent table, child tables must be hidden beforetheir parent tables.

Note: You can select consecutive objects by selecting an object, holding down the Shift key, and thenselecting the last object.You can select non-consecutive objects by holding down the Crtl key and thenselecting the objects you want to hide.

3. Once you have selected the object(s), you can hide the object(s) in either of the following ways:

• Click the Remove Object(s) button above the Available Schemas pane.

• Right-click your selected object(s) and select Remove Object(s).




The object is removed from your schema and is no longer visible to your application. When parent objects areremoved, their children are also hidden. If your application attempts to access any removed object, the driverwill return an error.

Removing ColumnsWhen you remove a column from a table, you are hiding it from the relational view of your data.You can removecolumns directly from the Column Information pane in either the main display or the Schema Tool Native View.

Note: You can hide or remove objects, including columns, from your relational schema in other ways. SeeRemoving Objects from a Schema on page 84 for details.

Note: Primary key columns cannot be removed from the relational view. To remove the column currentlymarked as the primary key, you must designate a new primary key before beginning this procedure. For moreinformation, see Designating a Primary Key on page 87.

1. Column Information is displayed in either of the following ways:

• From the main display, click the table of the column you want to remove.

• Navigate to the Schema Tool Native View by clicking the Add Table(s) button . Then, find the columnyou want to remove by selecting database and table from the drop-down list.

2. Under Column Information, select the column you want to remove and click the Remove Column button

.


Defining ColumnsYour native data source may not enforce consistent data types. Therefore, you may need to define columndata types to ensure data integrity as you build a relational map of your data. The DataDirect Schema Toolallows you to define a schema by letting you define column data types and specify the order in which columnsappear.

Note: The Schema Tool provides basic information about your data that will help you design schemas thatsuit your needs. For details, see Viewing Information and Statistics on page 71 and About Column Informationand Statistics on page 74.

The following steps illustrate how you can define columns and specify the order of columns through the ClientInformation pane.

1. Navigate to the main display.You can access the Column Information pane in one of the following ways:

• If you want to define columns for an existing table, click the table that contains the columns you want todefine.

• If you want to define columns when extracting a new table, right-click on a table you want to add to yourschema under a new name, and select Extract New Table. See Extracting a New Table on page82 for general information on extracting tables.

This is a view of the Column Information pane from the main display.



2. To change a column's name, double-click the Mapped Name field and enter the new name for the column.

3. To change a column's data type, click the column's SQL Type field and select an alternative data type fromthe drop-down list.

4. To change the size or length of applicable data types, double-click the column's VARCHAR Size field andenter the desired value.

5. To reorder columns, select the column you would like to reposition. Use the up and down arrows to movethe selected column left or right in the table.

Note: By default, columns are ordered left to right in the order in which they are discovered by the SchemaTool.

6. Save your changes from the main display. Click the Save button or select File>Save to save the modifiedschema.

Designating a Primary KeyThe Schema Tool allows you to designate the primary key column for your relational table view. By default,the primary key is set to the _ID column, which contains identifiers generated by your database that are usedto define rows. Although the _ID column typically provides a set of unique row identifiers that work seamlesslywith your application, you may want to designate a different primary key depending on your server configurationor the conceptual design of your data.



If you connect to a shard server that does not use the _ID field as the shard key, you must designate a newprimary key to ensure accurate joins on reads and avoid damaging data on writes. See your databasedocumentation for details on shard keys.

Based on the conceptual design of your data, you may prefer to designate a user-generated column as yourprimary key. User generated columns consist of data provided by users that may have significance externalto the database, such as order numbers or employee identification numbers. When designated as the primarykey, these columns can provide a real world association between your data and your identifiers, which maybetter complement the design of your data and your operational needs. Designating a new primary key allowsyou to further tailor the relational view to match your data concepts by permitting you to hide the _ID columnfrom relational tables. In the default settings, the Schema Tool prohibits hiding the _ID column because it isdesignated as the primary key. See Removing Columns on page 86 for additional information.

Caution: If you designate a primary key column other than _id in the Schema Tool, verify that all values inthe column are unique when fetched as the mapped SQL type of the column before disabling the Read Onlyconnection option. Executing write operations against data with duplicate primary keys can produce undesiredresults. It is also critical that all values of the primary key column are able to be represented as the SQL typeto which the column is mapped without any conversion errors or loss of precision. When conversion errorsoccur, the driver converts incompatible values to null, creating the potential for duplicate identifiers of null.

To designate a primary key:

1. Navigate to the main display.

2. In the Available Schemas pane, expand the tree to display your parent table's columns.



3. Right click on the column that you want to designate as your new primary key; then, select Mark As PrimaryKey.

Note: Columns mapped from complex data types, such as arrays and objects, cannot be designated asthe primary key.

The icon for the column you selected will change to the ID icon , indicating that it is now the primarykey. In a normalized view, foreign key columns will automatically be updated and renamed to reflect thenew primary key.

4. Save your changes from the main display. Click the Save button or select File>Save to save themodified schema.

Naming ConflictsWhen you generate a relational schema with the Schema Tool, the driver exposes native objects as unquoted,uppercase identifiers by default. Since native objects are case sensitive in MongoDB, the driver avoids namingconflicts by appending identifiers which have the same name but different cases with an underscore separatorand integer (for example, _1). If one of the conflicting names contains only uppercase characters, that namewill remain unaltered. For example, if the collections Test, TEST, and test exist in the native data, the driverwill expose the collections as tables in the following manner:

Table 17: Name Conflict Resolution Example

Table NameCollection Name

TEST_1Test

TESTTEST

TEST_2test

Note: When you initially connect to your native data with the Schema Tool, a warning message will appear ifthe driver detects any naming conflicts. This message will not appear in subsequent connections unless anaming conflict has been introduced into the native data.

Alternatively, you can use UppercaseIdentifiers to retain the names of native objects in the relational view ofyour data. When UppercaseIdentifiers is set to false, the driver maps the names of native objects as quotedidentifiers, maintaining the case of native object names in the relational view of native data. For details, see"Identifiers" and "ConfigOptions" in the driver documentation.

The remaining topics in this section discuss two specific naming conflict scenarios.

See alsoStarting the Schema Tool on page 49



Resolving Keyword Conflicts

Keyword conflicts occur when the name of an object matches the name of a SQL engine keyword.You canuse the KeywordConflictSuffix configuration option to avoid such conflicts. KeywordConflictSuffix specifies astring of up to five alphanumeric characters that the driver appends to any object or field name that conflictswith a SQL engine keyword. For example, if you specify KeywordConflictSuffix=TAB, the driver mapsthe Case object to CASETAB.

For details, see "Identifiers" and "ConfigOptions" in the driver documentation.


Replacing Leading Underscores

MongoDB collections automatically include the _id field, and the driver, by default, maps this field as an _IDcolumn. Because some third party applications are unable to process identifiers with a leading underscore,you may need to replace this leading underscore. The LeadingUnderscoreReplacement configuration optionallows you to replace leading underscores with a string. For example, by specifyingLeadingUnderscoreReplacement=XX, the _id field becomes the XXID column in the relational view ofyour data. In addition, any other fields or collections with a leading underscore would be modified in the samemanner.

For details, see "Identifiers" and "ConfigOptions" in the driver documentation.


Restarting the Wizard

If you want to reset the relational view of your schema map, you can do so by restarting the wizard. Restartingthe wizard overwrites your existing relational view, including customizations, and allows you to reselect theinitial relational view of your data.

Note that restarting the wizard only resets how native objects map to the relational view. Therefore, afterrestarting, your schema map will continue to use the existing file name and connection settings, includingsecurity and configuration option settings.

To restart the wizard, click the restart button or select File>Restart the Wizard from the Table Wizardwindow. Then follow the instructions in Creating a Schema with the Table Wizard on page 63 to create a newrelational view of your data.

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

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

• JDBC Driver Manager (see Connecting Using the JDBC Driver Manager on page 34)

• JDBC data sources (Connecting Using Data Sources on page 38)



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

Note: To take full advantage of driver functionality, use the DataDirect Schema Tool to create and customizeschema maps. For details, see Creating and Customizing Schemas Using the DataDirect Schema Tool onpage 48.

See Connection Property Descriptions on page 169 for an alphabetical list of connection properties and theirdescriptions.

Required Properties

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

Note: To take full advantage of driver functionality, use the DataDirect Schema Tool to create and customizeschema maps. For details, see Creating and Customizing Schemas Using the DataDirect Schema Tool onpage 48.

Table 18: Required Properties


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

Specifies the port number of the server listener. The default is 27017.PortNumber on page 195

See also

• Connection Property Descriptions on page 169

• Connecting from an Application on page 42

• Creating and Customizing Schemas Using the DataDirect Schema Tool on page 48

Mapping Properties

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

Table 19: Mapping Properties


Determines how the native data model is mapped to the relational data modelwhen the driver first connects to the database.

ConfigOptions on page 173

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

CreateDB on page 182


Using Connection Properties


Specifies the name of the database to which you want to connect. This valueis used as the default qualifier for unqualified table names in SQL queries.Required for User/ID password authentication.

Important: This value is case-insensitive if you have access privileges toquery the list of databases on the server. If you do not have access, this valueis case-sensitive.

DatabaseName on page 183

Specifies the name and location of the configuration file where the relationalmap of native data is written. The driver looks for this file when connecting toa MongoDB server. If the file does not exist, the driver creates one.

SchemaMap on page 200

See also


• Mapping Objects to Tables on page 16

Authentication Properties

The following table summarizes connection properties related to authentication.

Table 20: Authentication Properties


Specifies the database on the MongoDB server where user principal namesare stored for Kerberos authentication. The default is $external.

AuthenticationDatabase onpage 172

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

AuthenticationMethod onpage 173

Specifies the name of the database to which you are connecting. This valueis used as the default qualifier for unqualified table names in SQL queries.

DatabaseName on page 183

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

LoginConfigName on page 192

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

Password on page 194




Specifies the three-part service principal name registered with the keydistribution center (KDC) in a Kerberos configuration. When no value isspecified, the driver builds a service principle name based on environmentvariables.

ServicePrincipalName onpage 201

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

User on page 205

See alsoAuthentication on page 100Connection Property Descriptions on page 169

Data Encryption Properties

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






EncryptionMethod on page 184

Specifies a host name for certificate validation when SSL encryption is enabled(EncryptionMethod=SSL) and validation is enabled(ValidateServerCertificate=true). This property is optional andprovides additional security against man-in-the-middle (MITM) attacks byensuring that the server the driver is connecting to is the server that wasrequested.

HostNameInCertificate onpage 187

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

KeyPassword on page 189

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 190




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

KeyStorePassword on page190


TrustStore on page 203

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 page204

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


ValidateServerCertificate onpage 206

See alsoData Encryption on page 97Connection Property Descriptions on page 169Authentication Properties on page 92

Statement Pooling Properties

The following table summarizes statement pooling connection properties.

Table 22: 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 188




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 193

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 198

See alsoConnection Property Descriptions on page 169Statement Pool Monitor on page 124Performance Considerations on page 96

Additional Properties

The following table summarizes additional connection properties.

Table 23: Additional Properties


Specifies the maximum number of rows that the driver processes before returning datato the application for a single fetch request when executing a Select.This value providesa suggestion to the driver as to the number of rows that should be returned to theapplication. The driver may fetch fewer rows to conserve memory when processingexceptionally wide rows.

FetchSize on page185

One or multiple SQL commands to be executed by the driver after it has establishedthe connection to the database and has performed all initialization for the connection.

InitializationStringon page 188

Specifies the filename of the configuration file used to initialize driver logging.LogConfigFile onpage 191

Determines the amount of time, in seconds, that the driver waits for a connection to beestablished before timing out the connection request.

LoginTimeout onpage 193

Specifies whether the connection has read-only access to the data source.ReadOnly on page196

Specifies a preference for the type of member (server node) of a replica set to whichthe driver attempts to connect.

ReadPreference onpage 197




Specifies the maximum size, in megabytes, of an intermediate result set that the driverholds in memory.When this threshold is reached, the driver writes a portion of the resultset to disk in temporary files.

ResultMemorySizeon page 198

Enables DataDirect Spy to log detailed information about calls that are issued by thedriver on behalf of the application. DataDirect Spy is not enabled by default.

SpyAttributes onpage 202

Specifies how the driver handles manual transactions.TransactionMode onpage 203

See also


• Connecting from an Application on page 42


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

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

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.

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.

Note: See Designing JDBC applications for performance optimization on page 327 more information aboutusing prepared statement pooling to optimize performance.

ReadPreference: ReadPreference allows you to specify your preference for which replica set members areread when executing queries. Executing queries against primary members (read-write databases) returns themost recent version of the data, but increases the workload of the primary members and may negatively affectperformance. If your application does not require the most recent version of data, consider setting this connectionproperty to read from secondary members (read-only databases) to improve performance.



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.

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 accumulates in memory. This can reducethe likelihood of out-of-memory errors and improve performance by ensuring that result sets fit easily withinthe JVM's free heap space. In addition, when a limit is imposed by setting ResultMemorySize to -1 or x,increasing the max Java heap size can improve performance by reducing the need to write to disk, or removingit altogether.

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 Encryption

To fully implement SSL with the MongoDB driver, you must specify values for SSL connection properties inthese two distinct ways:

• First, you must specify values for SSL connection properties when creating a schema map with the SchemaTool. Specifically, in the Open Schema Map dialog, you must enter key-value pairs in the Connection Optionsfield. (See Starting the Schema Tool on page 49 for details.) These values must match the values youspecify in the connection URL used by your JDBC application.

Note: When creating or opening a schema map, the Schema Tool accesses data from the server for thepurpose of object mapping and generating column statistics. This process requires data to be transferredover networks, which can make data vulnerable to interception by unauthorized parties. To provide moresecure transmission of data, you should consider implementing SSL.

• Second, you must specify values for SSL connection properties in the connection URL used by your JDBCapplication. These values should match the values you specify when creating a schema map with theSchema Tool.

The following steps outline how to configure SSL encryption. These steps should be taken when you create aschema map with the Schema Tool and when you formulate the connection URL used by your application.Moreover, the connection property values specified in the Schema Tool must match the values specified in theconnection URL used by your JDBC application.


Data 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 alsoStarting the Schema Tool on page 49Data Encryption Properties on page 93Configuring SSL Server Authentication on page 98Configuring SSL Client Authentication on page 99

Configuring SSL Server Authentication

When 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 clientand server. If the certificate does not match, the connection fails and the driver throws an exception.

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

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

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

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

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



TrustStore=C:\Certficates\MyTruststore

and

TrustStorePassword=MyTruststorePassword

Any values specified by the TrustStore and TrustStorePassword properties override values specified bythe Java 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 Authentication

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

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

The drivers can use the following types of keystores:

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

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

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

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

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

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

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

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

KeyStore=C:\Certficates\MyKeyStore

and

KeyStorePassword=MyKeystorePassword


Data Encryption

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.

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.

Note: The userIdPassword setting is appropriate for servers that do not have authentication enabled. In ascenario where AuthenticationMethod has been set to userIdPassword but the server has not been configuredfor user ID/password authentication, the driver will still connect to the database server.

Configuring User ID/Password Authentication

Take the following steps to configure user ID/Password authentication:

1. Set the AuthenticationMethod property to userIdPassword.

2. If necessary, set the DatabaseName connection property.

If authentication has not been enabled, client applications will have access to all databases on the server.If authentication has been enabled, a client application will only have access to the database specified bythe DatabaseName property assuming it has the required permissions. However, an application withclusterAdmin privileges will have access to all databases on the server even when authentication is enabled.

Even when authentication has not been enabled, DatabaseName 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 173DatabaseName on page 183User on page 205Password on page 194



Configuring the Driver for Kerberos Authentication

Your Kerberos environment should be fully configured before you configure the driver for Kerberos authentication.You should refer to your MongoDB and Java documentation for instructions on configuring Kerberos. For aWindows Active Directory implementation, you should also consult your Windows documentation. For anon-Active Directory implementation (on a Windows or non-Windows operating system), you should consultMIT Kerberos documentation.

Important: A properly configured Kerberos environment must include a means of obtaining a Kerberos TicketGranting Ticket (TGT). For a Windows Active Directory implementation, Active Directory automatically obtainsthe TGT. However, for a non-Active Directory implementation, the means of obtaining the TGT must beautomated or handled manually.

Once your Kerberos environment has been configured, take the following steps to configure the driver.

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

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.

Note: Regardless of operating system, forward slashes must be used when designating the path of theJAAS login configuration 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");

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:


2. Ensure your JAAS login configuration file includes an entry with authentication technology that the drivercan use to establish a Kerberos connection. (See "The JAAS Login Configuration File" for details.)

Note: The JAAS login configuration file installed with the driver(install_dir/lib/JDBCDriverLogin.conf) includes a default entry with the name JDBC_DRIVER_01.This entry specifies the Kerberos authentication technology used with an Oracle JVM.


Authentication

The following examples show that the authentication technology used in a Kerberos environment dependson your JVM.

Oracle JVM


IBM JVM


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

4. Set the ServicePrincipalName connection property if the default value built by the driver does not matchthe service principal name registered with the KDC.

By default, the driver builds the ServicePrincipalName by concatenating the service name mongodb, thefully qualified domain name (FQDN) as specified with the HostName property, and the default realm nameas specified in the Kerberos configuration file. If this value does not match the service principal nameregistered with the KDC, then the value of the service principal name registered with the KDC should bespecified for the ServicePrincipalName property.

The ServicePrincipalName takes the following form.

Service_Name/Fully_Qualified_Domain_Name@REALM_NAME

See "ServicePrincipalName" for details on the composition of the service principal name.

5. Set the AuthenticationDatabase connection property if user principal names stored by MongoDB are storedin a database other than the default $external database. (See "AuthenticationDatabase" for details.)

6. Set the LoginConfigName connection property if the name of the JAAS login configuration file entry isdifferent from the driver default JDBC_DRIVER_01. (See "The JAAS Login Configuration File" and"LoginConfigName" for details.)

JDBC_DRIVER_01 is the default entry name for the JAAS login configuration file (JDBCDriverLogin.conf)installed with the driver.When configuring your Kerberos environment, your network or system administratormay have used a different entry name. Check with your administrator to verify the correct entry name.

7. Set the User connection property as appropriate. (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. Set the DatabaseName connection property as appropriate. (See "DatabaseName" for details.)

If authentication has not been enabled, client applications will have access to all databases on the server.If authentication has been enabled, a client application will only have access to the database specified bythe DatabaseName property assuming it has the required permissions. However, an application withclusterAdmin privileges will have access to all databases on the server even when authentication is enabled.

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

See alsoKerberos Authentication Requirements on page 103



The JAAS Login Configuration File on page 103AuthenticationMethod on page 173ServicePrincipalName on page 201AuthenticationDatabase on page 172LoginConfigName on page 192User on page 205DatabaseName on page 183

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 24: Kerberos Configuration Requirements

RequirementsComponent

The database server must be running MongoDB 2.4 or higher.Database server

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 Virtual Machine (JVM) that is Java SE 8 or higher, including OracleJDK, OpenJDK, and IBM SDK (Java) distributions.

Client

See alsoConfiguring the Driver for Kerberos Authentication on page 101

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 JAAS login configuration file must include an entry specifically for the driver. In addition, thelogin configuration file must be referenced either by setting the java.security.auth.login.configsystem property or by setting up a default configuration using the Java security properties file.


Authentication

Setting up a default configurationTo set up a default configuration, you must 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 files areread and concatenated into a single configuration. The following steps summarize how to modify the securityproperties file.

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

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

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


JAAS login configuration file entry for the driverYou can create your own JAAS login configuration file, or you can use the JDBCDriverLogin.conf fileinstalled in the /lib directory of the product installation directory. In either case, the login configuration filemust include an entry that specifies the Kerberos authentication technology to be used by the driver.

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

};

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



Oracle JVM


IBM JVM


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 101LoginConfigName on page 192

MongoDB ShardingMongoDB employs sharding as a horizontal scaling solution for supporting large sets of data. It is designed toprovide scalable throughput and storage capacity.To accomplish this, sharding shares logical databases acrossmultiple independent replica sets (clustered servers), or shards. By distributing data across servers, operationsare delegated only to the servers that store data relevant to the task. This increases the availability of serversand CPU capacity, resulting in increased throughput. If operations exceed the available processing capacityof the clusters, additional servers can be added to the cluster, which reduces the number of operations performedby each server and can improve performance. A similar principle applies to storage capacity, where serverscan be added to accommodate increased storage requirements.

Caution: Although the driver connects to a MongoDB sharded cluster transparently, it is critical that the primarykey column have unique values for every row (or document) in the table. The values for the default primarykey of _ID are generated by a MongoDB database; however, in a sharded cluster, these values are notguaranteed to be unique across shards unless specifically configured in the MongoDB cluster. If duplicateidentifiers are mapped to a relational view, write operations can produce undesired results.You can preventthis behavior by confirming that the values of _ID key are configured to be unique across shards, or bydesignating a new primary key. See Designating a Primary Key on page 87 for additional information.

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 128 characters. Quoted identifiers must be enclosed in double quotation marks (""). A quotedidentifier can contain any Unicode character, including the space character, and is case-sensitive. The driverrecognizes the Unicode escape sequence \uxxxx as a Unicode character.You can specify a double quotationmark in a quoted identifier by escaping it with a double quotation mark. Unquoted identifiers must start with anASCII alpha character and can be followed by zero or more ASCII alpha or numeric characters.


MongoDB Sharding

By default, the driver exposes native objects as unquoted, uppercase identifiers when creating the relationalschema of your native data. Since native objects are case sensitive in MongoDB, the driver avoids namingconflicts by appending identifiers which have the same name but different cases with an underscore separatorand integer (for example, _1). If one of the conflicting names contains only uppercase characters, that namewill remain unaltered. For example, if the collections Test, TEST, and test are found, the driver will exposethe collections as tables in the following manner:

Table 25: Name Conflict Resolution Example

Table NameCollection Name

TEST_1Test

TESTTEST

TEST_2test

Note: When you initially connect to your native data with the Schema Tool, a warning message will appear ifthe driver detects any naming conflicts. This message will not appear in subsequent connections unless anaming conflict has been introduced into the native data.

The driver allows you to change default behavior related to identifiers and manage identifiers directly throughthe use of the configuration options described in the following sections.

UppercaseIdentifiers OptionThe UppercaseIdentifiers configuration option determines whether native objects are mapped as unquoted,uppercase identifiers (the default) or quoted, mixed case identifiers that correspond directly with native objectnames. Therefore, as an alternative to the driver's default behavior, you can use UppercaseIdentifiers to retainthe names of native objects in the relational view of your data. When UppercaseIdentifiers is set to false, thedriver maps the names of native objects as quoted identifiers, maintaining the case of native object names inthe relational view of native data. If these identifiers are called in a SQL statement, the statement must enclosethe identifiers in double quotation marks and they must exactly match the case of the identifier name. Forexample, when UppercaseIdentifiers=false, you would use the following statement to query the Accounttable:

SELECT "id", "name" FROM "Account"

The setting for UppercaseIdentifiers also affects the use of catalog functions. When object names are passedas arguments to catalog functions, the case of the value must match the case of the name in the database. IfUppercaseIdentifiers=true (the default) when the schema map was created, the value passed to thecatalog function must be uppercase because unquoted identifiers are automatically converted to uppercaseby the driver. If UppercaseIdentifiers=false when the schema map was created, the value passed tothe catalog function must match the case of the name as it was defined. In addition, whenUppercaseIdentifiers=false, object names in results returned from catalog functions are returned inthe case that they are stored in the database.

KeywordConflictSuffix OptionYou can use the KeywordConflictSuffix configuration option to avoid naming conflicts when the name of anobject corresponds to the name of a SQL engine keyword. KeywordConflictSuffix specifies a string of up tofive alphanumeric characters that the driver appends to any object or field name that conflicts with a SQLengine keyword. For example, if you specify KeywordConflictSuffix=TAB, the driver maps the Caseobject to CASETAB.



LeadingUnderscoreReplacement OptionThe LeadingUnderscoreReplacement configuration option allows you to replace leading underscores with astring when leading underscores are used in identifiers for collections and fields. For example, MongoDBcollections automatically include the _id field. By specifying LeadingUnderscoreReplacement=XX, the _idfield becomes the XXID column in the relational view of the data. In addition, any other fields or collectionswith a leading underscore would be modified in the same manner.

See alsoConfigOptions on page 173Starting the Schema Tool on page 49Naming Conflicts on page 89

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

The HostName specified in the connection URL can resolve to an IPv4 or IPv6 address. For example, thefollowing URL can resolve to an IPv4 or IPv6 address.

jdbc:datadirect:mongodb://MyServer:27017;DatabaseName=Test;SchemaMap=MyUserProfile\\AppData\\Local\\Progress\\DataDirect\\MongoDB_Schema\\MyServer.config

You can specify addresses using IPv4 or IPv6 format in the host portion of the connection URL. For example,the following connection URL specifies the host using IPv4 format.

jdbc:datadirect:mongodb://123.456.78.90:27017;DatabaseName=Test;SchemaMap=MyUserProfile\\AppData\\Local\\Progress\\DataDirect\\MongoDB_Schema\\MyServer.config

You can also specify addresses in either format using the ServerName data source property. The followingexample shows a data source that specifies the host in IPv6 format using the setServerName method.

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

Note: When specifying IPv6 addresses or IPv4/IPv6 combination addresses in a connection URL or datasource property, the address must be enclosed by brackets.

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 host with IPv6 format, butuses the compressed syntax for strings of zero bits.

jdbc:datadirect:mongodb://[2001:DB8:0:0:8:800:200C:417A]:27017;DatabaseName=Test;SchemaMap=MyUserProfile\\AppData\\Local\\Progress\\DataDirect\\MongoDB_Schema\\MyServer.config

Similarly, the following connection URL specifies the host using an IPv4/IPv6 combination address.

jdbc:datadirect:mongodb://[0000:0000:0000:0000:0000:FFFF:123.456.78.90]:27017;DatabaseName=Test;SchemaMap=MyUserProfile\\AppData\\Local\\Progress\\DataDirect\\MongoDB_Schema\\MyServer.config

For complete information about IPv6, visit the following Web page.

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


IP Addresses

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

Parameter MetadataThe driver supports returning parameter metadata as described in Insert and Update Statements on page 108and Select Statements on page 108.

Insert and Update Statements

The 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 Statements

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

• 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 = ?

Views and Remote/Local TablesYou can create views with the Create View statement. A view is like a named query. The view can refer to anycombination of remote and local tables as well as other views.

You can create a local table using the Create Table statement. A local table is maintained by the driver and islocal to the machine on which the driver is running. A local table is exposed in the PUBLIC schema.

See Supported SQL Functionality on page 221 for details on the Create View and Create Table statements andother SQL statements supported by the driver.

Isolation LevelsMongoDB does not support transactions. However, manual transactions can be handled to some degree withthe TransactionMode connection property. See TransactionMode on page 203 for details.

Unicode supportMultilingual 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 Handling

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


Views and Remote/Local Tables

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

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

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 works

Typically, 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 pooling

1. 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 pooling

1. The application requests a connection from the connection pool.

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

3. The application sends a query to the database.



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

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

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

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

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

An application may use only one data source, but allow multiple users, each with their own set of logincredentials. The connection pool contains connections for all unique users using the same data source asshown in the following 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.


Connection Pool Manager

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 theJNDI naming 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 DataSource 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 pooling

To 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 DataSource objectThe following Java code example creates a Progress DataDirect DataSource object and registers it with aJNDI naming service. The DataSource class is database-dependent. This example is drawn from an Oracleuse case; therefore, the DataSource class is OracleDataSource. Nevertheless, the example informs theimplementation of DataSource objects for most Progress DataDirect drivers.

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

//************************************************************************// This code creates a Progress DataDirect for JDBC data source and // registers it to a JNDI naming service. This JDBC data source uses the// DataSource implementation provided by DataDirect Connect Series // for JDBC Drivers.//// This data source registers its name as <jdbc/ConnectSparkyOracle>.//// NOTE: To connect using a data source, the driver needs to access a JNDI data // store to persist the data source information. To download the JNDI File// System Service Provider, go to://// http://www.oracle.com/technetwork/java/javasebusiness/downloads/// java-archive-downloads-java-plat-419418.html#7110-jndi-1.2.1-oth-JPR//// // Make sure that the fscontext.jar and providerutil.jar files from the // download are on your classpath.//************************************************************************// From DataDirect Connect Series for JDBC:import com.ddtek.jdbcx.oracle.OracleDataSource;import javax.sql.*;import java.sql.*;import javax.naming.*;import javax.naming.directory.*;import java.util.Hashtable;public class OracleDataSourceRegisterJNDI{ public static void main(String argv[]) { try { // Set up data source reference data for naming context: // ---------------------------------------------------- // Create a class instance that implements the interface // ConnectionPoolDataSource OracleDataSource ds = new OracleDataSource(); ds.setDescription("Oracle on Sparky - Oracle Data Source"); ds.setServerName("sparky"); ds.setPortNumber(1521); ds.setUser("scott"); ds.setPassword("test"); // Set up environment for creating initial context Hashtable env = new Hashtable(); env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.fscontext.RefFSContextFactory"); env.put(Context.PROVIDER_URL, "file:c:\\JDBCDataSource"); Context ctx = new InitialContext(env); // Register the data source to JNDI naming service ctx.bind("jdbc/ConnectSparkyOracle", ds);



} catch (Exception e) { System.out.println(e); return; } } // Main // class OracleDataSourceRegisterJNDI

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

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

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

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

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

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

public class PoolMgrDataSourceRegisterJNDI{ public static void main(String argv[]) { try { // Set up data source reference data for naming context: // ---------------------------------------------------- // Create a pooling manager's class instance that implements // the interface DataSource PooledConnectionDataSource ds = new PooledConnectionDataSource();



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

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

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

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

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

// The pool maintenance thread will wake up and check the pool // every 20 seconds ds.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 connection ds.setTracing(false);

// Set up environment for creating initial context Hashtable 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 service ctx.bind("jdbc/SparkyOracle", ds);

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

See alsoCreating a driver DataSource object on page 113PooledConnectionDataSource on page 119

Configuring the connection pool

You 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 119

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

ds.setMaxPoolSize(10);

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

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

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

See alsoPooledConnectionDataSource on page 119

Connecting using a connection pool

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

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

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

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



public class TestDataSourceApp{ public static void main(String argv[]) { String strJNDILookupName = ""; // Get the JNDI lookup name for a data source int 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 object env = 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 name ctx = 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 time nStartTime = System.currentTimeMillis(); for (int j = 1; j <= nCount[i]; j++) { // Get Database Connection try { con = ds.getConnection("scott", "tiger"); // Do something with the connection // ... // Close Database Connection if (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 time nStopTime = System.currentTimeMillis(); // Compute elapsed time nElapsedTime = nStopTime - nStartTime; System.out.println("Test number " + i + ": looping " + nCount[i] + " times"); System.out.println("Elapsed Time: " + nElapsedTime + "\n"); } // for i loop // All done System.exit(0); // Main} // TestDataSourceApp



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

See alsoCreating the connection pool on page 114Creating a driver DataSource object on page 113

Closing the connection pool

To ensure that the connection pool is closed correctly when an application stops running, the application mustnotify the DataDirect Connection Pool Manager when it stops.When an application stops running, a notificationoccurs automatically.

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 version

To 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 tracing

You 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 210

Connection Pool Manager interfaces

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

PooledConnectionDataSourceFactoryThe PooledConnectionDataSourceFactory interface is used to create a PooledConnectionDataSourceobject 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 116

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

DescriptionConnectionPoolMonitor Methods

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

jndi_name-user_id

where:

jndi_name

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

user_id

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

String getName()

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

int getNumActive()

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

int getNumAvailable()

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

int getInitialPoolSize()



DescriptionConnectionPoolMonitor Methods

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

int getMaxPoolSize()

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

int getMinPoolSize()

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

int getPoolSize()

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

Using DataDirect-Specific Methods to Access the Statement PoolMonitor

To access the Statement Pool Monitor using DataDirect-specific methods, you should first enable statementpooling.You can enable statement pooling by setting the MaxPooledStatements on page 193 connection propertyto a value greater than zero (0).

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

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

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 26: poolEntries() Parameters

DescriptionValueParameter

Returns only prepared statementsExtStatementPoolMonitor.TYPE_PREPARED_STATEMENTstatementType

Returns only callable statementsExtStatementPoolMonitor.TYPE_CALLABLE_STATEMENT

Returns all statements regardlessof statement type

-1

Returns only statements withforward-only result sets

ResultSet.TYPE_FORWARD_ONLYresultSetType

Returns only statements with scrollinsensitive result sets

ResultSet.TYPE_SCROLL_INSENSITIVE

Returns only statements with scrollsensitive result sets

ResultSet.TYPE_SCROLL_SENSITIVE

Returns statements regardless ofresult set type

-1

Returns only statements with aread-only result set concurrency

ResultSet.CONCUR_READ_ONLYresultSetConcurrency

Returns only statements with anupdateable result set concurrency

ResultSet.CONCUR_UPDATABLE

Returns statements regardless ofresult set concurrency type

-1

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

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

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

For example:

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


Statement Pool Monitor

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

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

private void run(String[] args) { Connection con = null; PreparedStatement prepStmt = null; String sql = null; try { // Create the connection and enable statement pooling Class.forName("com.ddtek.jdbc.sqlserver.SQLServerDriver"); con = DriverManager.getConnection( "jdbc:datadirect:sqlserver://SMITH:1440;" + "RegisterStatementPoolMonitorMBean=true", "maxPooledStatements=10", "test", "test"); // Prepare a couple of statements sql = "INSERT INTO employees (id, name) VALUES(?, ?)"; prepStmt = con.prepareStatement(sql); prepStmt.close(); sql = "SELECT name FROM employees WHERE id = ?"; prepStmt = con.prepareStatement(sql); prepStmt.close(); ExtStatementPoolMonitor monitor = ((ExtConnection) con).getStatementPoolMonitor(); System.out.println("Statement Pool - " + monitor.getName()); System.out.println("Max Size: " + monitor.getMaxSize()); System.out.println("Current Size: " + monitor.getCurrentSize()); System.out.println("Hit Count: " + monitor.getHitCount()); System.out.println("Miss Count: " + monitor.getMissCount()); System.out.println("Statements:"); ArrayList statements = monitor.poolEntries(-1, -1, -1); Iterator itr = statements.iterator(); while (itr.hasNext()) { String entry = (String)itr.next(); System.out.println(entry); }} catch (Throwable except) { System.out.println("ERROR: " + except); } finally { if (con != null) { try { con.close(); } catch (SQLException except) {} } } }

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

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



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

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

Using JMX to Access the Statement Pool Monitor

Your application cannot access the Statement Pool Monitor using JMX unless the driver registers the StatementPool Monitor as a JMX MBean. To enable the Statement Pool Monitor as an MBean, statement pooling mustbe enabled with MaxPooledStatements on page 193, and the Statement Pool Monitor MBean must be registeredusing the RegisterStatementPoolMonitorMBean on page 198 connection property.

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

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

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

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

private void run(String[] args) { if (args.length < 2) { System.out.println("Not enough arguments supplied"); System.out.println("Usage: " + "ShowStatementPoolInfo hostname port"); } String hostname = args[0]; String port = args[1]; JMXServiceURL url = null; JMXConnector connector = null; MBeanServerConnection server = null; try { url = new JMXServiceURL("service:jmx:rmi:///jndi/rmi://" + hostname +":" + port + "/jmxrmi"); connector = JMXConnectorFactory.connect(url); server = connector.getMBeanServerConnection(); System.out.println("Connected to JMX MBean Server at " + args[0] + ":" + args[1]); // Get the MBeans that have been registered with the // com.ddtek.jdbc domain. ObjectName ddMBeans = new ObjectName("com.ddtek.jdbc:*"); Set<ObjectName> mbeans = server.queryNames(ddMBeans, null); // For each statement pool monitor MBean, display statistics and // contents of the statement pool monitored by that MBean for (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); }}

Importing Statements into a Statement Pool

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

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

To import statements into a statement pool:

1. Create a statement pool export file. See Statement pool export file example on page 215 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 on page 129.

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:mongodb://MyServer:27017; DatabaseName=INFORMATION_SCHEMA;

SchemaMap=C:\\Users\\Default\\AppData\\Local\\Progress\\DataDirect\\MongoDB_Schema\\MyServer.config;

User=admin;Password=secret; ImportStatementPool=C:\\statement_pooling\\stmt_export.txt

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

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

Clearing all statements in a statement pool

To 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 pool

Freezing 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.If the pool is frozen and the number of statements in the pool is the maximum, no statements can be added tothe pool.

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

Generating a statement pool export file

You 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 export file.

See alsoStatement pool export file example on page 215

DataDirect Statement Pool Monitor interfaces and classes

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

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

ExtStatementPoolMonitorMBean interface

DescriptionExtStatementPoolMonitorMBean Methods

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

String getName()

Returns the total number of statements cached in thestatement pool.

int getCurrentSize()

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

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

long getHitCount()




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

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

long getMissCount()

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

int getMaxSize()

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

int setMaxSize(int value)

Closes and discards all the statements in the statementpool.

void emptyPool()

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

void resetCounts()

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

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

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

void exportStatements(File file_object)

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

void exportStatements(String file_name)

Imports statements from the specified File object into thestatement pool.

void importStatements(File file_object)

Imports statements from the specified file into the statementpool.

void importStatements(String file_name)




Returns whether the state of the statement pool is frozen.When the statement pool is frozen, the statements that canbe stored in the pool are restricted to those that were inthe pool at the time the pool was frozen. Freezing a poolis useful if you have a core set of statements that you donot want 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 aSQL statement. 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 tutorial

This 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 the Database Selection window.You can use one of these URLsas a template when you make a JDBC connection. The default Config.txt filecontains example URLs for most databases.

Databases

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

InitialContextFactory

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

ContextProviderURL

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

Datasources

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

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

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

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

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

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


DataDirect Test



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 source

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.

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.

Important: For the Autonomous REST Connector: REST API data sources do not connect in the samemanner as database servers; therefore; the Connection Established notification does not guaranteethat the driver is properly configured. To confirm that the driver is correctly configured, you will need toretrieve data from an endpoint using the methods described in "Executing a simple database selection."

See alsoExecuting a simple Select statement on page 137

Connecting using database selection

To connect using database selection:


DataDirect Test

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.

Important: For the Autonomous REST Connector: REST API data sources do not connect in the samemanner as database servers; therefore; the Connection Established notification does not guaranteethat the driver is properly configured. To confirm that the driver is correctly configured, you will need toretrieve data from an endpoint using the methods described in "Executing a simple database selection."




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.


DataDirect Test

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

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

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

Executing a prepared statementThis example explains how to execute a parameterized statement multiple times.

To execute a prepared statement:

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

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



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

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 139 and Step 5 on page 139 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.




Retrieving database metadata

1. 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 set

1. From the Connection window menu, select Connection / Create JDBC 2.0 Statement. DataDirect Testprompts 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 145 through Step 4 on page 146 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 the previouslyinserted records are returned.




Returning parameter metadata

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 parameter metadata.


DataDirect Test

Establishing savepoints

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.



Click Submit; then, click Close.The Connection window 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 (LOB) dataThe 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 setEnableLoggingmethod in the com.ddtek.jdbc.extensions.ExtLogControl interface. See "Troubleshooting yourapplication" for information about using a DataDirect Spy log for troubleshooting.

See alsoTroubleshooting your application on page 207

Enabling DataDirect Spy

You 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 data source.

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

(spy_attribute[;spy_attribute]...)

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

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

Class.forName("com.ddtek.jdbc.redshift.RedshiftDriver");Connection conn = DriverManager.getConnection ("jdbc:datadirect:redshift://Server1:5439;DatabaseName=Test; User=admin;Password=secret; SpyAttributes=(log=(filePrefix)C:\\temp\\spy_;linelimit=80;logTName=yes; timestamp=yes)");


Tracking JDBC calls with DataDirect Spy

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

Using this example, DataDirect Spy loads the Amazon Redshift driver and logs all JDBC activity to thespy_x.log file located in the C:\temp directory (log=(filePrefix)C:\\temp\\spy_), where x is aninteger that increments by 1 for each connection on which the prefix is specified. The spy_x.log file logs amaximum of 80 characters on each line (linelimit=80) and includes the name of the current thread(logTName=yes) and a timestamp on each line in the log (timestamp=yes).

Example on UNIX:The following code example uses the JDBC Driver Manager to connect to Amazon Redshift while enablingDataDirect Spy:

Class.forName("com.ddtek.jdbc.redshift.RedshiftDriver");Connection conn = DriverManager.getConnection ("jdbc:datadirect:redshift://Server1:5439;DatabaseName=Test; User=TEST;Password=secret; SpyAttributes=(log=(filePrefix)/tmp/spy_;logTName=yes;timestamp=yes)");

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

See alsoDataDirect Spy attributes on page 167

Using JDBC data sourcesThe drivers implement the following JDBC features:

• JNDI for Naming Databases

• Connection Pooling

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

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

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

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



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

DataDirect Spy loads the DB2 driver and log all JDBC activity to the spy.log file located in the C:\tempdirectory (log=(file)C:\\temp\\spy.log). In addition to regular JDBC activity, the spy.log file alsologs activity on InputStream and Reader objects (logIS=yes). It also includes the name of the currentthread (logTName=yes).

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

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

DataDirect Spy loads the Oracle driver and logs all JDBC activity to the spy.log file located in the /tmpdirectory (log=(file)/tmp/spy.log). The spy.log file includes the name of the current thread(logTName=yes).

See alsoDataDirect Spy attributes on page 167

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

Table 27: 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.

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

log=(file)filename


Tracking JDBC calls with DataDirect Spy

DescriptionAttribute

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

where:

X

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

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

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

The following table is an alphabetical list of connection properties with their default values. Each property ishyperlinked to its full description.

Note: The data type listed in the full descriptions is the Java data type used for the property value in a JDBCdata source.

Table 28: Connection Properties with Defaults

DefaultConnection Property

$externalAuthenticationDatabase on page 172

userIdPasswordAuthenticationMethod on page 173

ColumnDiscoverySampleSize=1000;DefaultVarcharSize=1.5x;KeywordConflictSuffix=;LeadingUnderscoreReplacement=;MaxVarcharSize=4000;MinVarcharSize=255;SchemaFilter=;UppercaseIdentifiers=true

ConfigOptions on page 173

notExistCreateDB on page 182

INFORMATION_SCHEMADatabaseName on page 183

noEncryptionEncryptionMethod on page 184



100 (rows)FetchSize on page 185

NoneHostName on page 186

Empty stringHostNameInCertificate on page 187

Empty stringImportStatementPool on page 188

NoneInitializationString on page 188

NoneKeyPassword on page 189

NoneKeyStore on page 190

NoneKeyStorePassword on page 190

NoneLogConfigFile on page 191

JDBC_DRIVER_01LoginConfigName on page 192

0LoginTimeout on page 193

0MaxPooledStatements on page 193

NonePassword on page 194

27017PortNumber on page 195

trueReadOnly on page 196

primaryReadPreference on page 197

falseRegisterStatementPoolMonitorMBean on page 198

-1ResultMemorySize on page 198

For Windows:

application_data_folder\Local\Progress\

DataDirect\MongoDB_Schema\hostname.config

For UNIX/Linux:

˜/progress/datadirect/mongodb_schema/

hostname.config

SchemaMap on page 200

Driver builds value based on environmentServicePrincipalName on page 201


Chapter 4: Connection Property Descriptions


NoneSpyAttributes on page 202

noTransactionsTransactionMode on page 203

NoneTrustStore on page 203

NoneTrustStorePassword on page 204

NoneUser on page 205

trueValidateServerCertificate on page 206


• AuthenticationDatabase

• AuthenticationMethod

• ConfigOptions

• CreateDB

• DatabaseName

• EncryptionMethod

• FetchSize

• HostName

• HostNameInCertificate

• ImportStatementPool

• InitializationString

• KeyPassword

• KeyStore

• KeyStorePassword

• LogConfigFile

• LoginConfigName

• LoginTimeout

• MaxPooledStatements

• Password

• PortNumber

• ReadOnly

• ReadPreference


• RegisterStatementPoolMonitorMBean

• ResultMemorySize

• SchemaMap

• ServicePrincipalName

• SpyAttributes

• TransactionMode

• TrustStore

• TrustStorePassword

• User

• ValidateServerCertificate

AuthenticationDatabase

PurposeSpecifies the database on the MongoDB server where user principal names are stored for Kerberosauthentication. The default name of this database is $external.

Valid Valuesstring

where:

string

is the name of the database on the MongoDB server used for authentication.

NotesUser principal names must be added to the authentication database on the MongoDB server.The user principalname is passed via the Kerberos Service Ticket to the MongoDB server. MongoDB then checks the userprincipal name against the authentication database (default $external). If the user principal name is accepted,the user ID is passed in the final handshake and a client-server connection is established.

Default$external

Data TypeString

See also

• Authentication on page 100

• Authentication Properties on page 92



AuthenticationMethod

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

Valid Valueskerberos | userIdPassword

BehaviorIf 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

• The userIdPassword setting is appropriate for servers that do not have authentication enabled. In ascenario where AuthenticationMethod has been set to userIdPassword but the server has not beenconfigured 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 databases on the server.If authentication has been enabled, a client application will only have access to the database specified bythe DatabaseName property assuming it has the required permissions. However, an application withclusterAdmin privileges will have access to all databases on the server even when authentication is enabled.

DefaultuserIdPassword

Data TypeString

See also



ConfigOptions

PurposeDetermines how the mapping of the native data model to the relational data model is configured, customized,and updated.

Notes

• This property is primarily used for initial configuration of the driver for a particular user. It is not intended foruse with every connection. By default, the driver configures itself and this property is normally not needed.


AuthenticationMethod

Alternatively, you can specify values for configuration options when creating a schema map with the SchemaTool. Specifically, in the Open Schema Map dialog, you can indicate values using the key=value conventionin the Configuration Options field.

• If ConfigOptions is specified on a connection after the initial configuration, the values specified forConfigOptions must match the values specified for the initial configuration.

Valid Values( key = value [; key = value ])

where:

key

is one of the following configuration options:

• ColumnDiscoverySampleSize

• DefaultVarcharSize

• KeywordConflictSuffix

• LeadingUnderscoreReplacement

• MaxVarcharSize

• MinVarcharSize

• SchemaFilter

• UppercaseIdentifiers

value

specifies a setting for the configuration option.

When specifying configuration options in a connection string, key value pairs must be enclosed in parenthesesand separated by a semicolon. For example:

ConfigOptions=(ColumnDiscoverySampleSize=2000;DefaultVarcharSize=2x;KeywordConflictSuffix=TAB;LeadingUnderscoreReplacement=XX;MaxVarcharSize=5000;MinVarcharSize=500;SchemaFilter=oem_sales:november;UppercaseIdentifiers=false)

Default

ColumnDiscoverySampleSize=1000;DefaultVarcharSize=1.5x;KeywordConflictSuffix=;LeadingUnderscoreReplacement=;MaxVarcharSize=4000;MinVarcharSize=255;SchemaFilter=;UppercaseIdentifiers=true

Data TypeString

See alsoStarting the Schema Tool on page 49About Column Information and Statistics on page 74



Identifiers on page 105Naming Conflicts on page 89Using Connection Properties on page 90

ColumnDiscoverySampleSize (Configuration Option)

PurposeSpecifies the number of rows the driver fetches per collection when sampling data to detect columns and gathercolumn statistics. The information collected in these samples is used when creating a schema map with theDataDirect Schema Tool. Larger fetch sizes return samples that are more representative of your data, but atthe expense of slower performance.

Valid Valuesx

where:

x

specifies the number of rows the driver fetches per collection.

Default1000

See alsoConfigOptions on page 173

DefaultVarcharSize (Configuration Option)

PurposeDetermines the default length of fields that are mapped as VARCHAR.

Valid Valueslength | multiplier

where:

length

is the default length in characters given to columns that are discovered and mapped as VARCHAR.

multiplier

is a positive number immediately followed by the character x. For example, 3x. The positive integeris multiplied by the size of the largest object detected in a column to determine the default VARCHARlength for that column.


ConfigOptions

BehaviorIf set to length, the value specified is the default length in characters for all fields that are discovered andmapped as VARCHAR. Values that exceed the specified default length are truncated when selected via thedriver.

If set to multiplier, the default length for a VARCHAR column is defined by multiplying the multipliervalue by the size, in characters, of the largest value detected in that column. Values that exceed the defaultlength defined for the column are truncated when selected via the driver.

Note: When specifying a multiplier, you can define the maximum and minimum limits of the default lengthgenerated with the MaxVarcharSize and MinVarcharSize configuration options.

ExampleFor character values:

When DefaultVarcharSize is set to 200. When the driver discovers a column with a String size less than orequal to 200 characters, String is mapped as VARCHAR and the precision is 200 characters. When a columnwith a String size greater than 200 characters is discovered, the driver truncates the value to 200 characters.

For multiplier values:

When DefaultVarcharSize is set to 1.5x and the largest detected field in a column is 100 characters, the defaultlength of fields mapped to VARCHAR is determined by multiplying 1.5 by 100, which results in a default lengthof 150 characters. When a value in that column exceeds 150 characters, the driver truncates the value to 150characters.

Notes

• It is recommend that you specify a multiplier value for this option. Specifying a multiplier can improve memoryefficiency within the driver and the application by having the length for every VARCHAR column proportionateto the size of the data for a given column.

• When a column with a String size greater than 4000 is discovered, the column is mapped as LONGVARCHARand precision is 16 MB.

• The default length of fields for columns mapped as VARCHAR can be overridden using the Schema Tool.See About Column Information and Statistics on page 74 for details.

• DefaultVarcharSize is not applied to columns that contain only ObjectIDs. Columns that contain onlyObjectIDs are mapped as VARCHAR.

Default1.5x

See also

• ConfigOptions on page 173

• MaxVarcharSize (Configuration Option) on page 178

• MinVarcharSize (Configuration Option) on page 179

• About Column Information and Statistics on page 74



KeywordConflictSuffix (Configuration Option)

PurposeSpecifies a string of up to five alphanumeric characters that the driver appends to any object or field name thatconflicts with a SQL engine keyword.

Valid Valuesstring

where:

string

is a string of up to five alphanumeric characters.

ExampleA field called CASE exists in the native MongoDB data.To avoid a naming conflict with the SQL engine keywordCASE, you could set KeywordConflictSuffix=TAB. In this scenario, the driver maps the Case object tothe CASETAB column.

DefaultNone


LeadingUnderscoreReplacement (Configuration Option)

PurposeSpecifies the string of characters that replace leading underscores used in identifiers for collections, documents,and arrays.

Valid Valuesstring

where:

string

is comprised of any Unicode character or group of characters, including spaces.

ExampleMongoDB collections automatically include the _id field. By specifying LeadingUnderscoreReplacement=XX,the _id field becomes the XXID column in the relational view of the data. In addition, any other fields or collectionswith a leading underscore would be modified in the same manner.


ConfigOptions

NotesThe Schema Tool builds table and column identifiers by concatenating the names of nested collections,documents, and arrays. When specifying a value for LeadingUnderscoreReplacement, consider that the totallength of identifiers must not exceed 128 characters in length.

DefaultNone


MaxVarcharSize (Configuration Option)

PurposeSpecifies the maximum default length of fields that are mapped as VARCHAR when a multiplier is specifiedfor the DefaultVarcharSize configuration option (DefaultVarcharSize=multiplier).

MaxVarcharSize limits the size of the default length of VARCHAR fields that are determined by multiplying themultiplier value of the DefaultVarcharSize configuration option by the largest value detected in that column.When the largest value detected is significantly larger than the rest of the data in the column, this option canimprove the memory efficiency of applications by limiting the size of the default length and, therefore, theamount of data stored in a field.

Valid Valuesx

where:

x

is the maximum size of the default length in characters given to columns that are mapped asVARCHAR.

ExampleFor example, MaxVarcharSize is set to 3000 and DefaultVarcharSize is set to 3x. When the largest detectedvalue in a column mapped to VARCHAR is 500 characters, the driver determines that the default length forthat column is 1500 characters by multiplying the largest detected value (500) by the setting ofDefaultVarcharSize (3). However, suppose the largest detected value is 2000 characters. The driver calculatesa default value of 6000 characters, but, since this would exceed the value for MaxVarcharSize, the defaultlength is set to 3000 characters.



Notes

• This option can improve memory efficiency of applications by limiting the size of memory stored in VARCHARfields.

• When a column with a String size greater than 4000 is discovered, the column is mapped as LONGVARCHARand precision is 16 MB.

• You can configure a minimum limit for the default length of fields that are mapped as VARCHAR using theMinVarcharSize configuration option.


Default4000

See also


• DefaultVarcharSize (Configuration Option) on page 175

• MinVarcharSize (Configuration Option) on page 179


MinVarcharSize (Configuration Option)

PurposeSpecifies the minimum default length, in characters, of fields that are mapped as VARCHAR when a multipliervalue is specified for the DefaultVarcharSize configuration option (DefaultVarcharSize=multiplier).

MinVarcharSize enforces a minimum size for the default length of VARCHAR fields that are determined bymultiplying the value of the DefaultVarcharSize configuration option by the largest value detected in that column.When the default length would be less than the minimum value specified for this option, the driver increasesthe default length to the minimum. When correctly configured, this option can prevent the undesired truncationof VARCHAR values.

Valid Valuesx

where:

x

is the maximum size of the default length in characters given to columns that are mapped asVARCHAR.

ExampleFor example, MinVarcharSize is set to 1000 and DefaultVarcharSize is set to 3x. When the largest detectedvalue in a column mapped to VARCHAR is 1000 characters, the driver determines that the default length forthat column is 3000 characters by multiplying the size of the largest detected value (1000) by the setting ofDefaultVarcharSize (3). However, suppose the largest detected value is 200 characters. The driver calculatesa default length of 600 characters, but, since this would be less than the setting for MinVarcharSize, the lengthis set to 1000.


ConfigOptions

Notes

• This option can be configured to avoid the undesired truncation of values by enforcing a minimum size offields that are mapped as VARCHAR.

• You can configure a maximum limit for the default length of fields that are mapped as VARCHAR using theMaxVarcharSize configuration option.


Default255

See also


• DefaultVarcharSize (Configuration Option) on page 175

• MaxVarcharSize (Configuration Option) on page 178


SchemaFilter (Configuration Option)

PurposeSpecifies a comma-separated list of database and collection pairs for which you want the driver to fetchmetadata. SchemaFilter can significantly improve connection times by limiting the collections for which metadatais fetched to only those that are required by your application. If you do not specify a value, the driver fetchesmetadata for all the collections in every database that your account has access to, which can adversely impactperformance during the initial connection to a database.

Valid Valuesdatabase_name:collection_name[[,database_name:collection_name]...]

where:

database_name

is a literal value or regular expression for the database that contains collections for which the driverfetches metadata.

collection_name

is a literal value or regular expression of the collection for which the driver fetches metadata.

A schema or table name value can be:

• A literal name that does not contain either a comma ( , ) or a colon ( : )

• A literal name that contains a comma ( , ) or a colon ( : ) that is bounded by a slash ( / ) at the beginningand end. For example, a collection named sales:2019 would be represented by /sales:2019/

• A regular expression bounded by a slash ( / ) at the beginning and end, such as /sales.*\d/

• An asterisk ( * ), which represents all databases or collections within the corresponding schema(s).



Examples

• Literal values: The following example returns metadata for only the november and march collections inthe oem_sales database.

SchemaFilter=oem_sales:november,oem_sales:march

• Wildcard values: If you want the driver to fetch metadata for all the tables in a schema, replace the valuefor the table or schema name with an * (wildcard) character. For example, the following returns metadatafor all the tables in the oem_sales and for tables named customers in all databases.

SchemaFilter=oem_sales:*,*:customers

• Partial wildcard values:You can also use the asterisk to specify partial values for databases and collections.For example, the following returns metadata for all tables in the that end with region that are in schemasthat begin with sales.

SchemaFilter=/sales.*/:/.*region/

• Regular expressions: The following returns metadata for tables named tax in all databases that start withyear which end with a number.

SchemaFilter=*/year.*\d/:tax

DefaultEmpty string


UppercaseIdentifiers (Configuration Option)

PurposeSpecifies whether the driver maps all identifier names to uppercase. By default, the driver maps all identifiernames to uppercase.

Valid Valuestrue | false

BehaviorIf set to true, the driver maps identifiers to uppercase.

If set to false , the driver maps identifiers to the mixed case name of the object being mapped. If mixed caseidentifiers are used, SQL statements must enclose those identifiers in double quotes and the case of theidentifier must exactly match the case of the identifier name. In addition, object names in results returned fromcatalog functions are returned in the case that they are stored in the database.

ExampleIf UppercaseIdentifiers=false, to query the Account table you specify:

SELECT "id", "name" FROM "Account"


ConfigOptions

NotesDo not change the value of UppercaseIdentifiers unless the data source you are connecting to has objectswith names that differ only by case.

Defaulttrue


CreateDB

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

Valid Valuesno | notExist

BehaviorIf 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 specifiedby the value you enter for the SchemaMap connection property.

• You can refresh the internal files related to an existing relational view of your data in one of two ways. First,you can use the SQL extensions Refresh Map or Reload Map. Refresh Map runs a discovery against yournative data and updates your internal files accordingly, while Reload Map refreshes the internal files tointegrate configuration changes without running a discovery. Second, you can refresh these internal filesby launching the DataDirect Schema Tool and opening the corresponding schema map configuration file.When an existing schema is opened with the Schema Tool, the Schema Tool automatically compares thecontent of the schema configuration file to a snapshot of the data on the wire. When new native objects aredetected, the Schema Tool displays the newly detected objects by highlighting them in a hierarchical viewof the native data.

DefaultnotExist

Data TypeString



See also

• SchemaMap on page 200


• Refresh Map (EXT) on page 223

• Reload Map (EXT) on page 224

• Mapping Properties on page 91

DatabaseName

PurposeSpecifies the name of the database to which you are connecting. This value is used as the default qualifier forunqualified table names in SQL queries.

Valid Valuesdatabase_name

where:

database_name

is the name of a valid database.


NotesIf authentication has not been enabled, client applications will have access to all databases on the server. Ifauthentication has been enabled, a client application will only have access to the database specified by theDatabaseName property assuming it has the required permissions. However, an application with clusterAdminprivileges will have access to all databases on the server even when authentication is enabled.

DefaultINFORMATION_SCHEMA

Data TypeString

See also



• CreateDB on page 182

• SchemaMap on page 200


DatabaseName

EncryptionMethod

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

Valid ValuesnoEncryption | SSL | requestSSL

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.

If set to requestSSL, the login request and data is encrypted using SSL. If the database server does notsupport SSL, the driver establishes an unencrypted connection.

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

DefaultnoEncryption

Data TypeString

See also

• Data Encryption on page 97

• Performance Considerations on page 96



FetchSize

PurposeSpecifies 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 fetches and processes all of the rows of the result before returning control to the application.When large data sets are being processed, setting FetchSize to 0 can diminish performance and increase thelikelihood of 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 manyrows 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.

Default100 (rows)

Data TypeInt


FetchSize

See also

• Using Connection Properties on page 90


• ResultMemorySize on page 198

• Troubleshooting Out-of-Memory Errors on page 215

HostName

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

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. See IP Addresseson page 107 for details about these formats.

Notes

• In a Kerberos configuration, the value of the HostName property must match the fully qualified domain name(FQDN) registered with the KDC. The FQDN consists of a host name and a domain name. For the examplemyserver.test.com, myserver is the host name and test.com is the domain name.

• In a Kerberos configuration, an IP address cannot be used for the HostName connection property.

DefaultNone

Data TypeString

See also



• ServicePrincipalName on page 201




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

Valid Valueshost_name | #SERVERNAME#

where:

host_name

is a valid host name.

BehaviorIf host_name is specified, the driver compares the specified host name to the DNSName value of theSubjectAlternativeName in the certificate. If a DNSName value does not exist in the SubjectAlternativeNameor if the certificate does not have a SubjectAlternativeName, the driver compares the host name with theCommon Name (CN) part of the certificate’s Subject name. If the values do not match, the connection failsand the 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.

DefaultEmpty string

Data TypeString

See alsoData Encryption on page 97



ImportStatementPool

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

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

Defaultempty string

Data TypeString

See also

• Statement Pool Monitor on page 124

• Importing Statements into a Statement Pool on page 128

• MaxPooledStatements on page 193

• RegisterStatementPoolMonitorMBean on page 198

InitializationString

PurposeOne or multiple SQL commands to be executed by the driver after it has established the connection to thedatabase and has performed all initialization for the connection. If the execution of a SQL command fails, theconnection attempt also fails and the driver returns an error indicating which SQL command or commandsfailed.

Valid Valuescommand [[; command ]...]

where:



command

is one or multiple SQL commands.

Note: Multiple commands must be separated by semicolons. In addition, if this option is specified in a connectionURL, the entire value must be enclosed in parentheses when multiple commands are specified.

DefaultNone

Data TypeString

See alsoUsing Connection Properties on page 90

KeyPassword

PurposeSpecifies the password that is used to access the individual keys in the keystore file when SSL is enabled(EncryptionMethod=SSL) and SSL client authentication is enabled on the database server. This propertyis useful when individual keys in the keystore file have a different password than the keystore file.

Valid Values

string

where:

string

is a valid password.

DefaultNone

Data TypeString



KeyPassword

KeyStore

PurposeSpecifies the directory of the keystore file to be used when SSL is enabled (EncryptionMethod=SSL) andSSL client authentication is enabled on the database server. The keystore file contains the certificates that theclient sends to the server in response to the server’s certificate request.

Valid Values

string

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

DefaultNone

Data TypeString


KeyStorePassword

PurposeSpecifies 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 Values

string

where:

string

is a valid password.

Notes

• This value overrides the password of the keystore file that is specified by the javax.net.ssl.keyStorePasswordJava system property. If this property is not specified, the keystore password is specified by thejavax.net.ssl.keyStorePassword Java system property.

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

DefaultNone

Data TypeString


LogConfigFile

PurposeSpecifies the filename of the configuration file used to initialize driver logging.

Note: If the driver cannot locate the specified file when establishing the connection, the connection fails andthe 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 on page 218.

Defaultddlogging.properties


LogConfigFile

Data TypeString


LoginConfigName

PurposeSpecifies 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

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.


DefaultJDBC_DRIVER_01

Data TypeString

See also


• The JAAS Login Configuration File on page 103




LoginTimeout

PurposeDetermines the amount of time, in seconds, that the driver waits for a connection to be established beforetiming out the connection request.

Valid Values0 | x

where:

x

is a positive integer that represents a number of seconds.

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

If set to x, the driver waits for the specified number of seconds before returning control to the application andthrowing a timeout exception.

Default0

Data TypeInt


MaxPooledStatements

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


LoginTimeout

Valid Values

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

ExampleIf the value of this property is set to 20, the driver caches the last 20 prepared statements that are created bythe application.

Default0

Data TypeInt

See also



• RegisterStatementPoolMonitorMBean on page 198

• ImportStatementPool on page 188

Password

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

DefaultNone

Data TypeString

See also



PortNumber

PurposeSpecifies the port number of the server listener.

Valid Valuesport_number

where:

port_number

is the port number of the server listener. Check with your database administrator for the correctnumber.

Default27017

Data TypeInt


PortNumber


ReadOnly

PurposeSpecifies whether the connection has read-only access to the data source.


BehaviorIf set to true, the connection has read-only access.The following commands are the only commands that youcan use when a connection is read-only:

• Explain Plan

• Select (except Select Into)

• Set Schema

The driver returns an error if any other command is used.

If set to false, the connection is opened for read/write access, and you can use all commands supported bythe product.

Caution: Before disabling the ReadOnly connection property, it is critical to confirm that all values in theprimary key column are unique. Executing write operations against data with duplicate primary keys can produceunpredictable and undesirable results. See Designating a Primary Key on page 87 for more information.

NotesYou also can use the JDBC connection method setReadOnly to set a read-only state for a connection.

Defaulttrue

Data TypeBoolean




ReadPreference

PurposeSpecifies a preference for the type of member (server node) of a replica set to which the driver attempts toconnect. Connections to the primary member (read-write server nodes) return the most recent version of thedata when executing Select queries, but increase the workload of the primary member and may negativelyaffect performance. To reduce the demand on the primary member, secondary members (read-only servernodes) can be used at the expense of reading stale data.

Valid Valuesnone | primary | primaryPreferred | secondary | secondaryPreferred

BehaviorIf set to none, the driver attempts to connect to only the member authorized by the application.

If set to primary, the driver attempts to connect to only the primary member of a replica set. If the primarymember is unavailable, the connection fails.

If set to primaryPreferred, the driver attempts to connect to the primary member first; but if it is unavailable,the driver attempts to connect to secondary members.

If set to secondary, the driver attempts to connect to only secondary members of a replica set. If the secondarymembers of the replica set are unavailable, the connection fails.

If set to secondaryPreferred, the driver attempts to connect to secondary members first; but if they areunavailable, the driver attempts to connect to the primary member.

Notes

• When connected to secondary members (read-only) of a replica set, the driver will return an error whenattempting to execute write operations.To enable write operations, disconnect from the secondary memberand establish a new connection to a primary (read-write) member.You should verify that the ReadPreferenceproperty is configured to tolerate a connection to a primary member before attempting to establish the newconnection.

• If the ReadPreference property is configured to connect to a secondary member, the replica set that thedriver is connecting to must contain a secondary member. If no secondary member exists, the driver willreturn an error.

Defaultprimary

See also




ReadPreference

RegisterStatementPoolMonitorMBean

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

Defaultfalse

Data Typeboolean

See also


• MaxPooledStatements on page 193

• ImportStatementPool on page 188

ResultMemorySize

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

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

Default-1

Data TypeInt

See also



• FetchSize on page 185

• Troubleshooting Out-of-Memory Errors on page 215


ResultMemorySize

SchemaMap

PurposeSpecifies the fully qualified path of the configuration file where the relational map of native data is written. Thedriver looks for this file when connecting to a MongoDB 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\\MongoDB_Schema\\MyServer.config,the driver either creates or looks for the configuration file MyServer.config in the directoryC:\Users\Default\AppData\Local\Progress\DataDirect\MongoDB_Schema\.

Notes

• When connecting to a MongoDB server, the driver looks for the SchemaMap configuration file. If theconfiguration file does not exist, the driver creates a SchemaMap using the name and location you haveprovided. If you do not provide a name and location for SchemaMap, the driver creates a SchemaMap usingdefault 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 in one of two ways. First,you can use the SQL extensions Refresh Map or Reload Map. Refresh Map runs a discovery against yournative data and updates your internal files accordingly, while Reload Map refreshes the internal files tointegrate configuration changes without running a discovery. Second, you can refresh these internal filesby launching the DataDirect Schema Tool and opening the corresponding schema map configuration file.When an existing schema is opened with the Schema Tool, the Schema Tool automatically compares thecontent of the schema configuration file to a snapshot of the data on the wire. When new native objects aredetected, the Schema Tool displays the newly detected objects by highlighting them in a hierarchical viewof the native data.

• SchemaMap was formerly SchemaDefinition.

Default

• For Windows XP and Windows Server 2003

• userprofile\ApplicationData\Local\Progress\DataDirect\MongoDB_Schema\hostname.config

• For other Windows platforms

• User data source:userprofile\AppData\Local\Progress\DataDirect\MongoDB_Schema\hostname.config

• System data source:C:\Users\Default\AppData\Local\Progress\DataDirect\MongoDB_Schema\hostname.config



• For UNIX/Linux

• ˜/progress/datadirect/mongodb_schema/hostname.config

Data TypeString

See also


• Refresh Map (EXT) on page 223

• Reload Map (EXT) on page 224

• Mapping Objects to Tables on page 16

ServicePrincipalName

PurposeSpecifies 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 mongodb.

Fully_Qualified_Domain_Name

is the fully qualified domain name (FQDN) of the host machine. By default, the driver uses the valuespecified by the HostName property.This value must match the FQDN registered with the KDC.TheFQDN consists of a host name and a domain name. For the example myserver.test.com,myserver is the host name and test.com is the domain name.

REALM_NAME

is the name of the Kerberos realm. By default, the driver uses the default realm specified in theKerberos configuration file. 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.

Notes

• By default, the driver builds the ServicePrincipalName by concatenating the service name mongodb, theFQDN as specified with the HostName property, and the default realm name as specified in the Kerberosconfiguration file. If this value does not match the service principal name registered with the KDC, then thevalue of the service principal name registered with the KDC should be specified for the ServicePrincipalNameproperty.


ServicePrincipalName

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

mongodb/[email protected]

DefaultDriver builds value based on environment

See also



• HostName on page 186

SpyAttributes

PurposeEnables 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 Tracking JDBC calls with DataDirect Spy on page 165 foradditional information.

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)

Notes

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



DefaultNone

Data TypeString

TransactionMode

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

DefaultnoTransactions

Data TypeString


TrustStore

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


TransactionMode

Valid Values

string

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

DefaultNone

Data TypeString


TrustStorePassword

PurposeSpecifies 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 Values

string

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



DefaultNone

Data TypeString


User

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

Valid Valuesuserid | user_principal_name

where:

userid

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

user_principal_name

is a valid Kerberos user principal name with permissions to access the database 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.

DefaultNone

Data TypeString

See also




User


PurposeDetermines whether the driver validates the certificate that is sent by the database server when SSL encryptionis enabled (EncryptionMethod=SSL). When using SSL server authentication, any certificate that is sent bythe server must be issued by a trusted Certificate Authority (CA).


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

Defaulttrue

Data Typeboolean




5Troubleshooting

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


• Troubleshooting your application

• Troubleshooting connection pooling

• Troubleshooting statement pooling

• Troubleshooting Out-of-Memory Errors

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


Turning on and off DataDirect Spy logging

Once DataDirect Spy logging is enabled for a connection, you can turn on and off the logging at runtime usingthe setEnableLogging() method in the com.ddtek.jdbc.extensions.ExtLogControl interface. When DataDirectSpy logging is enabled, all Connection objects returned to an application provide an implementation of theExtLogControl interface.

The following code example is drawn from a Microsoft SQL Server use case but informs the use of loggingwith DataDirect Spy with most Progress DataDirect drivers. The code shows how to turn off logging usingsetEnableLogging(false).

import com.ddtek.jdbc.extensions.*

// Get Database ConnectionConnection con = DriverManager.getConnection ("jdbc:datadirect:sqlserver://server1:1433;User=TEST;Password=secret; SpyAttributes=(log=(file)/tmp/spy.log)");

((ExtLogControl) con).setEnableLogging(false);...

The setEnableLogging() method only turns on and off logging if DataDirect Spy logging has already beenenabled for a connection; it does not set or change DataDirect Spy attributes. See "Enabling DataDirect Spy"for information about enabling and customizing DataDirect Spy logging.

See alsoEnabling DataDirect Spy on page 165

DataDirect Spy log example

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

Note: The following code example is drawn from a Microsoft SQL Server use case but informs the use oflogging with DataDirect Spy with most Progress DataDirect drivers.

For example, suppose your application executes the following code and performs some operations:Class.forName("com.ddtek.jdbc.sqlserver.SQLServerDriver");DriverManager.getConnection("jdbc:datadirect:sqlserver:// nc-myserver\\sqlserver2005;useServerSideUpdatableCursors=true;resultsetMetaDataOptions=1;sendStringParametersAsUnicode=true;alwaysReportTriggerResults=false;spyAttributes=(log=(file)c:\\temp\\spy.log)","test04", "test04");

The log file generated by DataDirect Spy would look similar to the following example. Notes provide explanationsfor the referenced text.

spy>> Connection[1].getMetaData()spy>> OK (DatabaseMetaData[1])

spy>> DatabaseMetaData[1].getURL()spy>> OK (jdbc:datadirect:sqlserver://nc-myserver\sqlserver2005:1433;CONNECTIONRETRYCOUNT=5;RECEIVESTRINGPARAMETERTYPE=nvarchar;ALTERNATESERVERS=;DATABASENAME=;PACKETSIZE=16;INITIALIZATIONSTRING=;ENABLECANCELTIMEOUT=false;BATCHPERFORMANCEWORKAROUND=false;AUTHENTICATIONMETHOD=auto;SENDSTRINGPARAMETERSASUNICODE=true;LOGINTIMEOUT=0;WSID=;SPYATTRIBUTES=(log=(file)c:\temp\spy.log);RESULTSETMETADATAOPTIONS=1;ALWAYSREPORTTRIGGERRESULTS=false;TRANSACTIONMODE=implicit;USESERVERSIDEUPDATABLECURSORS=true;SNAPSHOTSERIALIZABLE=false;JAVADOUBLETOSTRING=false;SELECTMETHOD=direct;LOADLIBRARYPATH=;CONNECTIONRETRYDELAY=1;INSENSITIVERESULTSETBUFFERSIZE=2048;MAXPOOLEDSTATEMENTS=0;DESCRIBEPARAMETERS=noDescribe;CODEPAGEOVERRIDE=;NETADDRESS=000000000000;


Chapter 5: Troubleshooting

PROGRAMNAME=;LOADBALANCING=false;HOSTPROCESS=0)14

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

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

spy>> DatabaseMetaData[1].getDatabaseProductName()spy>> OK (Microsoft SQL Server)

spy>> DatabaseMetaData[1].getDatabaseProductVersion()spy>> OK (Microsoft SQL Server Yukon - 9.00.1399)

spy>> Connection Options :15

spy>> CONNECTIONRETRYCOUNT=5spy>> RECEIVESTRINGPARAMETERTYPE=nvarcharspy>> ALTERNATESERVERS=spy>> DATABASENAME=spy>> PACKETSIZE=16spy>> INITIALIZATIONSTRING=spy>> ENABLECANCELTIMEOUT=falsespy>> BATCHPERFORMANCEWORKAROUND=falsespy>> AUTHENTICATIONMETHOD=autospy>> SENDSTRINGPARAMETERSASUNICODE=truespy>> LOGINTIMEOUT=0spy>> WSID=spy>> SPYATTRIBUTES=(log=(file)c:\temp\spy.log)spy>> RESULTSETMETADATAOPTIONS=1spy>> ALWAYSREPORTTRIGGERRESULTS=falsespy>> TRANSACTIONMODE=implicitspy>> USESERVERSIDEUPDATABLECURSORS=truespy>> SNAPSHOTSERIALIZABLE=falsespy>> JAVADOUBLETOSTRING=falsespy>> SELECTMETHOD=directspy>> LOADLIBRARYPATH=spy>> CONNECTIONRETRYDELAY=1spy>> INSENSITIVERESULTSETBUFFERSIZE=2048spy>> MAXPOOLEDSTATEMENTS=0spy>> DESCRIBEPARAMETERS=noDescribespy>> CODEPAGEOVERRIDE=spy>> NETADDRESS=000000000000spy>> PROGRAMNAME=spy>> LOADBALANCING=falsespy>> HOSTPROCESS=0spy>> Driver Name = SQLServer16

spy>> Driver Version = 3.60.0 (000000.000000.000000)17

spy>> Database Name = Microsoft SQL Server18

spy>> Database Version = Microsoft SQL Server Yukon - 9.00.139919

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

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

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

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

The statement select empno,ename,job from emp where empno=7369 is created.22 Some metadata is requested.23 Some metadata is requested.


Troubleshooting your application

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

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

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

spy>> ResultSet[1].getString(int columnIndex)spy>> columnIndex = 2spy>> OK (SMITH)29

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

spy>> ResultSet[1].next()spy>> OK (false)31spy>> ResultSet[1].close()spy>> OK32

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

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 110

Enabling tracing with the setTracing method

You 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() methodon the PooledConnectionDataSource connection.

24 Some metadata is requested.25 Some metadata is requested.26 Some metadata is requested.27 The first row is retrieved and the application retrieves the result values.28 The first row is retrieved and the application retrieves the result values.29 The first row is retrieved and the application retrieves the result values.30 The first row is retrieved and the application retrieves the result values.31 The application attempts to retrieve the next row, but only one row was returned for this query.32 After the application has completed retrieving result values, the result set is closed.33 The application finishes and disconnects.



Pool Manager trace file example

The following example shows a DataDirect Connection Pool Manager trace file. Notes provide explanationsfor the referenced text to help you understand the content of your own Pool Manager trace files.

Note: The example is drawn from a Microsoft SQL Server use case but applies to most Progress DataDirectdrivers.

jdbc/SQLServerNCMarkBPool: *** ConnectionPool Created (jdbc/SQLServerNCMarkBPool, com.ddtek.jdbcx.sqlserver.SQLServerDataSource@1835282, 5, 5, 10, scott)34

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

jdbc/SQLServerNCMarkBPool: Enforced minimum!35

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

jdbc/SQLServerNCMarkBPool: Reused free connection.36


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




jdbc/SQLServerNCMarkBPool: Created new connection.37

34 The Pool Manager creates a connection pool. In this example, the characteristics of the connection pool are shown using the following format:

(JNDI_name,DataSource_class,initial_pool_size,min_pool_size,max_pool_size,user)

where:

JNDI_name is the JNDI name used to look up the connection pool (for example, jdbc/SQLServerNCMarkBPool).

DataSource_class is the DataSource class associated with the connection pool (for example com.ddtek.jdbcx.sqlserver.SQLServerDataSource).

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

min_pool_size is the minimum number of physical connections be kept open in the connection pool (for example, 5).

max_pool_size is the maximum number of physical connections allowed within a single pool at any one time. When this number is reached, 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).35 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.36 The driver requests a connection from the connection pool. The driver retrieves an available connection.37 The driver requests a connection from the connection pool. Because a connection is unavailable, the Pool Manager creates a new connection

for the request.


Troubleshooting connection pooling


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





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


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










38 A connection is closed by the application and returned to the connection pool.





jdbc/SQLServerNCMarkBPool: Enforced maximum!40


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

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

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


jdbc/SQLServerNCMarkBPool: Dumped free connection.41


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







jdbc/SQLServerNCMarkBPool: Dumped free connection.

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

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

41 The Pool Manager detects that a connection was idle in the connection pool longer than the maximum idle timeout. The idle connection is closed and discarded from the pool.


Troubleshooting connection pooling






jdbc/SQLServerNCMarkBPool: Closing a pool of the group jdbc/SQLServerNCMarkBPool43


jdbc/SQLServerNCMarkBPool: Pool closed44


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 highfor good 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 124

42 The Pool Manager detects that the number of connections dropped below the limit set by the minimum pool size, five connections. The Pool Manager creates new connections to satisfy the minimum pool size.

43 The Pool Manager closes one of the connection pools in the pool group. A pool group is a collection of pools created from the same PooledConnectionDataSource call. Different pools are created when different user IDs are used to retrieve connections from the pool. A pool group is created for each user ID that requests a connection. In our example, because only one user ID was used, only one pool group is closed.

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



Generating an export file with the exportStatement method

You can generate an export file by calling 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.

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

Statement pool export file example

The 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]45

VERSION=146

[STMT_ENTRY]47

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

[STMT_ENTRY]48

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 thanthe value specified will be written to disk as opposed to held in memory. When configured correctly, this

45 A string that identifies the file as a statement pool export file.46 The version of the export file.47 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.48 The next statement pool entry.


Troubleshooting Out-of-Memory Errors

avoids memory limitations by not relying on memory to process larger intermediate results. 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. By default,ResultMemorySize is set to -1, which sets the maximum size of intermediate results held in memory to apercentage of the max Java heap size. If you received errors using the default configuration, use the maxJava heap size divided 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 FetchSize on page 185 and ResultMemorySize on page 198 for additional information.

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.

Logging Components

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

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 Logging

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


Using Java logging

Using the JVM for loggingIf you want to configure logging using the properties file that is shipped with your JVM, use a text editor tomodify the properties file in your JVM. Typically, this file is named logging.properties and is located in theJRE/lib subdirectory of your JVM. The JRE looks for this file when it is loading.

You can also specify which properties file to use by setting the java.util.logging.config.file system property. Ata command prompt, enter:

java -Djava.util.logging.config.file=properties_file

where:

properties_file

is the name of the properties file you want to load.

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 MongoDB connections.

• Use a different properties file for each schema map. For example, if you have two maps(C:\data\db\mynormaldb.config and C:\data\db\myflatdb.config, for example), you can loadone properties file for the mynormaldb.config schema map and load another properties file for themyflatdb.config schema map.

Note: You must specify the name and path of the schema map using the SchemaMap connection property.See SchemaMap on page 200 for details.

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 218, 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 218, 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 218 , 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.

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



6Supported SQL Functionality

The MongoDB driver provides support for the SQL statements and the SQL extensions described in this chapter.SQL extensions are denoted by an (EXT) in the topic title.


• Delete

• Insert

• Refresh Map (EXT)

• Reload Map (EXT)

• Select

• Update

• SQL Expressions

• Subqueries

Delete

PurposeThe 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 tableare deleted, but the table is left intact. See "Where Clause" for information about the syntax of Whereclauses. 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

• Insert, Update, and Delete are supported for MongoDB for simple types at the root level.

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

See alsoWhere Clause on page 230

Insert

PurposeThe 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


Chapter 6: Supported SQL Functionality

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" 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" for information about Select statements.

Notes



See alsoLiterals on page 237Select on page 224

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 andassociated files.

SyntaxREFRESH MAP [NEW]


Refresh Map (EXT)

where

NEW

limits the sampling performed by the driver to only those collections that are newly discovered.Whenexecuting REFRESH MAP, this can offer significant performance gains if you only want to samplenew collections or the existing collections are unchanged. If NEW is not specified in the statement,all collections are resampled.

Notes

• Newly discovered objects are mapped using the same relational view you selected in Creating a Schemawith the Table Wizard on page 63. If you did not select a view with the Schema Tool, or selected a customview, the driver maps new objects using a normalized view.

• REFRESH MAP is an expensive query since it involves the discovery of native data. However, by specifyingNEW in the statement, you can reduce the overhead associated with this query by sampling only newcollections.

Reload Map (EXT)

PurposeThe RELOAD MAP statement reloads the schema map and associated files. This statement allows you toupdate your relational view of native data while the driver is connected to the data store.

SyntaxRELOAD MAP

Notes

• RELOAD MAP does not discover changes made to the native data store.

Select

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

Syntax

SELECT 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" for acomplete explanation.

from_clause

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

where_clause

is optional and restricts the results that are returned by the query. See "Where Clause" for a completeexplanation.

groupby_clause

is optional and allows query results to be aggregated in terms of groups. See "Group By Clause" fora 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" for a complete explanation.

UNION

is an optional operator that combines the results of the left and right Select statements into a singleresult. See "Union Operator" 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" 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 Operators"for a complete explanation.

orderby_clause

is optional and sorts the results that are returned by the query. See "Order By Clause" for a completeexplanation.

limit_clause

is optional and places an upper bound on the number of rows returned in the result. See "LimitClause" for a complete explanation.

See alsoSelect Clause on page 226From Clause on page 228Where Clause on page 230Group By Clause on page 231


Select

Having Clause on page 231Union Operator on page 232Intersect Operator on page 233Except and Minus Operators on page 234Order By Clause on page 234Limit Clause on page 235

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.

Syntax

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

where:

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 "SQLExpressions" for details.column_expression can also include aggregate functions. See "AggregateFunctions" 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.

See alsoSQL Expressions on page 237Aggregate Functions on page 227

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

The following table lists supported aggregate functions.

Table 29: 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)


Select

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

SELECT COUNT(amount) AS numOpportunities, MAX(amount) AS maxAmount, AVG(amount) AS avgAmount FROM opportunity o INNER JOIN user u ON o.ownerId = u.id WHERE o.isClosed = 'false' AND u.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

Subqueries can be used instead of table names. Subqueries must be enclosed in parentheses. See"Subquery in a From Clause" 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.deptName FROM 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.



See alsoSubquery in a From Clause on page 230

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} ON search-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 {oj Customers LEFT OUTER JOIN Orders ON Customers.CustID=Orders.CustID} WHERE Orders.Status='OPEN'

The following outer join escape sequences are supported by MongoDB databases:

• 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.deptName FROM 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.key ON search-condition


Select

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 Clause

Subqueries 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 alsoSubqueries on page 244

Where Clause

PurposeSpecifies the conditions that rows must meet to be retrieved.

SyntaxWHERE expr1rel_operatorexpr2

where:

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 alsoSubqueries on page 244SQL Expressions on page 237



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.

NotesThe driver uses the MongoDB aggregation framework whenever possible. In some instances, MongoDB mayaggregate data in unexpected ways. For example, if you use the GROUP BY clause to return zip codes andthe database contains the zip code 15237 as both a string and an integer, then two rows will be returned for15237 (one for the string representation and another for the integer representation).


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:


Select

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" for details regarding SQL expressions.

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

NotesThe driver uses the MongoDB aggregation framework whenever possible. In some instances, MongoDB mayaggregate data in unexpected ways. For example, if you use the HAVING clause to return zip codes and thedatabase contains the zip code 15237 as both a string and an integer, then two rows will be returned for 15237(one for the string representation and another for the integer representation).


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

Syntax

select_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 ofcolumn expressions with the same data types and must be specified in the same order.

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.

Syntax

select_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 numberof 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


Select

Except and Minus Operators

PurposeReturn the rows from the left Select statement that are not included in the result of the right Select statement.

Syntax

select_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 numberof 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

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 237

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 appliedto 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


Select

Update

PurposeAn Update statement changes the value of columns in the selected rows of a table.

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'

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



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

See alsoSubqueries on page 244Where Clause on page 230



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 MongoDB driver supports both unquoted and quoted identifiers. An unquoted identifier must start with anASCII alpha character and can be followed by zero or more ASCII alphanumeric characters. Unquoted identifiersare converted 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 MongoDB driver recognizes the Unicode escape sequence \uxxxxas a Unicode character.You can specify a double quotation mark in a quoted identifier by escaping it with adouble quotation mark.

The maximum length of both quoted and unquoted identifiers is 128 characters.

Valid expression elements are:

• Column names

• Literals

• Operators

• Functions

Column Names

The most common expression is a simple column name.You can combine a column name with other expressionelements.

Literals

Literals 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

• Timestamp

The following table describes the literal format for supported SQL data types.


SQL Expressions

Table 30: Literal Syntax Examples

ExampleLiteral SyntaxSQL Type

12 or -34 or 0n

where

n 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''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

Operators

This 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 31: 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 32: 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 MongoDB driver considers the UNKNOWN resultas FALSE.

The following table lists the supported comparison operators.

Table 33: 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 34: Logical Operators


SELECT * FROM emp WHERE NOT (job IS NULL)SELECT * FROM emp WHERE NOT (sal BETWEEN 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 conditionsare TRUE. 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 35: 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).

Functions

The MongoDB driver supports a number of functions that you can use in expressions, as listed and describedin Scalar functions on page 250.

Conditions

A 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 36: 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 froma subquery).

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.

Syntax

SELECT select_list FROM table1 t_alias1 WHERE expr rel_operator (SELECT column_list FROM table2 t_alias2 WHERE t_alias1.columnrel_operatort_alias2.column) UPDATE table1 t_alias1 SET column = (SELECT expr FROM table2 t_alias2 WHERE t_alias1.column = t_alias2.column) DELETE FROM table1 t_alias1 WHERE column rel_operator (SELECT expr FROM table2 t_alias2 WHERE t_alias1.column = t_alias2.column)

Notes

• Correlated column names in correlated subqueries must be explicitly qualified with the table name of theparent.

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 emp WHERE "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

Note: The Progress DataDirect MongoDB for JDBC driver also supports the custom function escapeCAST_TO_NATIVE.

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


• CAST_TO_NATIVE function escape

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 37: Supported Scalar Functions

System FunctionsTimedate FunctionsNumericFunctions

String Functions

CURSESSIONIDCURDATEABSASCII

DATABASECURTIMEACOSBIT_LENGTH

IDENTITYDATEDIFFASINCHAR


Chapter 7: SQL escape sequences for JDBC

System FunctionsTimedate FunctionsNumericFunctions

String Functions

DAYATANCHAR_LENGTH USER

DAYNAMEATAN2CHARACTER_LENGTH

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


Outer join escape sequences

table-reference

is a database table name.

search-condition

is the join condition you want to use for the tables.

Example:

SELECT Customers.CustID, Customers.Name, Orders.OrderID, Orders.Status FROM {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 '*'}

CAST_TO_NATIVE function escapeThe MongoDB driver supports the custom function escape CAST_TO_NATIVE. The CAST_TO_NATIVEfunction escape can be used in a filter to select or insert a value of a specific native type.

In some cases, a value with a specific native type can be concealed or obscured because the driver describesa field with inconsistent native types as a column with a single SQL type. For example, the driver maps aMongoDB _id field with the native types String and ObjectId to a relational _ID column with the VARCHARtype. In this context, the CAST_TO_NATIVE function escape allows users to send a value as it is defined inthe MongoDB database, rather than how it is described in the relational model of the data.

Currently, CAST_TO_NATIVE can only be used with the ObjectID type in SELECT statement filters and literalINSERT values.



Syntax

{fn CAST_TO_NATIVE('value','native_type')}

where:

value

is the value to be selected or inserted.

native_type

is the native type that in part defines the value.

Example SelectThe following statement selects records from Account where the _ID field has an ObjectID value of507f1f77bcf86cd799439011.

SELECT * FROM Account WHERE _ID = {fn CAST_TO_NATIVE('507f1f77bcf86cd799439011','objectid')}

Example InsertThe following statement inserts the ObjectID value 507f1f77bcf86cd799439011 into the _ID field.

INSERT INTO Account(_ID) VALUES ({fn CAST_TO_NATIVE('507f1f77bcf86cd799439011','objectid')})


CAST_TO_NATIVE function escape



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 8 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 Autonomous REST Connector and thedrivers for Jira, 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 Autonomous REST Connector and thedrivers for Jira, 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 Autonomous REST Connector and thedrivers for Jira, 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()




Clob Methods


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)


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

Yes4.0createArrayOf(String, Object[])

Only the Oracle driver supports this method.Yes4.0createStruct(String, Object[])

Yes4.0SQLXML createSQLXML()

Yes1.0Statement createStatement()

For the DB2 driver,ResultSet.TYPE_SCROLL_SENSITIVE isdowngraded toTYPE_SCROLL_INSENSITIVE.

For the Autonomous REST Connector andthe drivers for Jira, 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)




Connection Methods


All other drivers throw "unsupported method"exception.

Yes1.0Struct createStruct(String, Object[])

Yes1.0boolean getAutoCommit()

The Autonomous REST Connector and thedrivers 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, Jira,Impala, MongoDB, Oracle, Oracle Eloqua,Oracle Sales Cloud, Oracle Service Cloud,PostgreSQL, and Salesforce.

Yes1.0String getCatalog()

The Autonomous REST Connector and thedrivers for Apache Cassandra, Jira,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()

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)




Connection Methods

Yes1.0CallableStatement prepareCall(String)

For the Autonomous REST Connector andthe drivers for Apache Cassandra, DB2, Jira,MongoDB, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, and SalesforceResultSet.TYPE_SCROLL_ SENSITIVE isdowngraded 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)

For the DB2 driver,ResultSet.TYPE_SCROLL_ SENSITIVE isdowngraded toTYPE_SCROLL_INSENSITIVE.

For the Autonomous REST Connector andthe drivers for Apache Cassandra, Jira,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[])




Connection Methods



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 Autonomous REST Connector and thedrivers for Apache Cassandra, Jira,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 Autonomous REST Connector and thedrivers for Apache Cassandra, Apache Hive,Apache Spark SQL, Impala, Jira, MongoDB,Oracle Eloqua, Oracle Sales Cloud, OracleService Cloud, and Salesforce throw"transactions not supported" exception if setto false.

Yes1.0void setAutoCommit(boolean)

The Autonomous REST Connector and thedrivers 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, Jira,MongoDB, Oracle, Oracle Eloqua, OracleSales Cloud, Oracle Service Cloud,PostgreSQL, and Salesforce.

Yes1.0void setCatalog(String)


Yes4.0String setClientInfo(Properties)




Connection Methods


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

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 Autonomous REST Connector and thedrivers for Apache Cassandra, Apache Hive,Apache Spark SQL, Impala, Jira, MongoDB,Oracle Eloqua, Oracle Sales Cloud, OracleService Cloud, and Salesforce ignore anyspecified transaction isolation level.

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)

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

The Autonomous REST Connector and thedrivers for Apache Cassandra, Jira,MongoDB, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce do not support storing orretrieving client information.

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 Autonomous REST Connector and thedrivers for Apache Cassandra, Jira,MongoDB, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce return an empty result set.

Not supported by the drivers for ApacheHive, Apache Spark SQL, or Impala.

Yes4.0ResultSet getFunctions()

The Autonomous REST Connector and thedrivers for Apache Cassandra, Jira,MongoDB, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce return 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 Autonomous REST Connector andthe drivers for Jira, 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()

DataSource

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


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)


Yes3.0int getParameterType(int)


Yes3.0String getParameterTypeName(int)


Yes3.0int getPrecision(int)


Yes3.0int getScale(int)


Yes3.0int isNullable(int)




ParameterMetaData Methods


Yes3.0boolean isSigned(int)


Yes1.0boolean jdbcCompliant()


PooledConnection


PooledConnection Methods

Yes2.0 Optionalvoid addConnectionEventListener(listener)

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 Autonomous REST Connector andthe drivers for Apache Cassandra, Jira,MongoDB, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce, N methods are identical to theirnon-N counterparts.

Yes4.0void setNCharacterStream(int, Reader)


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 Autonomous REST Connector and thedrivers for Jira, 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)

Yes2.0 CoreArray getArray(String)

Yes1.0InputStream getAsciiStream(int)

Yes1.0InputStream getAsciiStream(String)




ResultSet Methods

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 Autonomous REST Connector andthe drivers for Jira, MongoDB, OracleEloqua, Oracle Sales Cloud, Oracle ServiceCloud, and Salesforce, N methods areidentical to their 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)




ResultSet Methods


Yes4.0void updateNClob(String, Reader, long)


Yes4.0void updateNString(int, String)


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)




ResultSet Methods

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)




ResultSetMetaData Methods

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.




Statement Methods

The Autonomous REST Connector and thedrivers for Apache Cassandra, Impala,Informix, Jira, MongoDB, ProgessOpenEdge, Oracle Service Cloud, OracleEloqua, Oracle Sales Cloud, and Salesforcethrow an "unsupported method" exception.

The Apache Hive, Apache Spark SQL49,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.

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)

49 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



Yes3.0int executeUpdate(String, int [])



Yes3.0int executeUpdate(String, String [])

Yes2.0 CoreConnection getConnection()

Yes2.0 Coreint getFetchDirection()

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 Autonomous REST Connector and thedrivers for Apache Cassandra, Jira,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 for




Statement Methods

Linux/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 Autonomous REST Connector and thedrivers for Jira, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, and Salesforcereturn an "unsupported method" exception.

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)




Statement Methods

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.

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 Autonomous REST Connector and thedrivers for Jira, 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,Autonomous REST Connector, DB2 V8.1for z/OS, Greenplum, Impala, Jira, OracleEloqua, Oracle Sales Cloud, Oracle ServiceCloud, PostgreSQL, and Salesforce.

Yes2.0 Optional(all)

XADataSource


XADataSource Methods

Supported for all drivers except AmazonRedshift, Apache Hive, Apache Spark SQL,Autonomous REST Connecter, DB2 V8.1for z/OS, Greenplum, Impala, OracleEloqua, Oracle Sales Cloud, Oracle ServiceCloud, PostgreSQL, and Salesforce.


XAResource


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






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 Autonomous RESTConnector and the drivers for Oracle Eloqua, Oracle Sales Cloud, OracleService Cloud, Salesforce, and Google BigQuery to extend the standardJDBC metadata results returned by the DatabaseMetaData.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();}...


Chapter 9: JDBC extensions

DatabaseMetaData interfaceThe following drivers support the DatabaseMetaData.getColumns() method:

• Autonomous REST Connector

• Jira

• Oracle Eloqua

• Oracle Sales Cloud

• Oracle Service Cloud

• Salesforce

The DatabaseMetaData.getColumns() method extends the standard JDBC metadata results returned toinclude the additional columns described in the following tables.

Table 38: 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 Autonomous REST Connector and the drivers for Jira, Oracle Eloqua, Oracle Sales Cloud, Oracle ServiceCloud, and Salesforce extend the standard JDBC metadata results returned by theDatabaseMetaData.getTables() method to include the following additional column.

Table 39: 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()


DatabaseMetaData interface

DescriptionDDBulkLoad Methods

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)

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 rowsthat were 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)


DDBulkLoad interface


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 numRows codePage binaryThreshold timeout characterThreshold logFile errorTolerance discardFile warningTolerance configFile readBufferSize startPosition 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 328

Reduce network traffic.Network communication is slow.

Using database metadata methods onpage 328

Selecting JDBC objects and methodson page 332

Simplify queries.Evaluation of complex SQL queries onthe database server is slow and canreduce concurrency.


See guidelines in…SolutionProblem

Returning data on page 330

Selecting JDBC objects and methodson page 332

Optimize application-to-driverinteraction.

Excessive calls from the application tothe driver slow performance.

Managing connections and updates onpage 335

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 methods

Compared 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 patterns

Using 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 characteristics

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

ResultSet 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 query PreparedStatement 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 data

Because 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 data

Sometimes 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 type

Retrieving 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 sets

Most 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 procedures

When 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 statement object instead of the PreparedStatement object

JDBC 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 statements

Updating 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 Times

PreparedStatement 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 Batch

PreparedStatement 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 cursor

Choosing 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 effectively

JDBC 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 keys

Many 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 LocalGeniusList WHERE 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 connections

Connection 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 itin one step rather than two steps. For example, some applications establish a connection and then call amethod in a separate component that reattaches and gathers information about the driver. Applications thatare designed as separate entities should pass the established connection object to the data collection routineinstead of establishing 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 transactions

Committing 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 model

Many 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 methods

Although 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 getBestRowIdentifier

Use 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 oneor more 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 127addresses

IPv4/IPv6 107aggregate functions 227application

connecting with driver 42data source, calling in 39, 48troubleshooting 207

arithmetic operators 240Array interface, methods 256arrays

mapping 18, 24ASCII

encoding 109authentication

client 99connection properties 92Kerberos 100server (SSL) 98SSL 99user ID/password 100

AuthenticationDatabase 172AuthenticationMethod 173auto generated keys

example, retrieving 335performance optimization 335

Autocommit mode 336

Bbatch inserts and updates

batch execution on a prepared statement withDataDirect Test 145using instead of prepared statements 333

behaviorchanges 12new 12

binaryliterals 239operators 240

Blob interface, methods 256Blobs

retrieving with DataDirect Test 160

CCallableStatement interface, methods 257certificate

validation 206

Certificate Authority (CA)SSL 98

changing the maximum pool size behavior 116character string literals 239classes

data source 15, 33, 42driver 15, 33, 42

CLASSPATH, settingJava Virtual Machine (JVM) 34, 43UNIX 34, 43Windows 34, 43

clearing statements in the statement pool 129client authentication

SSL 99Clob interface, methods 269Clobs

retrieving with DataDirect Test 160closing the connection pool 118collections

mapping to tables 16normalizing 17

columnnames 237

column information and statisticssample size 74

ColumnDiscoverySampleSize 175columns 87columns, adding 84columns, defining 86columns, removing 86committing transactions 336comparison operators 241complex types

arrays 18, 24documents 18, 24

concatenation operator 240conditions 243ConfigOptions

KeywordConflictSuffix 89–90, 105LeadingUnderscoreReplacement 89–90, 105UppercaseIdentifiers 89, 105

configuration optioncolumnDiscoverySampleSize 175DefaultVarcharSize 175KeywordConflictSuffix 177LeadingUnderscoreReplacement 177MinVarcharSize 179SchemaFilter 180

configuration optionsKeywordConflictSuffix 89–90, 105LeadingUnderscoreReplacement 89–90, 105


Index

configuration options (continued)MaxVarcharSize 178UppercaseIdentifiers 89, 105, 181

connectingDataDirect Test

using a data source 134using driver/database selection 135

using connection pool 116using DataDirect Test 134

Connection interface, methods 271connection management 336Connection object

managing connections 336transaction model 337

connection optionsReadPreference 197

Connection Pool Managerversion information 118

connection poolingconfiguring 115connection pool

closing 118connecting using 116

DataDirect Connection Pool Manager trace file 211javax.sql.ConnectionPoolDataSource interface 38, 47performance optimization 336using 110

connection propertiesadditional 95authentication 92AuthenticationDatabase 172AuthenticationMethod 173ConfigOptions 173CreateDB 182data encryption 93DatabaseName 183defaults 169EncryptionMethod 184FetchSize 185HostName 186HostNameInCertificate 187ImportStatementPool 188InitializationString 188KeyPassword 189KeyStore 190KeyStorePassword 190LogConfigFile 191LoginConfigName 192LoginTimeout 193MaxPooledStatements 193overview 90Password 194PortNumber 195ReadOnly 196reference 169

connection properties (continued)RegisterStatementPoolMonitorMBean 198required 91ResultMemorySize 198SchemaMap 200ServicePrincipalName 201SpyAttributes 165, 167, 202statement pooling 94TransactionMode 203TrustStore 203TrustStorePassword 204User 205ValidateServerCertificate 206

connection URLspecifying 34, 43

ConnectionEventListener interface, methods 276ConnectionPoolDataSource interface, methods 276ConnectionPoolMonitor

interface 123connections

data sources 38, 47JDBC data source 39, 48testing 35, 44

copyright 3correlated subqueries 246CreateDB 182cursors

choosing 334custom view

starting with 67

Ddata encryption

configuring 97SSL 93, 97

data sourceclasses 15, 33, 42

data sourcesapplication, calling in 39, 48connecting with 42connection pooling 110creating 113–114creating data sources 39, 48DataSource interface 38, 47File System JNDI Provider 39, 48implementing 38, 47JNDI Provider for LDAP 39, 48specifying SpyAttributes 165

data sources (data source object)DataSource object, connecting with 38, 47

data typescomplex 18, 24mapping 24mapping inconsistent types 26

data types, choosing for performance 331


Index

data types, defining 86data

typesDatabaseMetadata.getTypeInfo()getTypeInfo()getTypeInfo results 26results 26

databasetable characteristics, using dummy query todetermine 329

database information 71database metadata

retrieving with DataDirect Test 141DatabaseMetaData interface 313DatabaseMetaData interface, methods 276DatabaseName 183DataDirect Connection Pool Manager

trace file 210–211tracing, enabling 118, 210version information 118

DataDirect Schema Toolfunctionality 11table wizard 11

DataDirect Spyattributes 167enabling 165logging 207–208overview 165setEnableLogging() method 208SpyAttributes connection property 202troubleshooting 207

DataDirect Spy, enabling 166DataDirect Statement Pool Monitor

accessingusing the JMX API 127

classes and interfaces 130DataDirect Test

batch execution 145configuring 133connecting with 134database metadata, retrieving 141deleting rows 151executing

Select statement 137executing prepared statement 138inserting rows 151, 154LOB support 160parameter metadata, returning 147result set, scrolling through 143savepoints, establishing 148starting 133testing a connection 35, 44tutorial 132updatable result sets 151updating rows 151, 157using 132

DataSourceconnection pooling 112–114

DataSource interface, methods 285DataSource object

calling in an application 39, 48retrieving 39, 48

dateescape sequence 250

date/time literals 239DDBulkLoad interface, methods 313DefaultVarcharSize 175Delete statement 221deleting rows

with DataDirect Test 151documents

mapping 18, 24driver

class 15, 33, 42Driver interface, methods 285Driver Manager

connecting with 34, 42Driver Version string

format 16DriverManager

specifying SpyAttributes 165dummy query, using to determine table characteristics329

Eembedded database

creating 182encryption

configuring 97SSL 97

EncryptionMethod 184enhancements 12error handling

format 109escape sequences

date, time, and timestamp 250LIKE escape character for wildcards 252outer join 251

exampleouter join escape sequence 251scalar functions 250

Except operator 234EXISTS predicate 245export file for statement pool

example 215generating 129

ExtConnection interface, methods 320ExtDatabaseMetaData interface, methods 325extensions package

datadirect.jdbc.extensions package 311ExtLogControl class, methods 325ExtLogControl interface 208extracting a new table 82


Index

ExtStatementPoolMonitor class 130ExtStatementPoolMonitorMBean interface 130

Ffeatures

changes 12new 12

FetchSize 185, 215File System JNDI Provider 39, 48flattened view

generating 65flattening

arrays 24complex types 24documents 24

forward-only cursorperformance implications 334

freezing the statement pool 129From clause

Outer Join Escape Sequences 229function escapes 252functionality

changes 12new 12

functions, ODBC 243

GgetBestRowIdentifier() method 337getBlob() method 330getClob() method 330getObject() method 334Group By clause 231

HHaving clause 231help, online 31, 218HostName 186HostNameInCertificate 187

Iidentifiers

naming conflicts 89–90, 105importing statements into the statement pool 128ImportStatementPool 188IN predicate 245initial pool size 115InitializationString 188InputStream object, DataDirect Spy 166insensitive cursors

performance implications 334Insert statement 222

inserting rowswith DataDirect Test 154

Insertsparameter metadata 108

integer literals 239Interfaces, JDBC 255Intersect operator 233IP addresses

IPv4/IPv6 support 107isolation levels

read uncommitted 109

JJAAS (Java Authentication and Authorization Service)

login configuration file 103Java Authentication and Authorization Service (JAAS)

login configuration file 103Java Authentication and Authorization Service (JAAS)login module 101Java logging

components 216JDBC API logger 217SQL engine logger 217using 216

Java Naming Directory Interface (JNDI)connecting with 42data source

application, using in 39, 48initializing environment 39, 48

Java SErequirements 15

JDBCfunctionality supported 255interfaces 255JVM compatibility 255methods supported 255SQL escape sequences 249versions supported 255

JDBC API logger 217JDBC data source, specifying SpyAttributes 166JDBC data sources 38, 47JDBC data type

mapping 24mapping inconsistent types 26

JDBC Driver Managerconnecting with 34, 42specifying SpyAttribute 165

JDBC extensionsintroduction 311wrapper methods to access 312

JNDI Provider for LDAP 39, 48join in a From clause 229JSR 114 Rowsets

requirements 15


Index

JTA supporttransaction

model, choosing for performance 337JTA transaction support

managing commits 336JVM

JDBC compatibility 255properties file 218

KKerberos

JAAS login configuration file 103Kerberos authentication

configuration file 101product requirements 103

Kerberos Key Distribution Center (KDC) 101KeyPassword 189keyset-driven cursors, performance implications 334keystore

SSL 99KeyStore 190KeyStorePassword 190KeywordConflictSuffix 89, 105, 177

LLDAP 39, 48LeadingUnderscoreReplacement 89, 105, 177LIKE escape character for wildcards escape sequence252Limit clause 235literals

about 237arguments, using parameter markers 332binary 239character string 239date 250date/time 239integer 239numeric 239time 250timestamp 250

LOBs supportexecuting a query with DataDirect Test 160

local tabledeleting rows 221

LogConfigFile 191logging

DataDirect Spy 208JVM properties file 218with DataDirect Spy 165

logging, Javacomponents 216JDBC API logger 217SQL engine logger 217

logging, Java (continued)using 216

logical operators 242LoginConfigName 192LoginTimeout 193long data, retrieving and performance 330

Mmapping

complex types 18, 24connection properties 91schemas 76

mapping newly detected objects 81mapping objects 76mapping objects to tables

overview 16maximum idle time 115maximum pool size 115maximum pool size behavior 116MaxPooledStatements 193MaxVarcharSize 178MBean name, registering 127metadata

JDBC extensions 313metadata methods

reporting 11metadata methods, minimizing use of 328methods

Array interface 256Blob interface 256CallableStatement interface 257Clob interface 269Connection interface 271ConnectionEventListener interface 276ConnectionPoolDataSource interface 276DatabaseMetaData interface 276DatabaseMetadata.getTypeInfo() 26DataSource interface 285DDBulkLoad interface 313Driver interface 285ExtConnection interface 320ExtDatabaseMetaData interface 325ExtLogControl class 325ParameterMetaData interface 286PooledConnection interface 287PreparedStatement interface 287Ref interface 292ResultSet interface 292ResultSetMetaData interface 303RowSet interface 304SavePoint interface 304Statement interface 304StatementEventListener interface 308Struct interface 309XAConnection interface 309


Index

methods (continued)XADataSource interface 309XAResource interface 309

minimum pool size 115Minus operator 234MinVarcharSize 179MIT Kerberos 100MongoDB data type

mapping 24mapping inconsistent types 26

MongoDB sharding 105multilingual applications

development 109

Nnaming conflicts

identifiers 89, 105with _id 90with SQL keywords 90

nestedarrays 18, 24documents 18, 24

New Native Objects window 81normalization

naming conflicts 89–90, 105normalized view

generating 63normalizing

arrays 18collections 17complex types 18documents 18

numeric literals 239

Oobject

Connectionmanaging connections 336transaction model 337

DataSourcecalling in an application 39, 48retrieving 39, 48

Long (DB2) 295PooledConnectionDataSource

connecting with 116PreparedStatement

using Statement object instead of 332ResultSet

database metadata 328generating 328updating data 337

Statementusing instead of PreparedStatement object 332using multiple 336

object (continued)using addBatch() instead of PreparedStatement 333

objectsmapping to tables 16

objects, removing 84operators

arithmetic 240comparison 241concatenation 240logical 242precedence 242

Order By clause 234out-of-memory errors

troubleshooting 215outer join escape sequence, example 251Outer Join Escape Sequences 229

Pparameter markers, using as arguments to storedprocedures 332parameter metadata

returning 108returning with DataDirect Test 147

ParameterMetaData interface, methods 286Password (connection property) 194performance considerations 96performance optimization

auto generated keys, retrieving 335batches, using instead of prepared statements 333commits, managing 336connection

management 336pooling 336

database metadata methods 328designing JDBC applications 335get methods, using effectively 334getBestRowIdentifier() 337result sets, retrieving 331retrieving long data 330scrollable cursors 331selecting JDBC objects and methods 332transaction model, choosing 337update methods of the ResultSet object 337updating data 337

PooledConnection interface, methods 287PooledConnectionDataSource

interface 119PooledConnectionDataSource object

connecting with 116creating 112, 114, 119

PooledConnectionDataSourceFactoryinterface 119

poolEntries() method 124PortNumber 195


Index

predicateEXISTS 245IN 245UNIQUE 245

prepared statement pooling, performance optimization336prepared statement, executing with DataDirect Test 138prepared statements

using batches instead of 333PreparedStatement interface, methods 287PreparedStatement object

performanceimplications of using Statement object instead332of prepared statement pool 336

prepared statement pooling 336using Statement object instead of 332

product requirementsKerberos authentication 103

properties file for Java logging 218

Rread uncommitted

isolation level 109Reader object, DataDirect Spy 166ReadOnly 196ReadPreference 197Ref interface, methods 292Reference object

creating PooledConnectionDataSource object 119Refresh Map (EXT) 223registering MBean name 127RegisterStatementPoolMonitorMBean 198relational mapping

connection properties 91overview 16

relational viewresetting 90

Reload Map (EXT) 224requirements

Java SE 15JSR 114 Rowsets 15SSL 15

Restart the Wizard 90result sets

deleting rows with DataDirect Test 151inserting rows with DataDirect Test 151scrolling through a result set with DataDirect Test143updating rows with DataDirect Test 151

result sets, scrollableperformance optimization 331

ResultMemorySize 198, 215ResultSet interface, methods 292

ResultSet objectdatabase metadata 328generating 328updating data 337

ResultSetMetaData interface, methods 303RowSet interface, methods 304

Ssample size

column information and statistics 74SavePoint interface, methods 304savepoints

establishing with DataDirect Test 148scalar functions 250schema

customizing 67, 70flattening 63, 65normalizing 63Table Wizard 63views 63

Schema Toolextracting a new table 82functionality 11mapping objects 76starting 49, 55table wizard 11

SchemaFilter (configuration option 180SchemaMap 200schemas

mapping 76search patterns, avoiding 329security

SSL 93Select clause 226Select statement

executing with DataDirect Test 137selects

parameter metadata 108sensitive cursors

performance implications 334server authentication

configuring 98server-side RPCs 332ServicePrincipalName 201setEnableLogging() 208sharding 105SpyAttributes

connection property 202SQL

expressions 237functionality 11

SQL engine logger 217SQL escape sequences

date, time, and timestamp 250LIKE escape character for wildcards 252


Index

SQL escape sequences (continued)outer join 251scalar functions 250

SQL statement support 221SQL statements

Insert 222Update 236

SQLExceptionsreporting 109

SSLCertificate Authority (CA) 98client authentication 97, 99configuring 97data encryption properties 93keystore 99requirements 15server authentication 97–98truststore 98

Statement interface, methods 304Statement object

Connection object association 336using instead of PreparedStatement object 332using multiple 336when to use 332

statement poolclearing statements 129export file, generating 129freezing and unfreezing 129importing statements to 128

statement pool export fileexample 215generating 215

Statement Pool Monitoraccessing with DataDirect-specific methods 124classes and interfaces 130poolEntries() method 124

statement poolingconnection properties 94ImportStatementPool 188MaxPooledStatements 193registering JMX MBean 198RegisterStatementPoolMonitorMBean 198statement pool export file 215troubleshooting problems 214

StatementEventListener interface, methods 308stored procedures

parameter markers as arguments, using 332Struct interface, methods 309subdocuments

mapping 18, 24subqueries

correlated 246overview 244

subquery in a From clause 230support

online help 31, 218

support (continued)technical support 31, 218

Ttable information 71Table Wizard

about 63custom view 67flattened view 65normalized view 63

tablesremote/local 109views 109

Technical Support 31, 218testing a connection

instructions 35, 44time literal

escape sequence 250timestamp literal

escape sequence 250tracing, enabling for Pool Manager 118TransactionMode 203transactions , See JTA supporttroubleshooting

connection pooling problems 210statement pooling problems 214your application 207

truststoreSSL 98

TrustStore 203TrustStorePassword 204

Uunary operator 240understanding the maximum pool size 116unfreezing the statement pool 129Unicode support 109Union operator 232UNIQUE predicate 245UNIX CLASSPATH, setting 34, 43updatable result sets, DataDirect Test 151Update statement 236Updates

parameter metadata 108updating rows

with DataDirect Test 157UppercaseIdentifiers 89, 105, 181URL

connecting with 34, 42specifying connection 34, 43

User 205user ID/password authentication

configuring 100


Index

usingJMX API 127

UTF-16conversion 109encoding 109

VValidateServerCertificate 206Version string information

format 16views and remote/local tables

overview 109

WWhat's new? 12Where clause 230Windows Active Directory Kerberos 100Windows CLASSPATH, setting 34, 43wrapper methods

to access JDBC Extensions 312

XXAConnection interface, methods 309XADataSource interface, methods 309XAResource interface, methods 309


Index


Index

Documents

Progress® DataDirect® for JDBC™ for MongoDB™ Driver User's ...€¦ · • The driver has been enhanced to suppor t the native Decimal128 data type, which maps to the Decimal