JAVA-2815: Add support for transactions to the synchronous API

A few notes on the design and implementation:

* It introduces a small but significant breaking change to the existing
API for any applications that already depend on session support
(introduced in the 3.6 release to support causal consistency): the type
of ClientSession changes from com.mongodb.session.ClientSession to
com.mongodb.client.ClientSession.  This is both source and binary
incompatible.
* It adds an overload to MongoClient.startSession that takes no
ClientSessionOptions, as we expect it to be a common pattern to not
need any options.
* Internally, it moves ReadConcern from a property of ReadOperation
implementation classes to a property of the SessionContext, so that
ReadConcern can be applied properly when in a transaction (transactions
require that read concern is specified only on the first command of
a transaction, regardless of whether it's a read or a write

Author: jyemin

config/findbugs-exclude.xml

@@ -132,4 +132,9 @@
         <Bug pattern="NP_BOOLEAN_RETURN_NULL"/>
     </Match>
 
+    <Match>
+        <Class name="~com.mongodb.client.ClientSession.*"/>
+        <Bug pattern="NM_SAME_SIMPLE_NAME_AS_INTERFACE"/>
+    </Match>
+
 </FindBugsFilter>

driver-async/src/main/com/mongodb/async/client/ClientSessionHelper.java

@@ -22,7 +22,7 @@
 import com.mongodb.connection.ClusterDescription;
 import com.mongodb.connection.Server;
 import com.mongodb.connection.ServerDescription;
-import com.mongodb.internal.session.ClientSessionImpl;
+import com.mongodb.internal.session.BaseClientSessionImpl;
 import com.mongodb.internal.session.ServerSessionPool;
 import com.mongodb.lang.Nullable;
 import com.mongodb.selector.ServerSelector;
@@ -81,8 +81,8 @@ public void onResult(final Server server, final Throwable t) {
         }
     }
 
