CORDA-704: Implement @DoNotImplement annotation (corda#1903)

chrisr3 · web-flow · commit 2c84d07e8ed7 · 2017-10-19T17:18:35.000+01:00
* Enhance the API Scanner plugin to monitor class annotations.
* Implement @DoNotImplement annotation, and apply it.
* Update API definition.
* Update API change detection to handle @DoNotImplement.
* Document the `@DoNotImplement` annotation.
diff --git a/.ci/api-current.txt b/.ci/api-current.txt
diff --git a/.ci/check-api-changes.sh b/.ci/check-api-changes.sh
@@ -30,7 +30,15 @@ if [ $removalCount -gt 0 ]; then
 fi
 
 # Adding new abstract methods could also break the API.
-newAbstracts=$(echo "$diffContents" | grep "^+" | grep "\(public\|protected\) abstract")
+# However, first exclude anything with the @DoNotImplement annotation.
+
+function forUserImpl() {
+    awk '/DoNotImplement/,/^##/{ next }{ print }' $1
+}
+
+userDiffContents=`diff -u <(forUserImpl $apiCurrent) <(forUserImpl $APIHOME/../build/api/api-corda-*.txt) | tail --lines=+3`
+
+newAbstracts=$(echo "$userDiffContents" | grep "^+" | grep "\(public\|protected\) abstract")
 abstractCount=`grep -v "^$" <<EOF | wc -l
 $newAbstracts
 EOF
diff --git a/client/rpc/src/main/kotlin/net/corda/client/rpc/RPCConnection.kt b/client/rpc/src/main/kotlin/net/corda/client/rpc/RPCConnection.kt
@@ -1,5 +1,6 @@
 package net.corda.client.rpc
 
+import net.corda.core.DoNotImplement
 import net.corda.core.messaging.RPCOps
 import java.io.Closeable
 
@@ -10,6 +11,7 @@ import java.io.Closeable
  * [Closeable.close] may be used to shut down the connection and release associated resources. It is an
  * alias for [notifyServerAndClose].
  */
+@DoNotImplement
 interface RPCConnection<out I : RPCOps> : Closeable {
     /**
      * Holds a synthetic class that automatically forwards method calls to the server, and returns the response.
diff --git a/constants.properties b/constants.properties
@@ -1,4 +1,4 @@
-gradlePluginsVersion=2.0.5
+gradlePluginsVersion=2.0.6
 kotlinVersion=1.1.50
 guavaVersion=21.0
 bouncycastleVersion=1.57
diff --git a/core/src/main/kotlin/net/corda/core/DoNotImplement.kt b/core/src/main/kotlin/net/corda/core/DoNotImplement.kt
@@ -0,0 +1,18 @@
+package net.corda.core
+
+import java.lang.annotation.Inherited
+
+/**
+ * This annotation is for interfaces and abstract classes that provide Corda functionality
+ * to user applications. Future versions of Corda may add new methods to such interfaces and
+ * classes, but will not remove or modify existing methods.
+ *
+ * Adding new methods does not break Corda's API compatibility guarantee because applications
+ * should not implement or extend anything annotated with [DoNotImplement]. These classes are
+ * only meant to be implemented by Corda itself.
+ */
+@Retention(AnnotationRetention.BINARY)
+@Target(AnnotationTarget.CLASS)
+@MustBeDocumented
+@Inherited
+annotation class DoNotImplement
diff --git a/core/src/main/kotlin/net/corda/core/cordapp/Cordapp.kt b/core/src/main/kotlin/net/corda/core/cordapp/Cordapp.kt
@@ -1,5 +1,6 @@
 package net.corda.core.cordapp
 
+import net.corda.core.DoNotImplement
 import net.corda.core.flows.FlowLogic
 import net.corda.core.schemas.MappedSchema
 import net.corda.core.serialization.SerializationWhitelist
@@ -17,13 +18,14 @@ import java.net.URL
  * @property contractClassNames List of contracts
  * @property initiatedFlows List of initiatable flow classes
  * @property rpcFlows List of RPC initiable flows classes
- * @property serviceFlows List of [CordaService] initiable flows classes
+ * @property serviceFlows List of [net.corda.core.node.services.CordaService] initiable flows classes
  * @property schedulableFlows List of flows startable by the scheduler
- * @property servies List of RPC services
+ * @property services List of RPC services
  * @property serializationWhitelists List of Corda plugin registries
  * @property customSchemas List of custom schemas
  * @property jarPath The path to the JAR for this CorDapp
  */
+@DoNotImplement
 interface Cordapp {
     val name: String
     val contractClassNames: List<String>
diff --git a/core/src/main/kotlin/net/corda/core/cordapp/CordappProvider.kt b/core/src/main/kotlin/net/corda/core/cordapp/CordappProvider.kt
@@ -1,11 +1,13 @@
 package net.corda.core.cordapp
 
+import net.corda.core.DoNotImplement
 import net.corda.core.contracts.ContractClassName
 import net.corda.core.node.services.AttachmentId
 
 /**
  * Provides access to what the node knows about loaded applications.
  */
+@DoNotImplement
 interface CordappProvider {
     /**
      * Exposes the current CorDapp context which will contain information and configuration of the CorDapp that
diff --git a/core/src/main/kotlin/net/corda/core/flows/FlowLogicRef.kt b/core/src/main/kotlin/net/corda/core/flows/FlowLogicRef.kt
@@ -1,13 +1,14 @@
 package net.corda.core.flows
 
-import net.corda.core.crypto.SecureHash
+import net.corda.core.DoNotImplement
 import net.corda.core.serialization.CordaSerializable
 
 /**
  * The public factory interface for creating validated FlowLogicRef instances as part of the scheduling framework.
  * Typically this would be used from within the nextScheduledActivity method of a QueryableState to specify
  * the flow to run at the scheduled time.
  */
+@DoNotImplement
 interface FlowLogicRefFactory {
     fun create(flowClass: Class<out FlowLogic<*>>, vararg args: Any?): FlowLogicRef
 }
@@ -24,4 +25,5 @@ class IllegalFlowLogicException(type: Class<*>, msg: String) : IllegalArgumentEx
  */
 // TODO: align this with the existing [FlowRef] in the bank-side API (probably replace some of the API classes)
 @CordaSerializable
+@DoNotImplement
 interface FlowLogicRef
diff --git a/core/src/main/kotlin/net/corda/core/flows/FlowSession.kt b/core/src/main/kotlin/net/corda/core/flows/FlowSession.kt
@@ -1,6 +1,7 @@
 package net.corda.core.flows
 
 import co.paralleluniverse.fibers.Suspendable
+import net.corda.core.DoNotImplement
 import net.corda.core.identity.Party
 import net.corda.core.utilities.UntrustworthyData
 
@@ -41,6 +42,7 @@ import net.corda.core.utilities.UntrustworthyData
  *   will become
  *     otherSideSession.send(something)
  */
+@DoNotImplement
 abstract class FlowSession {
     /**
      * The [Party] on the other side of this session. In the case of a session created by [FlowLogic.initiateFlow]
diff --git a/core/src/main/kotlin/net/corda/core/identity/AbstractParty.kt b/core/src/main/kotlin/net/corda/core/identity/AbstractParty.kt
@@ -1,5 +1,6 @@
 package net.corda.core.identity
 
+import net.corda.core.DoNotImplement
 import net.corda.core.contracts.PartyAndReference
 import net.corda.core.serialization.CordaSerializable
 import net.corda.core.utilities.OpaqueBytes
@@ -10,6 +11,7 @@ import java.security.PublicKey
  * the party. In most cases [Party] or [AnonymousParty] should be used, depending on use-case.
  */
 @CordaSerializable
+@DoNotImplement
 abstract class AbstractParty(val owningKey: PublicKey) {
     /** Anonymised parties do not include any detail apart from owning key, so equality is dependent solely on the key */
     override fun equals(other: Any?): Boolean = other === this || other is AbstractParty && other.owningKey == owningKey
diff --git a/core/src/main/kotlin/net/corda/core/messaging/CordaRPCOps.kt b/core/src/main/kotlin/net/corda/core/messaging/CordaRPCOps.kt
@@ -24,7 +24,6 @@ import rx.Observable
 import java.io.InputStream
 import java.security.PublicKey
 import java.time.Instant
-import java.util.*
 
 @CordaSerializable
 data class StateMachineInfo(
diff --git a/core/src/main/kotlin/net/corda/core/messaging/FlowHandle.kt b/core/src/main/kotlin/net/corda/core/messaging/FlowHandle.kt
@@ -1,5 +1,6 @@
 package net.corda.core.messaging
 
+import net.corda.core.DoNotImplement
 import net.corda.core.concurrent.CordaFuture
 import net.corda.core.flows.StateMachineRunId
 import net.corda.core.serialization.CordaSerializable
@@ -11,6 +12,7 @@ import rx.Observable
  * @property id The started state machine's ID.
  * @property returnValue A [CordaFuture] of the flow's return value.
  */
+@DoNotImplement
 interface FlowHandle<A> : AutoCloseable {
     val id: StateMachineRunId
     val returnValue: CordaFuture<A>
diff --git a/core/src/main/kotlin/net/corda/core/messaging/RPCOps.kt b/core/src/main/kotlin/net/corda/core/messaging/RPCOps.kt
@@ -1,9 +1,12 @@
 package net.corda.core.messaging
 
+import net.corda.core.DoNotImplement
+
 /**
  * Base interface that all RPC servers must implement. Note: in Corda there's only one RPC interface. This base
  * interface is here in case we split the RPC system out into a separate library one day.
  */
+@DoNotImplement
 interface RPCOps {
     /** Returns the RPC protocol version. Exists since version 0 so guaranteed to be present. */
     val protocolVersion: Int
diff --git a/core/src/main/kotlin/net/corda/core/node/ServiceHub.kt b/core/src/main/kotlin/net/corda/core/node/ServiceHub.kt
@@ -1,5 +1,6 @@
 package net.corda.core.node
 
+import net.corda.core.DoNotImplement
 import net.corda.core.contracts.*
 import net.corda.core.cordapp.CordappProvider
 import net.corda.core.crypto.Crypto
@@ -19,6 +20,7 @@ import java.time.Clock
 /**
  * Part of [ServiceHub].
  */
+@DoNotImplement
 interface StateLoader {
     /**
      * Given a [StateRef] loads the referenced transaction and looks up the specified output [ContractState].
@@ -164,7 +166,7 @@ interface ServiceHub : ServicesForResolution {
     @Throws(TransactionResolutionException::class)
     fun <T : ContractState> toStateAndRef(stateRef: StateRef): StateAndRef<T> {
         val stx = validatedTransactions.getTransaction(stateRef.txhash) ?: throw TransactionResolutionException(stateRef.txhash)
-        return stx.resolveBaseTransaction(this).outRef<T>(stateRef.index)
+        return stx.resolveBaseTransaction(this).outRef(stateRef.index)
     }
 
     private val legalIdentityKey: PublicKey get() = this.myInfo.legalIdentitiesAndCerts.first().owningKey
diff --git a/core/src/main/kotlin/net/corda/core/node/services/AttachmentStorage.kt b/core/src/main/kotlin/net/corda/core/node/services/AttachmentStorage.kt
@@ -1,5 +1,6 @@
 package net.corda.core.node.services
 
+import net.corda.core.DoNotImplement
 import net.corda.core.contracts.Attachment
 import net.corda.core.crypto.SecureHash
 import java.io.IOException
@@ -11,6 +12,7 @@ typealias AttachmentId = SecureHash
 /**
  * An attachment store records potentially large binary objects, identified by their hash.
  */
+@DoNotImplement
 interface AttachmentStorage {
     /**
      * Returns a handle to a locally stored attachment, or null if it's not known. The handle can be used to open
diff --git a/core/src/main/kotlin/net/corda/core/node/services/ContractUpgradeService.kt b/core/src/main/kotlin/net/corda/core/node/services/ContractUpgradeService.kt
@@ -1,5 +1,6 @@
 package net.corda.core.node.services
 
+import net.corda.core.DoNotImplement
 import net.corda.core.contracts.StateRef
 import net.corda.core.contracts.UpgradedContract
 import net.corda.core.flows.ContractUpgradeFlow
@@ -9,6 +10,7 @@ import net.corda.core.flows.ContractUpgradeFlow
  * a specified and mutually agreed (amongst participants) contract version.
  * See also [ContractUpgradeFlow] to understand the workflow associated with contract upgrades.
  */
+@DoNotImplement
 interface ContractUpgradeService {
 
     /** Get contracts we would be willing to upgrade the suggested contract to. */
diff --git a/core/src/main/kotlin/net/corda/core/node/services/IdentityService.kt b/core/src/main/kotlin/net/corda/core/node/services/IdentityService.kt
@@ -1,6 +1,7 @@
 package net.corda.core.node.services
 
 import net.corda.core.CordaException
+import net.corda.core.DoNotImplement
 import net.corda.core.contracts.PartyAndReference
 import net.corda.core.identity.*
 import java.security.InvalidAlgorithmParameterException
@@ -16,6 +17,7 @@ import java.security.cert.*
  * whereas confidential identities are distributed only on a need to know basis (typically between parties in
  * a transaction being built). See [NetworkMapCache] for retrieving well known identities from the network map.
  */
+@DoNotImplement
 interface IdentityService {
     val trustRoot: X509Certificate
     val trustAnchor: TrustAnchor
diff --git a/core/src/main/kotlin/net/corda/core/node/services/KeyManagementService.kt b/core/src/main/kotlin/net/corda/core/node/services/KeyManagementService.kt
@@ -1,6 +1,7 @@
 package net.corda.core.node.services
 
 import co.paralleluniverse.fibers.Suspendable
+import net.corda.core.DoNotImplement
 import net.corda.core.crypto.DigitalSignature
 import net.corda.core.crypto.SignableData
 import net.corda.core.crypto.TransactionSignature
@@ -11,6 +12,7 @@ import java.security.PublicKey
  * The KMS is responsible for storing and using private keys to sign things. An implementation of this may, for example,
  * call out to a hardware security module that enforces various auditing and frequency-of-use requirements.
  */
+@DoNotImplement
 interface KeyManagementService {
     /**
      * Returns a snapshot of the current signing [PublicKey]s.
diff --git a/core/src/main/kotlin/net/corda/core/node/services/NetworkMapCache.kt b/core/src/main/kotlin/net/corda/core/node/services/NetworkMapCache.kt
@@ -1,5 +1,6 @@
 package net.corda.core.node.services
 
+import net.corda.core.DoNotImplement
 import net.corda.core.concurrent.CordaFuture
 import net.corda.core.identity.AbstractParty
 import net.corda.core.identity.CordaX500Name
@@ -43,6 +44,7 @@ interface NetworkMapCache : NetworkMapCacheBase {
 }
 
 /** Subset of [NetworkMapCache] that doesn't depend on an [IdentityService]. */
+@DoNotImplement
 interface NetworkMapCacheBase {
     // DOCSTART 1
     /**
diff --git a/core/src/main/kotlin/net/corda/core/node/services/TransactionStorage.kt b/core/src/main/kotlin/net/corda/core/node/services/TransactionStorage.kt
@@ -1,5 +1,6 @@
 package net.corda.core.node.services
 
+import net.corda.core.DoNotImplement
 import net.corda.core.crypto.SecureHash
 import net.corda.core.messaging.DataFeed
 import net.corda.core.transactions.SignedTransaction
@@ -8,6 +9,7 @@ import rx.Observable
 /**
  * Thread-safe storage of transactions.
  */
+@DoNotImplement
 interface TransactionStorage {
     /**
      * Return the transaction with the given [id], or null if no such transaction exists.
diff --git a/core/src/main/kotlin/net/corda/core/node/services/TransactionVerifierService.kt b/core/src/main/kotlin/net/corda/core/node/services/TransactionVerifierService.kt
@@ -1,12 +1,14 @@
 package net.corda.core.node.services
 
+import net.corda.core.DoNotImplement
 import net.corda.core.concurrent.CordaFuture
 import net.corda.core.transactions.LedgerTransaction
 
 /**
  * Provides verification service. The implementation may be a simple in-memory verify() call or perhaps an IPC/RPC.
  * @suppress
  */
+@DoNotImplement
 interface TransactionVerifierService {
     /**
      * @param transaction The transaction to be verified.
diff --git a/core/src/main/kotlin/net/corda/core/node/services/VaultService.kt b/core/src/main/kotlin/net/corda/core/node/services/VaultService.kt
@@ -1,6 +1,7 @@
 package net.corda.core.node.services
 
 import co.paralleluniverse.fibers.Suspendable
+import net.corda.core.DoNotImplement
 import net.corda.core.concurrent.CordaFuture
 import net.corda.core.contracts.*
 import net.corda.core.crypto.SecureHash
@@ -14,7 +15,6 @@ import net.corda.core.serialization.CordaSerializable
 import net.corda.core.toFuture
 import net.corda.core.utilities.NonEmptySet
 import rx.Observable
-import rx.subjects.PublishSubject
 import java.time.Instant
 import java.util.*
 
@@ -151,6 +151,7 @@ class Vault<out T : ContractState>(val states: Iterable<StateAndRef<T>>) {
  *
  * Note that transactions we've seen are held by the storage service, not the vault.
  */
+@DoNotImplement
 interface VaultService {
     /**
      * Prefer the use of [updates] unless you know why you want to use this instead.
diff --git a/core/src/main/kotlin/net/corda/core/node/services/vault/QueryCriteria.kt b/core/src/main/kotlin/net/corda/core/node/services/vault/QueryCriteria.kt
@@ -2,6 +2,7 @@
 
 package net.corda.core.node.services.vault
 
+import net.corda.core.DoNotImplement
 import net.corda.core.contracts.ContractState
 import net.corda.core.contracts.StateRef
 import net.corda.core.contracts.UniqueIdentifier
@@ -144,6 +145,7 @@ sealed class QueryCriteria {
     infix fun or(criteria: QueryCriteria): QueryCriteria = OrComposition(this, criteria)
 }
 
+@DoNotImplement
 interface IQueryCriteriaParser {
     fun parseCriteria(criteria: QueryCriteria.CommonQueryCriteria): Collection<Predicate>
     fun parseCriteria(criteria: QueryCriteria.FungibleAssetQueryCriteria): Collection<Predicate>
diff --git a/core/src/main/kotlin/net/corda/core/node/services/vault/QueryCriteriaUtils.kt b/core/src/main/kotlin/net/corda/core/node/services/vault/QueryCriteriaUtils.kt
@@ -2,6 +2,7 @@
 
 package net.corda.core.node.services.vault
 
+import net.corda.core.DoNotImplement
 import net.corda.core.internal.uncheckedCast
 import net.corda.core.schemas.PersistentState
 import net.corda.core.serialization.CordaSerializable
@@ -10,6 +11,7 @@ import kotlin.reflect.KProperty1
 import kotlin.reflect.jvm.javaGetter
 
 @CordaSerializable
+@DoNotImplement
 interface Operator
 
 enum class BinaryLogicalOperator : Operator {
@@ -138,6 +140,7 @@ data class Sort(val columns: Collection<SortColumn>) {
     }
 
     @CordaSerializable
+    @DoNotImplement
     interface Attribute
 
     enum class CommonStateAttribute(val attributeParent: String, val attributeChild: String?) : Attribute {
diff --git a/core/src/main/kotlin/net/corda/core/transactions/BaseTransaction.kt b/core/src/main/kotlin/net/corda/core/transactions/BaseTransaction.kt
@@ -1,5 +1,6 @@
 package net.corda.core.transactions
 
+import net.corda.core.DoNotImplement
 import net.corda.core.contracts.*
 import net.corda.core.identity.Party
 import net.corda.core.internal.castIfPossible
@@ -10,6 +11,7 @@ import java.util.function.Predicate
 /**
  * An abstract class defining fields shared by all transaction types in the system.
  */
+@DoNotImplement
 abstract class BaseTransaction : NamedByHash {
     /** The inputs of this transaction. Note that in BaseTransaction subclasses the type of this list may change! */
     abstract val inputs: List<*>
diff --git a/core/src/main/kotlin/net/corda/core/transactions/TransactionWithSignatures.kt b/core/src/main/kotlin/net/corda/core/transactions/TransactionWithSignatures.kt
diff --git a/docs/source/corda-api.rst b/docs/source/corda-api.rst
diff --git a/gradle-plugins/api-scanner/src/main/java/net/corda/plugins/ScanApi.java b/gradle-plugins/api-scanner/src/main/java/net/corda/plugins/ScanApi.java
diff --git a/node/src/main/kotlin/net/corda/node/services/statemachine/FlowLogicRefFactoryImpl.kt b/node/src/main/kotlin/net/corda/node/services/statemachine/FlowLogicRefFactoryImpl.kt

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-gradlePluginsVersion=2.0.5`
	`1`	`+gradlePluginsVersion=2.0.6`
`2`	`2`	`kotlinVersion=1.1.50`
`3`	`3`	`guavaVersion=21.0`
`4`	`4`	`bouncycastleVersion=1.57`