Progress DataDirect for

Transcription

1 Progress DataDirect for JDBC for Apache Cassandra User's Guide Release

2

3 Copyright 2018 Progress Software Corporation and/or its subsidiaries or affiliates. All rights reserved. These materials and all Progress software products are copyrighted and all rights are reserved by Progress Software Corporation. The information in these materials is subject to change without notice, and Progress Software Corporation assumes no responsibility for any errors that may appear therein. The references in these materials to specific platforms supported are subject to change. Corticon, DataDirect (and design), DataDirect Cloud, DataDirect Connect, DataDirect Connect64, DataDirect XML Converters, DataDirect XQuery, DataRPM, Deliver More Than Expected, Icenium, Kendo UI, NativeScript, OpenEdge, Powered by Progress, Progress, Progress Software Developers Network, Rollbase, SequeLink, Sitefinity (and Design), SpeedScript, Stylus Studio, TeamPulse, Telerik, Telerik (and Design), Test Studio, and WebSpeed are registered trademarks of Progress Software Corporation or one of its affiliates or subsidiaries in the U.S. and/or other countries. Analytics360, AppServer, BusinessEdge, DataDirect Spy, SupportLink, DevCraft, Fiddler, JustAssembly, JustDecompile, JustMock, Kinvey, NativeScript Sidekick, OpenAccess, ProDataSet, Progress Results, Progress Software, ProVision, PSE Pro, Sitefinity, SmartBrowser, SmartComponent, SmartDataBrowser, SmartDataObjects, SmartDataView, SmartDialog, SmartFolder, SmartFrame, SmartObjects, SmartPanel, SmartQuery, SmartViewer, SmartWindow, and WebClient are trademarks or service marks of Progress Software Corporation and/or its subsidiaries or affiliates in the U.S. and other countries. Java is a registered trademark of Oracle and/or its affiliates. Any other marks contained herein may be trademarks of their respective owners. Please refer to the readme applicable to the particular Progress product release for any third-party acknowledgements required to be provided in the documentation associated with the Progress product. Updated: 2018/03/28 3

4 Copyright 4

5 Contents Table of Contents Chapter 1: Welcome to the Progress DataDirect for JDBC for Apache Cassandra Driver...11 What's New in this Release?...12 Requirements...13 Driver and Data Source Classes...13 Version String Information...14 Connection Properties...14 Complex Type Normalization...15 Collection Types...15 Tuple and User-Defined Types...18 Nested Complex Types...21 Data Types...22 gettypeinfo()...24 Contacting Technical Support...32 Chapter 2: Getting started...35 Driver and Data Source Classes...35 Connecting Using the DriverManager...36 Setting the Classpath...36 Passing the Connection URL...37 Testing the Connection...37 Connecting Using Data Sources...40 How Data Sources Are Implemented...41 Creating Data Sources...41 Calling a Data Source in an Application...41 Chapter 3: Using the Driver...43 Connecting from an Application...44 Driver and Data Source Classes...44 Connecting Using the DriverManager...44 Connecting Using Data Sources...48 Using Connection Properties...50 Required Properties...50 Mapping Properties...51 Authentication Properties...51 Data Encryption Properties...52 Statement Pooling Properties

6 Contents Additional Properties...54 Performance Considerations...55 Authentication...56 Configuring User ID/Password Authentication...56 Configuring the Driver for Kerberos Authentication...57 Data Encryption...64 Configuring SSL Encryption...64 Configuring SSL Server Authentication...65 Configuring SSL Client Authentication...66 Identifiers...67 IP Addresses...67 Parameter Metadata Support...68 Insert and Update Statements...68 Select Statements...68 Isolation Levels...69 Unicode...69 Error Handling...69 Large Object (LOB) Support...70 Rowset Support...70 Executing CQL...71 Connection Pool Manager...71 How Connection Pooling Works...71 Implementing DataDirect Connection Pooling...73 Configuring the Connection Pool...76 Connecting Using a Connection Pool...77 Closing the Connection Pool...78 Checking the Pool Manager Version...79 Enabling Pool Manager Tracing...79 Connection Pool Manager Interfaces...79 Statement Pool Monitor...84 Using DataDirect-Specific Methods to Access the Statement Pool Monitor...85 Using JMX to Access the Statement Pool Monitor...87 Importing Statements into a Statement Pool...89 Clearing All Statements in a Statement Pool...89 Freezing and Unfreezing the Statement Pool...90 Generating a Statement Pool Export File...90 DataDirect Statement Pool Monitor Interfaces and Classes...90 DataDirect Test...92 DataDirect Test Tutorial...93 Tracking JDBC Calls with DataDirect Spy Enabling DataDirect Spy Chapter 4: Connection Property Descriptions AuthenticationMethod

7 Contents CreateMap EncryptionMethod FetchSize HostNameInCertificate ImportStatementPool InitializationString InsensitiveResultSetBufferSize KeyPassword KeyspaceName KeyStore KeyStorePassword LogConfigFile LoginConfigName LoginTimeout MaxPooledStatements NativeFetchSize Password PortNumber ReadConsistency ReadOnly RegisterStatementPoolMonitorMBean ResultMemorySize SchemaMap ServerName ServicePrincipalName SpyAttributes TransactionMode TrustStore TrustStorePassword User ValidateServerCertificate WriteConsistency Chapter 5: Troubleshooting Troubleshooting your application Turning On and Off DataDirect Spy Logging DataDirect Spy Log Example Troubleshooting Connection Pooling Enabling Tracing with the settracing Method Pool Manager Trace File Example Troubleshooting Statement Pooling Generating an Export File with the exportstatement Method Statement Pool Export File Example Troubleshooting Out-of-Memory Errors

8 Contents Troubleshooting Operation Timeouts Using Java logging Logging Components Configuring Logging Contacting Technical Support Chapter 6: Supported SQL Functionality Data Definition Language (DDL) Delete Insert Refresh Map (EXT) Select Select Clause Update SQL Expressions Column Names Literals Operators Functions Conditions Subqueries IN Predicate EXISTS Predicate UNIQUE Predicate Correlated Subqueries Chapter 7: SQL Escape Sequences for JDBC Date, time, and timestamp escape sequences Scalar Functions Outer Join Escape Sequences LIKE escape character sequence for wildcards Native and Refresh Escape Sequences Chapter 8: JDBC support JDBC and JVM Compatibility Supported Functionality Array Blob CallableStatement Clob Connection ConnectionEventListener ConnectionPoolDataSource

9 Contents DatabaseMetaData DataSource Driver ParameterMetaData PooledConnection PreparedStatement Ref ResultSet ResultSetMetaData RowSet SavePoint Statement StatementEventListener Struct XAConnection XADataSource XAResource Chapter 9: JDBC Extensions Using JDBC Wrapper Methods to Access JDBC Extensions DatabaseMetaData interface DDBulkLoad Interface ExtConnection Interface ExtDatabaseMetaData Interface ExtLogControl class Chapter 10: Designing JDBC Applications for Performance Optimization Using Database Metadata Methods Minimizing the Use of Database Metadata Methods Avoiding Search Patterns Using a Dummy Query to Determine Table Characteristics Returning Data Returning Long Data Reducing the Size of Returned Data Choosing the Right Data Type Retrieving Result Sets Selecting JDBC Objects and Methods Using Parameter Markers as Arguments to Stored Procedures Using the Statement Object Instead of the PreparedStatement Object Using Batches Instead of Prepared Statements Choosing the Right Cursor Using get Methods Effectively

10 Contents Retrieving Auto Generated Keys Managing Connections and Updates Managing Connections Managing Commits in Transactions Choosing the Right Transaction Model Using updatexxx Methods Using getbestrowidentifier Glossary Index

11 1 Welcome to the Progress DataDirect for JDBC for Apache Cassandra Driver The Progress DataDirect for JDBC for Apache Cassandra driver supports SQL read-write access to DataStax Enterprise 4.6 or higher and Apache Cassandra 2.0 or higher. To support SQL access to Cassandra, the driver creates a relational map of native Cassandra data and translates SQL statements to CQL. Cassandra complex data types Map, List, Set, Tuple, and user-defined types are supported alongside primitive CQL types. The driver optimizes performance when executing joins by leveraging data relationships among Cassandra objects to minimize the amount of data that needs to be fetched over the network. Relationships among objects can be reported with the metadata methods gettables(), getcolumns(), gettypeinfo(), getprimarykeys(), getexportedkeys(), and getbestrowidentifier(). For details, see the following topics: What's New in this Release? Requirements Driver and Data Source Classes Version String Information Connection Properties Complex Type Normalization Data Types Contacting Technical Support 11

12 Chapter 1: Welcome to the Progress DataDirect for JDBC for Apache Cassandra Driver What's New in this Release? Changes since Release Driver Enhancements The driver has been enhanced to support all the data consistency levels for read and write operations that are supported by Apache Cassandra data stores. Data consistency levels are configured using the ReadConsistency and WriteConsistency connection properties. For additional information, see ReadConsistency on page 149 and WriteConsistency on page 161. The driver has been enhanced to support SSL, incorporating the addition of eight new connection properties. See Data Encryption on page 64 and Data Encryption Properties on page 52 for details. The driver has been enhanced to support Kerberos authentication. See Authentication on page 56 and Authentication Properties on page 51 for details. The driver has been enhanced to support Cassandra's tunable consistency functionality with the ReadConsistency and WriteConsistency connection properties. See ReadConsistency on page 149 and WriteConsistency on page 161 for details. The driver has been enhanced to improve the handling of large result sets and reduce the likelihood of out-of-memory errors through the introduction of the FetchSize, NativeFetchSize, and ResultMemorySize connection properties. See FetchSize on page 135, NativeFetchSize on page 146, and WriteConsistency on page 161 for details. Changed Behavior The SchemaDefinition connection property has been replaced with the SchemaMap connection property. See SchemaMap on page 153 for details. Highlights of the Release Supports SQL read-write access to DataStax Enterprise 4.6 or higher and Apache Cassandra 2.0 or higher. See Supported SQL Functionality on page 177 for details. Supports JDBC core functions. See JDBC support on page 211 for details. Supports user id/password authentication. See Authentication on page 56 for details. Supports Cassandra data types, including the complex types Tuple, user-defined types, Map, List and Set. See Data Types on page 22 for details. Generates a relational view of Cassandra data. Tuple and user-defined types are flattened into a relational parent table, while collection types are mapped as relational child tables. See Complex Type Normalization on page 15 for details. Supports Native and Refresh escape sequences to embed CQL commands in SQL-92 statements. See Native and Refresh Escape Sequences on page 208 for details. Supports Cassandra's tunable consistency functionality with ReadConsistency on page 149 and WriteConsistency on page 161 connection properties. Supports the handling of large result sets with FetchSize on page 135, NativeFetchSize on page 146, and ResultMemorySize on page 151 connection properties. Includes the TransactionMode on page 157 connection property which allows you to configure the driver to report that it supports transactions, even though Cassandra does not support transactions. This provides a workaround for applications that do not operate with a driver that reports transactions are not supported. 12

13 Requirements Supports Binary Large Objects (BLOBs). See Large Object (LOB) Support on page 70 for details. Supports connection pooling. See Connection Pool Manager on page 71 for details. Supports statement pooling. See Statement Pool Monitor on page 84 for details. Includes the LoginTimeout on page 144 connection property which allows you to specify how long the driver waits for a connection to be established before timing out the connection request. Requirements The driver is compliant with JDBC 4.0 and earlier specifications. The following table lists the product requirements for using the driver. Table 1: Product Requirements For Applications Using... JDBC 4.0 API JDBC 3.0 API JSR 114 Rowsets JDBC 1.22 API Product Requirements Java SE 6 or higher Java SE 6 or higher Java SE 6 or higher Java SE 6 or higher Note: Standard installations of Java SE on some platforms do not include the jar file containing the extended encoding set that is required to support some of the less common database code pages. Check your Java SE installation to make sure that the charsets.jar is installed in the lib subdirectory of your Java SE installation directory. If you do not have the charsets.jar file, re-install Java SE, making sure that you install the international version of Java SE. Driver and Data Source Classes The driver class is: com.ddtek.jdbc.cassandra.cassandradriver Two data source classes are provided with the driver. Which data source class you use depends on the JDBC functionality your application requires. The following table shows the recommended data source class to use with different JDBC specifications. 13

14 Chapter 1: Welcome to the Progress DataDirect for JDBC for Apache Cassandra Driver Table 2: Choosing a Data Source Class If your application requires... JDBC 4.0 functionality and higher JDBC 3.x functionality and earlier specifications JVM Version Java SE 6 or higher Java SE 6 or higher Data Source Class com.ddtek.jdbcx.cassandra.cassandradatasource40 com.ddtek.jdbcx.cassandra.cassandradatasource See Connecting Using Data Sources on page 40 for information about Progress DataDirect data sources. Version String Information The 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: (C0003.F U000002) Driver Cloud Frame Utl Connection Properties The driver includes over 20 connection properties. You can use these connection properties to customize the driver for your environment. Connection properties can be 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 50 and Connection Property Descriptions on page 129 for more information. 14

15 Complex Type Normalization Complex Type Normalization To support SQL access to Apache Cassandra, the driver maps the Cassandra data model to a relational schema. This process involves the normalization of complex types. You may need to be familiar with the normalization of complex types to formulate SQL queries correctly. The driver handles the normalization of complex types in the following manner: If collection types (Map, List, and Set) are discovered, the driver normalizes the Cassandra table into a set of parent-child tables. Primitive types are mapped to a parent table, while each collection type is mapped to a child table that has a foreign key relationship to the parent table. Non-nested Tuple and user-defined types (also referred to as Usertype) are flattened into a parent table alongside primitive types. Any nested complex types (Tuple, user-defined types, Map, List, and Set) are exposed as JSON-style strings in the parent table. The normalization of complex types is described in greater detail in the following topics. Collection Types Cassandra collection types include the Map, List, and Set types. If collection types are discovered, the driver normalizes the native data into a set of parent-child tables. Primitive types are normalized in a parent table, while each collection type is normalized in a child table that has a foreign key relationship to the parent table. Take for example the following Cassandra table: CREATE TABLE employee ( empid int PRIMARY KEY, phone map<varchar, varint>, client list<varchar>, review set<date>); The following employee table is a tabular representation of the native Cassandra table with data included. In this example, four distinct relational tables are created. A parent table is created based on the empid column, and a child table is created for each of the three collection types (Map, List, and Set). Table 3: employee (native) empid phone client review (primary key) int map<varchar, varint> list<varchar> set<date> 103 home: Li mobile: Kumar office: Jones spouse: home: mobile: office: Yanev Bishop Bogdanov

16 Chapter 1: Welcome to the Progress DataDirect for JDBC for Apache Cassandra Driver The Parent Table The parent table is comprised of the primitive integer type column empid and takes its name from the native table. A SQL statement would identify the column as employee.empid. Table 4: employee (relational parent) empid (primary key) int A SQL insert on the employee parent table would take the form: INSERT INTO employee (empid) VALUES (107) The Map Child Table The Map collection is normalized into a three column child table called employee_phone. The name of the table is formulated by concatenating the name of the native table and the name of the Map column. A foreign key relationship to the parent table is maintained via the employee_empid column, and the Map's key value pairs are resolved into separate keycol and valuecol columns. In a SQL statement, these columns would be identified as the employee_phone.employee_empid, employee_phone.keycol, and employee_phone.valuecol, respectively. Table 5: employee_phone (relational child of the map column) employee_empid (foreign key) keycol valuecol int varchar varint home mobile office spouse home mobile office

