Package com.arc_e_tect.gradle.apionly.transcriberj.core

Class Generation

java.lang.Object

com.arc_e_tect.gradle.apionly.transcriberj.core.Generation

public final class Generation
extends Object

One generation run: a contract in, a tree of Java sources out.

The core emitter runs first; then every other emitter, in the order given, over the same model and the same class names.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	Generation.Derivation	What derive(java.nio.file.Path, java.nio.file.Path, java.lang.String, java.lang.String, com.arc_e_tect.gradle.apionly.transcriberj.spi.Settings) works out once: the model, the class names, the cases and the core's report, and the core's output, not yet written.

Method Summary

Modifier and Type	Method	Description
static Generation.Derivation	derive(Path contract, Path asyncContract, String contractVersion, String contractSha256, Settings settings)	Derives everything the core generates from a contract -- the model, the class names, the invalid-request cases, the report -- and the core's own sources, held in memory.
static GenerationReport	run(Path contract, String contractVersion, String contractSha256, Settings settings, Path outputDirectory, Path resourceDirectory, List<Emitter> emitters, Path endpointIndex)	Generates one contract's sources, replacing whatever the output directory held.
static GenerationReport	run(Path contract, Path asyncContract, String contractVersion, String contractSha256, Settings settings, Path outputDirectory, Path resourceDirectory, List<Emitter> emitters, Path endpointIndex)	Generates one contract's sources from both of its documents.
static GenerationReport	runEmitter(Generation.Derivation derivation, Emitter emitter, Path javaDirectory, Path resourceDirectory, Path filesDirectory)	Runs one emitter over a derivation, replacing whatever its three directories held.
static GenerationReport	writeCore(Generation.Derivation derivation, Path outputDirectory, Path resourceDirectory, Path endpointIndex)	Writes the core's sources and resources, replacing whatever the two directories held, and the endpoint index.

Methods inherited from class java.lang.Object

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

Method Details

run

public static GenerationReport run(Path contract,
 String contractVersion,
 String contractSha256,
 Settings settings,
 Path outputDirectory,
 Path resourceDirectory,
 List<Emitter> emitters,
 Path endpointIndex)

Generates one contract's sources, replacing whatever the output directory held.

Parameters:

contract - the fetched contract document

contractVersion - the version the build locked the contract at

contractSha256 - the SHA-256 the build locked the document at

settings - how the project asked for the classes

outputDirectory - where the sources go

resourceDirectory - where a resource an emitter writes goes

emitters - the emitters to run after the core emitter

endpointIndex - where to write the path of every operation class and inline schema class, keyed ClassName.PATH, for tools that read test sources without a classpath; null to write none

Returns:

what could not be generated in full

Throws:

GenerationException - when no sources can be generated from the contract

run

public static GenerationReport run(Path contract,
 Path asyncContract,
 String contractVersion,
 String contractSha256,
 Settings settings,
 Path outputDirectory,
 Path resourceDirectory,
 List<Emitter> emitters,
 Path endpointIndex)

Generates one contract's sources from both of its documents.

They are read into one model, so a fragment both use -- a username in a response and in an event payload -- is one component, and one class.

Parameters:

contract - the fetched OpenAPI document

asyncContract - the fetched AsyncAPI document, or null when the contract has none

contractVersion - the version the build locked the contract at

contractSha256 - the SHA-256 the build locked the document at

settings - how the project asked for the classes

outputDirectory - where the sources go

resourceDirectory - where a resource an emitter writes goes

emitters - the emitters to run after the core emitter

endpointIndex - where to write the path of every operation class and inline schema class, keyed ClassName.PATH, for tools that read test sources without a classpath; null to write none

Returns:

what could not be generated in full

Throws:

GenerationException - when no sources can be generated from the contract

derive

public static Generation.Derivation derive(Path contract,
 Path asyncContract,
 String contractVersion,
 String contractSha256,
 Settings settings)

Derives everything the core generates from a contract -- the model, the class names, the invalid-request cases, the report -- and the core's own sources, held in memory. Nothing is written: writeCore(com.arc_e_tect.gradle.apionly.transcriberj.core.Generation.Derivation, java.nio.file.Path, java.nio.file.Path, java.nio.file.Path) writes the core's output, and runEmitter(com.arc_e_tect.gradle.apionly.transcriberj.core.Generation.Derivation, com.arc_e_tect.gradle.apionly.transcriberj.spi.Emitter, java.nio.file.Path, java.nio.file.Path, java.nio.file.Path) runs one emitter over the same derivation.

Every step is deterministic, so two derivations of one contract with one set of settings are the same, whichever task makes them.

Parameters:

contract - the fetched OpenAPI document

asyncContract - the fetched AsyncAPI document, or null when the contract has none

contractVersion - the version the build locked the contract at

contractSha256 - the SHA-256 the build locked the document at

settings - how the project asked for the classes

Returns:

the derivation

Throws:

GenerationException - when no sources can be generated from the contract

writeCore

public static GenerationReport writeCore(Generation.Derivation derivation,
 Path outputDirectory,
 Path resourceDirectory,
 Path endpointIndex)

Writes the core's sources and resources, replacing whatever the two directories held, and the endpoint index.

Parameters:

derivation - the derivation

outputDirectory - where the core's sources go

resourceDirectory - where the core's resources go

endpointIndex - where the endpoint index goes; null to write none

Returns:

the core's report

runEmitter

public static GenerationReport runEmitter(Generation.Derivation derivation,
 Emitter emitter,
 Path javaDirectory,
 Path resourceDirectory,
 Path filesDirectory)

Runs one emitter over a derivation, replacing whatever its three directories held.

Parameters:

derivation - the derivation

emitter - the emitter

javaDirectory - where its Java sources go

resourceDirectory - where its classpath resources go

filesDirectory - where its files go

Returns:

what this emitter reported: the methods it degraded