Merge pull request datastax#246 from datastax/2.2-docs

2.2 doc updates

CHANGELOG.md

@@ -1,3 +1,29 @@
+2.2.0
+===========
+October 29, 2015
+
+Features
+--------
+* Refactored the schema metadata API (`CassSchema`) to use concrete types
+  (`CassKeyspaceMeta`, `CassTableMeta`, etc.) instead of the single
+  `CassSchemaMeta` type.
+* Added support for UDF/UDA schema metadata
+* Added support for whitelist filtering i.e. whitelist load balancing policy
+
+Other
+--------
+* Fixed `Address::compare()` issue that cause invalid comparisons for IPv4
+* Fixed issue that caused `StreamManager` to generate invalid stream IDs in
+  Windows release builds.
+* Fixed issue where `cass_cluster_set_protocol_version()` would return an error
+  for protocol versions higher than v3
+* Changed the default consistency from `CASS_CONSISTENCY_ONE` to
+  `CASS_CONSISTENCY_LOCAL_QUORUM`
+* When using prepared statements with protocol v4 (and higher) the driver will
+  use partition key metadata returned in the prepared response instead of using
+  schema metadata.
+* Improved the performance of UUID to string and UUID from string conversions
+
 2.2.0-beta1
 ===========
 September 21, 2015

README.md