17 Complex Type Normalization A SQL insert on the employee_phone child table would take the form 1 : INSERT INTO employee_phone (employee_empid, keycol, valuecol) VALUES (107, 'mobile', ) The List Child Table The List collection is normalized into a three column child table called employee_client. The name of the table is formulated by concatenating the name of the native table and the name of the List column. A foreign key relationship to the parent table is maintained via the employee_empid column; the order of the elements in the List is maintained via the current_list_index column; and the elements themselves are contained in the client column. SQL statements would identify these columns as employee_client.employee_empid, employee_client.current_list_index, and employee_client.client, respectively. Table 6: employee_client (relational child of the list column) employee_empid (foreign key) current_list_index client int int varchar Li Kumar Jones Yanev Bishop Bogdanov A SQL insert on the employee_client child table would take the form 1 : INSERT INTO employee_client (employee_empid, client) VALUES (107, 'Nelson') The Set Child Table The Set collection is normalized into a two column child table called employee_review. The name of the table is formulated by concatenating the name of the native table and the name of the Set column. A foreign key relationship to the parent table is maintained via the empid column, while the elements of the Set are given in natural order in the review column. In this child table, SQL statements would identify these columns as employee_review.employee_empid and employee_review.review 1 The driver supports an insert on a child table prior to an insert on a parent table, circumventing referential integrity constraints associated with traditional RDBMS. To maintain integrity between parent and child tables, it is recommended that an insert be performed on the parent table for each foreign key value added to the child. If such an insert is not first performed, the driver automatically inserts a row into the parent tables that contains only the primary key values and NULL values for all non-primary key columns. 17

18 Chapter 1: Welcome to the Progress DataDirect for JDBC for Apache Cassandra Driver Table 7: employee_review (relational child of the set column) employee_empid (foreign key) int review date A SQL insert on the employee_client child table would take the form 1 : INSERT INTO employee_review (employee_empid, review) VALUES (107, ' ') Update Support Update is supported for primitive types, non-nested Tuple types, and non-nested user-defined types. Update is also supported for value columns (valuecol) in non-nested Map types. The driver does not support updates on List types, Set types, or key columns (keycol) in Map types because the values in each are part of the primary key of their respective child tables and primary key columns cannot be updated. If an Update is attempted when not allowed, the driver issues the following error message: [DataDirect][Cassandra JDBC Driver][Cassandra]syntax error or access rule violation: UPDATE not permitted for column: column_name Tuple and User-Defined Types The driver supports Tuple and user-defined complex types which were introduced with Apache Cassandra 2.1. As long as there are no complex types nested in either the Tuple or user-defined types, the driver normalizes Tuple and user-defined types by flattening them into a relational version of the native Cassandra table. Take for example the following Cassandra table: CREATE TABLE agents1 ( agentid int PRIMARY KEY, varchar, contact tuple<varchar,varchar,varchar>); The following agents1 table is a tabular representation of the native Cassandra table with data included. 18

19 Complex Type Normalization Table 8: agents1 (native) agentid (primary key) contact 272 int varchar tuple<varchar, varchar, varchar> tv newspaper blog 564 radio tv magazine For the relational version of agents1, all fields are retained as separate columns, and columns with primitive types (agentid and ) correspond directly to columns in the native table. In turn, tuple fields are flattened into columns using a <tuplename>_<ordinal> naming pattern. The driver normalizes agents1 in the following manner. Table 9: agents1 (relational) agentid contact_1 contact_2 contact_3 (primary key) int varchar varchar varchar varchar 272 barronr@ .com tv newspaper blog 564 rothm@ .com radio tv magazine A SQL command would take the following form: INSERT INTO agents1 (agentid, ,contact_1,contact_2,contact_3) VALUES (839,'gonzalesn@ .com','radio','tv','magazine') The driver also flattens user-defined types when normalizing native Cassandra tables. In the following example, the native Cassandra agents2 table incorporates the user-defined address type. CREATE TYPE address ( street varchar, city varchar, state varchar, zip int); CREATE TABLE agents2 ( agentid int PRIMARY KEY, varchar, location frozen<address>); The following agents2 table is a tabular representation of the native Cassandra table with data included. 19

20 Chapter 1: Welcome to the Progress DataDirect for JDBC for Apache Cassandra Driver Table 10: agents2 (native) agentid (primary key) location int varchar address<street: varchar, city: varchar, state: varchar, zip: int> 095 street: 1551 Main Street city: Pittsburgh state: PA zip: street: 422 First Street city: Richmond state: VA zip: As with the previous example, all fields are retained as separate columns in the relational version of the table, and columns with primitive types (agentid and ) correspond directly to columns in the native table. Here a <columnname>_<fieldname> naming pattern is used to flatten the fields of the user-defined address type into columns. The driver normalizes agents2 in the following manner. Table 11: agents2 (native) agentid location_street location_city location_state location_zip (primary key) int varchar varchar varchar varchar int 095 barronr@ .com 1551 Main Street Pittsburgh PA rothm@ .com 422 First Street Richmond VA A SQL command would take the following form: INSERT INTO agents2 (agentid, ,location_street,location_city,location_state,location_zip) VALUES (839,'gonzalesn@ .com','9 Fifth Street', 'Morrisville', 'NC', 27566) 20

21 Complex Type Normalization Nested Complex Types The nesting of complex types within Tuple and user-defined types is permitted in CQL. The driver does not normalize such nested types, but rather the data is passed as a JSON-style string. For example, consider the table contacts which contains the columns id and contact. While id is a primitive int column, contact is a user-defined info column which contains name, , and location fields. The location field itself is a nested user-defined address column which contains street, city, state, and zip fields. In CQL, the structure of this table would take the following form: CREATE TYPE address ( street varchar, city varchar, state varchar, zip int); CREATE TYPE info ( name varchar, varchar, location frozen<address>); CREATE TABLE contacts ( id int PRIMARY KEY, contact frozen<info>); The following tabular representation of the contacts table shows how the driver returns data when complex types are nested in other complex types. Because the complex user-defined type address is embedded in the complex user-defined type info, the entire contact column is returned by the driver as a JSON string. Note: You can retrieve this string data by calling the DatabaseMetaData.getColumns() method. Table 12: contacts (relational) id (primary key) int contact info<name: varchar, varchar, location: address<street: varchar, city: varchar, state: varchar, zip: int>> {name: 'Jude', 'jnichols@ .com', location: {street: '101 Main Street', city: 'Albany', state:'ny', zip: 12210}} {name: 'Karen', 'kbrown@ .com', location: {street: '150 First Street', city: 'Portland', state: 'OR', zip: 97214}} When executing SQL commands involving nested complex types, the data must be passed as a JSON string. Furthermore, the syntax you use to connote the JSON string depends on whether you are passing the string directly in a SQL command or setting the JSON string as a parameter on a prepared statement. Note: Hints for parsing JSON-style strings are provided in the Remark column of the getcolumns() result. 21

