Package com.arc_e_tect.gradle.apionly.subscriber

Class ApiOnlySubscriberExtension

java.lang.Object
com.arc_e_tect.gradle.apionly.subscriber.ApiOnlySubscriberExtension
public abstract class ApiOnlySubscriberExtension extends Object
The apiOnlySubscriber block: which contracts this project builds against, and where they come from. 

 apiOnlySubscriber {
     channel {
         type = 'maven'
         groupId = 'com.example.contracts'
     }
     subscribe('user-account') {
         version = '2.1.0'
     }
 }

One channel serves every subscription in a project. Each subscription can carry its own version, because contracts are versioned independently; one that does not takes getVersion().

See Also:

  • Field Details

  • Constructor Details

    • ApiOnlySubscriberExtension

      @Inject public ApiOnlySubscriberExtension(org.gradle.api.model.ObjectFactory objects)
      Creates the extension.

      Gradle instantiates this when the plugin is applied; a build script configures the instance registered as apiOnlySubscriber.

      Parameters:
      objects - Gradle's object factory, supplied by injection

  • Method Details

    • getChannel

      public ChannelSpec getChannel()
      The channel every subscription in this project resolves through.
      Returns:
      the channel specification

    • channel

      public void channel(org.gradle.api.Action<? super ChannelSpec> action)
      Configures the channel. 
      
 channel {
     type = 'file'
     directory = "$rootDir/build/publish"
 }
      Parameters:
      action - configuration applied to the channel specification

    • getSubscriptions

      public org.gradle.api.NamedDomainObjectContainer<Subscription> getSubscriptions()
      Every declared subscription, keyed by target name.
      Returns:
      the container of subscriptions

    • subscribe

      public Subscription subscribe(String target, org.gradle.api.Action<? super Subscription> action)
      Declares a subscription and configures it. 
      
 subscribe('user-account') {
     version = '2.1.0'
 }

      Subscribing to the same target twice configures the existing subscription rather than creating a second one.

      Parameters:
      target - the contract to subscribe to
      action - configuration applied to the subscription
      Returns:
      the subscription, so it can be referenced immediately

    • subscribe

      public Subscription subscribe(String target)
      Declares a subscription without configuring it.

      Only useful when the version is set later, since a subscription with no version fails the build when it is resolved.

      Parameters:
      target - the contract to subscribe to
      Returns:
      the subscription

    • subscription

      public Subscription subscription(String target)
      Looks up a declared subscription, so a build file can wire its documents into whatever consumes them. 
      
 apiOnlySuite {
     rootDocument = apiOnlySubscriber.subscription('user-account').openapi
 }
      Parameters:
      target - the subscribed contract to look up
      Returns:
      the subscription for that target
      Throws:
      IllegalArgumentException - if no such subscription was declared; the message lists the targets that were

    • getLockfile

      public abstract org.gradle.api.file.RegularFileProperty getLockfile()
      Where the resolved versions and file hashes are recorded.

      Defaults to apionly.lock beside the build file. It is shared by every subscription in the project and is meant to be committed: it is what VerifyApiSpecTask checks the fetched documents against, and what makes "which contract is this project actually building against?" a question answerable by reading the repository.

      Returns:
      the lockfile location

    • getVersion

      public abstract org.gradle.api.provider.Property<String> getVersion()
      The contract version every subscription in this project resolves, unless it sets its own.

      Defaults to the apiContractVersion project property, so the version can live in gradle.properties -- in a multi-project build, the subproject's own -- or be given with -PapiContractVersion=... or ORG_GRADLE_PROJECT_apiContractVersion.

      
 apiOnlySubscriber {
     version = '2.1.0'
     subscribe('user-account')
 }
      Returns:
      the default contract version; unset when the property is not defined