README
     Progress(R) DataDirect(R)
     Progress(R) DataDirect Connect XE(R) for JDBC(TM) for Impala(TM) Driver
     Release 5.1.4
     December 2017


***********************************************************************
Copyright (C) 1994-2017 Progress and/or its 
subsidiaries or affiliates. All Rights Reserved.

***********************************************************************


CONTENTS

Requirements
Installation Directory
Changes since Service Pack 4
Changes for Service Pack 4
Features
Notes, Known Problems, and Restrictions
Documentation
Installed Files


     Requirements

Java SE 5 or higher must be installed and the JVM must be defined on your system
path.


     Installation Directory

The default installation directory for the driver is:

* Windows:
  C:\Program Files\Progress\DataDirect\JDBC_51

* UNIX/Linux:
  /opt/Progress/DataDirect/JDBC_51
  Note: For UNIX/Linux, if you do not have access to "/opt", your user's
  directory should be used in place of this directory.


     Changes since Service Pack 4

Certifications
--------------
* The driver has been certified with Cloudera Impala 2.4, 2.5, and 2.6.
  Driver version 5.1.4.000083 (F000302.U000131)

* The driver has been certified with Cloudera Impala 2.2 and 2.3.
  Driver version 5.1.4.000062 (F000260.U000115)

SSL Data Encryption
-------------------
The driver has been enhanced to support SSL data encryption. See 
"Configuring SSL Data Encrption" in the "Notes, Known Problems, and 
Restrictions" for detailed information.
  
Statement Pooling
-----------------
The driver no longer registers the Statement Pool Monitor as a JMX MBean by
default. To register the Statement Pool Monitor and manage statement pooling with
standard JMX API calls, the new RegisterStatementPoolMonitorMBean connection
property must be set to true. See "Notes, Known Problems, and Restrictions" for
details.


     Changes for Service Pack 4

Certifications
--------------
The driver has been certified with Cloudera Impala 2.0 and 2.1.

Data Types
----------
The driver has been enhanced to support the Char and Vachar data type with
Cloudera Impala 2.1 and higher.

Result Set Holdability
----------------------
Support for result set holdability has been added to the driver. 


     Features

The driver supports standard SQL query language for read-write access to
Cloudera Impala data stores, versions 1.3 and higher. By using DataDirect's Wire
Protocol technology, the driver eliminates the need for client libraries,
improving response time and throughput. 

* The driver supports all JDBC Core functions.

* The driver supports the core SQL-92 grammar.

* The driver supports the following data types:
  - BIGINT        maps to     BIGINT
  - BOOLEAN       maps to     BOOLEAN
  - CHAR          maps to     CHAR
  - DECIMAL       maps to     DECIMAL
  - DOUBLE        maps to     DOUBLE
  - FLOAT         maps to     REAL
  - INT           maps to     INTEGER
  - SMALLINT      maps to     SMALLINT
  - STRING        maps to     VARCHAR (or LONGVARCHAR)
  - TIMESTAMP     maps to     TIMESTAMP
  - TINYINT       maps to     TINYINT
  - VARCHAR       maps to     VARCHAR

* The driver package includes the following components:
  - DataDirect Connection Pool Manager
  - DataDirect Statement Pool Monitor
  - DataDirect Test for JDBC
  - DataDirect Spy for JDBC


     Notes, Known Problems, and Restrictions

The following are notes, known problems, and restrictions with the driver.

Configuring SSL Data Encrption
------------------------------
The following steps outline how to configure SSL encryption.

1. Set the EncryptionMethod property to SSL.
2. Use the CryptoProtocolVersion property to specify acceptable cryptographic 
   protocol versions (for example, TLSv1.2) supported by your server.
3. Specify the location and password of the truststore file used for SSL server
   authentication. Either set the TrustStore and TrustStorePassword properties 
   or their corresponding Java system properties (javax.net.ssl.trustStore and 
   javax.net.ssl.trustStorePassword, respectively).
4. To validate certificates sent by the database server, set the 
   ValidateServerCertificate property to true.