22 Chapter 1: Welcome to the Progress DataDirect for JDBC for Apache Cassandra Driver Connoting the JSON-Style String in a SQL Statement When passing the string directly in a SQL command, you must use the correct SQL syntax and escapes to maintain the structure of the data. To begin, the entire JSON string must be passed in single quotation marks ('). Furthermore, if the JSON string contains nested strings, two single quotation marks are used to indicate string values. The first quotation mark is an escape connoting the second embedded quotation mark. The following command inserts a new row into the contacts table. Note: In accordance with Java syntax, the Insert statement is placed in double quotation marks. However, in the JSON string, two single quotation marks are used to indicate string values. The first quotation mark is an escape connoting the second embedded quotation mark. Stmt.executeUpdate( "INSERT INTO contacts (id, contact) VALUES (075, '{name: ''Albert'', " + " ''aocampo@ .com'', location: {street: ''12 North Street'', " + "city: ''Durham'', state:''nc'', zip: 27704}}')"); After the insert has been executed, the Select command SELECT contact FROM contacts WHERE id = 75 returns: {name: 'Albert', 'aocampo@ .com', location: {street: '12 North Street', city: 'Durham', state:'nc', zip: } } Connoting the JSON-Style String as a Parameter Value on a Prepared Statement When setting the JSON string as a parameter value, you must follow Java syntax by placing the JSON string in double quotation marks. Escapes are not used to connote embedded single quotation marks. For example: pstmt.setstring( 2, "{name: 'Albert', 'aocampo@ .com', location: " + "{street: '12 North Street', city: 'Durham', state:'nc', " + "zip: 27704}}") Data Types The following table lists the Cassandra data types supported by the driver and how they are mapped to JDBC data types. The complex types List, Map, Set, Tuple, and user-defined types have no direct JDBC mapping. However, the driver normalizes these types to provide SQL access to Cassandra. For details on how complex types are mapped, see "Complex Type Normalization." See "gettypeinfo()" for gettypeinfo() results of data types supported by the driver. Table 13: Data Type Mapping Apache Cassandra JDBC ASCII VARCHAR 22

23 Data Types Apache Cassandra JDBC BIGINT BLOB BOOLEAN COUNTER 2 DATE 3 DECIMAL DOUBLE FLOAT INET INT LIST 4 MAP 4 SET 4 SMALLINT 3 TIME 3 TIMESTAMP TIMEUUID TINYINT 3 TUPLE 4 USERTYPE 5 UUID VARCHAR VARINT BIGINT LONGVARBINARY BOOLEAN BIGINT DATE DECIMAL DOUBLE REAL VARCHAR INTEGER LONGVARCHAR LONGVARCHAR LONGVARCHAR SMALLINT TIME TIMESTAMP CHAR TINYINT LONGVARCHAR LONGVARCHAR CHAR VARCHAR DECIMAL 2 Update is supported for Counter columns when all the other columns in the row comprise that row s primary key. See Update on page 191 for details. 3 Supported for Apache Cassandra 2.2 and higher. 4 See Complex Type Normalization on page 15 for details on how complex types are mapped. 5 Also referred to as user-defined types. These are data types created with the CQL CREATE TYPE statement. See Complex Type Normalization on page 15 for details on how Usertype is mapped. 23

24 Chapter 1: Welcome to the Progress DataDirect for JDBC for Apache Cassandra Driver See also Complex Type Normalization on page 15 gettypeinfo() The DatabaseMetaData.getTypeInfo() method returns information about data types. The following table provides gettypeinfo() results for supported Apache Cassandra data types. Table 14: gettypeinfo() TYPE_NAME = ascii AUTO_INCREMENT = NULL CASE_SENSITIVE = true CREATE_PARAMS = NULL DATA_TYPE = 12 (VARCHAR) FIXED_PREC_SCALE = false LITERAL_PREFIX = ' LITERAL_SUFFIX = ' LOCAL_TYPE_NAME = ascii MAXIMUM_SCALE = NULL MINIMUM_SCALE = NULL NULLABLE = 1 NUM_PREC_RADIX = NULL PRECISION = SEARCHABLE = 3 SQL_DATA_TYPE = NULL SQL_DATETIME_SUB = NULL UNSIGNED_ATTRIBUTE = NULL TYPE_NAME = bigint AUTO_INCREMENT = false CASE_SENSITIVE = false CREATE_PARAMS = NULL DATA_TYPE = -5 (BIGINT) FIXED_PREC_SCALE = false LITERAL_PREFIX = NULL LITERAL_SUFFIX = NULL LOCAL_TYPE_NAME = bigint MAXIMUM_SCALE = 0 MINIMUM_SCALE = 0 NULLABLE = 1 NUM_PREC_RADIX = 10 PRECISION = 19 SEARCHABLE = 3 SQL_DATA_TYPE = NULL SQL_DATETIME_SUB = NULL UNSIGNED_ATTRIBUTE = false 24

25 Data Types TYPE_NAME = blob AUTO_INCREMENT = NULL CASE_SENSITIVE = false CREATE_PARAMS = NULL DATA_TYPE = -4 (LONGVARBINARY) FIXED_PREC_SCALE = false LITERAL_PREFIX = X' LITERAL_SUFFIX = ' LOCAL_TYPE_NAME = blob MAXIMUM_SCALE = NULL MINIMUM_SCALE = NULL NULLABLE = 1 NUM_PREC_RADIX = NULL PRECISION = SEARCHABLE = 2 SQL_DATA_TYPE = NULL SQL_DATETIME_SUB = NULL UNSIGNED_ATTRIBUTE = NULL TYPE_NAME = boolean AUTO_INCREMENT = NULL CASE_SENSITIVE = false CREATE_PARAMS = NULL DATA_TYPE = 16 (BOOLEAN) FIXED_PREC_SCALE = false LITERAL_PREFIX = NULL LITERAL_SUFFIX = NULL LOCAL_TYPE_NAME = boolean MAXIMUM_SCALE = NULL MINIMUM_SCALE = NULL NULLABLE = 1 NUM_PREC_RADIX = NULL PRECISION = 1 SEARCHABLE = 2 SQL_DATA_TYPE = NULL SQL_DATETIME_SUB = NULL UNSIGNED_ATTRIBUTE = NULL TYPE_NAME = counter 6 AUTO_INCREMENT = false CASE_SENSITIVE = false CREATE_PARAMS = NULL DATA_TYPE = -5 (BIGINT) FIXED_PREC_SCALE = false LITERAL_PREFIX = NULL LITERAL_SUFFIX = NULL LOCAL_TYPE_NAME = counter MAXIMUM_SCALE = 0 MINIMUM_SCALE = 0 NULLABLE = 1 NUM_PREC_RADIX = 10 PRECISION = 19 SEARCHABLE = 3 SQL_DATA_TYPE = NULL SQL_DATETIME_SUB = NULL UNSIGNED_ATTRIBUTE = false 6 Update is supported for Counter columns when all the other columns in the row comprise that row s primary key. See Update on page 191 for details. 25

26 Chapter 1: Welcome to the Progress DataDirect for JDBC for Apache Cassandra Driver TYPE_NAME = date 7 AUTO_INCREMENT = NULL CASE_SENSITIVE = false CREATE_PARAMS = NULL DATA_TYPE = 91 (DATE) FIXED_PREC_SCALE = false LITERAL_PREFIX = date' LITERAL_SUFFIX = ' LOCAL_TYPE_NAME = date MAXIMUM_SCALE = 0 MINIMUM_SCALE = 0 NULLABLE = 1 NUM_PREC_RADIX = NULL PRECISION = 10 SEARCHABLE = 3 SQL_DATA_TYPE = NULL SQL_DATETIME_SUB = NULL UNSIGNED_ATTRIBUTE = NULL TYPE_NAME = decimal AUTO_INCREMENT = false CASE_SENSITIVE = false CREATE_PARAMS = NULL DATA_TYPE = 3 (DECIMAL) FIXED_PREC_SCALE = false LITERAL_PREFIX = NULL LITERAL_SUFFIX = NULL LOCAL_TYPE_NAME = decimal MAXIMUM_SCALE = 100 MINIMUM_SCALE = 0 NULLABLE = 1 NUM_PREC_RADIX = 10 PRECISION = 38 SEARCHABLE = 3 SQL_DATA_TYPE = NULL SQL_DATETIME_SUB = NULL UNSIGNED_ATTRIBUTE = false TYPE_NAME = double AUTO_INCREMENT = false CASE_SENSITIVE = false CREATE_PARAMS = NULL DATA_TYPE = 8 (DOUBLE) FIXED_PREC_SCALE = false LITERAL_PREFIX = ' LITERAL_SUFFIX = ' LOCAL_TYPE_NAME = double MAXIMUM_SCALE = 0 MINIMUM_SCALE = 0 NULLABLE = 1 NUM_PREC_RADIX = 10 PRECISION = 15 SEARCHABLE = 3 SQL_DATA_TYPE = NULL SQL_DATETIME_SUB = NULL UNSIGNED_ATTRIBUTE = false 7 Supported for Apache Cassandra 2.2 and higher. 26

27 Data Types TYPE_NAME = float AUTO_INCREMENT = false CASE_SENSITIVE = false CREATE_PARAMS = NULL DATA_TYPE = 7 (REAL) FIXED_PREC_SCALE = false LITERAL_PREFIX = NULL LITERAL_SUFFIX = NULL LOCAL_TYPE_NAME = float MAXIMUM_SCALE = 0 MINIMUM_SCALE = 0 NULLABLE = 1 NUM_PREC_RADIX = 10 PRECISION = 7 SEARCHABLE = 3 SQL_DATA_TYPE = NULL SQL_DATETIME_SUB = NULL UNSIGNED_ATTRIBUTE = false TYPE_NAME = inet AUTO_INCREMENT = NULL CASE_SENSITIVE = false CREATE_PARAMS = NULL DATA_TYPE = 12 (VARCHAR) FIXED_PREC_SCALE = false LITERAL_PREFIX = ' LITERAL_SUFFIX = ' LOCAL_TYPE_NAME = inet MAXIMUM_SCALE = NULL MINIMUM_SCALE = NULL NULLABLE = 1 NUM_PREC_RADIX = NULL PRECISION = 39 SEARCHABLE = 3 SQL_DATA_TYPE = NULL SQL_DATETIME_SUB = NULL UNSIGNED_ATTRIBUTE = NULL TYPE_NAME = int AUTO_INCREMENT = false CASE_SENSITIVE = false CREATE_PARAMS = NULL DATA_TYPE = 4 (INTEGER) FIXED_PREC_SCALE = false LITERAL_PREFIX = NULL LITERAL_SUFFIX = NULL LOCAL_TYPE_NAME = int MAXIMUM_SCALE = 0 MINIMUM_SCALE = 0 NULLABLE = 1 NUM_PREC_RADIX = 10 PRECISION = 10 SEARCHABLE = 3 SQL_DATA_TYPE = NULL SQL_DATETIME_SUB = NULL UNSIGNED_ATTRIBUTE = false 27

28 Chapter 1: Welcome to the Progress DataDirect for JDBC for Apache Cassandra Driver TYPE_NAME = list 8 AUTO_INCREMENT = NULL CASE_SENSITIVE = false CREATE_PARAMS = NULL DATA_TYPE = -1 (LONGVARCHAR) FIXED_PREC_SCALE = false LITERAL_PREFIX = ' LITERAL_SUFFIX = ' LOCAL_TYPE_NAME = list MAXIMUM_SCALE = NULL MINIMUM_SCALE = NULL NULLABLE = 1 NUM_PREC_RADIX = NULL PRECISION = SEARCHABLE = 0 SQL_DATA_TYPE = NULL SQL_DATETIME_SUB = NULL UNSIGNED_ATTRIBUTE = NULL TYPE_NAME = map 8 AUTO_INCREMENT = NULL CASE_SENSITIVE = false CREATE_PARAMS = NULL DATA_TYPE = -1 (LONGVARCHAR) FIXED_PREC_SCALE = false LITERAL_PREFIX = ' LITERAL_SUFFIX = ' LOCAL_TYPE_NAME = map MAXIMUM_SCALE = NULL MINIMUM_SCALE = NULL NULLABLE = 1 NUM_PREC_RADIX = NULL PRECISION = SEARCHABLE = 0 SQL_DATA_TYPE = NULL SQL_DATETIME_SUB = NULL UNSIGNED_ATTRIBUTE = NULL TYPE_NAME = set 8 AUTO_INCREMENT = NULL CASE_SENSITIVE = false CREATE_PARAMS = NULL DATA_TYPE = -1 (LONGVARCHAR) FIXED_PREC_SCALE = false LITERAL_PREFIX = ' LITERAL_SUFFIX = ' LOCAL_TYPE_NAME = set MAXIMUM_SCALE = NULL MINIMUM_SCALE = NULL NULLABLE = 1 NUM_PREC_RADIX = NULL PRECISION = SEARCHABLE = 0 SQL_DATA_TYPE = NULL SQL_DATETIME_SUB = NULL UNSIGNED_ATTRIBUTE = NULL 8 See Complex Type Normalization on page 15 for details on how complex types are mapped. 28

29 Data Types TYPE_NAME = smallint 7 AUTO_INCREMENT = false CASE_SENSITIVE = false CREATE_PARAMS = NULL DATA_TYPE = 5 (SMALLINT) FIXED_PREC_SCALE = false LITERAL_PREFIX = NULL LITERAL_SUFFIX = NULL LOCAL_TYPE_NAME = smallint MAXIMUM_SCALE = 0 MINIMUM_SCALE = 0 NULLABLE = 1 NUM_PREC_RADIX = 10 PRECISION = 5 SEARCHABLE = 3 SQL_DATA_TYPE = NULL SQL_DATETIME_SUB = NULL UNSIGNED_ATTRIBUTE = false TYPE_NAME = time 7 AUTO_INCREMENT = NULL CASE_SENSITIVE = false CREATE_PARAMS = NULL DATA_TYPE = 92 (TIME) FIXED_PREC_SCALE = false LITERAL_PREFIX = time' LITERAL_SUFFIX = ' LOCAL_TYPE_NAME = time MAXIMUM_SCALE = 9 MINIMUM_SCALE = 0 NULLABLE = 1 NUM_PREC_RADIX = NULL PRECISION = 18 SEARCHABLE = 3 SQL_DATA_TYPE = NULL SQL_DATETIME_SUB = NULL UNSIGNED_ATTRIBUTE = NULL TYPE_NAME = timestamp AUTO_INCREMENT = NULL CASE_SENSITIVE = false CREATE_PARAMS = NULL DATA_TYPE = 93 (TIMESTAMP) FIXED_PREC_SCALE = false LITERAL_PREFIX = timestamp' LITERAL_SUFFIX = ' LOCAL_TYPE_NAME = timestamp MAXIMUM_SCALE = 3 MINIMUM_SCALE = 0 NULLABLE = 1 NUM_PREC_RADIX = NULL PRECISION = 23 SEARCHABLE = 3 SQL_DATA_TYPE = NULL SQL_DATETIME_SUB = NULL UNSIGNED_ATTRIBUTE = NULL 29

30 Chapter 1: Welcome to the Progress DataDirect for JDBC for Apache Cassandra Driver TYPE_NAME = timeuuid AUTO_INCREMENT = NULL CASE_SENSITIVE = false CREATE_PARAMS = NULL DATA_TYPE = 1 (CHAR) FIXED_PREC_SCALE = false LITERAL_PREFIX = ' LITERAL_SUFFIX = ' LOCAL_TYPE_NAME = timeuuid MAXIMUM_SCALE = NULL MINIMUM_SCALE = NULL NULLABLE = 1 NUM_PREC_RADIX = NULL PRECISION = 36 SEARCHABLE = 3 SQL_DATA_TYPE = NULL SQL_DATETIME_SUB = NULL UNSIGNED_ATTRIBUTE = NULL TYPE_NAME = tinyint 7 AUTO_INCREMENT = false CASE_SENSITIVE = false CREATE_PARAMS = NULL DATA_TYPE = -6 (TINYINT) FIXED_PREC_SCALE = false LITERAL_PREFIX = NULL LITERAL_SUFFIX = NULL LOCAL_TYPE_NAME = tinyint MAXIMUM_SCALE = 0 MINIMUM_SCALE = 0 NULLABLE = 1 NUM_PREC_RADIX = 10 PRECISION = 3 SEARCHABLE = 3 SQL_DATA_TYPE = NULL SQL_DATETIME_SUB = NULL UNSIGNED_ATTRIBUTE = false TYPE_NAME = tuple 8 AUTO_INCREMENT = NULL CASE_SENSITIVE = false CREATE_PARAMS = NULL DATA_TYPE = -1 (LONGVARCHAR) FIXED_PREC_SCALE = false LITERAL_PREFIX = ' LITERAL_SUFFIX = ' LOCAL_TYPE_NAME = tuple MAXIMUM_SCALE = NULL MINIMUM_SCALE = NULL NULLABLE = 1 NUM_PREC_RADIX = NULL PRECISION = SEARCHABLE = 0 SQL_DATA_TYPE = NULL SQL_DATETIME_SUB = NULL UNSIGNED_ATTRIBUTE = NULL 30

31 Data Types TYPE_NAME = usertype 9 AUTO_INCREMENT = NULL CASE_SENSITIVE = false CREATE_PARAMS = NULL DATA_TYPE = -1 (LONGVARCHAR) FIXED_PREC_SCALE = false LITERAL_PREFIX = ' LITERAL_SUFFIX = ' LOCAL_TYPE_NAME = usertype MAXIMUM_SCALE = NULL MINIMUM_SCALE = NULL NULLABLE = 1 NUM_PREC_RADIX = NULL PRECISION = SEARCHABLE = 0 SQL_DATA_TYPE = NULL SQL_DATETIME_SUB = NULL UNSIGNED_ATTRIBUTE = NULL TYPE_NAME = uuid AUTO_INCREMENT = NULL CASE_SENSITIVE = false CREATE_PARAMS = NULL DATA_TYPE = 1 (CHAR) FIXED_PREC_SCALE = false LITERAL_PREFIX = ' LITERAL_SUFFIX = ' LOCAL_TYPE_NAME = uuid MAXIMUM_SCALE = NULL MINIMUM_SCALE = NULL NULLABLE = 1 NUM_PREC_RADIX = NULL PRECISION = 36 SEARCHABLE = 3 SQL_DATA_TYPE = NULL SQL_DATETIME_SUB = NULL UNSIGNED_ATTRIBUTE = NULL 9 Also referred to as user-defined types. These are data types created with the CQL CREATE TYPE statement. See Complex Type Normalization on page 15 for details on how Usertype is mapped. 31

32 Chapter 1: Welcome to the Progress DataDirect for JDBC for Apache Cassandra Driver TYPE_NAME = varchar AUTO_INCREMENT = NULL CASE_SENSITIVE = true CREATE_PARAMS = NULL DATA_TYPE = 12 (VARCHAR) FIXED_PREC_SCALE = false LITERAL_PREFIX = ' LITERAL_SUFFIX = ' LOCAL_TYPE_NAME = varchar MAXIMUM_SCALE = NULL MINIMUM_SCALE = NULL NULLABLE = 1 NUM_PREC_RADIX = NULL PRECISION = SEARCHABLE = 3 SQL_DATA_TYPE = NULL SQL_DATETIME_SUB = NULL UNSIGNED_ATTRIBUTE = NULL TYPE_NAME = varint AUTO_INCREMENT = false CASE_SENSITIVE = false CREATE_PARAMS = NULL DATA_TYPE = 3 (DECIMAL) FIXED_PREC_SCALE = false LITERAL_PREFIX = NULL LITERAL_SUFFIX = NULL LOCAL_TYPE_NAME = varint MAXIMUM_SCALE = 0 MINIMUM_SCALE = 0 NULLABLE = 1 NUM_PREC_RADIX = 10 PRECISION = 100 SEARCHABLE = 3 SQL_DATA_TYPE = NULL SQL_DATETIME_SUB = NULL UNSIGNED_ATTRIBUTE = false Contacting Technical Support Progress DataDirect offers a variety of options to meet your support needs. Please visit our Web site for more details 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 bulletins and 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 a case number if you have been provided one for your issue. If you do not have a SupportLink contract, the SupportLink representative assisting you will connect you with our Sales team. Your name, phone number, address, and organization. For a first-time call, you may be asked for full information, including location. 32

33 Contacting Technical Support 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 understand the problem. A brief description of the problem, including, but not limited to, any error messages you have received, what steps you followed prior to the initial occurrence of the problem, any trace logs capturing the issue, and so on. Depending on the complexity of the problem, you may be asked to submit an example or reproducible application 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 Web search engines, our Knowledgebase, or have tested additional configurations, applications, or other vendor products, 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. 33

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

35 2 Getting started After the driver has been installed and defined on your class path, you can connect from your application to your database in either of the following ways. Using the JDBC DriverManager, by specifying the connection URL in the DriverManager.getConnection() method. Creating a JDBC DataSource that can be accessed through the Java Naming Directory Interface (JNDI). For details, see the following topics: Driver and Data Source Classes Connecting Using the DriverManager Connecting Using Data Sources Driver and Data Source Classes The driver class is: com.ddtek.jdbc.cassandra.cassandradriver Two data source classes are provided with the driver. Which data source class you use depends on the JDBC functionality your application requires. The following table shows the recommended data source class to use with different JDBC specifications. 35

36 Chapter 2: Getting started Table 15: Choosing a Data Source Class If your application requires... JDBC 4.0 functionality and higher JDBC 3.x functionality and earlier specifications JVM Version Java SE 6 or higher Java SE 6 or higher Data Source Class com.ddtek.jdbcx.cassandra.cassandradatasource40 com.ddtek.jdbcx.cassandra.cassandradatasource See Connecting Using Data Sources on page 40 for information about Progress DataDirect data sources. Connecting Using the DriverManager One way to connect to a Cassandra keyspace is through the JDBC DriverManager using the DriverManager.getConnection() method. As the following example shows, this method specifies a string containing a connection URL. Connection conn = DriverManager.getConnection ("jdbc:datadirect:cassandra://myserver:9042;keyspacename=myks"); Note: A Cassandra keyspace is equivalent to a relational database. Setting the Classpath The driver must be defined on your CLASSPATH before you can connect. The CLASSPATH is the search string your Java Virtual Machine (JVM) uses to locate JDBC drivers on your computer. If the driver is not defined on your CLASSPATH, you will receive a class not found exception when trying to load the driver. Set your system CLASSPATH to include the cassandra.jar file as shown, where install_dir is the path to your product installation directory. install_dir/lib/cassandra.jar Windows Example CLASSPATH=.;C:\Program Files\Progress\DataDirect\JDBC_60\lib\cassandra.jar UNIX Example CLASSPATH=.:/opt/Progress/DataDirect/JDBC_60/lib/cassandra.jar 36

37 Connecting Using the DriverManager Passing the Connection URL After setting the CLASSPATH, the required connection information needs to be passed in the form of a connection URL. The connection URL takes the form: jdbc:datadirect:cassandra://server:port; KeyspaceName=keyspace;[property=value[;...]] where: server port specifies the name or the IP address of the server to which you want to connect. specifies the port of the server that is listening for connections to the Cassandra keyspace. The default is keyspace specifies the default name of the Cassandra keyspace to which the driver connects. This value is used as the default qualifier for unqualified table names in SQL queries. Note that a Cassandra keyspace is equivalent to a relational database. property=value specifies connection property settings. Multiple properties are separated by a semi-colon. For more information on connection properties, see Using Connection Properties on page 50. This example shows how to establish a connection to a Cassandra data store: Connection conn = DriverManager.getConnection ("jdbc:datadirect:cassandra://myserver:9042;keyspacename=myks"); Testing the Connection You can also use DataDirect Test to establish and test a DriverManager connection. The screen shots in this 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) 37

38 Chapter 2: Getting started The Test for JDBC Tool window appears: 3. Click Press Here to Continue. The main dialog appears: 38

39 Connecting Using the DriverManager 4. From the menu bar, select Connection > Connect to DB. The Select A Database dialog appears: 5. Select the appropriate database template from the Defined Databases field. 6. In the Database field, specify the ServerName, PortNumber, and KeyspaceName for your Apache Cassandra data store. For example: jdbc:datadirect:cassandra://myserver:9042;keyspacename=myks 39

40 Chapter 2: Getting started 7. If you are using user ID/password authentication, enter your user ID and password in the corresponding fields. Attention: User ID/password authentication is not supported for the preview version of the driver. 8. Click Connect. If the connection information is entered correctly, the JDBC/Database Output window reports that a connection has been established. (If a connection is not established, the window reports an error.) For more information about using DataDirect Test, see DataDirect Test on page 92. Connecting Using Data Sources A JDBC data source is a Java object, specifically a DataSource object, that defines connection information required for a JDBC driver to connect to the database. Each JDBC driver vendor provides their own data source implementation for this purpose. A Progress DataDirect data source is Progress DataDirect s implementation of a DataSource object that provides the connection information needed for the driver to connect to a database. 40

41 Connecting Using Data Sources Because data sources work with the Java Naming Directory Interface (JNDI) naming service, data sources can be created and managed separately from the applications that use them. Because the connection information is defined outside of the application, the effort to reconfigure your infrastructure when a change is made is minimized. For example, if the database is moved to another database server, the administrator need only change the relevant properties of the DataSource object. The applications using the database do not need to 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 following interfaces. javax.sql.datasource javax.sql.connectionpooldatasource (allows applications to use connection pooling) See also Driver and Data Source Classes on page 13 Connection Pool Manager on page 71 Creating Data Sources The following example files provide details on creating and using Progress DataDirect data sources with the Java 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 source and 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 JDBC data source and save it in your local file system using the File System JNDI Provider. See "Example Data Source" for an example data source definition for the example files. To connect using a JNDI data source, the driver needs to access a JNDI data store to persist the data source information. For a JNDI file system implementation, you must download the File System Service Provider from the 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 not required for LDAP implementations because the LDAP Service Provider has been included with Java SE since Java 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 the javax.sql.datasource object. This object loads the specified driver and can be used to establish a connection to the database. Once the data source has been registered with JNDI, it can be used by your JDBC application as shown in the following code example. Context ctx = new InitialContext(); DataSource ds = (DataSource)ctx.lookup("EmployeeDB"); Connection con = ds.getconnection("domino", "spark"); 41

42 Chapter 2: Getting started In this example, the JNDI environment is first initialized. Next, the initial naming context is used to find the logical name of the data source (EmployeeDB). The Context.lookup() method returns a reference to a Java object, which is narrowed to a javax.sql.datasource object. Then, the DataSource.getConnection() method is called to establish a connection. 42

43 3 Using the Driver This section provides information on how to connect to your data store using either the JDBC Driver Manager or DataDirect JDBC data sources, as well as information on how to implement and use functionality supported by the driver. For details, see the following topics: Connecting from an Application Using Connection Properties Performance Considerations Authentication Data Encryption Identifiers IP Addresses Parameter Metadata Support Isolation Levels Unicode Error Handling Large Object (LOB) Support Rowset Support Executing CQL 43

44 Chapter 3: Using the Driver Connection Pool Manager Statement Pool Monitor DataDirect Test Tracking JDBC Calls with DataDirect Spy Connecting from an Application Once the driver is installed and configured, you can connect from your application to your database in either of the following ways: Using the JDBC Driver Manager, by specifying the connection URL in the DriverManager.getConnection() method. Creating a JDBC data source that can be accessed through the Java Naming Directory Interface (JNDI). Driver and Data Source Classes The driver class is: com.ddtek.jdbc.cassandra.cassandradriver Two data source classes are provided with the driver. Which data source class you use depends on the JDBC functionality your application requires. The following table shows the recommended data source class to use with different JDBC specifications. Table 16: Choosing a Data Source Class If your application requires... JDBC 4.0 functionality and higher JDBC 3.x functionality and earlier specifications JVM Version Java SE 6 or higher Java SE 6 or higher Data Source Class com.ddtek.jdbcx.cassandra.cassandradatasource40 com.ddtek.jdbcx.cassandra.cassandradatasource See Connecting Using Data Sources on page 40 for information about Progress DataDirect data sources. Connecting Using the DriverManager One way to connect to a Cassandra keyspace is through the JDBC DriverManager using the DriverManager.getConnection() method. As the following example shows, this method specifies a string containing a connection URL. Connection conn = DriverManager.getConnection ("jdbc:datadirect:cassandra://myserver:9042;keyspacename=myks"); Note: A Cassandra keyspace is equivalent to a relational database. 44

45 Connecting from an Application Setting the Classpath The driver must be defined on your CLASSPATH before you can connect. The CLASSPATH is the search string your Java Virtual Machine (JVM) uses to locate JDBC drivers on your computer. If the driver is not defined on your CLASSPATH, you will receive a class not found exception when trying to load the driver. Set your system CLASSPATH to include the cassandra.jar file as shown, where install_dir is the path to your product installation directory. install_dir/lib/cassandra.jar Windows Example CLASSPATH=.;C:\Program Files\Progress\DataDirect\JDBC_60\lib\cassandra.jar UNIX Example CLASSPATH=.:/opt/Progress/DataDirect/JDBC_60/lib/cassandra.jar Passing the Connection URL After setting the CLASSPATH, the required connection information needs to be passed in the form of a connection URL. The connection URL takes the form: jdbc:datadirect:cassandra://server:port; KeyspaceName=keyspace;[property=value[;...]] where: server port specifies the name or the IP address of the server to which you want to connect. specifies the port of the server that is listening for connections to the Cassandra keyspace. The default is keyspace specifies the default name of the Cassandra keyspace to which the driver connects. This value is used as the default qualifier for unqualified table names in SQL queries. Note that a Cassandra keyspace is equivalent to a relational database. property=value specifies connection property settings. Multiple properties are separated by a semi-colon. For more information on connection properties, see Using Connection Properties on page 50. This example shows how to establish a connection to a Cassandra data store: Connection conn = DriverManager.getConnection ("jdbc:datadirect:cassandra://myserver:9042;keyspacename=myks"); 45

46 Chapter 3: Using the Driver Testing the Connection You can also use DataDirect Test to establish and test a DriverManager connection. The screen shots in this 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. 46

47 Connecting from an Application The main dialog appears: 4. From the menu bar, select Connection > Connect to DB. The Select A Database dialog appears: 5. Select the appropriate database template from the Defined Databases field. 6. In the Database field, specify the ServerName, PortNumber, and KeyspaceName for your Apache Cassandra data store. 47

48 Chapter 3: Using the Driver For example: jdbc:datadirect:cassandra://myserver:9042;keyspacename=myks 7. If you are using user ID/password authentication, enter your user ID and password in the corresponding fields. Attention: User ID/password authentication is not supported for the preview version of the driver. 8. Click Connect. If the connection information is entered correctly, the JDBC/Database Output window reports that a connection has been established. (If a connection is not established, the window reports an error.) For more information about using DataDirect Test, see DataDirect Test on page 92. Connecting Using Data Sources A JDBC data source is a Java object, specifically a DataSource object, that defines connection information required for a JDBC driver to connect to the database. Each JDBC driver vendor provides their own data source implementation for this purpose. A Progress DataDirect data source is Progress DataDirect s implementation of a DataSource object that provides the connection information needed for the driver to connect to a database. 48

49 Connecting from an Application Because data sources work with the Java Naming Directory Interface (JNDI) naming service, data sources can be created and managed separately from the applications that use them. Because the connection information is defined outside of the application, the effort to reconfigure your infrastructure when a change is made is minimized. For example, if the database is moved to another database server, the administrator need only change the relevant properties of the DataSource object. The applications using the database do not need to 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 following interfaces. javax.sql.datasource javax.sql.connectionpooldatasource (allows applications to use connection pooling) See also Driver and Data Source Classes on page 13 Connection Pool Manager on page 71 Creating Data Sources The following example files provide details on creating and using Progress DataDirect data sources with the Java 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 source and 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 JDBC data source and save it in your local file system using the File System JNDI Provider. See "Example Data Source" for an example data source definition for the example files. To connect using a JNDI data source, the driver needs to access a JNDI data store to persist the data source information. For a JNDI file system implementation, you must download the File System Service Provider from the 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 not required for LDAP implementations because the LDAP Service Provider has been included with Java SE since Java 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 the javax.sql.datasource object. This object loads the specified driver and can be used to establish a connection to the database. Once the data source has been registered with JNDI, it can be used by your JDBC application as shown in the following code example. Context ctx = new InitialContext(); DataSource ds = (DataSource)ctx.lookup("EmployeeDB"); Connection con = ds.getconnection("domino", "spark"); 49

50 Chapter 3: Using the Driver In this example, the JNDI environment is first initialized. Next, the initial naming context is used to find the logical name of the data source (EmployeeDB). The Context.lookup() method returns a reference to a Java object, which is narrowed to a javax.sql.datasource object. Then, the DataSource.getConnection() method is called to establish a connection. Using Connection Properties You can use connection properties to customize the driver for your environment. This section organizes connection properties according to functionality. You can use connection properties with either the JDBC DriverManager or a JDBC DataSource. For a DriverManager connection, a property is expressed as a key value pair and takes the form property=value. For a DataSource connection, a property is expressed as a JDBC method and takes the form setproperty(value). Connection property names are case-insensitive. For example, Password is the same as password. Note: In a JDBC DataSource, string values must be enclosed in double quotation marks, for example, setkeyspacename("myks"). See "Connection Property Descriptions" for an alphabetical list of connection properties and their descriptions. See also Connecting Using the DriverManager on page 36 Connecting Using Data Sources on page 40 Connection Property Descriptions on page 129 Required Properties The following table summarizes connection properties which are required to connect to a database. Table 17: Required Properties Property KeyspaceName on page 140 PortNumber on page 148 ServerName on page 154 Characteristic Specifies the default name of the Cassandra keyspace to which the driver connects. This value is used as the default qualifier for unqualified table names in SQL queries. Note that a Cassandra keyspace is equivalent to a relational database. Specifies the port of the server that is listening for connections to the Cassandra keyspace. The default is Specifies the name or the IP address of the server to which you want to connect. See also Connection Property Descriptions on page

51 Using Connection Properties Mapping Properties The following table summarizes connection properties involved in mapping a native data model to a relational data model. Table 18: Mapping Properties Property CreateMap on page 133 SchemaMap on page 153 Characteristic Determines whether the driver creates the internal files required for a relational view of the native data when establishing a connection. Specifies the name and location of the configuration file used to create the relational map of native data. The driver looks for this file when connecting to the server. If the file does not exist, the driver creates one. See also Complex Type Normalization on page 15 Connection Property Descriptions on page 129 Authentication Properties The following table summarizes connection properties related to authentication. Table 19: Authentication Properties Property AuthenticationMethod on page 132 KeyspaceName on page 140 LoginConfigName on page 143 Password on page 147 ServicePrincipalName on page 155 User on page 159 Characteristic Determines which authentication method the driver uses when establishing a connection. The default is useridpassword. Specifies the default name of the Cassandra keyspace to which the driver connects. This value is used as the default qualifier for unqualified table names in SQL queries. Specifies the name of the entry in the JAAS login configuration file that contains the authentication technology used by the driver to establish a Kerberos connection. The LoginModule-specific items found in the entry are passed on to the LoginModule. The default is JDBC_DRIVER_01. Specifies the password used to connect to your database for user ID/password authentication. Specifies the three-part service principal name registered with the key distribution center (KDC) in a Kerberos configuration. When no value is specified, the driver builds a service principle name based on environment variables. Specifies the user ID for user ID/password authentication or the user principal name for Kerberos authentication. 51

52 Chapter 3: Using the Driver See also Connection Property Descriptions on page 129 Data Encryption Properties The following table summarizes connection properties which can be used in the implementation of SSL data encryption, including server and client authentication. Table 20: Data Encryption Properties Property EncryptionMethod on page 134 Characteristic Determines whether data is encrypted and decrypted when transmitted over the network between the driver and database server. To enable SSL, set EncryptionMethod to SSL. The default is noencryption. HostNameInCertificate on page 136 KeyPassword on page 140 KeyStore on page 141 KeyStorePassword on page 142 TrustStore on page 158 Specifies a host name for certificate validation when SSL encryption is enabled (EncryptionMethod=SSL) and validation is enabled (ValidateServerCertificate=true). This property is optional and provides additional security against man-in-the-middle (MITM) attacks by ensuring that the server the driver is connecting to is the server that was requested. Specifies the password that is used to access the individual keys in the keystore file when SSL is enabled (EncryptionMethod=SSL) and SSL client authentication is enabled on the database server. This property is useful when individual keys in the keystore file have a different password than the keystore file. Specifies the directory of the keystore file to be used when SSL is enabled (EncryptionMethod=SSL) and SSL client authentication is enabled on the database server. The keystore file contains the certificates that the client sends to the server in response to the server s certificate request. Specifies 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 that the client sends to the server in response to the server s certificate request. Specifies the directory of the truststore file to be used when SSL is enabled (EncryptionMethod=SSL) and server authentication is used. The truststore file contains a list of the Certificate Authorities (CAs) that the client trusts. 52

53 Using Connection Properties Property TrustStorePassword on page 159 ValidateServerCertificate on page 160 Characteristic Specifies 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 the client trusts. Determines whether the driver validates the certificate that is sent by the database server when SSL encryption is enabled (EncryptionMethod=SSL). When using SSL server authentication, any certificate that is sent by the server must be issued by a trusted Certificate Authority (CA). The default is true. See also Data Encryption on page 64 Connection Property Descriptions on page 129 Authentication Properties on page 51 Statement Pooling Properties The following table summarizes statement pooling connection properties. Table 21: Statement Pooling Properties Property ImportStatementPool on page 137 MaxPooledStatements on page 145 RegisterStatementPoolMonitorMBean on page 150 Characteristic Specifies the path and file name of the file to be used to load the contents of the statement pool. When this property is specified, statements are imported into the statement pool from the specified file. Specifies the maximum number of prepared statements to be pooled for each connection and enables the driver s internal prepared statement pooling when set to an integer greater than zero (0). The driver s internal prepared statement pooling provides performance benefits when the driver is not running from within an application server or another application that provides its own statement pooling. Registers the Statement Pool Monitor as a JMX MBean when statement pooling has been enabled with MaxPooledStatements. This allows you to manage statement pooling with standard JMX API calls and to use JMX-compliant tools, such as JConsole. See also Statement Pool Monitor on page 84 53

54 Chapter 3: Using the Driver Connection Property Descriptions on page 129 Additional Properties The following table summarizes additional connection properties. Table 22: Additional Properties Property FetchSize on page 135 InitializationString on page 138 InsensitiveResultSetBufferSize on page 139 LogConfigFile on page 143 LoginTimeout on page 144 NativeFetchSize on page 146 ReadConsistency on page 149 ReadOnly on page 150 ResultMemorySize on page 151 SpyAttributes on page 156 TransactionMode on page 157 WriteConsistency on page 161 Characteristic Specifies the number of rows that the driver processes before returning data to the application when executing a Select. This value provides a suggestion to the driver as to the number of rows it should internally process before returning control to the application. The driver may fetch fewer rows to conserve memory when processing exceptionally wide rows. Specifies one or multiple SQL commands to be executed by the driver after it has established the connection to the database and has performed all initialization for the connection. If the execution of a SQL command fails, the connection attempt also fails and the driver throws an exception indicating which SQL command or commands failed. Determines the amount of memory used by the driver to cache insensitive result set data. Specifies the filename of the configuration file used to initialize driver logging. The amount of time, in seconds, that the driver waits for a connection to be established before timing out the connection request. Specifies the number of rows of data the driver attempts to fetch from the native data source on each request submitted to the server. Specifies how many replicas must respond to a read request before returning data to the client application. Specifies whether the connection supports read-only access to the data source. Specifies the maximum size, in megabytes, of an intermediate result set that the driver holds in memory. When this threshold is reached, the driver writes a portion of the result set to disk in temporary files. Enables DataDirect Spy to log detailed information about calls issued by the driver on behalf of the application. DataDirect Spy is not enabled by default. Specifies how the driver handles manual transactions. Determines the number of replicas on which the write must succeed before returning an acknowledgment to the client application. 54

55 Performance Considerations See also Connection Property Descriptions on page 129 Performance Considerations You can optimize application performance by adopting guidelines described in this section. EncryptionMethod: Data encryption may adversely affect performance because of the additional overhead (mainly CPU usage) required to encrypt and decrypt data. FetchSize/NativeFetchSize: The connection properties FetchSize and NativeFetchSize can be used to adjust the trade-off between throughput and response time. In general, setting larger values for FetchSize and NativeFetchSize will improve throughput, but can reduce response time. For example, if an application attempts to fetch 100,000 rows from the native data source and NativeFetchSize is set to 500, the driver must make 200 round trips across the network to get the 100,000 rows. If, however, NativeFetchSize is set to 10000, the driver only needs to make 10 round trips to retrieve 100,000 rows. Network round trips are expensive, so generally, minimizing these round trips increases throughput. For many applications, throughput is the primary performance measure, but for interactive applications, such as Web applications, response time (how fast the first set of data is returned) is more important than throughput. For example, suppose that you have a Web application that displays data 50 rows to a page and that, on average, you view three or four pages. Response time can be improved by setting FetchSize to 50 (the number of rows displayed on a page) and NativeFetchSize to 200. With these settings, the driver fetches all of the rows from the native data source that you would typically view in a single session and only processes the rows needed to display the first page. Note: FetchSize provides a suggestion to the driver as to the number of rows it should internally process before returning control to the application. The driver may fetch fewer rows to conserve memory when processing exceptionally wide rows. InsensitiveResultSetBufferSize: To improve performance, insensitive result set data can be cached instead of written to disk. If the size of the result set data is greater than the size allocated for the cache, the driver writes the result set to disk. The maximum cache size setting is 2 GB. JVM Heap Size: JVM heap size can be used to address memory and performance concerns. By increasing the max Java heap size, you increase the amount of data the driver may accumulate in memory. This can reduce the likelihood of out-of-memory errors and improve performance by ensuring that result sets fit easily within the JVM's free heap space. In addition, when a limit is imposed by setting ResultMemorySize to -1, increasing the max Java heap size can improve performance by reducing the need to write to disk, or removing it altogether. MaxPooledStatements: To improve performance, the driver's own internal prepared statement pooling should be enabled when the driver does not run from within an application server or from within another application that does not provide its own prepared statement pooling. When the driver's internal prepared statement pooling is 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 created by the application. If the value set for this property is greater than the number of prepared statements used by the application, all prepared statements are cached. (See "Designing JDBC Applications for Performance Optimization" for more information about using prepared statement pooling to optimize performance.) 55

56 Chapter 3: Using the Driver ResultMemorySize: ResultMemorySize can affect performance in two main ways. First, if the size of the result set 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 remove any limit on the size of an intermediate result set by setting ResultMemorySize to 0, you can realize performance gains for result sets that easily fit within the JVM's free heap space. However, the same setting can diminish performance for result sets that barely fit within the JVM's free heap space. See also EncryptionMethod on page 134 FetchSize on page 135 InsensitiveResultSetBufferSize on page 139 MaxPooledStatements on page 145 ResultMemorySize on page 151 Troubleshooting Out-of-Memory Errors on page 171 Designing JDBC Applications for Performance Optimization on page 283 Authentication The driver supports user ID/password and Kerberos authentication with the AuthenticationMethod connection property. When AuthenticationMethod=userIdPassword (default), the driver uses SCRAM-SHA-1 user ID/password authentication. The User property provides the user ID, and the Password property provides the password. When AuthenticationMethod=kerberos, the driver uses Kerberos authentication. When AuthenticationMethod=none, the driver does not attempt to authenticate with the server. See also AuthenticationMethod on page 132 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 KeyspaceName connection property. If authentication has not been enabled, client applications will have access to all keyspaces on the server. If authentication has been enabled, a client application will only have access to the keyspace specified by the KeyspaceName property assuming it has the required permissions. Even when authentication has not been enabled, KeyspaceName is strongly recommended because its value 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 also AuthenticationMethod on page

57 Authentication KeyspaceName on page 140 User on page 159 Password on page 147 Configuring the Driver for Kerberos Authentication To configure the driver for Kerberos authentication, take the following steps. 1. Verify that your environment meets the requirements outlined in "Kerberos Authentication Requirements." 2. Use one of the following methods to integrate the JAAS configuration file into your Kerberos environment. (See "The JAAS Login Configuration File" for details about this file.) Option 1. Specify a login configuration file directly in your application with the java.security.auth.login.config system property. For example: System.setProperty("java.security.auth.login.config","install_dir/lib/JDBCDriverLogin.conf"); Note: The install_dir/lib/jdbcdriverlogin.conf file is the JAAS login configuration file installed with the driver. You can use this file or another file as your JAAS login configuration file. Option 2. Set up a default configuration. Modify the Java security properties file to indicate the URL of the login 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 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 file as the value for a login.config.url.n property. For example: # Default login configuration file login.config.url.1=file:${user.home}/.java.login.config login.config.url.2=file:install_dir/lib/jdbcdriverlogin.conf 3. Modify your JAAS login configuration file to include an entry with authentication technology that the driver can use to establish a Kerberos connection. (See "The JAAS Login Configuration File" for details about this file.) 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 entry takes the following form. entry_name { login_module flag_value module_options }; 57

58 Chapter 3: Using the Driver where: entry_name is the name of the login configuration file entry. The driver's LoginConfigName connection property can be used to specify the name of this entry. JDBC_DRIVER_01 is the default entry name for the JDBCDriverLogin.conf file installed with the driver. login_module is the fully qualified class name of the authentication technology used with the driver. flag_value specifies whether the success of the module is required, requisite, sufficient, or optional. module_options specifies available options for the LoginModule. These options vary depending on the LoginModule being used. The following examples show that the LoginModule used for a Kerberos implementation depends on your JRE. Oracle JRE JDBC_DRIVER_01 { com.sun.security.auth.module.krb5loginmodule required useticketcache=true; }; IBM JRE JDBC_DRIVER_01 { com.ibm.security.auth.module.krb5loginmodule required usedefaultccache=true; }; 4. Set the Kerberos realm name and the KDC name for that realm using either of the following methods. Note: If using Windows Active Directory, the Kerberos realm name is the Windows domain name and the KDC name is the Windows domain controller name. Option 1. Modify the krb5.conf file to include the default realm name and the KDC name for that realm. (See "The krb5.conf File" for details about using and locating the krb5.conf file.) For example, if the realm name is XYZ.COM and the KDC name is kdc1, your krb5.conf file would include the following entries. [libdefaults] default_realm = XYZ.COM [realms] XYZ.COM = { kdc = kdc1 } 58

59 Authentication Option 2. Specify the Java system properties, java.security.krb5.realm and java.security.krb5.kdc, in your application. For example, if the realm name is XYZ.COM and the KDC name is kdc1, your application would include the following settings. System.setProperty("java.security.krb5.realm","XYZ.COM"); System.setProperty("java.security.krb5.kdc","kdc1") Note: Even if you do not use the krb5.conf file to specify the realm and KDC names, you may need to modify your krb5.conf file to suit your environment. Refer to your database vendor documentation for information. If you do not specify a valid Kerberos realm and a valid KDC name, the following exception is thrown. Message:[DataDirect][Cassandra JDBC Driver]Could not establish a connection using integrated security: No valid credentials provided 5. Set the driver's AuthenticationMethod connection property to kerberos. (See "AuthenticationMethod" for details.) 6. If any of the following statements is valid, specify the service principal name with the ServicePrincipalName connection property. (See "ServicePrincipalName" for details on the composition of the service principal name.) Note: The ServicePrincipalName takes the following form. Service_Name/Fully_Qualified_Domain_Name@REALM_NAME You are using a service name other than the default service name cassandra. The fully qualified domain name (FQDN) in your connection string is different from the FQDN registered with the KDC. You are using a Kerberos realm other than the default realm specified in the krb5.conf file. 7. If necessary, set the User connection property. (See "User" for details.) In most circumstances, there is no need to set the User connection property. By default, the driver uses the user principal name in the Kerberos Ticket Granting Ticket (TGT) as the value for the User property. 8. If necessary, set the KeyspaceName connection property. (See "KeyspaceName" for details.) If authentication has not been enabled, client applications will have access to all keyspaces on the server. If authentication has been enabled, a client application will only have access to the keyspace specified by the KeyspaceName property assuming it has the required permissions. Even when authentication has not been enabled, KeyspaceName is strongly recommended because its value functions as the default qualifier for unqualified tables in SQL queries. 9. If you want the driver to use user credentials other than the server user s operating system credentials, include code in your application to obtain and pass a javax.security.auth.subject used for authentication. (See "Specifying User Credentials for Kerberos Authentication (Delegation of Credentials)" for details.) 10. Establish a procedure for obtaining a Kerberos Ticket Granting Ticket (TGT) for your environment. (See "Obtaining a Kerberos Ticket Granting Ticket" for details.) Scenario 1. For Windows Active Directory configurations, Active Directory automatically obtains a TGT. 59

60 Chapter 3: Using the Driver Scenario 2. For non-active Directory configurations, you can enable the application to obtain a TGT in either of the following ways. a) Automate the method of obtaining the TGT as with a keytab. (See your Kerberos documentation for details.) b) Require the application user to obtain the TGT with a kinit command when logging on. A TGT can be obtained with a kinit command to the Kerberos server. For example, the following command requests a TGT from the server with a lifetime of 10 hours, which is renewable for 5 days. kinit -l 10h -r 5d user@realm Note: The klist command can be used on Windows or UNIX/Linux systems to verify that a TGT has been obtained. See also Kerberos Authentication Requirements on page 60 The JAAS Login Configuration File on page 61 LoginConfigName on page 143 The krb5.conf File on page 62 AuthenticationMethod on page 132 ServicePrincipalName on page 155 User on page 159 KeyspaceName on page 140 Specifying User Credentials for Kerberos Authentication (Delegation of Credentials) on page 63 Obtaining a Kerberos Ticket Granting Ticket on page 64 Kerberos Authentication Requirements Verify that your environment meets the requirements listed in the following table before you configure the driver for Kerberos authentication. Note: For Windows Active Directory, the domain controller must administer both the database server and the client. Table 23: Kerberos Configuration Requirements Database server Component Requirements The database server must be running Apache Cassandra 2.1 or higher. 60

