Added support for On-Demand tables

CHANGELOG.md

@@ -1,8 +1,19 @@
 # Change Log
 All notable changes to this project will be documented in this file.
-
 The format is based on [Keep a Changelog](http://keepachangelog.com/).
 
+## [Unreleased]
+
+### Added
+- Cloud only: Support for On-Demand tables in TableLimits
+- Row modification time made available in GetResult
+- Existing row modification time made available in PutResult and DeleteResult when operation fails and previous value is requested
+- On-Prem only: Support for setting Durability in write operations (put/delete/writeMultiple/multiDelete)
+
+### Changed
+- Internally, the SDK now detects the serial version of the server it's connected to, and adjusts its capabilities to match. If the server is an older version, and some features may not be available, client apps may get a one-time log message (at INFO level) with text like "The requested feature is not supported by the connected server".
+
+
 ## [5.2.31] 2022-01-28
 
 Oracle internal use release
@@ -78,7 +89,7 @@ NoSQLHandleConfig.setPoolMaxPending() and NoSQLHandleConfig.getPoolMaxPending().
   - Added new SignatureProvider constructors to allow use of an instance principal with delegation token in a file for authorization and authentication.
     - SignatureProvider.createInstancePrincipalForDelegation(File delegationTokenFile)
     - SignatureProvider.createInstancePrincipalForDelegation(String iamAuthUri, Region region, File delegationTokenFile, Logger logger)
-- Added is* methods on FieldValue for convenience checking of whether an instance is
+- Added methods on FieldValue for convenience checking of whether an instance is
 of a given type, e.g. FieldValue.isInteger(), etc.
 
 ### Changed

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.2.31</version>
+  <version>5.3.0</version>
 </dependency>
 ```
 

driver/pom.xml

@@ -29,7 +29,7 @@
 
   <groupId>com.oracle.nosql.sdk</groupId>
   <artifactId>nosqldriver</artifactId>
-  <version>5.2.31</version>
+  <version>5.3.0</version>
   <packaging>jar</packaging>
 
   <organization>

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

@@ -0,0 +1,234 @@
+/*-
+ * 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;
+
+/**
+ * Defines the durability characteristics associated with a standalone write
+ * (put or update) operation.
+ * <p>
+ * This is currently only supported in On-Prem installations. It is ignored
+ * in the cloud service.
+ * <p>
+ * The overall durability is a function of the {@link SyncPolicy} and {@link
+ * ReplicaAckPolicy} in effect for the Master, and the {@link SyncPolicy} in
+ * effect for each Replica.
+ * </p>
+ *
+ * @since 5.3.0
+ */
+public class Durability {
+
+    /**
+     * A convenience constant that defines a durability policy with COMMIT_SYNC
+     * for Master commit synchronization.
+     *
+     * The policies default to COMMIT_NO_SYNC for commits of replicated
+     * transactions that need acknowledgment and SIMPLE_MAJORITY for the
+     * acknowledgment policy.
+     */
+    public static final Durability COMMIT_SYNC =
+        new Durability(SyncPolicy.SYNC,
+                       SyncPolicy.NO_SYNC,
+                       ReplicaAckPolicy.SIMPLE_MAJORITY);
+
+    /**
+     * A convenience constant that defines a durability policy with
+     * COMMIT_NO_SYNC for Master commit synchronization.
+     *
+     * The policies default to COMMIT_NO_SYNC for commits of replicated
+     * transactions that need acknowledgment and SIMPLE_MAJORITY for the
+     * acknowledgment policy.
+     */
+    public static final Durability COMMIT_NO_SYNC =
+        new Durability(SyncPolicy.NO_SYNC,
+                       SyncPolicy.NO_SYNC,
+                       ReplicaAckPolicy.SIMPLE_MAJORITY);
+
+    /**
+     * A convenience constant that defines a durability policy with
+     * COMMIT_WRITE_NO_SYNC for Master commit synchronization.
+     *
+     * The policies default to COMMIT_NO_SYNC for commits of replicated
+     * transactions that need acknowledgment and SIMPLE_MAJORITY for the
+     * acknowledgment policy.
+     */
+    public static final Durability COMMIT_WRITE_NO_SYNC =
+        new Durability(SyncPolicy.WRITE_NO_SYNC,
+                       SyncPolicy.NO_SYNC,
+                       ReplicaAckPolicy.SIMPLE_MAJORITY);
+
+    /**
+     * Defines the synchronization policy to be used when committing a
+     * transaction. High levels of synchronization offer a greater guarantee
+     * that the transaction is persistent to disk, but trade that off for
+     * lower performance.
+     */
+    public enum SyncPolicy {
+
+        /**
+         *  Write and synchronously flush the log on transaction commit.
+         *  Transactions exhibit all the ACID (atomicity, consistency,
+         *  isolation, and durability) properties.
+         */
+        SYNC,
+
+        /**
+         * Do not write or synchronously flush the log on transaction commit.
+         * Transactions exhibit the ACI (atomicity, consistency, and isolation)
+         * properties, but not D (durability); that is, database integrity will
+         * be maintained, but if the application or system fails, it is
+         * possible some number of the most recently committed transactions may
+         * be undone during recovery. The number of transactions at risk is
+         * governed by how many log updates can fit into the log buffer, how
+         * often the operating system flushes dirty buffers to disk, and how
+         * often log checkpoints occur.
+         */
+        NO_SYNC,
+
+        /**
+         * Write but do not synchronously flush the log on transaction commit.
+         * Transactions exhibit the ACI (atomicity, consistency, and isolation)
+         * properties, but not D (durability); that is, database integrity will
+         * be maintained, but if the operating system fails, it is possible
+         * some number of the most recently committed transactions may be
+         * undone during recovery. The number of transactions at risk is
+         * governed by how often the operating system flushes dirty buffers to
+         * disk, and how often log checkpoints occur.
+         */
+        WRITE_NO_SYNC;
+    }
+
+    /**
+     * A replicated environment makes it possible to increase an application's
+     * transaction commit guarantees by committing changes to its replicas on
+     * the network. ReplicaAckPolicy defines the policy for how such network
+     * commits are handled.
+     */
+    public enum ReplicaAckPolicy {
+
+        /**
+         * All replicas must acknowledge that they have committed the
+         * transaction. This policy should be selected only if your replication
+         * group has a small number of replicas, and those replicas are on
+         * extremely reliable networks and servers.
+         */
+        ALL,
+
+        /**
+         * No transaction commit acknowledgments are required and the master
+         * will never wait for replica acknowledgments. In this case,
+         * transaction durability is determined entirely by the type of commit
+         * that is being performed on the master.
+         */
+        NONE,
+
+        /**
+         * A simple majority of replicas must acknowledge that they have
+         * committed the transaction. This acknowledgment policy, in
+         * conjunction with an election policy which requires at least a simple
+         * majority, ensures that the changes made by the transaction remains
+         * durable if a new election is held.
+         */
+        SIMPLE_MAJORITY;
+    }
+
+    /* The sync policy in effect on the Master node. */
+    private final SyncPolicy masterSync;
+
+    /* The sync policy in effect on a replica. */
+    final private SyncPolicy replicaSync;
+
+    /* The replica acknowledgment policy to be used. */
+    final private ReplicaAckPolicy replicaAck;
+
+    /**
+     * Creates an instance of a Durability specification.
+     *
+     * @param masterSync the SyncPolicy to be used when committing the
+     * transaction on the Master.
+     * @param replicaSync the SyncPolicy to be used remotely, as part of a
+     * transaction acknowledgment, at a Replica node.
+     * @param replicaAck the acknowledgment policy used when obtaining
+     * transaction acknowledgments from Replicas.
+     */
+    public Durability(SyncPolicy masterSync,
+                      SyncPolicy replicaSync,
+                      ReplicaAckPolicy replicaAck) {
+        this.masterSync = masterSync;
+        this.replicaSync = replicaSync;
+        this.replicaAck = replicaAck;
+    }
+
+    @Override
+    public String toString() {
+        return masterSync.toString() + "," +
+               replicaSync.toString() + "," +
+               replicaAck.toString();
+    }
+
+    /**
+     * Returns the transaction synchronization policy to be used on the Master
+     * when committing a transaction.
+     * @return the master transaction synchronization policy
+     */
+    public SyncPolicy getMasterSync() {
+        return masterSync;
+    }
+
+    /**
+     * Returns the transaction synchronization policy to be used by the replica
+     * as it replays a transaction that needs an acknowledgment.
+     * @return the replica transaction synchronization policy
+     */
+    public SyncPolicy getReplicaSync() {
+        return replicaSync;
+    }
+
+    /**
+     * Returns the replica acknowledgment policy used by the master when
+     * committing changes to a replicated environment.
+     * @return the replica acknowledgment policy
+     */
+    public ReplicaAckPolicy getReplicaAck() {
+        return replicaAck;
+    }
+
+    @Override
+    public int hashCode() {
+        final int prime = 31;
+        int result = 1;
+        result = (prime * result) + masterSync.hashCode();
+        result = (prime * result) + replicaAck.hashCode();
+        result = (prime * result) + replicaSync.hashCode();
+        return result;
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+        if (this == obj) {
+            return true;
+        }
+        if (obj == null) {
+            return false;
+        }
+        if (!(obj instanceof Durability)) {
+            return false;
+        }
+        Durability other = (Durability) obj;
+        if (!masterSync.equals(other.masterSync)) {
+            return false;
+        }
+        if (!replicaAck.equals(other.replicaAck)) {
+            return false;
+        }
+        if (!replicaSync.equals(other.replicaSync)) {
+            return false;
+        }
+        return true;
+    }
+}

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

@@ -150,7 +150,7 @@ public class NoSQLHandleConfig implements Cloneable {
     private List<String> ciphers;
 
     /**
-     * The protocols used by the driver, or null if not configured
+     * The SSL protocols used by the driver, or null if not configured
      * by the user.
      */
     private List<String> protocols;

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

@@ -0,0 +1,27 @@
+/*-
+ * 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;
+
+/**
+ * This exception is thrown if the server does not support the current
+ * driver protocol version.
+ *
+ * @since 5.3.0
+ */
+public class UnsupportedProtocolException extends NoSQLException {
+
+    private static final long serialVersionUID = 1L;
+
+    /**
+     * @hidden
+     * @param msg the exception message
+     */
+    public UnsupportedProtocolException(String msg) {
+        super(msg);
+    }
+}