5. Optionally, set the HostNameInCertificate property to a host name to be used
   to validate the certificate. 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.
6. If your database server is configured for SSL client authentication, 
   configure your keystore information:
   a. Specify the location and password of the keystore file. Either set the 
      KeyStore and 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 "SSL Data Encryption Properties" for full descriptions of these properties. 	  
	  
SSL Data Encrpyption Properties
---------------------------------
The following options are used to configure SSL Data Encryption.

* CryptoProtocolVersion

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

  Valid Values:
  <cryptographic_protocol> [[, <cryptographic_protocol> ]...]

  where:
  <cryptographic_protocol>
    is one of the following cryptographic protocols:

  TLSv1.2 | TLSv1.1 | TLSv1 | SSLv3 | SSLv2

  Caution: To avoid vulnerabilities associated with SSLv3 and SSLv2, good 
           security practices recommend using TLSv1 or higher.

  Example:
  If your server supports TLSv1.1 and TLSv1.2, you can specify acceptable 
  cryptographic protocols with the following key-value pair:
  CryptoProtocolVersion=TLSv1.1,TLSv1.2

  Notes:
  * When multiple protocols are specified, the driver uses the highest version
    supported by the server. If none of the specified protocols are supported 
	by the server, the connection fails and the driver returns an error.
  * When no value has been specified for CryptoProtocolVersion, the driver 
    establishes an SSL connection using the default. If the default is not 
	supported by the server, the connection fails and the driver returns 
	an error.

  Data Source Method:
  setCryptoProtocolVersion

  Default:
  The default is determined by the settings of the JRE.

  Data Type:
  String

* EncryptionMethod
  
  Purpose:
  Determines whether SSL encryption is used to encrypt and decrypt data 
  transmitted over the network between the driver and database server.

  Valid Values:
  noEncryption | SSL

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

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

  Notes:
  - Connection hangs can occur if the driver attempts to connect to a database 
    server that does not support SSL. You may want to set a login timeout using
	the LoginTimeout property to avoid problems when connecting to a server 
	that does not support SSL.
  - When SSL is enabled, the following properties also apply:
    * CryptoProtocolVersion
    * HostNameInCertificate
    * KeyStore (for SSL client authentication)
    * KeyStorePassword (for SSL client authentication)
    * KeyPassword (for SSL client authentication)
    * TrustStore
    * TrustStorePassword
    * ValidateServerCertificate
  
  Data Source Method:
  setEncryptionMethod

  Default:
  noEncryption

  Data Type:
  String 
  
* HostNameInCertificate

  Purpose:
  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.

  Valid Values:
  <host_name> | #SERVERNAME#

  where:
  <host_name>
    is a valid host name.

  Behavior:
  If <host_name> is specified, the driver compares the specified host name to 
  the DNSName value of the SubjectAlternativeName in the certificate. If a 
  DNSName value does not exist in the SubjectAlternativeName or if the 
  certificate does not have a SubjectAlternativeName, the driver compares the 
  host name with the Common Name (CN) part of the certificate’s Subject name. 
  If the values do not match, the connection fails and the driver throws an 
  exception.

  If #SERVERNAME# is specified, the driver compares the server name specified 
  in the connection URL or data source of the connection to the DNSName value
  of the SubjectAlternativeName in the certificate. If a DNSName value does not
  exist in the SubjectAlternativeName or if the certificate does not have a 
  SubjectAlternativeName, the driver compares the host name to the CN part of 
  the certificate’s Subject name. If the values do not match, the connection 
  fails and the driver throws an exception. If multiple CN parts are present, 
  the driver validates the host name against each CN part. If any one 
  validation succeeds, a connection is established.
  
  Notes:
  * If SSL encryption or certificate validation is not enabled, this property 
    is ignored.
  * If SSL encryption and validation is enabled and this property is 
    unspecified, the driver uses the server name specified in the connection 
	URL or data source of the connection to validate the certificate.

  Data Source Method:
  setHostNameInCertificate

  Default:
  empty string

  Data Type:
  String
  