61 Authentication Kerberos server Component Requirements The Kerberos server is the machine where the user IDs for authentication are administered. The Kerberos server is also the location of the Kerberos key distribution center (KDC). Network authentication must be provided by 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 Client Java SE 6 or higher must be installed. See also Configuring the Driver for Kerberos Authentication on page 57 The JAAS Login Configuration File The Java Authentication and Authorization Service (JAAS) login configuration file contains one or more entries that specify authentication technologies to be used by applications. To establish Kerberos connections with the driver, the login configuration file must be referenced either by setting the java.security.auth.login.config system property or by setting up a default configuration using the Java security properties file. In addition, the login configuration file must include an entry for the driver. (See "Configuring the Driver for Kerberos Authentication" for details.) You can create your own JAAS login configuration file, or you can use the JDBCDriverLogin.conf file installed with the driver. This file is installed in the /lib directory of the product installation directory. In either case, the login configuration file must include an entry that specifies the authentication technology to be used by the driver to establish a Kerberos connection. JAAS login configuration file entries begin with an entry name followed by one or more LoginModule items. Each LoginModule item contains information that is passed to the LoginModule. A login configuration file entry takes the following form. entry_name { login_module flag_value module_options }; 61

62 Chapter 3: Using the Driver where: entry_name is the name of the login configuration file entry. The driver's LoginConfigName connection property can be used to specify the name of this entry. JDBC_DRIVER_01 is the default entry name for the JDBCDriverLogin.conf file installed with the driver. login_module is the fully qualified class name of the authentication technology used with the driver. flag_value specifies whether the success of the module is required, requisite, sufficient, or optional. module_options specifies available options for the LoginModule. These options vary depending on the LoginModule being used. The following examples show that the LoginModule used for a Kerberos implementation depends on your JRE. Oracle JRE JDBC_DRIVER_01 { com.sun.security.auth.module.krb5loginmodule required useticketcache=true; }; IBM JRE JDBC_DRIVER_01 { com.ibm.security.auth.module.krb5loginmodule required usedefaultccache=true; }; Refer to Java Authentication and Authorization Service documentation for information about the JAAS login configuration file and implementing authentication technologies. See also Configuring the Driver for Kerberos Authentication on page 57 LoginConfigName on page 143 The krb5.conf File The krb5.conf file contains Kerberos configuration information. Typically, the default realm name and the KDC name for that realm are specified in the krb5.conf file. However, you can specify the realm and KDC names directly in your application with the java.security.krb5.realm and java.security.krb5.kdc system properties. Setting these system properties will override the settings in the krb5.conf file. When a client application does not use the java.security.krb5.realm and java.security.krb5.kdc system properties, the JVM looks for a krb5.conf file that contains the realm and KDC names. The JVM first looks for the krb5.conf file in the location specified with the java.security.krb5.conf system property. If this system property has not been used, then the JVM continues looking for the krb5.conf file using an internal algorithm. The JVM must be able to locate the krb5.conf to establish a Kerberos connection. Refer to your vendor's JVM documentation for the list of directories that the JVM searches in order to find the krb5.conf file. 62

