Support for new, flexible wire protocol (V4).

The previous protocol is still supported for communication with servers that do not yet support V4. The
version negotation is internal and automatic; however, use of V4 features will fail
at runtime when attempted with an older server. Failure may be an empty or
undefined result or an exception if the request cannot be serviced at all. The following
new features or interfaces depend on the new protocol version:
 - added set/getDurability to QueryRequest for queries that modify data
 - added pagination information to TableUsageResult and TableUsageRequest
 - added shard percent usage information to TableUsageResult
 - added IndexInfo.getFieldTypes to return the type information on an index on a JSON field
 - added the ability to ask for and receive the schema of a query using
     * PrepareRequest.setGetQuerySchema
     * PreparedStatement.getQuerySchema
 - Cloud only: added use of ETags, DefinedTags and FreeFormTags in TableRequest and TableResult

Changed:
- Consistency is now a class and no longer a simple enumeration. Applications must
  be recompiled but source compatibility is maintained for all but the more complex
  use of an enumeration
- Made one private serializer class public to allow for improved internal testing.
- MapValue now implements Iterable

Author: connelly38

CHANGELOG.md

@@ -2,6 +2,32 @@
 All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/).
 
+## [Unpublished]
+
+### Added
+- Support for new, flexible wire protocol (V4) has been added. The previous protocol
+is still supported for communication with servers that do not yet support V4. The
+version negotation is internal and automatic; however, use of V4 features will fail
+at runtime when attempted with an older server. Failure may be an empty or
+undefined result or an exception if the request cannot be serviced at all. The following
+new features or interfaces depend on the new protocol version
+ - added set/getDurability to QueryRequest for queries that modify data
+ - added pagination information to TableUsageResult and TableUsageRequest
+ - added shard percent usage information to TableUsageResult
+ - added IndexInfo.getFieldTypes to return the type information on an index on a JSON
+field
+ - added the ability to ask for and receive the schema of a query using
+     * PrepareRequest.setGetQuerySchema
+     * PreparedStatement.getQuerySchema
+ - Cloud only: added use of ETags, DefinedTags and FreeFormTags in TableRequest and TableResult
+
+### Changed
+- Consistency is now a class and no longer a simple enumeration. Applications must
+be recompiled but source compatibility is maintained for all but the more complex
+use of an enumeration
+- Made one private serializer class public to allow for improved internal testing.
+- MapValue now implements Iterable
+
 ## [5.3.7] 2022-10-18
 
 ### Changed
@@ -21,7 +47,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/).
 
 ## [5.3.5] 2022-07-20
 
-### Changed
+### Added
 - Made one private serializer class public to allow for improved internal testing.
 
 ## [5.3.4] 2022-06-16
@@ -40,8 +66,6 @@ query that returns row_version() as a BinaryValue. The Version can be used for
 conditional put and delete operations
 - added support for setting an extension to the User Agent http header by
 setting the ExtensionUserAgent property on NoSQLHandlerConfig.
-
-### Changed
 - Cloud only: Added OCI regions: CDG (Paris), MAD (Madrid), QRO (Queretaro)
 
 ## [5.3.2] 2022-03-21

README.md

@@ -37,7 +37,7 @@ project. The version changes with each release.
 <dependency>
   <groupId>com.oracle.nosql.sdk</groupId>
   <artifactId>nosqldriver</artifactId>
