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('customer-orders') {
         version = '2.1.0'
     }
 }

A project implements at most one contract, and may call any number of APIs. subscribe(String, Action) declares the contract it implements; a second one is refused, because each contract belongs in a project of its own. subscribeAsClient(String, Action) declares an API it calls, which gets every check the implemented contract gets.

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 the contract this project implements, and configures it. 
      
 subscribe('customer-orders') {
     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
      Throws:
      org.gradle.api.InvalidUserDataException - if this project already implements another contract, or calls this one; the message says why, and what to do

    • subscribe

      public Subscription subscribe(String target)
      Declares the contract this project implements, 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
      Throws:
      org.gradle.api.InvalidUserDataException - if this project already implements another contract, or calls this one; the message says why, and what to do

    • subscribeAsClient

      public Subscription subscribeAsClient(String target, org.gradle.api.Action<? super Subscription> action)
      Declares an API this project calls, and configures it. 
      
 subscribeAsClient('order-payments') {
     apiContractVersion = '1.4.0'
 }

      A project may call any number of APIs, next to the one contract it implements. A client subscription is fetched, checked against its archive's manifest, locked and verified exactly like the implemented contract. It differs in two ways. It sets its own version, because getApiContractVersion() and apiContractVersion are the version of the contract this project implements. And with the java plugin, its documents reach the classpath under contracts/<target>/, leaving the root to that contract.

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

      Parameters:
      target - the API to subscribe to
      action - configuration applied to the subscription
      Returns:
      the subscription, so it can be referenced immediately
      Throws:
      org.gradle.api.InvalidUserDataException - if this project implements that contract; a project either implements a contract or calls it

    • subscribeAsClient

      public Subscription subscribeAsClient(String target)
      Declares an API this project calls, without configuring it.
      Parameters:
      target - the API to subscribe to
      Returns:
      the subscription
      Throws:
      org.gradle.api.InvalidUserDataException - if this project implements that contract
      See Also:

    • subscription

      public Subscription subscription(String target)
      Looks up a declared subscription, so a build file can wire its documents into whatever consumes them. 
      
 openApiGenerate {
     inputSpec = apiOnlySubscriber.subscription('customer-orders').openapi.map { it.asFile.path }
 }
      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

    • getApiContractVersion

      public abstract org.gradle.api.provider.Property<String> getApiContractVersion()
      The version of the contract this project implements, unless its subscription sets its own. An API the project calls is not affected.

      Defaults to the apiContractVersion project property, so the version can live in gradle.properties -- in a multi-project build, the subproject's own -- in the build script's ext, or in ORG_GRADLE_PROJECT_apiContractVersion. Given on the command line, with -PapiContractVersion=..., the property overrides every version the build sets for the implemented contract.

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

    • setVersion

      public void setVersion(Object version)
      Refuses the property's old name. Without it, a build script that still sets version here would set the project's own version instead, silently.
      Parameters:
      version - ignored
      Throws:
      org.gradle.api.GradleException - always, naming the new property