63 Authentication Depending on your environment, other modifications may need to be made to your krb5.conf file. Refer to the following resources for more information on configuring Kerberos and the krb5.conf file. Your database vendor documentation "Keberos Requirements" in Java Documentation "krb5.conf" in MIT Kerberos Documentation See also Configuring the Driver for Kerberos Authentication on page 57 Specifying User Credentials for Kerberos Authentication (Delegation of Credentials) By default, when Kerberos authentication is used, the driver takes advantage of the user name and password maintained by the operating system to authenticate users to the database. By allowing the database to share the user name and password used for the operating system, users with a valid operating system account can log into the database without supplying a user name and password. Many application servers or Web servers act on behalf of the client user logged on the machine on which the application is running, rather than the server user. If you want the driver to use user credentials other than the operating system user name and password, include code in your application to obtain and pass a javax.security.auth.subject used for authentication as shown in the following example. import javax.security.auth.subject; import javax.security.auth.login.logincontext; import java.sql.*; // The following code creates a javax.security.auth.subject instance // used for authentication. Refer to the Java Authentication // and Authorization Service documentation for details on using a // LoginContext to obtain a Subject. LoginContext lc = null; Subject subject = null; try { lc = new LoginContext("JaasSample", new TextCallbackHandler()); lc.login(); subject = lc.getsubject(); } catch (Exception le) {... // display login error }// This application passes the javax.security.auth.subject // to the driver by executing the driver code as the subject Connection con = (Connection) Subject.doAs(subject, new PrivilegedExceptionAction() { public Object run() { Connection con = null; try { Class.forName("com.ddtek.jdbc.cassandra.CassandraDriver"); String url = "jdbc:datadirect:cassandra://myserver:27017"; con = DriverManager.getConnection(url); } catch (Exception except) {... //log the connection error Return null; } }); } return con; 63

64 Chapter 3: Using the Driver // This application now has a connection that was authenticated with // the subject. The application can now use the connection. Statement stmt = con.createstatement(); String sql = "SELECT * FROM employee"; ResultSet rs = stmt.executequery(sql);... // do something with the results See also Configuring the Driver for Kerberos Authentication on page 57 Obtaining a Kerberos Ticket Granting Ticket Kerberos uses the credentials in a Ticket Granting Ticket (TGT) to verify the identity of users and control access to services. Depending on your environment, you will need to establish a procedure for obtaining a TGT. For Windows Active Directory configurations, Active Directory automatically obtains a TGT. For non-active Directory configurations, you can enable the application to obtain a TGT in one of two ways. First, you can automate the method of obtaining the TGT as with a keytab. Second, you can require the application user to obtain the TGT with a kinit command when logging on. A TGT can be obtained directly with a kinit command to the Kerberos server. For example, the following command requests a TGT from the server with a lifetime of 10 hours, which is renewable for 5 days. kinit -l 10h -r 5d user@realm Note: The klist command can be used on Windows or UNIX/Linux systems to verify that a TGT has been obtained. Refer to your Kerberos documentation for more information on automating the process of obtaining a TGT. See also Configuring the Driver for Kerberos Authentication on page 57 Data Encryption SSL works by allowing the client and server to send each other encrypted data that only they can decrypt. SSL negotiates the terms of the encryption in a sequence of events known as the SSL handshake. The handshake involves the following types of authentication: SSL server authentication requires the server to authenticate itself to the client. SSL client authentication is optional and requires the client to authenticate itself to the server after the server has authenticated itself to the client. Configuring SSL Encryption The following steps outline how to configure SSL encryption. 64

65 Data Encryption Note: Connection hangs can occur when the driver is configured for SSL and the database server does not support SSL. You may want to set a login timeout using the LoginTimeout property to avoid problems when connecting 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 the TrustStore 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. The HostNameInCertificate property provides additional security against man-in-the-middle (MITM) attacks by ensuring 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 KeyStorePassword properties or their corresponding Java system properties (javax.net.ssl.keystore and javax.net.ssl.keystorepassword, respectively). b) If any key entry in the keystore file is password-protected, set the KeyPassword property to the key password. See also Data Encryption Properties on page 52 Configuring SSL Server Authentication on page 65 Configuring SSL Client Authentication on page 66 Configuring SSL Server Authentication When the client makes a connection request, the server presents its public certificate for the client to accept or deny. The client checks the issuer of the certificate against a list of trusted Certificate Authorities (CAs) that resides 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 subject matches the value that the application expects), an encrypted connection is established between the client and 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 locate the truststore and unlock the truststore with the appropriate password. You can specify truststore information in 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. 65