-  <version>5.3.7</version>
+  <version>5.4.7</version>
 </dependency>
 ```
 
@@ -140,6 +140,11 @@ You may run the Cloud Simulator on localhost.
 Authorization for the Cloud Simulator is a simple no-op class implemented directly
 in the Quickstart example.
 
+## Logging
+
+Addional logging can be enabled using a java properties file. For full details, see
+"Logging in the SDK" at https://oracle.github.io/nosql-java-sdk/oracle/nosql/driver/package-summary.html
+
 ## Quickstart
 
 The following is a quick start tutorial to run a simple program in all supported

driver/pom.xml

@@ -29,7 +29,7 @@
 
   <groupId>com.oracle.nosql.sdk</groupId>
   <artifactId>nosqldriver</artifactId>
-  <version>5.3.7</version>
+  <version>5.4.7</version>
   <packaging>jar</packaging>
 
   <organization>
@@ -46,8 +46,8 @@
     <copyright>Copyright (c) 2011, 2022 Oracle and/or its affiliates. All rights reserved.</copyright>
     <java.apidoc>http://docs.oracle.com/javase/8/docs/api</java.apidoc>
     <maven.deploy.skip>false</maven.deploy.skip>
-    <netty.version>4.1.82.Final</netty.version>
-    <jackson.version>2.12.5</jackson.version>
+    <netty.version>4.1.85.Final</netty.version>
+    <jackson.version>2.13.2</jackson.version>
     <bouncy.version>1.70</bouncy.version>
    <!-- by default, skip tests; tests require a profile -->
    <maven.test.skip>true</maven.test.skip>
@@ -347,7 +347,7 @@
                May need to post-process the doc to remove the package and link.
           -->
           <excludePackageNames>
-            oracle.nosql.driver.http;oracle.nosql.driver.httpclient;oracle.nosql.driver.query;oracle.nosql.driver.util
+            oracle.nosql.driver.http;oracle.nosql.driver.httpclient;oracle.nosql.driver.query;oracle.nosql.driver.util;oracle.nosql.driver.ops.serde.nson
           </excludePackageNames>
           <stylesheetfile>${basedir}/../doc/style.css</stylesheetfile>
           <show>public</show>
@@ -413,6 +413,16 @@
         <artifactId>exec-maven-plugin</artifactId>
         <version>3.0.0</version>
         <executions>
+          <execution>
+            <id>human-readable NSON string generation</id>
+            <phase>generate-sources</phase>
+            <configuration>
+              <executable>${basedir}/scripts/build_nson_strings.sh</executable>
+            </configuration>
+            <goals>
+              <goal>exec</goal>
+            </goals>
+          </execution>
           <execution>
             <id>add license files to runtime jar</id>
             <phase>package</phase>

driver/scripts/build_nson_strings.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+
+# Copyright (C) 2011, 2022 Oracle and/or its affiliates. All rights reserved.
+#
+# This file was distributed by Oracle as part of a version of Oracle NoSQL
+# Database made available at:
+#
+# http://www.oracle.com/technetwork/database/database-technologies/nosqldb/downloads/index.html
+#
+# Please see the LICENSE file included in the top-level directory of the
+# appropriate version of Oracle NoSQL Database for a copy of the license and
+# additional information.
+
+# this script creates java code to enable using human-readable strings for field
+# names in nson debug/logging/verbose output. It modifies NsonProtocol.java to
+# add a map of field names to human readable field names.
+
+PROTOCOL_FILE=src/main/java/oracle/nosql/driver/ops/serde/nson/NsonProtocol.java
+
+# delete everything after the last static string
+lastline=$(grep -n 'public static String [A-Z]' $PROTOCOL_FILE | tail -1 | sed -e 's/:.*$//')
+head -$lastline $PROTOCOL_FILE > /tmp/proto.$$
+
+# add a static array of string arrays
+grep 'public static String ' /tmp/proto.$$ | awk 'BEGIN{printf("\n    private static String[][] mapVals = new String[][] {\n");}{printf("        {%s,\"%s\"},\n",$4,$4);}END{printf("    };\n");}' >> /tmp/proto.$$
+
+# add remaining logic
+cat << EOT >> /tmp/proto.$$
+
+    private static HashMap<String, String> fieldMap = null;
+
+    public static String readable(String field) {
+        if (fieldMap == null) {
+            fieldMap = new HashMap<String, String>();
+            for (int x=0; x<mapVals.length; x++) {
+                fieldMap.put(mapVals[x][0], mapVals[x][1]);
+            }
+        }
+        String val = fieldMap.get(field);
+        if (val == null) {
+            return field;
+        }
+        return val;
+    }
+}
+EOT
+
+# replace file
+mv /tmp/proto.$$ $PROTOCOL_FILE
+

driver/src/main/java/oracle/nosql/driver/Consistency.java

@@ -27,7 +27,44 @@
  * Consistency can be specified as an optional argument to all read operations.
  * </p>
  */
-public enum Consistency {
-    EVENTUAL,
-    ABSOLUTE
+public class Consistency {
+    final private Type type;
+
+    public enum Type {
+        EVENTUAL,
+        ABSOLUTE
+    }
+
+    public static Consistency ABSOLUTE = new Consistency(Type.ABSOLUTE);
+    public static Consistency EVENTUAL = new Consistency(Type.EVENTUAL);
+
+    /**
+     * Returns the {@link Type} of Consistency
+     * @return the type
+     */
+    public Type getType() {
+        return type;
+    }
+
+    /**
+     * Returns true if this is Consistency.ABSOLUTE
+     *
+     * @return true if this instance represents ABSOLUTE Consistency
+     */
+    public boolean isAbsolute() {
+        return type == Type.ABSOLUTE;
+    }
+
+    /**
+     * Returns true if this is Consistency.EVENTUAL
+     *
+     * @return true if this instance represents EVENTUAL Consistency
+     */
+    public boolean isEventual() {
+        return type == Type.EVENTUAL;
+    }
+
+    private Consistency(Type type) {
+        this.type = type;
+    }
 }

driver/src/main/java/oracle/nosql/driver/DefinedTags.java

@@ -0,0 +1,97 @@
+/*-
+ * Copyright (c) 2011, 2022 Oracle and/or its affiliates. All rights reserved.
+ *
+ * Licensed under the Universal Permissive License v 1.0 as shown at
+ *  https://oss.oracle.com/licenses/upl/
+ */
+
+package oracle.nosql.driver;
+
+import java.util.Iterator;
+import java.util.Map;
+
+import oracle.nosql.driver.values.FieldValue;
+import oracle.nosql.driver.values.MapValue;
+
+/**
+ * Cloud service only.
+ *
+ * DefinedTags is a class to encapsulate defined tags which are returned
+ * from calls to {@link NoSQLHandle#getTable}. They can also be set during
+ * table creation operations as well as alter table operations.
+ * @since 5.4
+ */
+public class DefinedTags {
+    private final MapValue tags;
+
+    /**
+     * Creates a new instance of DefinedTags. This method along with
+     * {@link #addTag} is used to add tags to a call to create or modify
+     * a table.
+     */
+    public DefinedTags() {
+        tags = new MapValue();
+    }
+
+    /**
+     * Creates a new instance of DefinedTags from JSON string input.
+     * @param jsonString a JSON string
+     */
+    public DefinedTags(String jsonString) {
+        tags = (MapValue) FieldValue.createFromJson(jsonString, null);
+    }
+
+    /**
+     * Adds a new tag to the set of tags in the specified namespace
+     *
+     * @param namespace the namespace for the tag
+     * @param key the tag key
+     * @param value the tag value
+     * @return this
+     */
+    public DefinedTags addTag(String namespace, String key, String value) {
+        if (!tags.contains(namespace)) {
+            tags.put(namespace, new MapValue());
+        }
+        MapValue nsMap = (MapValue) tags.get(namespace);
+        nsMap.put(key, value);
+        return this;
+    }
+
+    /**
+     * Returns the value of the named tag in the specified namespace or null
+     * if it does not exist
+     * @param namespace the namespace
+     * @param key the key
+     * @return the tag value or null
+     */
+    public String getTag(String namespace, String key) {
+        if (tags.contains(namespace)) {
+            FieldValue val = ((MapValue)tags.get(namespace)).get(key);
+            return val == null ? null : val.getString();
+        }
+        return null;
+    }
+
+    /**
+     * Returns true if the specified key exists in the specified namespace
+     * @param namespace the namespace
+     * @param key the key
+     * @return true if the key exists
+     */
+    public boolean contains(String namespace, String key) {
+        if (tags.contains(namespace)) {
+            return ((MapValue)tags.get(namespace)).contains(key);
+        }
+        return false;
+    }
+
+    /**
+     * Returns the free-form tags as a JSON string
+     * @return the JSON string
+     */
+    @Override
+    public String toString() {
+        return tags.toString();
+    }
+}