Package com.arc_e_tect.gradle.apionly.subscriber

Class Subscription

java.lang.Object
com.arc_e_tect.gradle.apionly.subscriber.Subscription
public abstract class Subscription extends Object
One subscribed contract: which target, at which version, landing where.

Created through ApiOnlySubscriberExtension.subscribe(String, org.gradle.api.Action):


 apiOnlySubscriber {
     subscribe('user-account') {
         version = '2.1.0'
     }
 }

The version is declared per target rather than per channel, because each target is versioned independently. A change confined to one service's fragments must not oblige every other service to take a new version.

Each subscription registers a fetchApiSpec<Target> and a verifyApiSpec<Target> task, and contributes to the aggregate fetchApiSpec and verifyApiSpec tasks.

See Also:

  • Constructor Summary

    Constructors
    Constructor
    Description
    Subscription(String target, org.gradle.api.model.ObjectFactory objects)
    Creates a subscription for one target.

  • Method Summary

    Modifier and Type
    Method
    Description
    abstract org.gradle.api.provider.Property<Boolean>
    getAllowPrerelease()
    Whether this subscription may resolve a pre-release contract.
    abstract org.gradle.api.provider.Property<String>
    getArtifactId()
    Overrides the artifact name this target is published under.
    org.gradle.api.provider.Provider<org.gradle.api.file.RegularFile>
    getAsyncapi()
    The fetched AsyncAPI document.
    abstract org.gradle.api.provider.Property<String>
    getGroupId()
    Overrides ChannelSpec.getGroupId() for this one target.
    abstract org.gradle.api.file.DirectoryProperty
    getInto()
    Where the fetched documents land.
    String
    getName()
    The name this subscription is keyed by in its container.
    org.gradle.api.provider.Provider<org.gradle.api.file.RegularFile>
    getOpenapi()
    The fetched OpenAPI document.
    String
    getTarget()
    The contract this subscription is for.
    abstract org.gradle.api.provider.Property<String>
    getVersion()
    The version of this target's contract to build against.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • Subscription

      @Inject public Subscription(String target, org.gradle.api.model.ObjectFactory objects)
      Creates a subscription for one target.

      Gradle instantiates this through its object factory; build scripts call ApiOnlySubscriberExtension.subscribe(String, org.gradle.api.Action) rather than constructing one directly.

      Parameters:
      target - the contract this subscription is for, which is also the element's name within the container
      objects - Gradle's object factory, supplied by injection

  • Method Details

    • getName

      public String getName()
      The name this subscription is keyed by in its container.

      Gradle's NamedDomainObjectContainer requires it; here it is always the target name, so this and getTarget() agree.

      Returns:
      the target name

    • getTarget

      public String getTarget()
      The contract this subscription is for.
      Returns:
      the target name, the same value as getName()

    • getVersion

      public abstract org.gradle.api.provider.Property<String> getVersion()
      The version of this target's contract to build against.

      Defaults to ApiOnlySubscriberExtension.getVersion(), which in turn defaults to the apiContractVersion project property; one of the three must be set. A pre-release version is refused unless getAllowPrerelease() is set.

      Returns:
      the version to resolve

    • getGroupId

      public abstract org.gradle.api.provider.Property<String> getGroupId()
      Overrides ChannelSpec.getGroupId() for this one target.

      Useful when most contracts come from one group but a particular target is published elsewhere.

      Returns:
      the group id for this target; unset, meaning the channel's applies

    • getArtifactId

      public abstract org.gradle.api.provider.Property<String> getArtifactId()
      Overrides the artifact name this target is published under.
      Returns:
      the artifact id; defaults to the target name

    • getAllowPrerelease

      public abstract org.gradle.api.provider.Property<Boolean> getAllowPrerelease()
      Whether this subscription may resolve a pre-release contract.

      False by default, and deliberately. API-Only design means implementation begins against a contract that is not finished, so pre-releases must exist — but a pre-release must never quietly satisfy a build that did not ask for one. Opting in is a visible, reviewable line in a build file:

      
 subscribe('user-account') {
     version = '2.1.0-rc.1'
     allowPrerelease = true
 }

      Both the SemVer spelling (-rc.1, -alpha.3) and Maven's -SNAPSHOT count as pre-releases.

      Returns:
      whether a pre-release may be resolved; defaults to false

    • getInto

      public abstract org.gradle.api.file.DirectoryProperty getInto()
      Where the fetched documents land.

      Defaults to build/api-spec/<target>/ rather than src/main/resources. Generated files inside a source tree show up in IDE search, tempt hand-editing, and survive a clean. From build/ they reach the classpath identically, because the plugin registers this directory as an additional resources source directory.

      Writing into src/ remains possible for teams whose tooling insists on it; it is simply not the default.

      Returns:
      the directory fetched documents are unpacked into

    • getOpenapi

      public org.gradle.api.provider.Provider<org.gradle.api.file.RegularFile> getOpenapi()
      The fetched OpenAPI document.

      Wire this into whatever validates against the contract, and the dependency on the fetch travels with it:

      
 apiOnlySuite {
     rootDocument = apiOnlySubscriber.subscription('user-account').openapi
 }
      Returns:
      a provider for openapi.yaml inside getInto(), carrying a dependency on the fetch task
      Throws:
      IllegalStateException - if read before the plugin has registered the fetch task, which cannot happen from a build script

    • getAsyncapi

      public org.gradle.api.provider.Provider<org.gradle.api.file.RegularFile> getAsyncapi()
      The fetched AsyncAPI document.
      Returns:
      a provider for asyncapi.yaml inside getInto(), carrying a dependency on the fetch task
      Throws:
      IllegalStateException - if read before the plugin has registered the fetch task, which cannot happen from a build script
      See Also: