README
     Progress(R) DataDirect(R)
     Progress(R) DataDirect(R) for JDBC(TM) for Apache Cassandra(TM) Driver
     Release 6.0
     December 2016


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

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


CONTENTS

Requirements
Installation Directory
Changes since GA
Release 6.0 Features
Notes, Known Problems, and Restrictions
Documentation
Installed Files
Third Party Acknowledgements


     Requirements

Java SE 6 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_60

* UNIX/Linux:
  /opt/Progress/DataDirect/JDBC_60
  Note: For UNIX/Linux, if you do not have access to "/opt", your user's home
  directory will take the place of this directory.


     Changes since GA

Note: Refer to the fixes.txt file in the product installation directory for a
list of changes by component build number.

Kerberos Authentication
-----------------------
The driver has been enhanced to support Kerberos authentication. See
"Authentication" in the USER'S GUIDE for detailed information.

SchemaMap Connection Property
-----------------------------
The SchemaDefinition connection property has been replaced with the SchemaMap
connection property.

Certifications
--------------
* Certified against DataStax Enterprise 5.0.

* Certified against Apache Cassandra 3.0 and 3.7.

Tunable Consistency Enhancement
-------------------------------
The driver has been enhanced to support Cassandra's tunable consistency
functionality with the ReadConsistency and WriteConsistency connection
properties.

Dynamic Fetch Enhancement
-------------------------
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.


     Release 6.0 Features

The driver supports SQL read-write access to DataStax Enterprise (4.6 and higher)
and Apache Cassandra (2.0 and higher).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 following metadata methods: getTables(), getColumns(),
getTypeInfo(), getPrimaryKeys(), getExportedKeys(), and getBestRowIdentifier().

* Supports SQL read-write access to DataStax Enterprise (4.6 and higher) and
  Apache Cassandra (2.0 and higher).

* Certified against DataStax Enterprise 4.7 and 4.8.

* Certified against Apache Cassandra 2.0, 2.1, and 2.2.

* Supports JDBC core functions.

* Supports user id/password authentication.

* Supports the following Cassandra data types:
  - ASCII	maps to VARCHAR
  - Bigint	maps to BIGINT
  - Blob	maps to LONGVARBINARY
  - Boolean	maps to BOOLEAN
  - Counter     maps to BIGINT
  - Date        maps to DATE
  - Decimal     maps to DECIMAL
  - Double	maps to DOUBLE
  - Float       maps to REAL
  - Inet        maps to VARCHAR
  - Int         maps to INTEGER
  - List        maps to LONGVARCHAR
  - Map         maps to LONGVARCHAR
  - Set         maps to LONGVARCHAR
  - Smallint    maps to SMALLINT
  - Time        maps to TIME
  - Timestamp   maps to TIMESTAMP
  - TimeUUID	maps to CHAR
  - Tinyint     maps to TINYINT
  - Tuple       maps to LONGVARCHAR
  - Usertype    maps to LONGVARCHAR
  - UUID        maps to CHAR
  - Varchar     maps to VARCHAR
  - Varint      maps to DECIMAL

* Generates a normalized 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.

* Supports Native and Refresh escape sequences to embed CQL commands in SQL-92
  statements.

* Includes the TransactionMode 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.

* Supports Binary Large Objects (BLOBs).

* Supports connection pooling.

* Supports statement pooling.

* Includes the LoginTimeout connection property which allows you to specify how
  long the driver waits for a connection to be established before timing out the
  connection request.


     Notes, Known Problems, and Restrictions

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

Inserts, Updates, and Upserts
-----------------------------
Inserts and Updates are in effect handled as Upserts in Cassandra. If an insert
is performed on a row that already exists, the row will be updated. If an update
is performed on a row that does not exist, the row will be inserted.

Updates on Counter Columns
--------------------------
Update is supported for Counter columns only when all the other columns in the
row comprise that row's primary key. When updating a Counter column on an
existing row, the Counter column is updated according to the increment (or
decrement) specified in the SQL statement. When updating a Counter column for
which there is no existing row, the values of the columns that comprise the row's
primary key are inserted into the table alongside the value of the Counter
column.

Operation Timeouts
------------------
Cassandra imposes timeouts on read and write operations to prevent a given
operation from negatively impacting the performance of the cluster. If you
encounter an operation timeout, you can take the following actions to promote
operation success.

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

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

* Decrease the value of the NativeFetchSize connection property. By decreasing
  NativeFetchSize, you reduce the amount of data that must be transmitted between
  the driver and the native data source. For read operations, the smaller the
  chunks of data requested, the faster the cluster can assemble results for
  transmission to the driver. For write operations, smaller chunks of data allow
  the driver to communicate more efficiently with the native data source and thus
  expedite write operations. Note that setting NativeFetchSize too low negatively
  impacts performance by requiring unnecessary round trips across the network.

* Optimize your operations by taking one or more of the following actions.
  - Limit the number of results returned.
  - Add indexes to Cassandra tables and base operations on indexes as
    appropriate.
  - Use Where clause filtering that can be pushed down to Cassandra, allowing
    operations to be evaluated and handled quickly. See the following DataStax
    Web pages for more information about Where clause functionality and
    limitations.
    - http://www.datastax.com/dev/blog/a-deep-look-to-the-cql-where-clause
    - http://docs.datastax.com/en/cql/3.1/cql/cql_reference/select_r.html?scroll=
      reference_ds_d35_v2q_xj__filtering-data-using-where

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

