KCBC-62 Temporarily remove OptIn requirements for volatile and uncommitted API

Motivation
----------
Kotlin's opt-in system has not yet been stabilized in Kotlin 1.6.
Rather than risk incompatibility with the future stable implementation,
we're going to hold off on adding opt-in requirements.

Modifications
-------------
Features annotated with @VolatileCouchbaseApi and @UncommittedCouchbaseApi
no longer require opt-in.

Note that they will likely require opt-in in the future,
once Kotlin's opt-in feature has stabilized.

Change-Id: Ia7c5014d2fbb96bb5e53eae5b704cfa449179b91
Reviewed-on: https://review.couchbase.org/c/couchbase-jvm-clients/+/170986
Tested-by: Build Bot <[email protected]>
Reviewed-by: David Nault <[email protected]>

Author: dnault

kotlin-client/pom.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
 
     <modelVersion>4.0.0</modelVersion>
 
@@ -22,7 +22,7 @@
         <kotlin.coroutines.version>1.6.0</kotlin.coroutines.version>
         <kotlin.code.style>official</kotlin.code.style>
         <dokka.version>1.6.0</dokka.version>
-        <moshi.version>1.12.0</moshi.version>
+        <moshi.version>1.13.0</moshi.version>
     </properties>
 
 
@@ -97,7 +97,7 @@
         <dependency>
             <groupId>io.github.microutils</groupId>
             <artifactId>kotlin-logging-jvm</artifactId>
-            <version>2.0.8</version>
+            <version>2.1.21</version>
             <scope>test</scope>
             <exclusions>
                 <!-- prevent stdlib version mismatch -->
@@ -125,15 +125,12 @@
                         <!-- Require explicit visibility modifiers so we don't
                              accidentally leak stuff into the public API -->
                         <arg>-Xexplicit-api=strict</arg>
-
-                        <!-- Flag uncommitted and volatile API -->
-                        <arg>-Xopt-in=kotlin.RequiresOptIn</arg>
                     </args>
                 </configuration>
                 <executions>
                     <execution>
                         <id>compile</id>
-                        <phase>compile</phase>
+                        <phase>process-sources</phase>
                         <goals>
                             <goal>compile</goal>
                         </goals>

kotlin-client/src/integrationTest/kotlin/com/couchbase/client/kotlin/KeyValueIntegrationTest.kt

@@ -68,7 +68,6 @@ import java.time.temporal.ChronoUnit.SECONDS as ChronoSeconds
 // with Gerrit verification.  Remove when mock is fixed:
 //    http://review.couchbase.org/c/CouchbaseMock/+/148081
 @IgnoreWhen(clusterTypes = [ClusterType.MOCKED])