* KeyPassword

  Purpose:
  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.
  
  Valid Values:
  <string>

  where:
  <string>
    is a valid password.

  Data Source Method:
  setKeyPassword

  Default:
  None
 
  Data Type:
  String

* KeyStore

  Purpose:
  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.

  This value overrides the directory of the keystore file that is specified by 
  the javax.net.ssl.keyStore Java system property. If this property is not 
  specified, the keystore directory is specified by the javax.net.ssl.keyStore 
  Java system property.

  Valid Values:
  <string>
  
  where:
  <string>
    is a valid directory of a keystore file.

  Notes:
  * The keystore and truststore files can be the same file.

  Data Source Method:
  setKeyStore

  Default:
  None

  Data Type:
  String
  
* TrustStore

  Purpose:
  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.
  
  This value overrides the directory of the truststore file that is specified 
  by the javax.net.ssl.trustStore Java system property. If this property is not
  specified, the truststore directory is specified by the 
  javax.net.ssl.trustStore Java system property.
  
  This property is ignored if ValidateServerCertificate=false.

  Valid Values:
  <string>

  where:
  <string>
    is the directory of the truststore file.

  Data Source Method:
  setTrustStore

  Default:
  None

  Data Type
  String
  
* TrustStorePassword

  Purpose:
  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.

  This value overrides the password of the truststore file that is specified by
  the javax.net.ssl.trustStorePassword Java system property. If this property 
  is not specified, the truststore password is specified by the 
  javax.net.ssl.trustStorePassword Java system property.

  This property is ignored if ValidateServerCertificate=false.

  Valid Values:
  <string>

  where:
  <string>
    is a valid password for the truststore file.

  Data Source Method:
  setTrustStorePassword

  Default:
  None

  Data Type:
  String

* ValidateServerCertificate
 
  Purpose:
  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). Allowing the driver 
  to trust any certificate that is returned from the server even if the issuer 
  is not a trusted CA is useful in test environments because it eliminates the 
  need to specify truststore information on each client in the 
  test environment.
  
  Valid Values:
  true | false

  Behavior:
  If set to true, the driver validates the certificate that is sent by the 
  database server. Any certificate from the server must be issued by a trusted 
  CA in the truststore file. If the HostNameInCertificate property is 
  specified, the driver also validates the certificate using a host name. The 
  HostNameInCertificate property is optional 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.

  If set to false, the driver does not validate the certificate that is sent by
  the database server. The driver ignores any truststore information that is 
  specified by the TrustStore and TrustStorePassword properties or Java system 
  properties.
  
  Notes:
  * Truststore information is specified using the TrustStore and 
    TrustStorePassword properties or by using Java system properties.

  Data Source Method:
  setValidateServerCertificate

  Default:
  true

  Data Type:
  boolean
  
Statement Pooling 
-----------------
* The RegisterStatementPoolMonitorMBean connection property 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.
  - Valid values are true | false
  - If set to true, the driver registers an MBean for the statement pool monitor
    for each statement pool. This gives applications access to the Statement
    Pool Monitor through JMX when statement pooling is enabled.
  - If set to false, the driver does not register an MBean for the Statement Pool
    Monitor for any statement pool.
  - 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.
  - The default is false.
  - The data type is boolean.

Cloudera Impala Limitations 
---------------------------
* Cloudera Impala is not designed for OLTP workloads and does not offer
  row-level updates or deletes. Cloudera Impala is instead designed for batch
  type jobs over large data sets with high latency.

* Cloudera Impala does not support transactions, and by default, the driver
  reports that transactions are not supported. However, some applications will 
  not operate with a driver that reports transactions are not supported. The
  TransactionMode connection property allows you to configure the driver to
  report that it supports transactions. In this mode, the driver ignores
  requests to enter manual commit mode, start a transaction, or commit a 
  transaction and return success. Requests to rollback a transaction return an
  error regardless of the transaction mode specified.

* Cloudera Impala Functional Limitations
  - No support for transactions
  - No support for canceling a running query
  - No support for row-level updates or deletes
  - No support for stored procedures
  - No support for auto-generated keys

