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

* 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.

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

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>

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

core/src/main/kotlin/net/corda/core/flows/FlowLogicRef.kt

@@ -1,6 +1,6 @@
 package net.corda.core.flows
 
-import net.corda.core.crypto.SecureHash
+import net.corda.core.DoNotImplement
 import net.corda.core.serialization.CordaSerializable
 
 /**
@@ -8,6 +8,7 @@ import net.corda.core.serialization.CordaSerializable
  * 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

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]

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

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(

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>

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

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

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

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. */

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

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.

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
     /**

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.

core/src/main/kotlin/net/corda/core/node/services/TransactionVerifierService.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.transactions.LedgerTransaction
 
@@ -7,6 +8,7 @@ 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.

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.

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>

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 {

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<*>

core/src/main/kotlin/net/corda/core/transactions/TransactionWithSignatures.kt

@@ -1,5 +1,6 @@
 package net.corda.core.transactions
 
+import net.corda.core.DoNotImplement
 import net.corda.core.contracts.NamedByHash
 import net.corda.core.crypto.TransactionSignature
 import net.corda.core.crypto.isFulfilledBy
@@ -10,6 +11,7 @@ import java.security.PublicKey
 import java.security.SignatureException
 
 /** An interface for transactions containing signatures, with logic for signature verification */
+@DoNotImplement
 interface TransactionWithSignatures : NamedByHash {
     val sigs: List<TransactionSignature>