@@ -13,17 +13,15 @@ Cassandra's native protocol and Cassandra Query Language v3.
 - Mailing List: https://groups.google.com/a/lists.datastax.com/forum/#!forum/cpp-driver-user
 - IRC: [#datastax-drivers on `irc.freenode.net <http://freenode.net>`](http://webchat.freenode.net/?channels=datastax-drivers)
 
-## What's New in 2.2 Beta1
+## What's New in 2.2
 
 - Support for new Cassandra 2.2 datatypes: `tinyint`, `smallint`, `date` and
   `time`
 - Support for custom payloads
 - Support for server-side warnings
-
-## Upgrading from 1.0 to 2.0
-
-There were a couple breaking API changes between 1.0 and 2.0 that are
-documented [here](http://www.datastax.com/dev/blog/datastax-c-driver-2-0-released).
+- UDF/UDA metadata
+- Whitelist load balancing policy
+- Default consistency has been changed from `ONE` to `LOCAL_QUORUM`
 
 ## Features
 - [Asynchronous API]

docs.yaml

@@ -23,8 +23,10 @@ sections:
       INLINE_SOURCES = NO
 
 versions:
-  - name: v2.1
+  - name: v2.2
     ref: HEAD
+  - name: v2.1
+    ref: 2c97015988e0a9e9342b233db5f37ca9386e4d7d
   - name: v2.0
     ref: fc9c25a3db879894d40306642864413ef8f7d979
   - name: v1.0

include/cassandra.h

@@ -53,7 +53,7 @@
 #define CASS_VERSION_MAJOR 2
 #define CASS_VERSION_MINOR 2
 #define CASS_VERSION_PATCH 0
-#define CASS_VERSION_SUFFIX "beta1"
+#define CASS_VERSION_SUFFIX ""
 
 #ifdef __cplusplus
 extern "C" {

packaging/build_deb.sh

@@ -12,7 +12,7 @@ function check_command {
 check_command "dch" "debhelper"
 check_command "lsb_release" "lsb-release"
 
-version="2.2.0~beta1"
+version="2.2.0"
 release=1
 dist=$(lsb_release -s -c)
 base="cassandra-cpp-driver-$version"

packaging/build_rpm.sh

@@ -17,7 +17,7 @@ if [[ ! -z $1 ]]; then
   arch=$1
 fi
 
-version="2.2.0beta1"
+version="2.2.0"
 base="cassandra-cpp-driver-$version"
 archive="$base.tar.gz"
 files="CMakeLists.txt cmake_uninstall.cmake.in include src README.md LICENSE.txt"

topics/README.md

@@ -150,7 +150,7 @@ Each I/O thread maintains a small number of connections for each node in the
 Cassandra cluster and each of those connections can handle several simultaneous
 requests using pipelining. Asynchronous I/O and pipelining together allow each
 connection to handle several (up to 128 requests with protocol v1/v2 and 32k with
-protocol v3) in-flight requests concurrently. This significantly reduces the
+protocol v3/v4) in-flight requests concurrently. This significantly reduces the
 number of connections required to be open to Cassandra and
 allows the driver to batch requests destined for the same node.
 
@@ -175,7 +175,6 @@ Here are some features that are missing from the C/C++ driver, but are included
 - Event registration and notification
 - Callback interfaces for load balancing, authentication, reconnection and retry
 - Generic SASL authentication interface
-- [User Defined Type (UDT)](http://www.datastax.com/documentation/cql/3.1/cql/cql_reference/cqlRefUDType.html)
 
 [`cass_int32_t`]: http://datastax.github.io/cpp-driver/api/cassandra.h/#cass-int32-t
 [`cass_result_first_row()`]: http://datastax.github.io/cpp-driver/api/CassResult/#cass-result-first-row

topics/basics/README.md

@@ -12,90 +12,114 @@
 <table class="table table-striped table-hover table-condensed">
   <thead>
     <tr>
-      <th>Driver</th>
-      <th>Cassandra</th>
+      <th>Cassandra Type(s)</th>
+      <th>Driver Type</th>
       <th>Supported Versions</th>
     </tr>
   </thead>
   <tbody>
     <tr>
-      <td><code>cass_int32_t</code></td>
       <td><code>int</code></td>
+      <td><code>cass_int32_t</code></td>
       <td>1.2+</td>
     </tr>
 
     <tr>
-      <td><code>cass_int64_t</code></td>
       <td><code>bigint</code>, <code>counter</code>, <code>timestamp</code></td>
+      <td><code>cass_int64_t</code></td>
       <td>1.2+</td>
     </tr>
 
     <tr>
-      <td><code>cass_float_t</code></td>
       <td><code>float</code></td>
+      <td><code>cass_float_t</code></td>
       <td>1.2+</td>
     </tr>
 
     <tr>
-      <td><code>cass_double_t</code></td>
       <td><code>double</code></td>
+      <td><code>cass_double_t</code></td>
       <td>1.2+</td>
     </tr>
 
     <tr>
-      <td><code>cass_boot_t</code></td>
       <td><code>boolean</code></td>
+      <td><code>cass_boot_t</code></td>
       <td>1.2+</td>
     </tr>
 
     <tr>
-      <td><code>const char*</code></td>
       <td><code>ascii</code>, <code>text</code>, <code>varchar</code></td>
+      <td><code>const char*</code></td>
       <td>1.2+</td>
     </tr>
 
     <tr>
-      <td><code>const cass_byte_t*</code></td>
       <td><code>blob</code>, <code>varint</code></td>
+      <td><code>const cass_byte_t*</code></td>
       <td>1.2+</td>
     </tr>
 
     <tr>
-      <td><code>CassUuid</code></td>
       <td><code>uuid</code>, <code>timeuuid</code></td>
+      <td><code>CassUuid</code></td>
       <td>1.2+</td>
     </tr>
 
     <tr>
-      <td><code>CassInet</code></td>
       <td><code>inet</code></td>
+      <td><code>CassInet</code></td>
       <td>1.2+</td>
     </tr>
 
     <tr>
-      <td><code>const cass_byte_t* (varint) and a cass_int32_t (scale)</code></td>
       <td><code>decimal</code></td>
+      <td><code>const cass_byte_t* (varint) and a cass_int32_t (scale)</code></td>
       <td>1.2+</td>
     </tr>
 
     <tr>
-      <td><code>CassCollection</code></td>
       <td><code>list</code>, <code>map</code>, <code>set</code></td>
+      <td><code>CassCollection</code></td>
       <td>1.2+</td>
     </tr>
 
     <tr>
-      <td><code>CassTuple</code></td>
       <td><code>tuple</code></td>
+      <td><code>CassTuple</code></td>
       <td>2.1+</td>
     </tr>
 
     <tr>
+      <td><code>user defined type</code></td>
       <td><code>CassUserType</code></td>
-      <td><code>type</code></td>
       <td>2.1+</td>
     </tr>
 
+    <tr>
+      <td><code>tinyint</code></td>
+      <td><code>cass_int8_t</code></td>
+      <td>2.2+</td>
+    </tr>
+
+    <tr>
+      <td><code>smallint</code></td>
+      <td><code>cass_int16_t</code></td>
+      <td>2.2+</td>
+    </tr>
+
+    <tr>
+      <td><code>date</code></td>
+      <td><code>cass_uint32_t</code></td>
+      <td>2.2+</td>
+    </tr>
+
+    <tr>
+      <td><code>time</code></td>
+      <td><code>cass_int64_t</code></td>
+      <td>2.2+</td>
+    </tr>
+
   </tbody>
 </table>
 

topics/basics/batches/README.md

@@ -1,9 +1,9 @@
 # Batches
 
-Batches can be used to group multiple mutations (`UPDATE`, `INSERT`, `DELETE`) together into a single statement; simple or perpared. There are three different types of batches supported by Cassandra 2.0 or later.
+Batches can be used to group multiple mutations (`UPDATE`, `INSERT`, `DELETE`) together into a single statement; simple or prepared. There are three different types of batches supported by Cassandra 2.0 or later.
 
-* `CASS_BATCH_TYPE_LOGGED` is used to make sure that multiple mutations across multiple partitions happen atomically, that is, all the included mutations will eventually succeed. However, there is a performance penalty imposed by atomcity guarantee.
-* `CASS_BATCH_TYPE_UNLOGGED` is generally used to group mutations for a single partition and do not suffer from the performance penalty imposed by logged batches, but there is no atomicty guarantee for  multi-partition updates.
+* `CASS_BATCH_TYPE_LOGGED` is used to make sure that multiple mutations across multiple partitions happen atomically, that is, all the included mutations will eventually succeed. However, there is a performance penalty imposed by atomicity guarantee.
+* `CASS_BATCH_TYPE_UNLOGGED` is generally used to group mutations for a single partition and do not suffer from the performance penalty imposed by logged batches, but there is no atomicity guarantee for  multi-partition updates.
 * `CASS_BATCH_TYPE_COUNTER` is used to group counters updates.
 
 **Important**: Be careful when using batches as a [performance optimization](http://www.datastax.com/documentation/cql/3.1/cql/cql_using/useBatch.html).

topics/basics/binding_parameters/README.md

@@ -29,25 +29,12 @@ cass_statement_bind_string_by_name(statement, "column1", "abc");
 cass_statement_free(statement);
 ```
 
-## Large Values
+## Unbound parameters
 
-The data of values bound to a statement are copied into the statement. That means that values bound to statements can be freed immediately after being bound. However, this might be problematic for large values so the driver provides `cass_statement_bind_custom()` which allocates a buffer where the large values can be directly stored avoiding an extra allocation and copy.
-
-```c
-/* Create a statement with two parameters */
-CassStatement* statement
-  = cass_statement_new("INSERT INTO table1 (column1, column2) VALUES (?, ?)", 2);
-
-cass_statement_bind_string(statement, 0, "abc");
-
-cass_byte_t* bytes;
-cass_statement_bind_custom(statement, 1, 8 * 1024 * 1024, &bytes);
-
-/* 'bytes' then can be used in the application to store a large value */
-
-/* Execute statment */
-
-```
+When using Cassandra 2.2+ the driver will send a special `unset` value for
+unbound parameters (leaving the unbound column unaffected). If using older
+versions of Cassandra (2.1 and below) the driver will return an error for
+unbound parameters.
 
 ## Constructing Collections
 

topics/basics/consistency/README.md

@@ -1,6 +1,14 @@
 # Consistency
 
-A setting that defines a successful write or read by the number of cluster replicas that acknowledge the write or respond to the read request, respectively.
+A setting that defines a successful write or read by the number of cluster
+replicas that acknowledge the write or respond to the read request,
+respectively.
+
+## Default consistency
+
+The default consistency is now `CASS_CONSISTENCY_LOCAL_QUORUM` for driver
+versions 2.2 and above it  was `CASS_CONSISTENCY_ONE` for all previous versions
+(2.1 and below).
 
 ## Consistency Levels
 

topics/basics/data_types/README.md

@@ -21,22 +21,26 @@ CREATE TYPE person (name text,
 **Important**: Any `const [CassDataType]*` object doesn't need to be freed. It's
 lifetime is bound to the object it came from.
 
-UDT data types can be retrieved using a [`CassSchema`] object. The resulting
+UDT data types can be retrieved using a [`CassSchemaMeta`] object. The resulting
 data type object can be used to construct a new [`CassUserType`] object using
 [`cass_user_type_new_from_data_type()`].
 
 ```c
 /* Get schema object (this should be cached) */
-const CassSchema* schema = cass_session_get_schema(session);
+const CassSchemaMeta* schema_meta = cass_session_get_schema_meta(session);
+
+/* Get the keyspace for the user defined type. It doesn't need to be freed */
+const CassKeyspaceMeta* keyspace_meta =
+  cass_schema_meta_keyspace_by_name("examples");
 
 /* This data type object doesn't need to be freed */
 const DataType* person_data_type =
-  cass_schema_get_udt(schema, "keyspace", "person");
+  cass_keyspace_meta_user_type_by_name(keyspace_meta, "person");
 
 /* ... */
 
 /* Schema object must be freed */
-cass_schema_free(schema);
+cass_schema_meta_free(schema_meta);
 ```
 
 Data types can also be retrieved from [`CassResult`], [`CassPrepared`], and
@@ -127,7 +131,7 @@ cass_collection_free(phone_numbers);
 [`CassPrepared`]: http://datastax.github.io/cpp-driver/api/CassPrepared/
 [`CassResult`]: http://datastax.github.io/cpp-driver/api/CassResult/
 [`CassValue`]: http://datastax.github.io/cpp-driver/api/CassValue/
-[`CassSchema`]: http://datastax.github.io/cpp-driver/api/CassSchema/
+[`CassSchemaMeta`]: http://datastax.github.io/cpp-driver/api/CassSchemaMeta/
 [`cass_user_type_new_from_data_type()`]: http://datastax.github.io/cpp-driver/api/CassUserType/#cass-user-type-new-from-data-type
 [`cass_result_column_data_type()`]: http://datastax.github.io/cpp-driver/api/CassResult/#cass-result-column-data-type
 [`cass_prepared_parameter_data_type()`]: http://datastax.github.io/cpp-driver/api/CassPrepared/#cass-prepared-parameter-data-type