Support explain for find operations (#620)

Support is only for server versions 3.2+

JAVA-3909

Author: jyemin

driver-core/src/main/com/mongodb/internal/operation/AsyncExplainableReadOperation.java

@@ -0,0 +1,25 @@
+/*
+ * 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.internal.operation;
+
+import com.mongodb.ExplainVerbosity;
+import com.mongodb.lang.Nullable;
+import org.bson.codecs.Decoder;
+
+public interface AsyncExplainableReadOperation<T> extends AsyncReadOperation<T> {
+    <R> AsyncReadOperation<R> asAsyncExplainableOperation(@Nullable ExplainVerbosity verbosity, Decoder<R> resultDecoder);
+}

driver-core/src/main/com/mongodb/internal/operation/ExplainHelper.java

@@ -18,14 +18,18 @@
 
 import com.mongodb.ExplainVerbosity;
 import com.mongodb.MongoInternalException;
+import com.mongodb.lang.Nullable;
 import org.bson.BsonDocument;
 import org.bson.BsonString;
 
 final class ExplainHelper {
 
-    static BsonDocument asExplainCommand(final BsonDocument command, final ExplainVerbosity explainVerbosity) {
-        return new BsonDocument("explain", command)
-               .append("verbosity", getVerbosityAsString(explainVerbosity));
+    static BsonDocument asExplainCommand(final BsonDocument command, @Nullable final ExplainVerbosity explainVerbosity) {
+        BsonDocument explainCommand = new BsonDocument("explain", command);
+        if (explainVerbosity != null) {
+            explainCommand.append("verbosity", getVerbosityAsString(explainVerbosity));
+        }
+        return explainCommand;
     }
 
     private static BsonString getVerbosityAsString(final ExplainVerbosity explainVerbosity) {

driver-core/src/main/com/mongodb/internal/operation/ExplainableReadOperation.java

@@ -0,0 +1,25 @@
+/*
+ * 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.internal.operation;
+
+import com.mongodb.ExplainVerbosity;
+import com.mongodb.lang.Nullable;
+import org.bson.codecs.Decoder;
+
+public interface ExplainableReadOperation<T> extends ReadOperation<T> {
+    <R> ReadOperation<R> asExplainableOperation(@Nullable ExplainVerbosity verbosity, Decoder<R> resultDecoder);
+}

driver-core/src/main/com/mongodb/internal/operation/FindOperation.java

@@ -17,6 +17,7 @@
 package com.mongodb.internal.operation;
 
 import com.mongodb.CursorType;
+import com.mongodb.ExplainVerbosity;
 import com.mongodb.MongoCommandException;
 import com.mongodb.MongoNamespace;
 import com.mongodb.MongoQueryException;
@@ -43,7 +44,6 @@
 import org.bson.BsonInt64;
 import org.bson.BsonString;
 import org.bson.BsonValue;
-import org.bson.codecs.BsonDocumentCodec;
 import org.bson.codecs.Decoder;
 
 import java.util.concurrent.TimeUnit;
@@ -60,6 +60,7 @@
 import static com.mongodb.internal.operation.CommandOperationHelper.executeCommandWithConnection;
 import static com.mongodb.internal.operation.DocumentHelper.putIfNotNull;
 import static com.mongodb.internal.operation.DocumentHelper.putIfNotNullOrEmpty;
+import static com.mongodb.internal.operation.ExplainHelper.asExplainCommand;
 import static com.mongodb.internal.operation.OperationHelper.AsyncCallableWithConnectionAndSource;
 import static com.mongodb.internal.operation.OperationHelper.LOGGER;
 import static com.mongodb.internal.operation.OperationHelper.cursorDocumentToQueryResult;
@@ -76,7 +77,7 @@
  * @param <T> the operations result type.
  * @since 3.0
  */
-public class FindOperation<T> implements AsyncReadOperation<AsyncBatchCursor<T>>, ReadOperation<BatchCursor<T>> {
+public class FindOperation<T> implements AsyncExplainableReadOperation<AsyncBatchCursor<T>>, ExplainableReadOperation<BatchCursor<T>> {
     private static final String FIRST_BATCH = "firstBatch";
 
     private final MongoNamespace namespace;
@@ -757,16 +758,20 @@ public void onResult(final T result, final Throwable t) {
         };
     }
 
+    @Override
+    public <R> ReadOperation<R> asExplainableOperation(@Nullable final ExplainVerbosity verbosity,
+                                                       final Decoder<R> resultDecoder) {
+        return new CommandReadOperation<R>(getNamespace().getDatabaseName(),
+                asExplainCommand(getCommand(NoOpSessionContext.INSTANCE), verbosity),
+                resultDecoder);
+    }
 
-    /**
-     * Gets an operation whose execution explains this operation.
-     *
-     * @return a read operation that when executed will explain this operation
-     */
-    public ReadOperation<BsonDocument> asExplainableOperation() {
-        return new CommandReadOperation<>(getNamespace().getDatabaseName(),
-                new BsonDocument("explain", getCommand(NoOpSessionContext.INSTANCE, null)),
-                new BsonDocumentCodec());
+    @Override
+    public <R> AsyncReadOperation<R> asAsyncExplainableOperation(@Nullable final ExplainVerbosity verbosity,
+                                                                 final Decoder<R> resultDecoder) {
+        return new CommandReadOperation<R>(getNamespace().getDatabaseName(),
+                asExplainCommand(getCommand(NoOpSessionContext.INSTANCE), verbosity),
+                resultDecoder);
     }
 
     private BsonDocument asDocument(final ConnectionDescription connectionDescription, final ReadPreference readPreference) {
@@ -811,7 +816,7 @@ private BsonDocument asDocument(final ConnectionDescription connectionDescriptio
         return document;
     }
 
-    private BsonDocument getCommand(final SessionContext sessionContext, final ConnectionDescription description) {
+    private BsonDocument getCommand(final SessionContext sessionContext) {
         BsonDocument commandDocument = new BsonDocument("find", new BsonString(namespace.getCollectionName()));
 
         appendReadConcernToCommand(sessionContext, commandDocument);
@@ -885,7 +890,7 @@ private CommandCreator getCommandCreator(final SessionContext sessionContext) {
             @Override
             public BsonDocument create(final ServerDescription serverDescription, final ConnectionDescription connectionDescription) {
                 validateFindOptions(connectionDescription, sessionContext.getReadConcern(), collation, allowDiskUse);
-                return getCommand(sessionContext, connectionDescription);
+                return getCommand(sessionContext);
             }
         };
     }

driver-core/src/main/com/mongodb/internal/operation/SyncOperations.java

@@ -88,7 +88,7 @@ public <TResult> ReadOperation<BatchCursor<TResult>> findFirst(final Bson filter
         return operations.findFirst(filter, resultClass, options);
     }
 
-    public <TResult> ReadOperation<BatchCursor<TResult>> find(final Bson filter, final Class<TResult> resultClass,
+    public <TResult> ExplainableReadOperation<BatchCursor<TResult>> find(final Bson filter, final Class<TResult> resultClass,
                                                               final FindOptions options) {
         return operations.find(filter, resultClass, options);
     }

driver-core/src/test/functional/com/mongodb/internal/operation/FindOperationSpecification.groovy

@@ -404,7 +404,7 @@ class FindOperationSpecification extends OperationFunctionalSpecification {
 
         def operation = new FindOperation<Document>(getNamespace(), new DocumentCodec())
                 .hint((BsonValue) hint)
-                .asExplainableOperation()
+                .asExplainableOperation(null, new BsonDocumentCodec())
 
         when:
         def explainPlan = execute(operation, async)

driver-legacy/src/main/com/mongodb/DBCursor.java

@@ -33,7 +33,7 @@
 import java.util.NoSuchElementException;
 import java.util.concurrent.TimeUnit;
 
-import static com.mongodb.DBObjects.toDBObject;
+import static com.mongodb.MongoClient.getDefaultCodecRegistry;
 import static com.mongodb.assertions.Assertions.notNull;
 import static java.util.concurrent.TimeUnit.MILLISECONDS;
 
@@ -339,9 +339,9 @@ public DBCursor maxTime(final long maxTime, final TimeUnit timeUnit) {
      */
     @Deprecated
     public DBObject explain() {
-        return toDBObject(executor.execute(getQueryOperation(collection.getObjectCodec())
-                                           .asExplainableOperation(),
-                                           getReadPreference(), getReadConcern()));
+        return executor.execute(getQueryOperation(collection.getObjectCodec())
+                        .asExplainableOperation(null, getDefaultCodecRegistry().get(DBObject.class)),
+                getReadPreference(), getReadConcern());
     }
 
     /**

driver-reactive-streams/src/main/com/mongodb/reactivestreams/client/FindPublisher.java

@@ -17,8 +17,10 @@
 package com.mongodb.reactivestreams.client;
 
 import com.mongodb.CursorType;
+import com.mongodb.ExplainVerbosity;
 import com.mongodb.client.model.Collation;
 import com.mongodb.lang.Nullable;
+import org.bson.Document;
 import org.bson.conversions.Bson;
 import org.reactivestreams.Publisher;
 
@@ -246,4 +248,50 @@ public interface FindPublisher<TResult> extends Publisher<TResult> {
      * @mongodb.server.release 4.4
      */
     FindPublisher<TResult> allowDiskUse(@Nullable Boolean allowDiskUse);
+
+    /**
+     * Explain the execution plan for this operation with the server's default verbosity level
+     *
+     * @return the execution plan
+     * @since 4.2
+     * @mongodb.driver.manual reference/command/explain/
+     * @mongodb.server.release 3.2
+     */
+    Publisher<Document> explain();
+
+    /**
+     * Explain the execution plan for this operation with the given verbosity level
+     *
+     * @param verbosity the verbosity of the explanation
+     * @return the execution plan
+     * @since 4.2
+     * @mongodb.driver.manual reference/command/explain/
+     * @mongodb.server.release 3.2
+     */
+    Publisher<Document> explain(ExplainVerbosity verbosity);
+
+    /**
+     * Explain the execution plan for this operation with the server's default verbosity level
+     *
+     * @param <E> the type of the document class
+     * @param explainResultClass the document class to decode into
+     * @return the execution plan
+     * @since 4.2
+     * @mongodb.driver.manual reference/command/explain/
+     * @mongodb.server.release 3.2
+     */
+    <E> Publisher<E> explain(Class<E> explainResultClass);
+
+    /**
+     * Explain the execution plan for this operation with the given verbosity level
+     *
+     * @param <E> the type of the document class
+     * @param explainResultClass the document class to decode into
+     * @param verbosity            the verbosity of the explanation
+     * @return the execution plan
+     * @since 4.2
+     * @mongodb.driver.manual reference/command/explain/
+     * @mongodb.server.release 3.2
+     */
+    <E> Publisher<E> explain(Class<E> explainResultClass, ExplainVerbosity verbosity);
 }

driver-reactive-streams/src/main/com/mongodb/reactivestreams/client/internal/FindPublisherImpl.java

@@ -17,14 +17,18 @@
 package com.mongodb.reactivestreams.client.internal;
 
 import com.mongodb.CursorType;
+import com.mongodb.ExplainVerbosity;
 import com.mongodb.client.model.Collation;
 import com.mongodb.internal.async.AsyncBatchCursor;
 import com.mongodb.internal.client.model.FindOptions;
+import com.mongodb.internal.operation.AsyncExplainableReadOperation;
 import com.mongodb.internal.operation.AsyncReadOperation;
 import com.mongodb.lang.Nullable;
 import com.mongodb.reactivestreams.client.ClientSession;
 import com.mongodb.reactivestreams.client.FindPublisher;
+import org.bson.Document;
 import org.bson.conversions.Bson;
+import org.reactivestreams.Publisher;
 
 import java.util.concurrent.TimeUnit;
 
@@ -172,9 +176,36 @@ public FindPublisher<T> allowDiskUse(@Nullable final Boolean allowDiskUse) {
         return this;
     }
 
+    @Override
+    public Publisher<Document> explain() {
+        return publishExplain(Document.class, null);
+    }
+
+    @Override
+    public Publisher<Document> explain(final ExplainVerbosity verbosity) {
+        return publishExplain(Document.class, notNull("verbosity", verbosity));
+    }
+
+    @Override
+    public <E> Publisher<E> explain(final Class<E> explainResultClass) {
+        return publishExplain(explainResultClass, null);
+    }
+
+    @Override
+    public <E> Publisher<E> explain(final Class<E> explainResultClass, final ExplainVerbosity verbosity) {
+        return publishExplain(explainResultClass, notNull("verbosity", verbosity));
+    }
+
+    private <E> Publisher<E> publishExplain(final Class<E> explainResultClass, @Nullable final ExplainVerbosity verbosity) {
+        notNull("explainDocumentClass", explainResultClass);
+        return getMongoOperationPublisher().createReadOperationMono(() ->
+                        asAsyncReadOperation().asAsyncExplainableOperation(verbosity,
+                                getCodecRegistry().get(explainResultClass)),
+                getClientSession());
+    }
 
     @Override
-    AsyncReadOperation<AsyncBatchCursor<T>> asAsyncReadOperation() {
+    AsyncExplainableReadOperation<AsyncBatchCursor<T>> asAsyncReadOperation() {
         return getOperations().find(filter, getDocumentClass(), findOptions);
     }
 

driver-reactive-streams/src/test/functional/com/mongodb/reactivestreams/client/ExplainTest.java

@@ -0,0 +1,31 @@
+/*
+ * 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.reactivestreams.client;
+
+import com.mongodb.MongoClientSettings;
+import com.mongodb.client.AbstractExplainTest;
+import com.mongodb.client.MongoClient;
+import com.mongodb.lang.NonNull;
+import com.mongodb.reactivestreams.client.syncadapter.SyncMongoClient;
+
+public class ExplainTest extends AbstractExplainTest {
+    @Override
+    @NonNull
+    protected MongoClient createMongoClient(@NonNull final MongoClientSettings settings) {
+        return new SyncMongoClient(MongoClients.create(settings));
+    }
+}