66 Chapter 3: Using the Driver Specify values for the connection properties TrustStore and TrustStorePassword in the connection URL. For example: jdbc:datadirect:cassandra://myserver:9042;keyspacename=myks; Password=secr3t;TrustStore=C:\Certficates\MyTruststore.jks; TrustStorePassword=MyTruststorePassword;User=jsmith; Any values specified by the TrustStore and TrustStorePassword properties override values specified by the Java system properties. This allows you to choose which truststore file you want to use for a particular connection. Alternatively, you can configure the drivers to trust any certificate sent by the server, even if the issuer is not a trusted CA. Allowing a driver to trust any certificate sent from the server is useful in test environments because it eliminates the need to specify truststore information on each client in the test environment. If the driver is configured 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 the server has proved its identity. Similar to SSL server authentication, the client sends a public certificate to the server 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 password to 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 of each entry is a certificate and the certificate s private key. Each keystore entry can have the same password as the keystore password or a different password. If a keystore entry has a password different than the keystore password, the driver must provide this password to unlock the entry and gain access to the certificate and its private key. PKCS #12 keystores. To gain access to the certificate and its private key, the driver must provide the keystore 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 keystore entry has a password different than the keystore password, the KeyPassword connection property must specify the password of the keystore entry (for example, KeyPassword=MyKeyPassword). Specify values for the connection properties KeyStore and KeyStorePassword in the connection URL. For example: jdbc:datadirect:cassandra://myserver:9042;keyspacename=myks; KeyStore=C:\Certficates\MyTruststore.jks;KeyStorePassword=MyKeystorePassword; Password=secr3t;User=jsmith; 66

67 Identifiers Note: If the keystore specified by the KeyStore connection property is a JKS and the keystore entry has a password different than the keystore password, the KeyPassword connection property must specify the password of the keystore entry (for example, KeyPassword=MyKeyPassword). Any values specified by the KeyStore and KeyStorePassword properties override values specified by the Java system properties. This allows you to choose which keystore file you want to use for a particular connection. Identifiers Identifiers are used to refer to objects exposed by the driver, such as tables and columns. The driver supports both quoted and unquoted identifiers for naming objects. The maximum length of both quoted and unquoted identifiers is 48 characters for table names and 128 characters for column names. Quoted identifiers must be enclosed in double quotation marks (""). The characters supported in quoted identifiers depends on the version of Cassandra being used. For details on valid characters, refer to the Cassandra documentation for your database version. Naming conflicts can arise from restrictions imposed by third party applications, from the normalization of native data, or from the truncation of object names. The driver avoids naming conflicts by appending an underscore separator and integer (for example, _1) to identifiers with the same name. For example, if a third party application restricts the naming of three columns such that each column retains the name address, the driver would expose the columns in the following manner: address address_1 address_2 IP Addresses The driver supports Internet Protocol (IP) addresses in IPv4 and IPv6 format. The server name specified in the connection URL, or data source, can resolve to an IPv4 or IPv6 address. For example, the following URL can resolve to either type of address:: jdbc:datadirect:cassandra://myserver:9042;keyspacename=myks Alternately, you can specify addresses using IPv4 or IPv6 format in the server portion of the connection URL. For example, the following connection URL specifies the server using an IPv4 address: jdbc:datadirect:cassandra:// :9042;keyspacename=myks You also can specify addresses in either format using the ServerName data source property. The following example shows a data source definition that specifies the server name using IPv6 format: CassandraDataSource mds = new CassandraDataSource(); mds.setdescription("my CassandraDataSource"); mds.setservername("[abcd:ef01:2345:6789:abcd:ef01:2345:6789]");... Note: When specifying IPv6 addresses in a connection URL or data source property, the address must be enclosed by brackets. 67

68 Chapter 3: Using the Driver In addition to the normal IPv6 format, the drivers support IPv6 alternative formats for compressed and IPv4/IPv6 combination addresses. For example, the following connection URL specifies the server using IPv6 format, but uses the compressed syntax for strings of zero bits: jdbc:datadirect:cassandra://[2001:db8:0:0:8:800:200c:417a]:9042;keyspacename=myks Similarly, the following connection URL specifies the server using a combination of IPv4 and IPv6: jdbc:datadirect:cassandra://[0000:0000:0000:0000:0000:ffff: ]:54321;keyspacename=myks For complete information about IPv6, go to the following URL: Parameter Metadata Support The driver supports returning parameter metadata as described in Insert and Update Statements on page 68 and Select Statements on page 68. 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 ANSI SQL-92 entry-level predicates, for example, such as COMPARISON, BETWEEN, IN, LIKE, and EXISTS predicate 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 the associated FROM clause. For example: SELECT * FROM foo WHERE bar >? In this case, the value expression "bar" can be targeted against the table "foo" to determine the appropriate metadata for the parameter. 68

69 Isolation Levels The statement contains a predicate value expression part that is a nested query. The nested query's metadata must 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 BY statements are supported. For example: SELECT * FROM t1 WHERE col =? ORDER BY 1 Joins are supported. For example: SELECT * FROM t1,t2 WHERE t1.col1 =? Fully qualified names and aliases are supported. For example: SELECT a, b, c, d FROM T1 AS A, T2 AS B WHERE A.a =? AND B.b =? Isolation Levels Apache Cassandra does not support transactions. However, manual transactions can be handled to some degree with the TransactionMode connection property. See TransactionMode on page 157 for details. Unicode Multilingual JDBC applications can be developed on any operating system using the driver to access both Unicode and non-unicode enabled databases. Internally, Java applications use UTF-16 Unicode encoding for string data. When fetching data, the driver automatically performs the conversion from the character encoding used by the database to UTF-16. Similarly, when inserting or updating data in the database, the driver automatically 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 data to or from many popular character encodings. Error Handling SQLExceptions The driver reports errors to the application by throwing SQLExceptions. Each SQLException contains the following information: 69

70 Chapter 3: Using the Driver 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 Errors An error generated by the driver has the format shown in the following example: [DataDirect][Cassandra JDBC Driver]Timeout expired. You may need to check the last JDBC call your application made and refer to the JDBC specification for the recommended action. Database Errors An error generated by the database has the format shown in the following example: [DataDirect][Cassandra JDBC Driver][Cassandra]Invalid Object Name. If you need additional information, use the native error code to look up details in your database documentation. Large Object (LOB) Support The driver allows you to retrieve LONGVARBINARY data, using JDBC methods designed for Binary Large Objects (BLOBs). When using these methods to update long data as BLOBs, the updates are made to the local copy of the data contained in the BLOB object. Retrieving and updating long data using JDBC methods designed for BLOBs provides some of the same benefits as retrieving and updating BLOBs, such as: Provides random access to data Allows searching for patterns in the data To provide the benefits normally associated with BLOBs, data must be cached. Because data is cached, your application will incur a performance penalty, particularly if data is read once sequentially. This performance penalty can be severe if the size of the long data is larger than available memory. Rowset Support The driver supports any JSR 114 implementation of the RowSet interface, including: CachedRowSets FilteredRowSets WebRowSets JoinRowSets JDBCRowSets Visit for more information about JSR

71 Executing CQL Executing CQL The driver supports new Native and Refresh escape sequences to embed CQL commands in SQL-92 statements. The Native escape sequence allows you to execute CQL directly through the client application. The Refresh escape sequence is then used to incorporate any changes introduced by the Native escape into the driver's relational map of the data. Note: The Native and Refresh escape sequences are mainly intended for the execution of DDL commands, such as ALTER, CREATE, and DROP. A returning clause for the Native escape is not currently supported by the driver. Therefore, results cannot be retrieved using the Native escape sequence. See also Native and Refresh Escape Sequences on page 208 Connection Pool Manager The DataDirect Connection Pool Manager allows you to pool connections when accessing databases. When your applications use connection pooling, connections are reused rather than created each time a connection is requested. Because establishing a connection is among the most costly operations an application may perform, 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 pooling allows you to reuse connections rather than create a new one every time an application needs to connect to the database. Connection pooling manages connection sharing across different user requests to maintain performance and reduce the number of new connections that must be created. For example, compare the following 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. 71

72 Chapter 3: Using the Driver 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 of the close request. The Connection Pool Environment There is a one-to-one relationship between a JDBC connection pool and a data source, so the number of connection pools used by an application depends on the number of data sources configured to use connection pooling. If multiple applications are configured to use the same data source, those applications share the same connection pool as shown in the following figure. An application may use only one data source, but allow multiple users, each with their own set of login credentials. The connection pool contains connections for all unique users using the same data source as shown in 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. The DataDirect Connection Pool Manager Connection pooling is performed in the background and does not affect how an application is coded. To use connection pooling, an application must use a DataSource object (an object implementing the DataSource interface) to obtain a connection instead of using the DriverManager class. A DataSource object registers with a JNDI naming service. Once a DataSource object is registered, the application retrieves it from the JNDI naming service in the standard way. Connection pool implementations, such as the DataDirect Connection Pool Manager, use objects that implement the javax.sql.connectionpooldatasource interface to create the connections managed in a connection pool. All Progress DataDirect data source objects implement the ConnectionPoolDataSource interface. 72