* Cloudera Impala uses a subset of SQL and HiveQL, which provides much of the
  functionality of SQL, and therefore has some differences and limitations.
  - Column values and parameters are always nullable.
  - No support for row-level updates or deletes
  - Subqueries are supported, but they can only exist in the FROM and WHERE
    clauses.
  - No support for stored procedures
  - No ROWID support
  - No support for materialized views
  - No support for synonyms
  - Primary and foreign keys are not supported.
  - Support for indexes is incomplete.
  - A single quote within a string literal must be escaped using a \ instead
    of using a single quote.
  For more information, refer to the Impala SQL Language Reference: 
  http://www.cloudera.com/content/cloudera/en/documentation/cloudera-impala/
  latest/topics/impala_langref.html

Executing JDBC Shell Scripts
----------------------------
For UNIX users: If you receive an error message when executing any DataDirect
for JDBC shell script, make sure that the file has EXECUTE permission. To do
this, use the chmod command. For example, to grant EXECUTE permission to the
testforjdbc.sh file, change to the directory containing testforjdbc.sh and
enter: chmod +x testforjdbc.sh

Clob Data Type Support  
----------------------
The driver allows PreparedStatement.setXXX methods and ResultSet.getXXX
methods on Clob data types, in addition to the functionality described in
the JDBC specification. The supported conversions typically are the same as
those for LONGVARCHAR, except where limited by database support.

Performance Wizard
------------------
The Performance Tuning Wizard is not available with the driver. For
information on tuning the driver for performance, see the "Performance
Considerations" topic in the help system.

Internet Explorer with the Google Toolbar 
-----------------------------------------
Internet Explorer with the Google Toolbar installed sometimes displays the
following error when the browser is closed: "An error has occurred in the
script on this page." This is a known issue with the Google Toolbar and has
been reported to Google. When closing the driver's help system, this error may
display.


     Documentation

The PROGRESS DATADIRECT FOR JDBC FOR IMPALA DRIVER USER'S GUIDE is available as
an HTML help system and as a PDF.

* The HTML version of the USER'S GUIDE is installed in the ImpalaHelp
  subdirectory of your product installation directory. This help system is also
  available on the Progress DataDirect Web site:
  https://www.progress.com/resources/documentation/by-data-source

* The PDF version of the USER'S GUIDE is available on the Progress DataDirect
  Web site:
  https://www.progress.com/resources/documentation/by-data-source


     Installed Files

When you extract the contents of the installation download package to your
installer directory, you will notice the following files that are required to
install the driver:

*  Windows:
   - PROGRESS_DATADIRECT_JDBC_INSTALL.exe
   - PROGRESS_DATADIRECT_JDBC_IMPALA_5.1.4_INSTALL.iam.zip
   - PROGRESS_DATADIRECT_JDBC_COMMON_5.1.4_INSTALL.iam.zip
   - PROGRESS_DATADIRECT_JDBC_DOCUMENTATION_5.1.4_INSTALL.iam.zip

*  Non-Windows:
   - PROGRESS_DATADIRECT_JDBC_INSTALL.jar
   - PROGRESS_DATADIRECT_JDBC_IMPALA_5.1.4_INSTALL.iam.zip
   - PROGRESS_DATADIRECT_JDBC_COMMON_5.1.4_INSTALL.iam.zip
   - PROGRESS_DATADIRECT_JDBC_DOCUMENTATION_5.1.4_INSTALL.iam.zip

When you install the driver, the installer creates the following directories and
files in the product installation directory in the default installation
directory or in an installation directory you specify, represented by
INSTALL_DIR.


INSTALL_DIR/:
-------------
LicenseTool.jar            Product license file manager

DDProcInfo.exe             Windows executable to start the Processor Information
                           Utility

DDProcInfo                 UNIX/Linux script to start the Processor Information
                           Utility


INSTALL_DIR/Examples/Bulk/:
---------------------------
Load From File/bulkLoadFileDemo.java
                           Java source example for bulk loading from a CSV file

Load From File/load.txt    Sample data for the example

Streaming/bulkLoadStreamingDemo.java
                           Java source example for bulk loading from a result
                           set