-@OptIn(VolatileCouchbaseApi::class)
 internal class KeyValueIntegrationTest : KotlinIntegrationTest() {
 
     val nearFutureExpiry = Expiry.of(Instant.now().plus(3, ChronoDays).truncatedTo(ChronoSeconds))
@@ -140,7 +139,6 @@ internal class KeyValueIntegrationTest : KotlinIntegrationTest() {
     }
 
     @Nested
-    @VolatileCouchbaseApi
     inner class GetAnyReplicaOrNull {
         @Test
         fun `returns null`(): Unit = runBlocking {

kotlin-client/src/integrationTest/kotlin/com/couchbase/client/kotlin/LookupInIntegrationTest.kt

@@ -3,7 +3,6 @@ package com.couchbase.client.kotlin
 import com.couchbase.client.core.error.DocumentNotFoundException
 import com.couchbase.client.core.error.subdoc.DocumentTooDeepException
 import com.couchbase.client.core.msg.kv.CodecFlags
-import com.couchbase.client.kotlin.annotations.VolatileCouchbaseApi
 import com.couchbase.client.kotlin.codec.Content
 import com.couchbase.client.kotlin.internal.toStringUtf8
 import com.couchbase.client.kotlin.kv.LookupInSpec
@@ -20,7 +19,6 @@ import org.junit.jupiter.api.Nested
 import org.junit.jupiter.api.Test
 import org.junit.jupiter.api.assertThrows
 
-@OptIn(VolatileCouchbaseApi::class)
 @IgnoreWhen(clusterTypes = [ClusterType.MOCKED])
 internal class LookupInIntegrationTest : KotlinIntegrationTest() {
 

kotlin-client/src/integrationTest/kotlin/com/couchbase/client/kotlin/SubdocMutateIntegrationTest.kt

@@ -20,7 +20,6 @@ import com.couchbase.client.core.error.DocumentNotFoundException
 import com.couchbase.client.core.error.subdoc.PathExistsException
 import com.couchbase.client.core.error.subdoc.PathNotFoundException
 import com.couchbase.client.core.error.subdoc.XattrInvalidKeyComboException
-import com.couchbase.client.kotlin.annotations.VolatileCouchbaseApi
 import com.couchbase.client.kotlin.kv.Expiry
 import com.couchbase.client.kotlin.kv.LookupInSpec
 import com.couchbase.client.kotlin.kv.MutateInMacro
@@ -380,7 +379,6 @@ internal class SubdocMutateIntegrationTest : KotlinIntegrationTest() {
         assertEquals(7, updatedContent.getInt("foo"))
     }
 
-    @OptIn(VolatileCouchbaseApi::class)
     @IgnoreWhen(clusterTypes = [MOCKED])
     @Test
     fun `insert expand macro xattr do not flag`(): Unit = runBlocking {
@@ -390,7 +388,6 @@ internal class SubdocMutateIntegrationTest : KotlinIntegrationTest() {
         assertEquals("\${Mutation.CAS}", updatedContent.getString("foo"))
     }
 
-    @OptIn(VolatileCouchbaseApi::class)
     @IgnoreWhen(clusterTypes = [MOCKED])
     @Test
     fun `insert expand macro xattr`(): Unit = runBlocking {
@@ -400,7 +397,6 @@ internal class SubdocMutateIntegrationTest : KotlinIntegrationTest() {
         assertThat(updatedContent.getString("foo")).matches(HEX_ENCODED_INT64)
     }
 
-    @OptIn(VolatileCouchbaseApi::class)
     @IgnoreWhen(clusterTypes = [MOCKED])
     @Test
     fun `insert expand macro crc32 xattr`(): Unit = runBlocking {
@@ -410,7 +406,6 @@ internal class SubdocMutateIntegrationTest : KotlinIntegrationTest() {
         assertThat(updatedContent.getString("foo")).matches(HEX_ENCODED_INT32)
     }
 
-    @OptIn(VolatileCouchbaseApi::class)
     @IgnoreWhen(clusterTypes = [MOCKED])
     @Test
     fun `insert expand macro seqno xattr`(): Unit = runBlocking {
@@ -420,7 +415,6 @@ internal class SubdocMutateIntegrationTest : KotlinIntegrationTest() {
         assertThat(updatedContent.getString("foo")).matches(HEX_ENCODED_INT64)
     }
 
-    @OptIn(VolatileCouchbaseApi::class)
     @IgnoreWhen(clusterTypes = [MOCKED])
     @Test
     fun `upsert expand macro xattr`(): Unit = runBlocking {

kotlin-client/src/integrationTest/kotlin/com/couchbase/client/kotlin/ViewIntegrationTest.kt

@@ -16,7 +16,6 @@
 
 package com.couchbase.client.kotlin
 
-import com.couchbase.client.kotlin.annotations.VolatileCouchbaseApi
 import com.couchbase.client.kotlin.manager.view.DesignDocument
 import com.couchbase.client.kotlin.manager.view.View
 import com.couchbase.client.kotlin.manager.view.ViewIndexManager
@@ -38,9 +37,7 @@ import org.junit.jupiter.api.Assertions.assertNotNull
 import org.junit.jupiter.api.Assertions.assertNull
 import org.junit.jupiter.api.BeforeAll
 import org.junit.jupiter.api.Test
-import java.util.*
 
-@OptIn(VolatileCouchbaseApi::class)
 @IgnoreWhen(clusterTypes = [MOCKED, CAVES])
 internal class ViewIntegrationTest : KotlinIntegrationTest() {
     private val DDOC_NAME = "everything"

kotlin-client/src/main/kotlin/com/couchbase/client/kotlin/Cluster.kt

@@ -42,7 +42,6 @@ import com.couchbase.client.kotlin.analytics.AnalyticsParameters
 import com.couchbase.client.kotlin.analytics.AnalyticsPriority
 import com.couchbase.client.kotlin.analytics.AnalyticsScanConsistency
 import com.couchbase.client.kotlin.analytics.internal.AnalyticsExecutor
-import com.couchbase.client.kotlin.annotations.VolatileCouchbaseApi
 import com.couchbase.client.kotlin.codec.JsonSerializer
 import com.couchbase.client.kotlin.diagnostics.DiagnosticsResult
 import com.couchbase.client.kotlin.diagnostics.PingResult
@@ -297,7 +296,6 @@ public class Cluster internal constructor(
      * @sample com.couchbase.client.kotlin.samples.checkSearchQueryResultForPartialFailure
      * @sample com.couchbase.client.kotlin.samples.searchQueryWithFacets
      */
-    @Stability.Volatile
     public fun searchQuery(
         indexName: String,
         query: SearchQuery,
@@ -464,7 +462,6 @@ public class Cluster internal constructor(
      * @sample com.couchbase.client.kotlin.samples.singleValueQueryAnonymous
      * @sample com.couchbase.client.kotlin.samples.singleValueQueryNamed
      */
-    @OptIn(VolatileCouchbaseApi::class)
     public fun query(
         statement: String,
         common: CommonOptions = CommonOptions.Default,

kotlin-client/src/main/kotlin/com/couchbase/client/kotlin/Collection.kt

@@ -125,7 +125,7 @@ public class Collection internal constructor(
      * To work around this limitation, consider specifying shallower paths or
      * fetching the whole document.
      *
-     * @throws DocumentNotFoundException if the document id is not found in the collection.
+     * @throws DocumentNotFoundException if a document with ID [id] is not found in the collection.
      */
     public suspend fun get(
         id: String,
@@ -171,7 +171,7 @@ public class Collection internal constructor(
     }
 
     /**
-     * @throws DocumentNotFoundException if the document id is not found in the collection.
+     * @throws DocumentNotFoundException if a document with ID [id] is not found in the collection.
      */
     public suspend fun getAndLock(
         id: String,
@@ -234,7 +234,6 @@ public class Collection internal constructor(
         id: String,
         common: CommonOptions = CommonOptions.Default,
     ): GetReplicaResult {
-        @OptIn(VolatileCouchbaseApi::class)
         return getAnyReplicaOrNull(id, common)
             ?: throw DocumentUnretrievableException(ReducedKeyValueErrorContext.create(id, collectionId))
     }
@@ -288,6 +287,10 @@ public class Collection internal constructor(
         }
     }
 
+    /**
+     * @throws DocumentNotFoundException if a document with ID [id] is not found in the collection.
+     * @throws CasMismatchException if [cas] != 0 and does not match the existing document's CAS value.
+     */
     public suspend fun remove(
         id: String,
         common: CommonOptions = CommonOptions.Default,
@@ -313,6 +316,27 @@ public class Collection internal constructor(
         }
     }
 
+    /**
+     * Like [remove], but returns null instead of throwing
+     * [DocumentNotFoundException] if the document was not found.
+     */
+    @VolatileCouchbaseApi
+    public suspend fun removeOrNull(
+        id: String,
+        common: CommonOptions = CommonOptions.Default,
+        durability: Durability = Durability.none(),
+        cas: Long = 0,
+    ): MutationResult? {
+        return try {
+            remove(id, common, durability, cas)
+        } catch (_: DocumentNotFoundException) {
+            null;
+        }
+    }
+
+    /**
+     * @throws DocumentExistsException if a document with the same ID already exists.
+     */
     public suspend inline fun <reified T> insert(
         id: String,
         content: T,
@@ -418,6 +442,10 @@ public class Collection internal constructor(
         }
     }
 
+    /**
+     * @throws DocumentNotFoundException if a document with ID [id] is not found in the collection.
+     * @throws CasMismatchException if [cas] != 0 and does not match the existing document's CAS value.
+     */
     public suspend inline fun <reified T> replace(
         id: String,
         content: T,
@@ -629,7 +657,6 @@ public class Collection internal constructor(
         val encodedCommands = spec.commands.map { it.encode(defaultCreateParent, serializer ?: defaultJsonSerializer) }
         val timeout = common.actualKvTimeout(durability)
 
-        @OptIn(VolatileCouchbaseApi::class)
         val request = SubdocMutateRequest(
             timeout,
             core.context(),

kotlin-client/src/main/kotlin/com/couchbase/client/kotlin/Scope.kt

@@ -17,6 +17,7 @@
 package com.couchbase.client.kotlin
 
 import com.couchbase.client.core.Core
+import com.couchbase.client.core.annotation.SinceCouchbase
 import com.couchbase.client.core.io.CollectionIdentifier
 import com.couchbase.client.core.io.CollectionIdentifier.DEFAULT_COLLECTION
 import com.couchbase.client.core.io.CollectionIdentifier.DEFAULT_SCOPE
@@ -25,7 +26,6 @@ import com.couchbase.client.kotlin.analytics.AnalyticsParameters
 import com.couchbase.client.kotlin.analytics.AnalyticsPriority
 import com.couchbase.client.kotlin.analytics.AnalyticsScanConsistency
 import com.couchbase.client.kotlin.analytics.internal.AnalyticsExecutor
-import com.couchbase.client.kotlin.annotations.VolatileCouchbaseApi
 import com.couchbase.client.kotlin.codec.JsonSerializer
 import com.couchbase.client.kotlin.internal.toOptional
 import com.couchbase.client.kotlin.query.QueryFlowItem
@@ -36,7 +36,6 @@ import com.couchbase.client.kotlin.query.QueryResult
 import com.couchbase.client.kotlin.query.QueryRow
 import com.couchbase.client.kotlin.query.QueryScanConsistency
 import com.couchbase.client.kotlin.query.internal.QueryExecutor
-import com.couchbase.client.core.annotation.SinceCouchbase
 import kotlinx.coroutines.flow.Flow
 import java.util.*
 import java.util.concurrent.ConcurrentHashMap
@@ -145,7 +144,6 @@ public class Scope(
      * @param raw an "escape hatch" for passing arbitrary query options that
      * aren't otherwise exposed by this method.
      */
-    @OptIn(VolatileCouchbaseApi::class)
     public fun query(
         statement: String,
         common: CommonOptions = CommonOptions.Default,

kotlin-client/src/main/kotlin/com/couchbase/client/kotlin/analytics/AnalyticsResult.kt

@@ -21,7 +21,6 @@ import com.couchbase.client.kotlin.annotations.VolatileCouchbaseApi
 import com.couchbase.client.kotlin.codec.JsonSerializer
 import com.couchbase.client.kotlin.codec.typeRef
 import kotlinx.coroutines.flow.Flow
-import kotlinx.coroutines.flow.collect
 
 public class AnalyticsResult(
     public val rows: List<AnalyticsRow>,

kotlin-client/src/main/kotlin/com/couchbase/client/kotlin/annotations/Api.kt

@@ -35,11 +35,11 @@ import com.couchbase.client.core.annotation.Stability
  * Couchbase Java SDK and core-io library. The Kotlin SDK uses a separate
  * annotation in order to specify opt-in requirements.
  */
-@RequiresOptIn(level = RequiresOptIn.Level.ERROR)
+@MustBeDocumented
 public annotation class VolatileCouchbaseApi
 
 /**
- * No commitment is made about the API.
+ * The API will probably remain stable, but no commitment has been made yet.
  *
  * It may be changed in incompatible ways or dropped from one release
  * to another. The difference between uncommitted and volatile
@@ -52,5 +52,5 @@ public annotation class VolatileCouchbaseApi
  * Couchbase Java SDK and core-io library. The Kotlin SDK uses a separate
  * annotation in order to specify opt-in requirements.
  */
-@RequiresOptIn(level = RequiresOptIn.Level.WARNING)
+@MustBeDocumented
 public annotation class UncommittedCouchbaseApi