-    private ClientSessionImpl createClientSession(final ClientSessionOptions options) {
-        return new ClientSessionImpl(serverSessionPool, mongoClient, options);
+    private ClientSession createClientSession(final ClientSessionOptions options) {
+        return new BaseClientSessionImpl(serverSessionPool, mongoClient, options);
     }
 
     @SuppressWarnings("deprecation")

driver-core/src/main/com/mongodb/ClientSessionOptions.java

@@ -21,6 +21,8 @@
 import com.mongodb.lang.Nullable;
 import com.mongodb.session.ClientSession;
 
+import static com.mongodb.assertions.Assertions.notNull;
+
 /**
  * The options to apply to a {@code ClientSession}.
  *
@@ -33,11 +35,13 @@
 public final class ClientSessionOptions {
 
     private final Boolean causallyConsistent;
+    private final boolean autoStartTransaction;
+    private final TransactionOptions defaultTransactionOptions;
 
     /**
      * Whether operations using the session should causally consistent with each other.
      *
-     * @return whether operations using the session should be causally consistent.  A null value indicates to use the the global default,
+     * @return whether operations using the session should be causally consistent.  A null value indicates to use the global default,
      * which is currently true.
      * @mongodb.driver.dochub core/causal-consistency Causal Consistency
      */
@@ -46,6 +50,70 @@ public Boolean isCausallyConsistent() {
         return causallyConsistent;
     }
 
+    /**
+     * Gets whether a transaction should be automatically started along with the session.
+     *
+     * @return whether a transaction should be automatically started along with the session.  The default is false.
+     * @since 3.8
+     * @mongodb.server.release 4.0
+     */
+    public boolean getAutoStartTransaction() {
+        return autoStartTransaction;
+    }
+
+    /**
+     * Gets the default transaction options for the session.
+     *
+     * @return the default transaction options for the session
+     * @since 3.8
+     * @mongodb.server.release 4.0
+     */
+    public TransactionOptions getDefaultTransactionOptions() {
+        return defaultTransactionOptions;
+    }
+
+    @Override
+    public boolean equals(final Object o) {
+        if (this == o) {
+            return true;
+        }
+        if (o == null || getClass() != o.getClass()) {
+            return false;
+        }
+
+        ClientSessionOptions that = (ClientSessionOptions) o;
+
+        if (autoStartTransaction != that.autoStartTransaction) {
+            return false;
+        }
+        if (causallyConsistent != null ? !causallyConsistent.equals(that.causallyConsistent) : that.causallyConsistent != null) {
+            return false;
+        }
+        if (defaultTransactionOptions != null ? !defaultTransactionOptions.equals(that.defaultTransactionOptions)
+                : that.defaultTransactionOptions != null) {
+            return false;
+        }
+
+        return true;
+    }
+
+    @Override
+    public int hashCode() {
+        int result = causallyConsistent != null ? causallyConsistent.hashCode() : 0;
+        result = 31 * result + (autoStartTransaction ? 1 : 0);
+        result = 31 * result + (defaultTransactionOptions != null ? defaultTransactionOptions.hashCode() : 0);
+        return result;
+    }
+
+    @Override
+    public String toString() {
+        return "ClientSessionOptions{"
+                + "causallyConsistent=" + causallyConsistent
+                + ", autoStartTransaction=" + autoStartTransaction
+                + ", defaultTransactionOptions=" + defaultTransactionOptions
+                + '}';
+    }
+
     /**
      * Gets an instance of a builder
      *
@@ -55,12 +123,30 @@ public static Builder builder() {
         return new Builder();
     }
 
+    /**
+     * Gets an instance of a builder initialized with the given options
+     *
+     * @param options the options with which to initialize the builder
+     * @return a builder instance
+     * @since 3.8
+     */
+    public static Builder builder(final ClientSessionOptions options) {
+        notNull("options", options);
+        Builder builder = new Builder();
+        builder.causallyConsistent = options.isCausallyConsistent();
+        builder.autoStartTransaction = options.getAutoStartTransaction();
+        builder.defaultTransactionOptions = options.getDefaultTransactionOptions();
+        return builder;
+    }
+
     /**
      * A builder for instances of {@code ClientSession}
      */
     @NotThreadSafe
     public static final class Builder {
         private Boolean causallyConsistent;
+        private boolean autoStartTransaction;
+        private TransactionOptions defaultTransactionOptions = TransactionOptions.builder().build();
 
         /**
          * Sets whether operations using the session should causally consistent with each other.
@@ -74,6 +160,33 @@ public Builder causallyConsistent(final boolean causallyConsistent) {
             return this;
         }
 
+        /**
+         * Sets whether operations using the session should causally consistent with each other.
+         *
+         * @param autoStartTransaction whether a transaction should be started automatically when the session is started.
+         *
+         * @return this
+         * @since 3.8
+         * @mongodb.server.release 4.0
+         */
+        public Builder autoStartTransaction(final boolean autoStartTransaction) {
+            this.autoStartTransaction = autoStartTransaction;
+            return this;
+        }
+
+        /**
+         * Sets whether operations using the session should causally consistent with each other.
+         *
+         * @param defaultTransactionOptions the default transaction options to use for all transactions on this session,
+         * @return this
+         * @since 3.8
+         * @mongodb.server.release 4.0
+         */
+        public Builder defaultTransactionOptions(final TransactionOptions defaultTransactionOptions) {
+            this.defaultTransactionOptions = notNull("defaultTransactionOptions", defaultTransactionOptions);
+            return this;
+        }
+
         /**
          * Build the session options instance.
          *
@@ -89,5 +202,7 @@ private Builder() {
 
     private ClientSessionOptions(final Builder builder) {
         this.causallyConsistent = builder.causallyConsistent;
+        this.autoStartTransaction = builder.autoStartTransaction;
+        this.defaultTransactionOptions = builder.defaultTransactionOptions;
     }
 }

driver-core/src/main/com/mongodb/ReadConcern.java

@@ -68,6 +68,14 @@ public ReadConcern(final ReadConcernLevel level) {
      */
     public static final ReadConcern LINEARIZABLE = new ReadConcern(ReadConcernLevel.LINEARIZABLE);
 
+    /**
+     * The snapshot read concern.
+     *
+     * @since 3.8
+     * @mongodb.server.release 4.0
+     */
+    public static final ReadConcern SNAPSHOT = new ReadConcern(ReadConcernLevel.SNAPSHOT);
+
     /**
      * Gets the read concern level.
      *

driver-core/src/main/com/mongodb/ReadConcernLevel.java

@@ -48,7 +48,15 @@ public enum ReadConcernLevel {
      * @since 3.4
      * @mongodb.server.release 3.4
      */
-    LINEARIZABLE("linearizable");
+    LINEARIZABLE("linearizable"),
+
+    /**
+     * The snapshot read concern level.
+     *
+     * @since 3.8
+     * @mongodb.server.release 4.0
+     */
+    SNAPSHOT("snapshot");
 
     private final String value;
 

driver-core/src/main/com/mongodb/TransactionOptions.java

@@ -0,0 +1,168 @@
+/*
+ * Copyright 2008-present MongoDB, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.mongodb;
+
+import com.mongodb.annotations.Immutable;
+import com.mongodb.lang.Nullable;
+
+import static com.mongodb.assertions.Assertions.isTrueArgument;
+import static com.mongodb.assertions.Assertions.notNull;
+
+/**
+ * Options to apply to transactions.
+ *
+ * @see com.mongodb.session.ClientSession
+ * @see ClientSessionOptions
+ * @since 3.8
+ * @mongodb.server.release 4.0
+ */
+@Immutable
+public final class TransactionOptions {
+    private final ReadConcern readConcern;
+    private final WriteConcern writeConcern;
+
+    /**
+     * Gets the read concern.
+     *
+     * @return the read concern, which defaults to {@link ReadConcern#SNAPSHOT}
+     */
+    @Nullable
+    public ReadConcern getReadConcern() {
+        return readConcern;
+    }
+
+    /**
+     * Gets the write concern.
+     *
+     * @return the write concern, which defaults to {@link WriteConcern#ACKNOWLEDGED}
+     */
+    @Nullable
+    public WriteConcern getWriteConcern() {
+        return writeConcern;
+    }
+
+    /**
+     * Gets an instance of a builder
+     *
+     * @return a builder instance
+     */
+    public static Builder builder() {
+        return new Builder();
+    }
+
+    /**
+     * Merge the two provided transaction options, with the first taking precedence over the second.
+     *
+     * @param options the transaction options, which take precedence for any property that is non-null
+     * @param defaultOptions the default transaction options
+     * @return the merged transaction options
+     */
+    public static TransactionOptions merge(final TransactionOptions options, final TransactionOptions defaultOptions) {
+        notNull("options", options);
+        notNull("defaultOptions", defaultOptions);
+        return TransactionOptions.builder()
+                .writeConcern(options.getWriteConcern() == null
+                        ? defaultOptions.getWriteConcern() : options.getWriteConcern())
+                .readConcern(options.getReadConcern() == null
+                        ? defaultOptions.getReadConcern() : options.getReadConcern())
+                .build();
+    }
+
+    @Override
+    public boolean equals(final Object o) {
+        if (this == o) {
+            return true;
+        }
+        if (o == null || getClass() != o.getClass()) {
+            return false;
+        }
+
+        TransactionOptions that = (TransactionOptions) o;
+
+        if (readConcern != null ? !readConcern.equals(that.readConcern) : that.readConcern != null) {
+            return false;
+        }
+        if (writeConcern != null ? !writeConcern.equals(that.writeConcern) : that.writeConcern != null) {
+            return false;
+        }
+
+        return true;
+    }
+
+    @Override
+    public int hashCode() {
+        int result = readConcern != null ? readConcern.hashCode() : 0;
+        result = 31 * result + (writeConcern != null ? writeConcern.hashCode() : 0);
+        return result;
+    }
+
+    @Override
+    public String toString() {
+        return "TransactionOptions{readConcern="
+                + readConcern + ", writeConcern="
+                + writeConcern + '}';
+    }
+
+    /**
+     * The builder for transaction options
+     */
+    public static final class Builder {
+        private ReadConcern readConcern;
+        private WriteConcern writeConcern;
+
+        /**
+         * Sets the read concern.
+         *
+         * @param readConcern the read concern
+         * @return this
+         */
+        public Builder readConcern(@Nullable final ReadConcern readConcern) {
+            this.readConcern = readConcern;
+            return this;
+        }
+
+        /**
+         * Sets the write concern.
+         *
+         * @param writeConcern the write concern, which must be acknowledged
+         * @return this
+         */
+        public Builder writeConcern(@Nullable final WriteConcern writeConcern) {
+            this.writeConcern = writeConcern;
+            isTrueArgument("acknowledged write concern", writeConcern != null && writeConcern.isAcknowledged());
+            return this;
+        }
+
+        /**
+         * Build the transaction options instance.
+         *
+         * @return The {@code TransactionOptions}
+         */
+        public TransactionOptions build() {
+            return new TransactionOptions(this);
+        }
+
+        private Builder() {
+        }
+    }
+
+
+    private TransactionOptions(final Builder builder) {
+        readConcern = builder.readConcern;
+        writeConcern = builder.writeConcern;
+    }
+}