73 Connection Pool Manager The DataDirect Connection Pool Manager creates database connections, referred to as PooledConnections, by using the getpooledconnection() method of the ConnectionPoolDataSource interface. Then, the Pool Manager registers itself as a listener to the PooledConnection. When a client application requests a connection, the Pool Manager assigns an available connection. If a connection is unavailable, the Pool Manager establishes a new connection and assigns it to that application. When the application closes the connection, the driver uses the ConnectionEventListener interface to notify the Pool Manager that the connection is free and available for reuse. The driver also uses the ConnectionEventListener interface to notify the Pool Manager when a connection is corrupted so that the Pool Manager can remove that connection from the pool. Using a Connection Pool Data Source Object Once a PooledConnectionDataSource object has been created and registered with JNDI, it can be used by 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 to find the logical name of the JDBC DataSource (EmployeeDB). The Context.lookup method returns a reference to a Java object, which is narrowed to a javax.sql.connectionpooldatasource object. Next, the ConnectionPoolDataSource.getPooledConnection() method is called to establish a connection with the underlying database. Then, the application obtains a connection from the ConnectionPoolDataSource. Implementing DataDirect Connection Pooling To use connection pooling, an application must use a DataSource object (an object implementing the DataSource interface) to obtain a connection instead of using the DriverManager class. A DataSource object registers with a JNDI naming service. Once a DataSource object is registered, the application retrieves it 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 DataSource object can be used by a connection pool (PooledConnectionDataSource object created in "Creating a Driver 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 PooledConnectionDataSource object. A PooledConnectionDataSource creates and manages one or multiple connection pools. The PooledConnectionDataSource uses the driver DataSource object created in "Creating the Connection Pool" to create the connections for the connection pool. Creating a Driver Data Source Object The following Java code example creates a Progress DataDirect data source object and registers it with a JNDI naming service. Note: The DataSource class implements the ConnectionPoolDataSource interface for pooling in addition to the DataSource interface for non-pooling. 73

74 Chapter 3: Using the Driver //************************************************************************ // This code creates a Progress DataDirect for JDBC data source and // registers it to a JNDI naming service. This JDBC data source uses the // DataSource implementation provided by Progress DataDirect for JDBC Drivers. // // This data source registers its name as <jdbc/connectcassandra>. //// NOTE: To connect using a data source, the driver needs to access a JNDI data // store to persist the data source information. To download the JNDI File // System Service Provider, go to: // // // java-archive-downloads-java-plat html#7110-jndi oth-jpr //// // Make sure that the fscontext.jar and providerutil.jar files from the // download are on your classpath. //************************************************************************ // From Progress DataDirect for JDBC: import com.ddtek.jdbcx.cassandra.cassandradatasource; import javax.sql.*; import java.sql.*; import javax.naming.*; import javax.naming.directory.*; import java.util.hashtable; public class CassandraDataSourceRegisterJNDI { public static void main(string argv[]) { try { // Set up data source reference data for naming context: // // Create a class instance that implements the interface // ConnectionPoolDataSource CassandraDataSource ds = new CassandraDataSource(); ds.setdescription("cassandra Data Source"); ds.setservername("server1"); ds.setportnumber(9042); ds.setkeyspacename(mykeyspace); ds.setuser("test"); ds.setpassword("secret"); // Set up environment for creating initial 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/connectcassandra", ds); } catch (Exception e) { System.out.println(e); return; } } // Main // class CassandraDataSourceRegisterJNDI See also Implementing DataDirect Connection Pooling on page 73 Creating the Connection Pool on page 74 Creating the Connection Pool After the Progress DataDirect data source object has been created and registered, you must create the PooledConnectionDataSource object and register it with a JNDI naming service as shown in the following Java code example. 74

75 Connection Pool Manager Note: The parameter of the DataSourceName method must be set to the JNDI name of a registered driver DataSource object. This specifies the driver DataSource object to be used by the connection pool. The following code example sets the parameter of the DataSourceName method to the JNDI name of the driver DataSource object created in the previous topic, "Creating a Driver DataSource Object." //************************************************************************ // This code creates a data source and registers it to a JNDI naming service. // This data source uses the PooledConnectionDataSource // implementation provided by the DataDirect com.ddtek.pool package. // // This data source refers to a registered // Progress DataDirect for JDBC driver DataSource object. // // This data source registers its name as <jdbc/poolcassandra>. // // NOTE: To connect using a data source, the driver needs to access a JNDI data // store to persist the data source information. To download the JNDI File // System Service Provider, go to: // // // java-archive-downloads-java-plat html#7110-jndi 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("cassandra Data Source"); // Specify a registered driver DataSource object to be used // by this data source to create pooled connections ds.setdatasourcename("jdbc/connectcassandra"); // 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 75

76 Chapter 3: Using the Driver 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/poolcassandra", ds); } } } catch (Exception e) { System.out.println(e); return; See also Implementing DataDirect Connection Pooling on page 73 Creating a Driver Data Source Object on page 73 Configuring the Connection Pool You can configure attributes of a connection pool for optimal performance and scalability using the methods provided 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 is initialized Maximum idle time, which is the amount of time a pooled connection remains idle before it is removed from the connection pool See also Connection Pool Manager Interfaces on page 79 Configuring the Maximum Pool Size You 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 the PooledConnectionDataSource.setMaxPoolSizeBehavior() method: If setmaxpoolsizebehavior(softcap), the number of active connections can exceed the maximum pool size, but the number of idle connections for each user in the pool cannot exceed this limit. If a user requests a connection and an idle connection is unavailable, the Pool Manager creates a new connection 76

77 Connection Pool Manager for that user. When the connection is no longer needed, it is returned to the pool. If the number of idle connections exceeds the maximum pool size, the Pool Manager closes idle connections to enforce the pool size limit. This is the default behavior. If setmaxpoolsizebehavior(hardcap), the total number of active and idle connections cannot exceed the maximum pool size. Instead of creating a new connection for a connection request if an idle connection is unavailable, the Pool Manager queues the connection request until a connection is available or the request times out. This behavior is useful if your client or application server has memory limitations or if your database server is licensed for only a certain number of connections. See also PooledConnectionDataSource on page 80 Connecting Using a Connection Pool Because an application uses connection pooling by referencing the JNDI name of a registered PooledConnectionDataSource object, code changes are not required for an application to use connection pooling. The following example shows Java code that looks up and uses the JNDI-registered PooledConnectionDataSource object created in "Creating the Connection Pool." //******************************************************************** // Test program to look up and use a JNDI-registered data source. // // To run the program, specify the JNDI lookup name for the // command-line argument, for example: // // java TestDataSourceApp <jdbc/poolcassandra> //******************************************************************** import javax.sql.*; import java.sql.*; import javax.naming.*; import java.util.hashtable; public class TestDataSourceApp { public static void main(string argv[]) { String strjndilookupname = ""; // Get the JNDI lookup name for a data 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) { 77

78 Chapter 3: Using the Driver 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 the command-line argument when you run the preceding application. For example, the following command specifies the driver DataSource object created in "Creating a Driver DataSource Object": java TestDataSourceApp jdbc/connectcassandra. See also Creating a Driver Data Source Object on page 73 Creating the Connection Pool on page 74 PooledConnectionDataSource on page 80 Closing the Connection Pool To ensure that the connection pool is closed correctly when an application stops running, the application must notify the DataDirect Connection Pool Manager when it stops. For applications running on Java SE 5 and higher, notification occurs automatically when the application stops running. The PooledConnectionDataSource.close() method also can be used to explicitly close the connection pool while the application is running. For example, if changes are made to the pool configuration using a pool management tool, the PooledConnectionDataSource.close() method can be used to force the connection pool to close and re-create the pool using the new configuration values. 78

79 Connection Pool Manager Checking the Pool Manager Version To check the version of your DataDirect Connection Pool Manager, navigate to the directory containing the DataDirect Connection Pool Manager (install_dir/pool manager where install_dir is your product installation 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 programmatically by 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 PooledConnectionDataSource connection. 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() method on the PooledConnectionDataSource connection. See "Troubleshooting Connection Pooling" for information about using a Pool Manager trace file for troubleshooting. See also Troubleshooting Connection Pooling on page 166 Connection Pool Manager Interfaces This section describes the methods used by the DataDirect Connection Pool Manager interfaces: PooledConnectionDataSourceFactory, PooledConnectionDataSource, and ConnectionPoolMonitor. 79

80 Chapter 3: Using the Driver PooledConnectionDataSourceFactory The PooledConnectionDataSourceFactory interface is used to create a PooledConnectionDataSource object from a Reference object that is stored in a naming or directory service. These methods are typically invoked by a JNDI service provider; they are not usually invoked by a user application. PooledConnectionDataSourceFactory Methods static Object getobjectinstance(object refobj, Name name, Context namectx, Hashtable env) Description Creates a PooledConnectionDataSource object from a Reference object that is stored in a naming or directory service. This is an implementation of the method of the same name defined in the javax.naming.spi.objectfactory interface. Refer to the Javadoc for this interface for a description. PooledConnectionDataSource The PooledConnectionDataSource interface is used to create a PooledConnectionDataSource object for use with the DataDirect Connection Pool Manager. PooledConnectionDataSource Methods void close() Connection getconnection() Connection getconnection(string user, String password) String getdatasourcename() String getdescription() int getinitialpoolsize() int getlogintimeout() PrintWriter getlogwriter() int getmaxidletime() Description Closes the connection pool. All physical connections in the pool are closed. Any subsequent connection request re-initializes the connection pool. Obtains a physical connection from the connection pool. Obtains a physical connection from the connection pool, where user is the user requesting the connection and password is the password for the connection. Returns the JNDI name that is used to look up the DataSource object referenced by this PooledConnectionDataSource. Returns the description of this PooledConnectionDataSource. Returns the value of the initial pool size, which is the number of physical connections created when the connection pool is initialized. Returns the value of the login timeout, which is the time allowed for the database login to be validated. Returns the writer to which the Pool Manager sends trace information about its activities. Returns the value of the maximum idle time, which is the time a physical connection can remain idle in the connection pool before it is removed from the connection pool. 80

81 Connection Pool Manager PooledConnectionDataSource Methods int getmaxpoolsize() int getmaxpoolsizebehavior() int getminpoolsize() int getpropertycycle() Reference getreference() public static ConnectionPoolMonitor[ ] getmonitor() public static ConnectionPoolMonitor getmonitor(string name) Description Returns the value of the maximum pool size. See "Configuring the Maximum Pool Size" for more information about how the Pool Manager implements the maximum pool size. Returns the value of the maximum pool size behavior. See "Configuring the Maximum Pool Size" for more information about how the Pool Manager implements the maximum pool size. Returns the value of the minimum pool size, which is the minimum number of idle connections to be kept in the pool. Returns the value of the property cycle, which specifies how often the pool maintenance thread wakes up and checks the connection pool. Obtains a javax.naming. Reference object for this PooledConnectionDataSource. The Reference object contains all the state information needed to recreate an instance of this data source using the PooledConnectionDataSourceFactory object. This method is typically called by a JNDI service provider when this PooledConnectionDataSource is bound to a JNDI naming service. Returns an array of Connection Pool Monitors, one for each connection pool managed by the Pool Manager. Returns the name of the Connection Pool Monitor for the connection pool specified by name. If a pool with the specified name cannot be found, this method returns null. The connection pool name has the form: jndi_name-user_id where: jndi_name is the name used for the JNDI lookup of the driver DataSource object from which the pooled connection was obtained and user_id is the user ID used to establish the connections contained in the pool. boolean istracing() Determines whether tracing is enabled. If enabled, tracing information is sent to the PrintWriter that is passed to the setlogwriter() method or the standard output System.out if the setlogwriter() method is not called. 81

82 Chapter 3: Using the Driver PooledConnectionDataSource Methods void setdatasourcename(string datasourcename) void setdatasourcename(string datasourcename, ConnectionPoolDataSource datasource) void setdatasourcename(string datasourcename, Context ctx) void setdescription(string description) void setinitialpoolsize(int initialpoolsize) void setlogintimeout(int i) void setlogtimestamp(boolean value) void setlogtname(boolean value) void setlogwriter(printwriter printwriter) void setmaxidletime(int maxidletime) Description Sets the JNDI name, which is used to look up the driver DataSource object referenced by this PooledConnectionDataSource. The driver DataSource object bound to this PooledConnectionDataSource, specified by datasourcename, is not persisted. Any changes made to the PooledConnectionDataSource bound to the specified driver DataSource object affect this PooledConnectionDataSource. Sets the JNDI name associated with this PooledConnectionDataSource, specified by datasourcename, and the driver DataSource object, specified by datasource, referenced by this PooledConnectionDataSource. The driver DataSource object, specified by datasource, is persisted with this PooledConnectionDataSource. Changes made to the specified driver DataSource object after this PooledConnectionDataSource is persisted do not affect this PooledConnectionDataSource. Sets the JNDI name, specified by datasourcename, and context, specified by ctx, to be used to look up the driver DataSource referenced by this PooledConnectionDataSource. The JNDI name, specified by datasourcename, and context, specified by ctx, are used to look up a driver DataSource object. The driver DataSource object is persisted with this PooledConnectionDataSource. Changes made to the driver DataSource after this PooledConnectionDataSource is persisted do not affect this PooledConnectionDataSource. Sets the description of the PooledConnectionDataSource, where description is the description. Sets the value of the initial pool size, which is the number of connections created when the connection pool is initialized. Sets the value of the login timeout, where i is the login timeout, which is the time allowed for the database login to be validated. If set to true, the timestamp is logged when DataDirect Spy logging is enabled. If set to false, the timestamp is not logged. If set to true, the thread name is logged when DataDirect Spy logging is enabled. If set to false, the thread name is not logged. Sets the writer, where printwriter is the writer to which the stream will be printed. Sets the value in seconds of the maximum idle time, which is the time a connection can remain unused in the connection pool before it is closed and removed from the pool. Zero (0) indicates no limit. 82

83 Connection Pool Manager PooledConnectionDataSource Methods void setmaxpoolsize(int maxpoolsize) void setmaxpoolsizebehavior(string value) void setminpoolsize(int minpoolsize) void setpropertycycle(int propertycycle) void settracing(boolean value) Description Sets the value of the maximum pool size, which is the maximum number of connections for each user allowed in the pool. See "Configuring the Maximum Pool Size" for more information about how the Pool Manager implements the maximum pool size. Sets the value of the maximum pool size behavior, which is either softcap or hardcap. If setmaxpoolsizebehavior(softcap), the number of active connections may exceed the maximum pool size, but the number of idle connections in the connection pool for each user cannot exceed this limit. If a user requests a connection and an idle connection is unavailable, the Pool Manager creates a new connection for that user. When the connection is no longer needed, it is returned to the pool. If the number of idle connections exceeds the maximum pool size, the Pool Manager closes idle connections to enforce the maximum pool size limit. This is the default behavior. If setmaxpoolsizebehavior(hardcap), the total number of active and idle connections cannot exceed the maximum pool size. Instead of creating a new connection for a connection request if an idle connection is unavailable, the Pool Manager queues the connection request until a connection is available or the request times out. This behavior is useful if your database server has memory limitations or is licensed for only a specific number of connections.the timeout is set using the LoginTimeout connection property. If the connection request times out, the driver throws an exception. See "Configuring the Maximum Pool Size" for more information about how the Pool Manager implements the maximum pool size. Sets the value of the minimum pool size, which is the minimum number of idle connections to be kept in the connection pool. Sets the value in seconds of the property cycle, which specifies how often the pool maintenance thread wakes up and checks the connection pool. Enables or disables tracing. If set to true, tracing is enabled; if false, it is disabled. If enabled, tracing information is sent to the PrintWriter that is passed to the setlogwriter() method or the standard output System.out if the setlogwriter() method is not called. See also Configuring the Maximum Pool Size on page 76 ConnectionPoolMonitor The ConnectionPoolMonitor interface is used to return information that is useful for monitoring the status of your connection pools. 83

84 Chapter 3: Using the Driver ConnectionPoolMonitor Methods String getname() Description 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 the PooledConnectionDataSource object from which the pooled connection was obtained user_id is the user ID used to establish the connections contained in the pool. int getnumactive() int getnumavailable() int getinitialpoolsize() int getmaxpoolsize() int getminpoolsize() int getpoolsize() Returns the number of connections that have been checked out of the pool and are currently in use. Returns the number of connections that are idle in the pool (available connections). Returns the initial size of the connection pool (the number of available connections in the pool when the pool was first created). Returns the maximum number of available connection in the connection pool. If the number of available connections exceeds this value, the Pool Manager removes one or multiple available connections from the pool. Returns the minimum number of available connections in the connection pool. When the number of available connections is lower than this value, the Pool Manager creates additional connections and makes them available. Returns the current size of the connection pool, which is the total of active connections and available connections. Statement Pool Monitor The driver supports the DataDirect Statement Pool Monitor. You can use the Statement Pool Monitor to load statements into and remove statements from the statement pool as well as generate information to help you troubleshoot statement pooling performance. The Statement Pool Monitor is an integrated component of the driver, and you can manage statement pooling directly with DataDirect-specific methods. In addition, the Statement Pool Monitor can be enabled as a Java Management Extensions (JMX) MBean. When enabled as a JMX MBean, the Statement Pool Monitor can be used to manage statement pooling with standard JMX API calls, and it can easily be used by JMX-compliant tools, such as JConsole. 84

85 Statement Pool Monitor Using DataDirect-Specific Methods to Access the Statement Pool Monitor To access the Statement Pool Monitor using DataDirect-specific methods, you should first enable statement pooling. You can enable statement pooling by setting the MaxPooledStatements connection property to a value greater than zero (0). The ExtConnection.getStatementPoolMonitor() method returns an ExtStatementPoolMonitor object for the statement pool associated with the connection. This method is provided by the ExtConnection interface in the com.ddtek.jdbc.extensions package. If the connection does not have a statement pool, the method returns null. Once you have an ExtStatementPoolMonitor object, you can use the poolentries() method of the ExtStatementPoolMonitorMBean interface implemented by the ExtStatementPoolMonitor to return a list of statements in the statement pool as an array. See also MaxPooledStatements on page 145 Using the poolentries Method Using the poolentries() method, your application can return all statements in the pool or filter the list based on the following criteria: Statement type (prepared statement or callable statement) Result set type (forward only, scroll insensitive, or scroll sensitive) Concurrency type of the result set (read only and updateable) The following table lists the parameters and the valid values supported by the poolentries() method. Table 24: poolentries() Parameters Parameter statementtype resultsettype Value ExtStatementPoolMonitor.TYPE_PREPARED_STATEMENT ExtStatementPoolMonitor.TYPE_CALLABLE_STATEMENT -1 ResultSet.TYPE_FORWARD_ONLY ResultSet.TYPE_SCROLL_INSENSITIVE ResultSet.TYPE_SCROLL_SENSITIVE -1 Description Returns only prepared statements Returns only callable statements Returns all statements regardless of statement type Returns only statements with forward-only result sets Returns only statements with scroll insensitive result sets Returns only statements with scroll sensitive result sets Returns statements regardless of result set type 85

86 Chapter 3: Using the Driver Parameter Value Description resultsetconcurrency ResultSet.CONCUR_READ_ONLY ResultSet.CONCUR_UPDATABLE -1 Returns only statements with a read-only result set concurrency Returns only statements with an updateable result set concurrency Returns statements regardless of result set concurrency type The result of the poolentries() method is an array that contains a String entry for each statement in the statement 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 names that will be returned as generated keys. For example: SQL_TEXT=[INSERT INTO emp(id, name) VALUES(99,?)]; STATEMENT_TYPE=Prepared Statement;RESULTSET_TYPE=Forward Only; RESULTSET_CONCURRENCY=ReadOnly;AUTOGENERATEDKEYSREQUESTED=false; REQUESTEDKEYCOLUMNS=id,name Generating a List of Statements in the Statement Pool The following code shows how to return an ExtStatementPoolMonitor object using a connection and how to generate a list of statements in the statement pool associated with the connection. private void run(string[] args) { Connection con = null; PreparedStatement prepstmt = null; String sql = null; try { // Create the connection and enable statement pooling Class.forName("com.ddtek.jdbc.cassandra.CassandraDriver"); con = DriverManager.getConnection( "jdbc:datadirect:cassandra://myserver:9042;" + "KeyspaceName=MyKS" + "RegisterStatementPoolMonitorMBean=true;" + "MaxPooledStatements=10", "test", "test"); // Prepare a couple of 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()); 86

87 Statement Pool Monitor System.out.println("Hit Count: System.out.println("Miss Count: 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) {} } } } " + monitor.gethitcount()); " + monitor.getmisscount()); In the previous code example, the PoolEntries() method returns all statements in the statement pool regardless of statement type, result set cursor type, and concurrency type by specifying the value -1 for each parameter as shown in the following code: ArrayList statements = monitor.poolentries(-1, -1, -1); We could have easily filtered the list of statements to return only prepared statements that have a forward-only result 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 Statement Pool Monitor as a JMX MBean. To enable the Statement Pool Monitor as an MBean, statement pooling must be enabled with the MaxPooled Statements propery, and the Statement Pool Monitor MBean must be registered using the RegisterStatementPoolMonitorMBean property. When the Statement Pool Monitor is enabled, the driver registers a single MBean for each statement pool. The registered MBean name has the following form, where monitor_name is the string returned by the ExtStatementPoolMonitor.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 can prevent garbage collection on connections if the connections are not properly closed. When garbage collection does 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 the com.ddtek.jdbc domain and search through the list for the StatementPoolMonitor type attribute. The following code 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"); 87

88 Chapter 3: Using the Driver } 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); } See also MaxPooledStatements on page 145 RegisterStatementPoolMonitorMBean on page

89 Statement Pool Monitor Importing Statements into a Statement Pool When importing statements into a statement pool, for each statement entry in the export file, a statement is added to the statement pool provided a statement with the same SQL text and statement attributes does not already exist in the statement pool. Existing statements in the pool that correspond to a statement entry are kept in the pool unless the addition of new statements causes the number of statements to exceed the maximum pool size. In this case, the driver closes and discards some statements until the pool size is shrunk to the maximum pool size. For example, if the maximum number of statements allowed for a statement pool is 10 and the number of statements to be imported is 20, only the last 10 imported statements are placed in the statement pool. The other statements are created, closed, and discarded. Importing more statements than the maximum number of statements allowed in the statement pool can negatively affect performance because the driver unnecessarily creates some statements that are never placed in the pool. To import statements into a statement pool: 1. Create a statement pool export file. See the "Statement Pool Export File Example" topic for an example of a statement pool export file. Note: The easiest way to create a statement pool export file is to generate an export file from the statement pool associated with the connection as described in "Generating a Statement Pool Export File." 2. Edit the export file to contain statements to be added to the statement pool. 3. Import the contents of the export file to the statement pool using either of the following methods to specify the path and file name of the export file: Use the ImportStatementPool property. For example: jdbc:datadirect:cassandra://myserver:9042; KeyspaceName=MyKS;User=admin;Password=secret; ImportStatementPool=C:\\statement_pooling\\stmt_export.txt Use the importstatements() method of the ExtStatementPoolMonitorMBean interface. For example: ExtStatementPoolMonitor monitor = ((ExtConnection) con).getstatementpoolmonitor().importstatements ("C:\\statement_pooling\\stmt_export.txt"); See also Statement Pool Export File Example on page 170 Generating a Statement Pool Export File on page 90 Clearing All Statements in a Statement Pool To close and discard all statements in a statement pool, use the emptypool() method of the ExtStatementPoolMonitorMBean interface. For example: ExtStatementPoolMonitor monitor = ((ExtConnection) con).getstatementpoolmonitor().emptypool(); 89

