Skip to content

Replace @Evolving with @Sealed where appropriate #1141

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jun 16, 2023
Merged

Replace @Evolving with @Sealed where appropriate #1141

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
46102dd
Replace `@Evolving` with `@Sealed` where appropriate
stIncMale Jun 9, 2023
bd61050
Address review concerns
stIncMale Jun 12, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions driver-core/src/main/com/mongodb/annotations/Evolving.java
View file
Open in desktop
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Evolving should have been annotated with @Sealed rather than @Evolving, but the idea of @Sealed did not come at that time, and now it will be a breaking change, even though one may be quite sure that no one extended Evolving.

Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note the documentation change.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor and optional: the example is the same for the last two items.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's because both apply there.

*/
@Retention(RetentionPolicy.CLASS)
@Target(ElementType.TYPE)
Expand Down
4 changes: 3 additions & 1 deletion driver-core/src/main/com/mongodb/annotations/Sealed.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
4 changes: 2 additions & 2 deletions driver-core/src/main/com/mongodb/client/model/search/AddSearchScoreExpression.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
}
4 changes: 2 additions & 2 deletions driver-core/src/main/com/mongodb/client/model/search/AutocompleteSearchOperator.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions driver-core/src/main/com/mongodb/client/model/search/CompoundSearchOperator.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions driver-core/src/main/com/mongodb/client/model/search/CompoundSearchOperatorBase.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -25,7 +25,7 @@
* @see SearchOperator#compound()
* @since 4.7
*/
@Evolving
@Sealed
@Beta(Beta.Reason.CLIENT)
public interface CompoundSearchOperatorBase {
/**
Expand Down
4 changes: 2 additions & 2 deletions driver-core/src/main/com/mongodb/client/model/search/ConstantSearchScore.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
}
4 changes: 2 additions & 2 deletions driver-core/src/main/com/mongodb/client/model/search/ConstantSearchScoreExpression.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
}
4 changes: 2 additions & 2 deletions driver-core/src/main/com/mongodb/client/model/search/DateNearSearchOperator.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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
Expand Down
4 changes: 2 additions & 2 deletions driver-core/src/main/com/mongodb/client/model/search/DateRangeSearchOperator.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions driver-core/src/main/com/mongodb/client/model/search/DateRangeSearchOperatorBase.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand All @@ -28,7 +28,7 @@
* @see SearchOperator#dateRange(Iterable)
* @since 4.7
*/
@Evolving
@Sealed
@Beta(Beta.Reason.CLIENT)
public interface DateRangeSearchOperatorBase {
/**
Expand Down
4 changes: 2 additions & 2 deletions driver-core/src/main/com/mongodb/client/model/search/DateSearchFacet.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
/**
Expand Down
4 changes: 2 additions & 2 deletions driver-core/src/main/com/mongodb/client/model/search/ExistsSearchOperator.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions driver-core/src/main/com/mongodb/client/model/search/FacetSearchCollector.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
}
4 changes: 2 additions & 2 deletions driver-core/src/main/com/mongodb/client/model/search/FieldSearchPath.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -25,7 +25,7 @@
* @see SearchPath#fieldPath(String)
* @since 4.7
*/
@Evolving
@Sealed
@Beta(Beta.Reason.CLIENT)
public interface FieldSearchPath extends SearchPath {
/**
Expand Down
4 changes: 2 additions & 2 deletions driver-core/src/main/com/mongodb/client/model/search/FilterCompoundSearchOperator.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -26,7 +26,7 @@
* @see CompoundSearchOperatorBase#filter(Iterable)
* @since 4.7
*/
@Evolving
@Sealed
@Beta(Beta.Reason.CLIENT)
public interface FilterCompoundSearchOperator extends CompoundSearchOperator {
@Override
Expand Down
4 changes: 2 additions & 2 deletions driver-core/src/main/com/mongodb/client/model/search/FunctionSearchScore.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
}
4 changes: 2 additions & 2 deletions driver-core/src/main/com/mongodb/client/model/search/FuzzySearchOptions.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;

/**
Expand All @@ -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 {
/**
Expand Down
4 changes: 2 additions & 2 deletions driver-core/src/main/com/mongodb/client/model/search/GaussSearchScoreExpression.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
/**
Expand Down
4 changes: 2 additions & 2 deletions driver-core/src/main/com/mongodb/client/model/search/GeoNearSearchOperator.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions driver-core/src/main/com/mongodb/client/model/search/Log1pSearchScoreExpression.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
}
Loading