Package com.arc_e_tect.gradle.apionly.transcriberj

Class TranscriberJSubscription

java.lang.Object
com.arc_e_tect.gradle.apionly.transcriberj.TranscriberJSubscription
All Implemented Interfaces:
org.gradle.api.Named
public abstract class TranscriberJSubscription extends Object implements org.gradle.api.Named
How the classes for one subscribed contract are generated.

Its name is the contract's name, exactly as the apiOnlySubscriber block subscribes to it.

  • Nested Class Summary

    Nested classes/interfaces inherited from interface org.gradle.api.Named

    org.gradle.api.Named.Namer

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    DEFAULT_DESCRIPTION_PLACEHOLDER
    The description of a class or field the contract does not describe, when descriptions are generated.

  • Constructor Summary

    Constructors
    Constructor
    Description
    TranscriberJSubscription(String name)
    Creates the settings for one contract.

  • Method Summary

    Modifier and Type
    Method
    Description
    EmitterSpec
    emitter(String id, org.gradle.api.Action<? super EmitterSpec> action)
    Configures one emitter for this subscription: its source sets, its options and where its output goes.
    abstract org.gradle.api.provider.Property<String>
    getBasePackage()
    The package the core classes are generated into.
    abstract org.gradle.api.provider.ListProperty<String>
    getDerive()
    The kinds of contract case derived: success, notFound, notAcceptable, unsupportedMediaType and invalidRequest.
    abstract org.gradle.api.provider.Property<String>
    getDescriptionBundle()
    The base name of a ResourceBundle the generated classes resolve their descriptions through, such as docs.Descriptions.
    abstract org.gradle.api.provider.Property<String>
    getDescriptionPlaceholder()
    The description of a class or field the contract does not describe, when getGenerateDocs() is on: it says the description is still to come.
    abstract org.gradle.api.provider.MapProperty<String,Map<String,String>>
    getEmitterOptions()
    Deprecated.
    Configure each emitter in its own block, emitter('<id>') { options = [...] }.
    org.gradle.api.NamedDomainObjectContainer<EmitterSpec>
    getEmitters()
    Every emitter this subscription configures with emitter(...), by id.
    abstract org.gradle.api.file.RegularFileProperty
    getEndpointIndex()
    The endpoint index the generation writes: the path of every generated operation and inline schema class, keyed ClassName.PATH.
    abstract org.gradle.api.file.RegularFileProperty
    getEndpointIndexFile()
    Where the generation writes the endpoint index.
    abstract org.gradle.api.provider.Property<Boolean>
    getGenerateDocs()
    Whether the generated descriptions come from the contract.
    abstract org.gradle.api.file.DirectoryProperty
    getInto()
    Where the core's sources -- the schema classes, operations and cases -- are generated.
    abstract org.gradle.api.file.DirectoryProperty
    getIntoResources()
    Where the core's resources are generated.
    abstract org.gradle.api.provider.Property<String>
    getInvalidRequestStatus()
    The response status that means "the request is invalid".
    String
    getName()
    The contract's name.
    protected abstract org.gradle.api.model.ObjectFactory
    getObjects()
    Gradle's object factory, which creates each emitter(...) block.
    abstract org.gradle.api.provider.Property<Integer>
    getRecursionDepth()
    How many times a recursive reference is followed before the rest of a body is documented as a subsection.
    abstract org.gradle.api.file.RegularFileProperty
    getReportFile()
    Where the generation writes its report: every degraded method, recommendation and undecided construct.
    abstract org.gradle.api.provider.Property<String>
    getSchemaClasses()
    How the schema classes reach the subscription's source sets: perSourceSet, where each source set compiles them, or shared, where one source set, transcriberj<Contract>, compiles them once and every listed source set depends on it.
    abstract org.gradle.api.provider.ListProperty<String>
    getSourceSets()
    The source sets the generated classes are compiled with.
    abstract org.gradle.api.provider.Property<Boolean>
    getStrictRequests()
    Whether a request object that does not declare additionalProperties forbids members it does not declare, so that an unknown-member case is derived for it.
    abstract org.gradle.api.provider.ListProperty<String>
    getValidateFormats()
    The formats, such as email, an invalid-request case is derived for.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • DEFAULT_DESCRIPTION_PLACEHOLDER

      public static final String DEFAULT_DESCRIPTION_PLACEHOLDER
      The description of a class or field the contract does not describe, when descriptions are generated.
      See Also:

  • Constructor Details

    • TranscriberJSubscription

      @Inject public TranscriberJSubscription(String name)
      Creates the settings for one contract.
      Parameters:
      name - the contract's name

  • Method Details

    • getObjects

      @Inject protected abstract org.gradle.api.model.ObjectFactory getObjects()
      Gradle's object factory, which creates each emitter(...) block.
      Returns:
      the factory

    • getEmitters

      public org.gradle.api.NamedDomainObjectContainer<EmitterSpec> getEmitters()
      Every emitter this subscription configures with emitter(...), by id.
      Returns:
      the emitters

    • emitter

      public EmitterSpec emitter(String id, org.gradle.api.Action<? super EmitterSpec> action)
      Configures one emitter for this subscription: its source sets, its options and where its output goes.
      Parameters:
      id - the emitter's id, as it names itself, such as restdocs
      action - its configuration
      Returns:
      the emitter's block

    • getSchemaClasses

      public abstract org.gradle.api.provider.Property<String> getSchemaClasses()
      How the schema classes reach the subscription's source sets: perSourceSet, where each source set compiles them, or shared, where one source set, transcriberj<Contract>, compiles them once and every listed source set depends on it.

      Default: perSourceSet.

      Returns:
      the mode

    • getDerive

      public abstract org.gradle.api.provider.ListProperty<String> getDerive()
      The kinds of contract case derived: success, notFound, notAcceptable, unsupportedMediaType and invalidRequest. A kind left out derives no case, and the response coverage says why for every response it would have covered.

      Default: every kind.

      Returns:
      the kinds

    • getName

      public String getName()
      The contract's name.
      Specified by:
      getName in interface org.gradle.api.Named
      Returns:
      the name

    • getBasePackage

      public abstract org.gradle.api.provider.Property<String> getBasePackage()
      The package the core classes are generated into. Required: there is no default.
      Returns:
      the base package

    • getSourceSets

      public abstract org.gradle.api.provider.ListProperty<String> getSourceSets()
      The source sets the generated classes are compiled with.

      Default: test.

      Returns:
      the source set names

    • getRecursionDepth

      public abstract org.gradle.api.provider.Property<Integer> getRecursionDepth()
      How many times a recursive reference is followed before the rest of a body is documented as a subsection.

      Default: 3.

      Returns:
      the depth

    • getGenerateDocs

      public abstract org.gradle.api.provider.Property<Boolean> getGenerateDocs()
      Whether the generated descriptions come from the contract. When they do, a class or field the contract does not describe is reported, and documented with the placeholder.

      Default: false. The class tree is for contract testing; documentation is usually generated elsewhere, from text a technical writer owns.

      Returns:
      the setting

    • getDescriptionPlaceholder

      public abstract org.gradle.api.provider.Property<String> getDescriptionPlaceholder()
      The description of a class or field the contract does not describe, when getGenerateDocs() is on: it says the description is still to come. With it off, every description is the empty string, and this is not used.

      Default: "INTENTIONALLY LEFT BLANK - WILL BE PROVIDED AT A LATER STAGE".

      Returns:
      the placeholder

    • getDescriptionBundle

      public abstract org.gradle.api.provider.Property<String> getDescriptionBundle()
      The base name of a ResourceBundle the generated classes resolve their descriptions through, such as docs.Descriptions. The project owns the text; what generation produced -- the contract's description, or the placeholder -- is the fallback for a key the bundle does not carry.

      Unset by default, and then the generated classes are the ones generated before there were bundles: the text is compiled into them, and nothing is resolved.

      -Dapionly.descriptions.bundle names another bundle for one run, and -Dapionly.descriptions.locale the locale to resolve in, which is what a documentation build rendering several languages from one generated tree uses.

      Returns:
      the bundle's base name

    • getInvalidRequestStatus

      public abstract org.gradle.api.provider.Property<String> getInvalidRequestStatus()
      The response status that means "the request is invalid". An invalid-request case is derived for an operation only when it declares exactly this status; an operation that constrains its request input without declaring it is reported as a gap.

      Default: "400".

      Returns:
      the status

    • getStrictRequests

      public abstract org.gradle.api.provider.Property<Boolean> getStrictRequests()
      Whether a request object that does not declare additionalProperties forbids members it does not declare, so that an unknown-member case is derived for it. An explicit additionalProperties: true, an additionalProperties schema, or patternProperties is respected either way.

      Default: true. Turning it off prints a warning on every generation, citing OWASP API3:2023 and API10:2023, and records it in the report.

      Returns:
      the setting

    • getValidateFormats

      public abstract org.gradle.api.provider.ListProperty<String> getValidateFormats()
      The formats, such as email, an invalid-request case is derived for. A format beside a pattern never gets one: the pattern wins.

      Default: none.

      Returns:
      the format names

    • getEmitterOptions

      @Deprecated public abstract org.gradle.api.provider.MapProperty<String,Map<String,String>> getEmitterOptions()
      Deprecated.
      Configure each emitter in its own block, emitter('<id>') { options = [...] }. Supported until 1.0.0, which removes it; every generation warns while it is set.
      Options for the emitters, by emitter id, each a map of names to values. The TranscriberJ passes them to the emitters unchanged, and fails the build when one names an emitter that is not on the transcriberjEmitters classpath. 
       emitterOptions = [restdocs: [tests: 'true']]

      Default: none.

      Returns:
      the options

    • getReportFile

      public abstract org.gradle.api.file.RegularFileProperty getReportFile()
      Where the generation writes its report: every degraded method, recommendation and undecided construct.

      Default: build/reports/transcriberj/<contract>.txt.

      Returns:
      the report file

    • getEndpointIndexFile

      public abstract org.gradle.api.file.RegularFileProperty getEndpointIndexFile()
      Where the generation writes the endpoint index. A tool reads the index through getEndpointIndex(), which carries the generation task.

      Default: build/generated/transcriberj-index/<contract>/contract-endpoints.properties.

      Returns:
      the index file

    • getEndpointIndex

      public abstract org.gradle.api.file.RegularFileProperty getEndpointIndex()
      The endpoint index the generation writes: the path of every generated operation and inline schema class, keyed ClassName.PATH. Read-only; it carries the generation task, so a tool reading it runs after the generation. getEndpointIndexFile() says where it is written. 
       doppelgangerApiDetector {
     propertyFiles.from(apiOnlyTranscriberJ.subscriptions.named('orders').flatMap { it.endpointIndex })
 }
      Returns:
      the index

    • getInto

      public abstract org.gradle.api.file.DirectoryProperty getInto()
      Where the core's sources -- the schema classes, operations and cases -- are generated. Each emitter's go where its emitter(...) block says.

      Default: build/generated/sources/transcriberj/<contract>/core.

      Returns:
      the directory

    • getIntoResources

      public abstract org.gradle.api.file.DirectoryProperty getIntoResources()
      Where the core's resources are generated. Each emitter's go where its emitter(...) block says.

      Default: build/generated/resources/transcriberj/<contract>/core.

      Returns:
      the directory