Threaded Streaming/bulkLoadThreadedStreamingDemo.java
                           Java source example for multi-threaded bulk loading
                           from a result set

Threaded Streaming/README.txt
                           Instructions on how to use the thread.properties file

Threaded Streaming/thread.properties
                           Properties file for the example


INSTALL_DIR/Examples/Connector/:
--------------------------------
ConnectorSample.ear        J2EE Application Enterprise Archive file containing
                           the ConnectorSample application 

connectorsample.htm        USING DATADIRECT CONNECT FOR JDBC RESOURCE ADAPTERS
                           document

graphics/*.*               Images referenced by the USING DATADIRECT CONNECT FOR
                           JDBC RESOURCE ADAPTERS document

src/ConnectorSample.jsp    Source for the JavaServer Page used to access the
                           ConnectorSample application

src/connectorsample/ConnectorSample.java     
                           Java source file defining the remote interface for
                           the ConnectorSample EJB

src/connectorsample/ConnectorSampleBean.java  
                           Java source file defining the home interface for the
                           ConnectorSample EJB

src/connectorsample/ConnectorSampleHome.java  
                           Java source file containing the implementation for
                           the ConnectorSample EJB


INSTALL_DIR/Examples/JNDI/:
---------------------------
JNDI_FILESYSTEM_Example.java
                           Example Java(TM) source file

JNDI_LDAP_Example.java     Example Java source file


INSTALL_DIR/Examples/SforceSamples/:
------------------------------------
buildsamples.bat           Batch file to build the Salesforce example

buildsamples.sh            Shell script to build the Salesforce example
 
ddlogging.properties       Logging properties file

runsalesforceconnectsample.bat
                           Batch file to run the Salesforce example

runsalesforceconnectsample.sh
                           Shell script to run the Salesforce example

bin/com/ddtek/jdbc/samples/SalesforceConnectSample.class
                           Java example class

bin/com/ddtek/jdbc/samples/SampleException.class
                           Java example class

src/com/ddtek/jdbc/samples/SalesforceConnectSample.java
                           Java source example


INSTALL_DIR/Help/: 
------------------
ImpalaHelp/index.html      Driver HTML help system entry file

ImpalaHelp/*               Support files and folders for the driver help system


INSTALL_DIR/install/: 
---------------------
.psc_dd_inst_reg.xml       Support file for the installation logs

logs/*.*                   Log file generated upon installing or uninstalling


INSTALL_DIR/jre/:
-----------------
*.*                        Files associated with the driver. Installed only when
                           installing on Windows with the Windows executable
                           file.


INSTALL_DIR/lib/:
-----------------
impala.jar                 Impala Driver and DataSource classes


INSTALL_DIR/NOTICES/:
---------------------
JDBC for Impala v5.1.4 notices.txt
                           Third party agreement information


INSTALL_DIR/pool manager/:
--------------------------
pool.jar                   All DataDirect Connection Pool Manager classes


INSTALL_DIR/READMES/:
---------------------
JDBC for Impala v5.1.4 readme.txt
                           This file


INSTALL_DIR/testforjdbc/:
-------------------------
Config.txt                 Configuration file for DataDirect Test

ddlogging.properties       Logging properties file

testforjdbc.bat            Batch file to start DataDirect Test

testforjdbc.sh             Shell script to start DataDirect Test

lib/testforjdbc.jar        DataDirect Test classes


INSTALL_DIR/uninstall/:
-----------------------
.com.zerog.registry.xml    Support file for the uninstaller

.psc_dd_uninst_reg.xml     Support file for the uninstaller

InstallScript.iap_xml      Support file for the uninstaller

installvariables.properties
                           Support file for the Windows uninstaller

uninstall_Progress_DataDirect_for_JDBC_5.1_SP4.exe
                           Windows uninstaller

uninstall_Progress_DataDirect_for_JDBC_5.1_SP4.lax
                           Support file for the Windows uninstaller

uninstaller.jar            Java uninstaller

resource/*.*               Resource files for the Windows uninstaller


8 December 2017
=============
End of README