Replace @Evolving with @Sealed where appropriate (#1141)

JAVA-5020
mongodb · Jun 16, 2023 · 0f68e1e · 0f68e1e
1 parent ce6c119
commit 0f68e1e
Show file tree

Hide file tree

Showing 49 changed files with 180 additions and 140 deletions.
diff --git a/driver-core/src/main/com/mongodb/annotations/Evolving.java b/driver-core/src/main/com/mongodb/annotations/Evolving.java
@@ -18,6 +18,9 @@
 
 package com.mongodb.annotations;
 
+import com.mongodb.connection.StreamFactoryFactory;
+import org.bson.conversions.Bson;
+
 import java.lang.annotation.Documented;
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
@@ -30,6 +33,41 @@
  * of doing extra work during upgrades.
  * Using such program elements is no different from using ordinary unannotated program elements.
  * Note that the presence of this annotation implies nothing about the quality or performance of the API in question.
+ * <p>
+ * Unless we currently want to allow users to extend/implement API program elements, we must annotate them with
+ * {@code @}{@link Sealed} rather than {@code @}{@link Evolving}. Replacing {@code @}{@link Sealed} with {@code @}{@link Evolving}
+ * is a backward-compatible change, while the opposite is not.</p>
+ *
+ * <table>
+ *   <caption>Reasons we may allow users to extend/implement an API program element</caption>
+ *   <tr>
+ *     <th>Reason</th>
+ *     <th>Example</th>
+ *     <th>Applicability of {@code @}{@link Evolving}</th>
+ *   </tr>
+ *   <tr>
+ *     <td>Doing so allows/simplifies integrating user code with the API.</td>
+ *     <td>{@link Bson}</td>
+ *     <td>Not applicable.</td>
+ *   </tr>
+ *   <tr>
+ *     <td>Doing so allows customizing API behavior.</td>
+ *     <td>{@link StreamFactoryFactory}</td>
+ *     <td>Not applicable.</td>
+ *   </tr>
+ *   <tr>
+ *     <td>Doing so facilitates writing application unit tests by creating a fake implementation.</td>
+ *     <td>{@code com.mongodb.client.MongoClient}</td>
+ *     <td>Applicable.</td>
+ *   </tr>
+ *   <tr>
+ *     <td>The program element was introduced before {@code @}{@link Evolving}.</td>
+ *     <td>{@code com.mongodb.client.MongoClient}</td>
+ *     <td>Applicable.</td>
+ *   </tr>
+ * </table>
+ *
+ * @see Sealed
  */
 @Retention(RetentionPolicy.CLASS)
 @Target(ElementType.TYPE)

diff --git a/driver-core/src/main/com/mongodb/annotations/Sealed.java b/driver-core/src/main/com/mongodb/annotations/Sealed.java
@@ -26,13 +26,15 @@
 
 /**
  * Signifies that the annotated class or interface should be treated as sealed:
- * it must not be extended or implemented.
+ * it must not be extended or implemented by consumers of the library.
  *
  * <p>Using such classes and interfaces is no different from using ordinary
  * unannotated classes and interfaces.
  *
  * <p>This annotation does not imply that the API is experimental or
  * {@link Beta}, or that the quality or performance of the API is inferior.
+ *
+ * @see Evolving
  */
 @Retention(RetentionPolicy.CLASS)
 @Target(ElementType.TYPE)

diff --git a/driver-core/src/main/com/mongodb/client/model/search/AddSearchScoreExpression.java b/driver-core/src/main/com/mongodb/client/model/search/AddSearchScoreExpression.java
@@ -16,13 +16,13 @@
 package com.mongodb.client.model.search;
 
 import com.mongodb.annotations.Beta;
-import com.mongodb.annotations.Evolving;
+import com.mongodb.annotations.Sealed;
 
 /**
  * @see SearchScoreExpression#addExpression(Iterable)
  * @since 4.7
  */
-@Evolving
+@Sealed
 @Beta(Beta.Reason.CLIENT)
 public interface AddSearchScoreExpression extends SearchScoreExpression {
 }
diff --git a/driver-core/src/main/com/mongodb/client/model/search/AutocompleteSearchOperator.java b/driver-core/src/main/com/mongodb/client/model/search/AutocompleteSearchOperator.java
@@ -16,14 +16,14 @@
 package com.mongodb.client.model.search;
 
 import com.mongodb.annotations.Beta;
-import com.mongodb.annotations.Evolving;
+import com.mongodb.annotations.Sealed;
 
 /**
  * @see SearchOperator#autocomplete(FieldSearchPath, String, String...)
  * @see SearchOperator#autocomplete(FieldSearchPath, Iterable)
  * @since 4.7
  */
-@Evolving
+@Sealed
 @Beta(Beta.Reason.CLIENT)
 public interface AutocompleteSearchOperator extends SearchOperator {
     @Override

diff --git a/driver-core/src/main/com/mongodb/client/model/search/CompoundSearchOperator.java b/driver-core/src/main/com/mongodb/client/model/search/CompoundSearchOperator.java
@@ -16,13 +16,13 @@
 package com.mongodb.client.model.search;
 
 import com.mongodb.annotations.Beta;
-import com.mongodb.annotations.Evolving;
+import com.mongodb.annotations.Sealed;
 
 /**
  * @see SearchOperator#compound()
  * @since 4.7
  */
-@Evolving
+@Sealed
 @Beta(Beta.Reason.CLIENT)
 public interface CompoundSearchOperator extends CompoundSearchOperatorBase, SearchOperator {
     @Override

diff --git a/driver-core/src/main/com/mongodb/client/model/search/CompoundSearchOperatorBase.java b/driver-core/src/main/com/mongodb/client/model/search/CompoundSearchOperatorBase.java
@@ -16,7 +16,7 @@
 package com.mongodb.client.model.search;
 
 import com.mongodb.annotations.Beta;
-import com.mongodb.annotations.Evolving;
+import com.mongodb.annotations.Sealed;
 
 /**
  * A base for a {@link CompoundSearchOperator} which allows creating instances of this operator.
@@ -25,7 +25,7 @@
  * @see SearchOperator#compound()
  * @since 4.7
  */
-@Evolving
+@Sealed
 @Beta(Beta.Reason.CLIENT)
 public interface CompoundSearchOperatorBase {
     /**

diff --git a/driver-core/src/main/com/mongodb/client/model/search/ConstantSearchScore.java b/driver-core/src/main/com/mongodb/client/model/search/ConstantSearchScore.java
@@ -16,13 +16,13 @@
 package com.mongodb.client.model.search;
 
 import com.mongodb.annotations.Beta;
-import com.mongodb.annotations.Evolving;
+import com.mongodb.annotations.Sealed;
 
 /**
  * @see SearchScore#constant(float)
  * @since 4.7
  */
-@Evolving
+@Sealed
 @Beta(Beta.Reason.CLIENT)
 public interface ConstantSearchScore extends SearchScore {
 }
diff --git a/driver-core/src/main/com/mongodb/client/model/search/ConstantSearchScoreExpression.java b/driver-core/src/main/com/mongodb/client/model/search/ConstantSearchScoreExpression.java
@@ -16,13 +16,13 @@
 package com.mongodb.client.model.search;
 
 import com.mongodb.annotations.Beta;
-import com.mongodb.annotations.Evolving;
+import com.mongodb.annotations.Sealed;
 
 /**
  * @see SearchScoreExpression#constantExpression(float)
  * @since 4.7
  */
-@Evolving
+@Sealed
 @Beta(Beta.Reason.CLIENT)
 public interface ConstantSearchScoreExpression extends SearchScoreExpression {
 }
diff --git a/driver-core/src/main/com/mongodb/client/model/search/DateNearSearchOperator.java b/driver-core/src/main/com/mongodb/client/model/search/DateNearSearchOperator.java
@@ -16,7 +16,7 @@
 package com.mongodb.client.model.search;
 
 import com.mongodb.annotations.Beta;
-import com.mongodb.annotations.Evolving;
+import com.mongodb.annotations.Sealed;
 
 import java.time.Duration;
 import java.time.Instant;
@@ -26,7 +26,7 @@
  * @see SearchOperator#near(Instant, Duration, Iterable)
  * @since 4.7
  */
-@Evolving
+@Sealed
 @Beta(Beta.Reason.CLIENT)
 public interface DateNearSearchOperator extends SearchOperator {
     @Override

diff --git a/driver-core/src/main/com/mongodb/client/model/search/DateRangeSearchOperator.java b/driver-core/src/main/com/mongodb/client/model/search/DateRangeSearchOperator.java
@@ -16,14 +16,14 @@
 package com.mongodb.client.model.search;
 
 import com.mongodb.annotations.Beta;
-import com.mongodb.annotations.Evolving;
+import com.mongodb.annotations.Sealed;
 
 /**
  * @see SearchOperator#dateRange(FieldSearchPath, FieldSearchPath...)
  * @see SearchOperator#dateRange(Iterable)
  * @since 4.7
  */
-@Evolving
+@Sealed
 @Beta(Beta.Reason.CLIENT)
 public interface DateRangeSearchOperator extends DateRangeSearchOperatorBase, SearchOperator {
     @Override

diff --git a/driver-core/src/main/com/mongodb/client/model/search/DateRangeSearchOperatorBase.java b/driver-core/src/main/com/mongodb/client/model/search/DateRangeSearchOperatorBase.java
@@ -16,7 +16,7 @@
 package com.mongodb.client.model.search;
 
 import com.mongodb.annotations.Beta;
-import com.mongodb.annotations.Evolving;
+import com.mongodb.annotations.Sealed;
 
 import java.time.Instant;
 
@@ -28,7 +28,7 @@
  * @see SearchOperator#dateRange(Iterable)
  * @since 4.7
  */
-@Evolving
+@Sealed
 @Beta(Beta.Reason.CLIENT)
 public interface DateRangeSearchOperatorBase {
     /**

diff --git a/driver-core/src/main/com/mongodb/client/model/search/DateSearchFacet.java b/driver-core/src/main/com/mongodb/client/model/search/DateSearchFacet.java
@@ -16,13 +16,13 @@
 package com.mongodb.client.model.search;
 
 import com.mongodb.annotations.Beta;
-import com.mongodb.annotations.Evolving;
+import com.mongodb.annotations.Sealed;
 
 /**
  * @see SearchFacet#dateFacet(String, FieldSearchPath, Iterable)
  * @since 4.7
  */
-@Evolving
+@Sealed
 @Beta({Beta.Reason.CLIENT, Beta.Reason.SERVER})
 public interface DateSearchFacet extends SearchFacet {
     /**

diff --git a/driver-core/src/main/com/mongodb/client/model/search/ExistsSearchOperator.java b/driver-core/src/main/com/mongodb/client/model/search/ExistsSearchOperator.java
@@ -16,13 +16,13 @@
 package com.mongodb.client.model.search;
 
 import com.mongodb.annotations.Beta;
-import com.mongodb.annotations.Evolving;
+import com.mongodb.annotations.Sealed;
 
 /**
  * @see SearchOperator#exists(FieldSearchPath)
  * @since 4.7
  */
-@Evolving
+@Sealed
 @Beta(Beta.Reason.CLIENT)
 public interface ExistsSearchOperator extends SearchOperator {
     @Override

diff --git a/driver-core/src/main/com/mongodb/client/model/search/FacetSearchCollector.java b/driver-core/src/main/com/mongodb/client/model/search/FacetSearchCollector.java
@@ -16,13 +16,13 @@
 package com.mongodb.client.model.search;
 
 import com.mongodb.annotations.Beta;
-import com.mongodb.annotations.Evolving;
+import com.mongodb.annotations.Sealed;
 
 /**
  * @see SearchCollector#facet(SearchOperator, Iterable)
  * @since 4.7
  */
-@Evolving
+@Sealed
 @Beta({Beta.Reason.CLIENT, Beta.Reason.SERVER})
 public interface FacetSearchCollector extends SearchCollector {
 }
diff --git a/driver-core/src/main/com/mongodb/client/model/search/FieldSearchPath.java b/driver-core/src/main/com/mongodb/client/model/search/FieldSearchPath.java
@@ -16,7 +16,7 @@
 package com.mongodb.client.model.search;
 
 import com.mongodb.annotations.Beta;
-import com.mongodb.annotations.Evolving;
+import com.mongodb.annotations.Sealed;
 import org.bson.conversions.Bson;
 
 import static com.mongodb.internal.client.model.Util.SEARCH_PATH_VALUE_KEY;
@@ -25,7 +25,7 @@
  * @see SearchPath#fieldPath(String)
  * @since 4.7
  */
-@Evolving
+@Sealed
 @Beta(Beta.Reason.CLIENT)
 public interface FieldSearchPath extends SearchPath {
     /**

diff --git a/driver-core/src/main/com/mongodb/client/model/search/FilterCompoundSearchOperator.java b/driver-core/src/main/com/mongodb/client/model/search/FilterCompoundSearchOperator.java
@@ -16,7 +16,7 @@
 package com.mongodb.client.model.search;
 
 import com.mongodb.annotations.Beta;
-import com.mongodb.annotations.Evolving;
+import com.mongodb.annotations.Sealed;
 
 /**
  * A representation of a {@link CompoundSearchOperator} that allows changing
@@ -26,7 +26,7 @@
  * @see CompoundSearchOperatorBase#filter(Iterable)
  * @since 4.7
  */
-@Evolving
+@Sealed
 @Beta(Beta.Reason.CLIENT)
 public interface FilterCompoundSearchOperator extends CompoundSearchOperator {
     @Override

diff --git a/driver-core/src/main/com/mongodb/client/model/search/FunctionSearchScore.java b/driver-core/src/main/com/mongodb/client/model/search/FunctionSearchScore.java
@@ -16,13 +16,13 @@
 package com.mongodb.client.model.search;
 
 import com.mongodb.annotations.Beta;
-import com.mongodb.annotations.Evolving;
+import com.mongodb.annotations.Sealed;
 
 /**
  * @see SearchScore#function(SearchScoreExpression)
  * @since 4.7
  */
-@Evolving
+@Sealed
 @Beta(Beta.Reason.CLIENT)
 public interface FunctionSearchScore extends SearchScore {
 }
diff --git a/driver-core/src/main/com/mongodb/client/model/search/FuzzySearchOptions.java b/driver-core/src/main/com/mongodb/client/model/search/FuzzySearchOptions.java
@@ -16,7 +16,7 @@
 package com.mongodb.client.model.search;
 
 import com.mongodb.annotations.Beta;
-import com.mongodb.annotations.Evolving;
+import com.mongodb.annotations.Sealed;
 import org.bson.conversions.Bson;
 
 /**
@@ -26,7 +26,7 @@
  * @mongodb.atlas.manual atlas-search/text/ text operator
  * @since 4.7
  */
-@Evolving
+@Sealed
 @Beta(Beta.Reason.CLIENT)
 public interface FuzzySearchOptions extends Bson {
     /**

diff --git a/driver-core/src/main/com/mongodb/client/model/search/GaussSearchScoreExpression.java b/driver-core/src/main/com/mongodb/client/model/search/GaussSearchScoreExpression.java
@@ -16,13 +16,13 @@
 package com.mongodb.client.model.search;
 
 import com.mongodb.annotations.Beta;
-import com.mongodb.annotations.Evolving;
+import com.mongodb.annotations.Sealed;
 
 /**
  * @see SearchScoreExpression#gaussExpression(double, PathSearchScoreExpression, double)
  * @since 4.7
  */
-@Evolving
+@Sealed
 @Beta(Beta.Reason.CLIENT)
 public interface GaussSearchScoreExpression extends SearchScoreExpression {
     /**

diff --git a/driver-core/src/main/com/mongodb/client/model/search/GeoNearSearchOperator.java b/driver-core/src/main/com/mongodb/client/model/search/GeoNearSearchOperator.java
@@ -16,15 +16,15 @@
 package com.mongodb.client.model.search;
 
 import com.mongodb.annotations.Beta;
-import com.mongodb.annotations.Evolving;
+import com.mongodb.annotations.Sealed;
 import com.mongodb.client.model.geojson.Point;
 
 /**
  * @see SearchOperator#near(Point, Number, FieldSearchPath, FieldSearchPath...)
  * @see SearchOperator#near(Point, Number, Iterable)
  * @since 4.7
  */
-@Evolving
+@Sealed
 @Beta(Beta.Reason.CLIENT)
 public interface GeoNearSearchOperator extends SearchOperator {
     @Override

diff --git a/driver-core/src/main/com/mongodb/client/model/search/Log1pSearchScoreExpression.java b/driver-core/src/main/com/mongodb/client/model/search/Log1pSearchScoreExpression.java
@@ -16,13 +16,13 @@
 package com.mongodb.client.model.search;
 
 import com.mongodb.annotations.Beta;
-import com.mongodb.annotations.Evolving;
+import com.mongodb.annotations.Sealed;
 
 /**
  * @see SearchScoreExpression#log1pExpression(SearchScoreExpression)
  * @since 4.7
  */
-@Evolving
+@Sealed
 @Beta(Beta.Reason.CLIENT)
 public interface Log1pSearchScoreExpression extends SearchScoreExpression {
 }