Out-of-memory Errors
--------------------
The driver has been designed to handle large result sets. However, out-of-memory
errors can occur. The following items outline how to reduce the likelihood of
out-of-memory errors for your environment.

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

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

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

system.indexes collection
-------------------------
The driver hides the system.indexes collection, and tables containing the "$"
character are hidden to prevent naming conflicts.

oplog.rs system table
---------------------
The driver hides the oplog.rs system table.

System.exit() method and Process Termination
--------------------------------------------
The System.exit() method ensures that all registered shutdown hooks are run.
Applications terminate faster when System.exit(0) is used. When applications omit
the System.exit() call, the termination process may linger for about 10 seconds
before exiting.

Executing DataDirect Shell Script
---------------------------------
For UNIX/Linux 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

JDBC Methods
------------
The following notes on JDBC methods apply generally to Progress DataDirect for
JDBC drivers.

* When attempting to create an updatable, scroll-sensitive result set for a
  query that contains an expression as one of the columns, the driver cannot
  satisfy the scroll-sensitive request. The driver downgrades the type of the
  result returned to scroll-insensitive.

* The ResultSet methods getTimestamp(), getDate(), and getTime() return
  references to mutable objects. If the object reference returned from any of
  these methods is modified, re-fetching the column using the same method
  returns the modified value. The value is only modified in memory; the
  database value is not modified.


     Documentation	 	 

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

* The HTML help system is installed in the CassandraHelp subdirectory of your
  product installation directory.

* The HTML help system and the PDF are available on the Progress DataDirect Web
  site:
  https://www.progress.com/resources/documentation/datadirect-documentation


     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_CASSANDRA_6.0.0_INSTALL.iam.zip
   - PROGRESS_DATADIRECT_JDBC_COMMON_6.0.0_INSTALL.iam.zip
   - PROGRESS_DATADIRECT_JDBC_DOCUMENTATION_6.0.0_INSTALL.iam.zip
   - config.properties

*  Non-Windows:
   - PROGRESS_DATADIRECT_JDBC_INSTALL.jar
   - PROGRESS_DATADIRECT_JDBC_CASSANDRA_6.0.0_INSTALL.iam.zip
   - PROGRESS_DATADIRECT_JDBC_COMMON_6.0.0_INSTALL.iam.zip
   - PROGRESS_DATADIRECT_JDBC_DOCUMENTATION_6.0.0_INSTALL.iam.zip
   - config.properties

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/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/:
-----------------
cassandra.jar              Apache Cassandra Driver and DataSource classes

JDBCDriverLogin.conf       The JAAS login configuration file installed with the
                           driver


INSTALL_DIR/NOTICES/:
---------------------
JDBC for Apache Cassandra v6.0 notices.txt
                           Third party agreement information


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


INSTALL_DIR/READMES/:
---------------------
JDBC for Apache Cassandra v6.0 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_JDBC_60.exe      Windows uninstaller

Uninstall_JDBC_60.lax      Support file for the Windows uninstaller

uninstaller.jar            Java uninstaller

resource/*.*               Resource files for the Windows uninstaller


     Third Party Acknowledgments

Copyright (c) (1987-2016) Progress Software Corporation and/or one of its 
subsidiaries or affiliates. All rights reserved.

One or more products in the Progress DataDirect for JDBC for Apache Cassandra 
v6.0 release includes third-party components covered by licenses that require 
that the following documentation notices be provided.  If changes in 
third-party components occurred for the current release of the Product, the 
following Third-party Acknowledgements may contain notice updates to any 
earlier versions provided in documentation or a README file. 

Progress DataDirect for JDBC for Apache Cassandra v6.0 incorporates HyperSQL 
database v1.8.0.10 from The HSQL Development Group.  Such technology is subject 
to the following terms and conditions: Copyright (c) 2001-2005, The HSQL 
Development Group All rights reserved. Redistribution and use in source and 
binary forms, with or without modification, are permitted provided that the 
following conditions are met: Redistributions of source code must retain the 
above copyright notice, this list of conditions and the following disclaimer.  
Redistributions in binary form must reproduce the above copyright notice, this 
list of conditions and the following disclaimer in the documentation and/or 
other materials provided with the distribution. Neither the name of the HSQL 
Development Group nor the names of its contributors may be used to endorse or 
promote products derived from this software without specific prior written 
permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 
ARE DISCLAIMED. IN NO EVENT SHALL HSQL DEVELOPMENT GROUP, HSQLDB.ORG, OR 
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT 
OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 
IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 
OF SUCH DAMAGE.

Progress DataDirect for JDBC for Apache Cassandra v6.0 incorporates Stax2 API 
v3.1.1 from the Woodstox Project.  Such technology is subject to the following 
terms and conditions: Copyright (c) 2004-2010, Woodstox Project 
(http://woodstox.codehaus.org/) All rights reserved. Redistribution and use in 
source and binary forms, with or without modification, are permitted provided 
that the following conditions are met: 1. Redistributions of source code must 
retain the above copyright notice, this list of conditions and the following 
disclaimer. 2. Redistributions in binary form must reproduce the above 
copyright notice, this list of conditions and the following disclaimer in the 
documentation and/or other materials provided with the distribution. 3. Neither 
the name of the Woodstox XML Processor nor the names of its contributors may be 
used to endorse or promote products derived from this software without specific 
prior written permission. 
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR 
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON 
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


21 December 2016
================
End of README