90 Chapter 3: Using the Driver 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 the pool was frozen. For example, perhaps you have a core set of statements that you do not want replaced by new statements when your core statements are closed. You can freeze the pool using the setfrozen() method: ExtStatementPoolMonitor monitor = ((ExtConnection) con).getstatementpoolmonitor().setfrozen(true); Similarly, you can use the same method to unfreeze the statement pool: ExtStatementPoolMonitor monitor = ((ExtConnection) con).getstatementpoolmonitor().setfrozen(false); When the statement pool is frozen, your application can still clear the pool and import statements into the pool. In addition, if your application is using Java SE 6 or higher, you can use the Statement.setPoolable() method to add or remove single statements from the pool regardless of the pool s frozen state, assuming the pool is not full. If the pool is frozen and the number of statements in the pool is the maximum, no statements can be added to the 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 the file 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 statement pool performance. To generate a statement pool export file, use the exportstatements() method of the ExtStatementPoolMonitorMBean interface. For example, the following code exports the contents of the statement 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 also Statement Pool Export File Example on page 170 DataDirect Statement Pool Monitor Interfaces and Classes This section describes the methods used by the DataDirect Statement Pool Monitor interfaces and classes. 90

91 Statement Pool Monitor ExtStatementPoolMonitor Class This class is used to control and monitor a single statement pool. This class implements the ExtStatementPoolMonitorMBean interface. ExtStatementPoolMonitorMBean Interface ExtStatementPoolMonitorMBean Methods Description String getname() int getcurrentsize() long gethitcount() long getmisscount() int getmaxsize() int setmaxsize(int value) void emptypool() Returns the name of a Statement Pool Monitor instance associated with the connection. The name is comprised of the name of the driver that established the connection, and the name and port of the server to which the Statement Pool Monitor is connected, and the MBean ID of the connection. Returns the total number of statements cached in the statement pool. Returns the hit count for the statement pool. The hit count is the number of times a lookup is performed for a statement that results in a cache hit. A cache hit occurs when the Statement Pool Monitor successfully finds a statement in the pool with the same SQL text, statement type, result set type, result set concurrency, and requested generated key information. This method is useful to determine if your workload is using the statement pool effectively. For example, if the hit count is low, the statement pool is probably not being used to its best advantage. Returns the miss count for the statement pool. The miss count is the number of times a lookup is performed for a statement that fails to result in a cache hit. A cache hit occurs when the Statement Pool Monitor successfully finds a statement in the pool with the same SQL text, statement type, result set type, result set concurrency, and requested generated key information. This method is useful to determine if your workload is using the statement pool effectively. For example, if the miss count is high, the statement pool is probably not being used to its best advantage. Returns the maximum number of statements that can be stored in the statement pool. Changes the maximum number of statements that can be stored in the statement pool to the specified value. Closes and discards all the statements in the statement pool. 91

92 Chapter 3: Using the Driver ExtStatementPoolMonitorMBean Methods Description void resetcounts() Resets the hit and miss counts to zero (0). See long gethitcount() and long getmisscount() for more information. ArrayList poolentries(int statementtype, int resultsettype, int resultsetconcurrency) Returns a list of statements in the pool. The list is an array that contains a String entry for each statement in the statement pool. void exportstatements(file file_object) void exportstatements(string file_name) void importstatements(file file_object) void importstatements(string file_name) boolean isfrozen() void setfrozen(boolean) Exports statements from the statement pool into the specified file. The file format contains an entry for each statement in the statement pool. Exports statements from statement pool into the specified file. The file format contains an entry for each statement in the statement pool. Imports statements from the specified File object into the statement pool. Imports statements from the specified file into the statement pool. Returns whether the state of the statement pool is frozen. When the statement pool is frozen, the statements that can be stored in the pool are restricted to those that were in the pool at the time the pool was frozen. Freezing a pool is useful if you have a core set of statements that you do not want replaced by other statements when the core statements are closed. setfrozen(true) freezes the statement pool. setfrozen(false) unfreezes the statement pool. When the statement pool is frozen, the statements that can be stored in the pool are restricted to those that were in the pool at the time the pool was frozen. Freezing a pool is useful if you have a core set of statements that you do not want replaced by other statements when the core statements are closed. DataDirect Test Use DataDirect Test to test your JDBC applications and learn the JDBC API. DataDirect Test contains menu selections that correspond to specific JDBC functions, for example, connecting to a database or passing a SQL 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 easily perform some common tasks, such as returning result sets 92

93 DataDirect Test Display the results of all JDBC function calls in one window, while displaying fully commented, JDBC code in 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 JDBC API) and assumes that you can connect to a database with the standard available demo table or fine-tune the sample 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 functionality described may not apply to the driver or data store you are using. Additionally, examples are drawn from a variety 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 forget to add these steps when you use equivalent code in your applications. Configuring DataDirect Test The 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: Drivers DefaultDriver Databases InitialContextFactory ContextProviderURL Datasources A list of colon-separated JDBC driver classes. The default JDBC driver that appears in the Get Driver URL window. A list of comma-separated JDBC URLs. The first item in the list appears as the default in the Database Selection window. You can use one of these URLs as a template when you make a JDBC connection. The default Config.txt file contains example URLs for most databases. Set to com.sun.jndi.fscontext.reffscontextfactory if you are using file system data sources, or com.sun.jndi.ldap.ldapctxfactory if you are using LDAP. The location of the.bindings file if you are using file system data sources, or your LDAP Provider URL if you are using LDAP. A list of comma-separated JDBC data sources. The first item in the list appears as the default in the Data Source Selection window. 93

94 Chapter 3: Using the Driver To connect using a data source, DataDirect Test needs to access a JNDI data store to persist the data source information. By default, DataDirect Test is configured to use the JNDI File System Service Provider to persist the data source. You can download the JNDI File System Service Provider from the Oracle Java Platform Technology Downloads page. Make sure that the fscontext.jar and providerutil.jar files from the download are on your classpath. Starting DataDirect Test How you start DataDirect Test depends on your platform: As a Java application on Windows. Run the testforjdbc.bat file located in the testforjdbc subdirectory of your product installation directory. As a Java application on Linux/UNIX. Run the testforjdbc.sh shell script located in the testforjdbc subdirectory in the installation directory. After you start DataDirect Test, the Test for JDBC Tool window appears. The main Test for JDBC Tool window shows the following information: In the Connection List box, a list of available connections. In the JDBC/Database Output scroll box, a report indicating whether the last action succeeded or failed. In the Java Code scroll box, the actual Java code used to implement the last action. Tip: DataDirect Test windows contain two Concatenate check boxes. Select a Concatenate check box to see a cumulative record of previous actions; otherwise, only the last action is shown. Selecting Concatenate can degrade performance, particularly when displaying large result sets. 94

95 DataDirect Test Connecting Using DataDirect Test You 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 source information. By default, DataDirect Test is configured to use the JNDI File System Service Provider to persist the data source. You can download the JNDI File System Service Provider from the Oracle Java Platform Technology 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, type values for the User and Password connection properties; then, click Connect. For information about JDBC connection properties, refer to your driver's connection property descriptions. 3. If the connection was successful, the Connection window appears and shows the Connection Established message in the JDBC/Database Output scroll box. 95

96 Chapter 3: Using the Driver Connecting Using Database Selection To connect using database selection: 1. From the Test for JDBC Tool window menu, select Driver / Register Driver. DataDirect Test prompts for a JDBC driver name. 2. In the Please Supply a Driver URL field, specify a driver (for example com.ddtek.jdbc.sqlserver.sqlserverdriver); then, click OK. If the driver was registered successfully, the Test for JDBC Tool window appears with a confirmation in the JDBC/Database Output scroll box. 3. From the Test for JDBC Tool window, select Connection / Connect to DB. The Select A Database window 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 the connection URL appropriately for your environment. Note: There are two entries for DB2: one with locationname and another with databasename. If you are connecting to DB2 for Linux/UNIX/Windows, select the entry containing databasename. If you are connecting to 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 connection property descriptions. 6. If the connection was successful, the Connection window appears and shows the Connection Established message in the JDBC/Database Output scroll box. 96

97 DataDirect Test Executing a Simple Select Statement This 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 window indicates that the creation of the statement was successful. 2. Select Statement / Execute Stmt Query. DataDirect Test displays a dialog box that prompts for a SQL statement. 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 Output scroll box. 97

98 Chapter 3: Using the Driver 5. Scroll through the code in the Java Code scroll box to see which JDBC calls have been implemented by DataDirect Test. Executing a Prepared Statement This 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 Test prompts 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: 98

99 DataDirect Test a) Type the parameter number. b) Select the parameter type. c) Type the parameter value. d) Click Set to pass this information to the JDBC driver. 4. When you are finished, click Close. 5. Select Statement / Execute Stmt Update. The JDBC/Database Output scroll box indicates that one row has been inserted. 99

100 Chapter 3: Using the Driver 6. If you want to insert multiple records, repeat Step 3 on page 98 and Step 5 on page 99 for each record. 7. If you repeat the steps described in "Executing a Simple Select Statement," you will see that the previously inserted records are also returned. 100

101 DataDirect Test See also Executing a Simple Select Statement on page 97 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 are connected is returned. 101

102 Chapter 3: Using the Driver 3. Scroll through the Java code in the Java Code scroll box to find out which JDBC calls have been implemented by 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 test Select MetaData / Tables. 5. In the Schema Pattern field, type test Click Ok. The Connection window indicates that gettables() succeeded. 7. Select Results / Show All Results. All tables with a test01 schema pattern are returned. 102

103 DataDirect Test Scrolling Through a Result Set 1. From the Connection window menu, select Connection / Create JDBC 2.0 Statement. DataDirect Test prompts for a result set type and concurrency. 2. Complete the following fields: a) In the resultsettype field, select TYPE_SCROLL_SENSITIVE. b) In the resultsetconcurrency field, select CONCUR_READ_ONLY. c) Click Submit; then, click Close. 3. Select Statement / Execute Stmt Query. 4. Type a Select statement and click Submit. Then, click Close. 103

104 Chapter 3: Using the Driver 5. Select Results / Scroll Results. The Scroll Result Set window indicates that the cursor is positioned before the first row. 6. Click the Absolute, Relative, Before, First, Prev, Next, Last, and After buttons as appropriate to navigate through the result set. After each action, the Scroll Result Set window displays the data at the current position of the cursor. 104

105 DataDirect Test 7. Click Close. Batch Execution on a Prepared Statement Batch execution on a prepared statement allows you to update or insert multiple records simultaneously. In some cases, this can significantly improve system performance because fewer round trips to the database are required. 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. 105

106 Chapter 3: Using the Driver 4. Click Add to add the specified set of parameters to the batch. To add multiple parameter sets to the batch, repeat Step 2 on page 105 through Step 4 on page 106 as many times as necessary. When you are finished adding parameter sets to the batch, click Close. 5. Select Statement / Execute Stmt Batch. DataDirect Test displays the rowcount for each of the elements in the batch. 6. If you re-execute the Select statement from "Executing a Simple Select Statement," you see that the previously inserted records are returned. 106

107 DataDirect Test See also Executing a Simple Select Statement on page 97 Returning ParameterMetaData Note: Returning ParameterMetaData requires a Java SE 5 or higher JVM. 1. From the Connection window menu, select Connection / Create Prepared Statement. Type the prepared statement and click Submit. Then, click Close. 2. Select Statement / Get ParameterMetaData. The Connection window displays ParameterMetaData. 107

108 Chapter 3: Using the Driver Establishing Savepoints Note: Savepoints require a Java SE 5 or higher JVM. 1. From the Connection window menu, select Connection / Connection Properties. 2. Select TRANSACTION_COMMITTED from the Transaction Isolation drop-down list. Do not select the Auto Commit check box. 3. Click Set; then, click Close. 4. From the Connection window menu, select Connection / Load and Go. The Get Load And Go SQL window appears. 5. Type a statement and click Submit. 108

109 DataDirect Test 6. Select Connection / Set Savepoint. 7. In the Set Savepoints window, type a savepoint name. 8. Click Apply; then, click Close. The Connection window indicates whether or not the savepoint succeeded. 9. Return to the Get Load And Go SQL window and specify another statement. Click Submit. 109

110 Chapter 3: Using the Driver 10. Select Connection / Rollback Savepoint. In the Rollback Savepoints window, specify the savepoint name. 11. Click Apply; then, click Close. The Connection window indicates whether or not the savepoint rollback succeeded. 12. Return to the Get Load And Go SQL window and specify another statement. 110

111 DataDirect Test Click Submit; then, click Close. The Connection window displays the data inserted before the first Savepoint. The second insert was rolled back. Updatable Result Sets The 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. 2. Complete the following fields: a) In the resultsettype field, select TYPE_SCROLL_SENSITIVE. b) In the resultsetconcurrency field, select CONCUR_UPDATABLE. 111

112 Chapter 3: Using the Driver 3. Click Submit; then, click Close. 4. Select Statement / Execute Stmt Query. 5. Specify the Select statement and click Submit. Then, click Close. 6. Select Results / Inspect Results. The Inspect Result Set window appears. 112

113 DataDirect Test 7. Click Next. Current Row changes to Click Delete Row. 9. To verify the result, return to the Connection menu and select Connection / Load and Go. The Get Load And Go SQL window appears. 10. Specify the statement that you want to execute and click Submit. Then, click Close. 113

114 Chapter 3: Using the Driver 11. The Connection window shows that the row has been deleted. Inserting a Row 1. From the Connection window menu, select Connection / Create JDBC 2.0 Statement. 2. Complete the following fields: a) In the resultsettype field, select TYPE_SCROLL_SENSITIVE. b) In the resultsetconcurrency field, select CONCUR_UPDATABLE. 114

115 DataDirect Test 3. Click Submit; then, click Close. 4. Select Statement / Execute Stmt Query. 5. Specify the Select statement that you want to execute and click Submit. Then, click Close. 6. Select Results / Inspect Results. The Inspect Result Set window appears. 115

116 Chapter 3: Using the Driver 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. 12. To verify the result, return to the Connection menu and select Connection / Load and Go. The Get Load And Go SQL window appears. 13. Specify the statement that you want to execute and click Submit. Then, click Close. 116

117 DataDirect Test 14. The Connection window shows the newly inserted row. Caution: The ID will be 3 for the row you just inserted because it is an auto increment column. Updating a Row 1. From the Connection window menu, select Connection / Create JDBC 2.0 Statement. 2. Complete the following fields: a) In the resultsettype field, select TYPE_SCROLL_SENSITIVE. b) In the resultsetconcurrency field, select CONCUR_UPDATABLE. 117

118 Chapter 3: Using the Driver 3. Click Submit; then, click Close. 4. Select Statement / Execute Stmt Query. 5. Specify the Select statement that you want to execute. 6. Click Submit; then, click Close. 7. Select Results / Inspect Results. The Inspect Result Set window appears. 118

119 DataDirect Test 8. Click Next. Current Row changes to In Set Cell Value, type RALEIGH. Then, click Set Cell. 10. Click Update Row. 11. To verify the result, return to the Connection menu and select Connection / Load and Go. The Get Load And Go SQL window appears. 12. Specify the statement that you want to execute. 119

120 Chapter 3: Using the Driver 13. Click Submit; then, click Close. 14. The Connection window shows LOC for accounting changed from NEW YORK to RALEIGH. Retrieving Large Object Data Note: LOB support (Blobs and Clobs) requires a Java SE 5 or higher JVM. The following example uses Clob data; however, this procedure also applies to Blob data. This example illustrates only one of multiple ways in which LOB data can be processed. 1. From the Connection window menu, select Connection / Create Statement. 2. Select Statement / Execute Stmt Query. 3. Specify the Select statement that you want to execute. 120

121 DataDirect Test 4. Click Submit; then, click Close. 5. Select Results / Inspect Results. The Inspect Result Set window appears. 6. Click Next. Current Row changes to Deselect Auto Traverse. This disables automatic traversal to the next row. 121

122 Chapter 3: Using the Driver 8. Click Get Cell. Values are returned in the Get Cell Value field. 9. Change the data type to Clob. 122

123 DataDirect Test 10. Click Get Cell. The Clob data window appears. 123

124 Chapter 3: Using the Driver 11. Click Get Cell. Values are returned in the Cell Value field. 124