Support creation of time-series collections (#723)

JAVA-3997

Author: jyemin

driver-core/src/main/com/mongodb/client/model/CreateCollectionOptions.java

@@ -19,12 +19,15 @@
 import com.mongodb.lang.Nullable;
 import org.bson.conversions.Bson;
 
+import java.util.concurrent.TimeUnit;
+
 import static com.mongodb.assertions.Assertions.notNull;
 
 /**
  * Options for creating a collection
  *
  * @mongodb.driver.manual reference/method/db.createCollection/ Create Collection
+ * @mongodb.driver.manual core/timeseries-collections/ Time-series collections
  * @since 3.0
  */
 public class CreateCollectionOptions {
@@ -35,6 +38,8 @@ public class CreateCollectionOptions {
     private IndexOptionDefaults indexOptionDefaults = new IndexOptionDefaults();
     private ValidationOptions validationOptions = new ValidationOptions();
     private Collation collation;
+    private long expireAfterSeconds;
+    private TimeSeriesOptions timeSeriesOptions;
 
     /**
      * Gets the maximum number of documents allowed in a capped collection.
@@ -194,6 +199,71 @@ public CreateCollectionOptions collation(@Nullable final Collation collation) {
         return this;
     }
 
+    /**
+     * Returns the expire-after option.  The default value is 0, which indicates no expiration.
+     *
+     * @param timeUnit the time unit
+     * @return the expire-after option, which may be null.
+     * @since 4.3
+     * @mongodb.driver.manual core/timeseries-collections/ Time-series collections
+     */
+    public long getExpireAfter(final TimeUnit timeUnit) {
+        notNull("timeUnit", timeUnit);
+        return timeUnit.convert(expireAfterSeconds, TimeUnit.SECONDS);
+    }
+
+    /**
+     * Sets the expire-after option.
+     *
+     * <p>
+     * A duration indicating after how long old time-series data should be deleted. Partial seconds are ignored.
+     * </p>
+     * <p>
+     * Currently applies only to time-series collections, so if this value is set then so must the time-series options
+     * </p>
+     * @param expireAfter the expire-after duration.  After conversion to seconds using
+     * {@link TimeUnit#convert(long, java.util.concurrent.TimeUnit)}, the value must be &gt;= 0.  A value of 0 indicates no expiration.
+     * @param timeUnit the time unit
+     * @return this
+     * @since 4.3
+     * @see #timeSeriesOptions(TimeSeriesOptions)
+     * @mongodb.driver.manual core/timeseries-collections/ Time-series collections
+     */
+    public CreateCollectionOptions expireAfter(final long expireAfter, final TimeUnit timeUnit) {
+        notNull("timeUnit", timeUnit);
+        long asSeconds = TimeUnit.SECONDS.convert(expireAfter, timeUnit);
+        if (asSeconds < 0) {
+            throw new IllegalArgumentException("expireAfter, after conversion to seconds, must be >= 0");
+        }
+        this.expireAfterSeconds = asSeconds;
+        return this;
+    }
+
+    /**
+     * Gets the time series collection options.
+     *
+     * @return the options for a time-series collection
+     * @since 4.3
+     * @mongodb.driver.manual core/timeseries-collections/ Time-series collections
+     */
+    @Nullable
+    public TimeSeriesOptions getTimeSeriesOptions() {
+        return timeSeriesOptions;
+    }
+
+    /**
+     * Sets the time-series collection options.
+     *
+     * @param timeSeriesOptions the time-series options
+     * @return this
+     * @since 4.3
+     * @mongodb.driver.manual core/timeseries-collections/ Time-series collections
+     */
+    public CreateCollectionOptions timeSeriesOptions(final TimeSeriesOptions timeSeriesOptions) {
+        this.timeSeriesOptions = timeSeriesOptions;
+        return this;
+    }
+
     @Override
     public String toString() {
         return "CreateCollectionOptions{"
@@ -204,6 +274,8 @@ public String toString() {
                 + ", indexOptionDefaults=" + indexOptionDefaults
                 + ", validationOptions=" + validationOptions
                 + ", collation=" + collation
+                + ", expireAfterSeconds=" + expireAfterSeconds
+                + ", timeSeriesOptions=" + timeSeriesOptions
                 + '}';
     }
 }

driver-core/src/main/com/mongodb/client/model/TimeSeriesGranularity.java

@@ -0,0 +1,46 @@
+/*
+ * 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.client.model;
+
+/**
+ * An enumeration of time-series data granularity.
+ * <p>
+ * It describes the units one would use to describe the expected interval between subsequent measurements for a time-series.
+ * </p>
+ * @since 4.3
+ * @see TimeSeriesOptions
+ * @see CreateCollectionOptions
+ */
+public enum TimeSeriesGranularity {
+    /**
+     * Seconds-level granularity.
+     * <p>
+     * If granularity of a time-series collection is unspecified, this is the default value.
+     * </p>
+     */
+    SECONDS,
+
+    /**
+     * Minutes-level granularity.
+     */
+    MINUTES,
+
+    /**
+     * Hours-level granularity.
+     */
+    HOURS
+}

driver-core/src/main/com/mongodb/client/model/TimeSeriesOptions.java

@@ -0,0 +1,115 @@
+/*
+ * 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.client.model;
+
+import com.mongodb.lang.Nullable;
+
+import static com.mongodb.assertions.Assertions.notNull;
+
+/**
+ * Options related to the creation of time-series collections.
+ *
+ * @since 4.3
+ * @see CreateCollectionOptions
+ * @mongodb.driver.manual core/timeseries-collections/ Time-series collections
+ */
+public final class TimeSeriesOptions {
+    private final String timeField;
+    private String metaField;
+    private TimeSeriesGranularity granularity;
+
+    /**
+     * Construct a new instance.
+     *
+     * @param timeField the name of the top-level field to be used for time. Inserted documents must have this field, and the field must be
+     *                 of the BSON datetime type.
+     */
+    public TimeSeriesOptions(final String timeField) {
+        this.timeField = notNull("timeField", timeField);
+    }
+
+    /**
+     * Gets the name of the field holding the time value.
+     *
+     * @return the name of the field holding the time value.
+     */
+    public String getTimeField() {
+        return timeField;
+    }
+
+    /**
+     * Gets the name of the meta field.
+     *
+     * @return the name of the meta field
+     * @see #metaField(String)
+     */
+    @Nullable
+    public String getMetaField() {
+        return metaField;
+    }
+
+    /**
+     * Sets the name of the meta field.
+     * <p>
+     *  The name of the field which contains metadata in each time series document. The metadata in the specified field should be data
+     *  that is used to label a unique series of documents. The metadata should rarely, if ever, change.  This field is used to group
+     *  related data and may be of any BSON type, except for array. This name may not be the same as the {@code timeField} or "_id".
+     * </p>
+     * @param metaField the name of the meta field
+     * @return this
+     * @see #getMetaField()
+     */
+    public TimeSeriesOptions metaField(@Nullable final String metaField) {
+        this.metaField = metaField;
+        return this;
+    }
+
+    /**
+     * Gets the granularity of the time-series data.
+     *
+     * @return the time-series granularity
+     * @see #granularity(TimeSeriesGranularity)
+     */
+    @Nullable
+    public TimeSeriesGranularity getGranularity() {
+        return granularity;
+    }
+
+    /**
+     * Sets the granularity of the time-series data.
+     * <p>
+     * The default value is {@link TimeSeriesGranularity#SECONDS}.
+     * </p>
+     *
+     * @param granularity the time-series granularity
+     * @return this
+     * @see #getGranularity()
+     */
+    public TimeSeriesOptions granularity(@Nullable final TimeSeriesGranularity granularity) {
+        this.granularity = granularity;
+        return this;
+    }
+
+    @Override
+    public String toString() {
+        return "TimeSeriesOptions{"
+                + "timeField='" + timeField + '\''
+                + ", metaField='" + metaField + '\''
+                + ", granularity=" + granularity
+                + '}';
+    }
+}

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

@@ -17,16 +17,19 @@
 package com.mongodb.internal.operation;
 
 import com.mongodb.WriteConcern;
-import com.mongodb.internal.async.SingleResultCallback;
 import com.mongodb.client.model.Collation;
+import com.mongodb.client.model.TimeSeriesGranularity;
+import com.mongodb.client.model.TimeSeriesOptions;
 import com.mongodb.client.model.ValidationAction;
 import com.mongodb.client.model.ValidationLevel;
 import com.mongodb.connection.ConnectionDescription;
+import com.mongodb.internal.async.SingleResultCallback;
 import com.mongodb.internal.binding.AsyncWriteBinding;
 import com.mongodb.internal.binding.WriteBinding;
 import com.mongodb.internal.connection.AsyncConnection;
 import com.mongodb.internal.connection.Connection;
 import com.mongodb.internal.operation.OperationHelper.CallableWithConnection;
+import com.mongodb.lang.Nullable;
 import org.bson.BsonBoolean;
 import org.bson.BsonDocument;
 import org.bson.BsonString;
@@ -67,6 +70,8 @@ public class CreateCollectionOperation implements AsyncWriteOperation<Void>, Wri
     private ValidationLevel validationLevel = null;
     private ValidationAction validationAction = null;
     private Collation collation = null;
+    private long expireAfterSeconds;
+    private TimeSeriesOptions timeSeriesOptions;
 
     /**
      * Construct a new instance.
@@ -341,6 +346,16 @@ public CreateCollectionOperation collation(final Collation collation) {
         return this;
     }
 
+    public CreateCollectionOperation expireAfter(final long expireAfterSeconds) {
+        this.expireAfterSeconds = expireAfterSeconds;
+        return this;
+    }
+
+    public CreateCollectionOperation timeSeriesOptions(@Nullable final TimeSeriesOptions timeSeriesOptions) {
+        this.timeSeriesOptions = timeSeriesOptions;
+        return this;
+    }
+
     @Override
     public Void execute(final WriteBinding binding) {
         return withConnection(binding, new CallableWithConnection<Void>() {
@@ -407,7 +422,32 @@ private BsonDocument getCommand(final ConnectionDescription description) {
         if (collation != null) {
             document.put("collation", collation.asDocument());
         }
+        putIfNotZero(document, "expireAfterSeconds", expireAfterSeconds);
+        if (timeSeriesOptions != null) {
+            BsonDocument timeSeriesDocument = new BsonDocument("timeField", new BsonString(timeSeriesOptions.getTimeField()));
+            String metaField = timeSeriesOptions.getMetaField();
+            if (metaField != null) {
+                timeSeriesDocument.put("metaField", new BsonString(metaField));
+            }
+            TimeSeriesGranularity granularity = timeSeriesOptions.getGranularity();
+            if (granularity != null) {
+                timeSeriesDocument.put("granularity", new BsonString(getGranularityAsString(granularity)));
+            }
+            document.put("timeseries", timeSeriesDocument);
+        }
         return document;
     }
 
+    private String getGranularityAsString(final TimeSeriesGranularity granularity) {
+        switch (granularity) {
+            case SECONDS:
+                return "seconds";
+            case MINUTES:
+                return "minutes";
+            case HOURS:
+                return "hours";
+            default:
+                throw new AssertionError("Unexpected granularity " + granularity);
+        }
+    }
 }