Package com.arc_e_tect.gradle.apionly.transcriberj.spi

Interface EmitterContext

public interface EmitterContext
What an emitter is given to write one contract's classes.

  • Method Summary

    Modifier and Type
    Method
    Description
    default List<ContractCase>
    contractCases(String location)
    The contract cases of an operation, in the order its generated CASES lists them: success, not found, not acceptable, unsupported media type, then invalid requests.
    String
    degraded(String className, String method, Finding finding)
    Records that a generated method cannot represent a construct, and returns the statement its body consists of instead: one that throws UnsupportedOperationException with the reason and, where there is one, the remedy.
    ContractModel
    model()
    The contract.
    ClassNames
    names()
    The core classes, whose names an emitter's companions follow.
    default Optional<String>
    parameterSchema(String location, String in, String name)
    The schema a path, query or header parameter of an operation must satisfy, as a self-contained JSON Schema 2020-12 document, made as requestBodySchema(java.lang.String, java.lang.String) makes a body's.
    default Optional<String>
    requestBodySchema(String location, String mediaType)
    The schema a request body of an operation must satisfy, as a self-contained JSON Schema 2020-12 document: every $ref bundled into $defs, strict as the core's own notion of validity is when strictRequests is on, and with format asserted only for the formats validateFormats names -- any other is written as the annotation x-format.
    default Optional<ResponseBody>
    responseBody(String location, String status)
    The body of a response an operation declares, in its first content type: the class that response's contract cases name, and the text its generated requiredBody() and fullBody() return, or why the core cannot build one.
    Settings
    settings()
    How the project has asked for the classes to be generated.
    default void
    writeFile(String path, byte[] content)
    Writes one file that belongs on no classpath -- a mapping file, part of an archive -- replacing any file already written at that path in this run.
    default void
    writeFile(String path, String content)
    Writes one text file that belongs on no classpath, UTF-8 encoded, as writeFile(String, byte[]) does.
    void
    writeJava(String packageName, String simpleName, String source)
    Writes one Java source file, replacing any file already written for that class in this run.
    void
    writeResource(String path, String content)
    Writes one resource file, replacing any file already written at that path in this run -- a properties file a generated or hand-written class reads through getResourceAsStream, for instance.

  • Method Details

    • model

      ContractModel model()
      The contract.
      Returns:
      the model

    • settings

      Settings settings()
      How the project has asked for the classes to be generated.
      Returns:
      the settings

    • names

      ClassNames names()
      The core classes, whose names an emitter's companions follow.
      Returns:
      the class names

    • writeJava

      void writeJava(String packageName, String simpleName, String source)
      Writes one Java source file, replacing any file already written for that class in this run.
      Parameters:
      packageName - the package
      simpleName - the class's simple name
      source - the whole compilation unit

    • writeResource

      void writeResource(String path, String content)
      Writes one resource file, replacing any file already written at that path in this run -- a properties file a generated or hand-written class reads through getResourceAsStream, for instance.

      path is /-separated and relative to the resource root, and may nest in directories, such as "META-INF/emitter/service.properties". It may not be absolute, and may not use empty, . or .. segments.

      Parameters:
      path - the resource's path within the resource root
      content - the resource's content, written UTF-8

    • writeFile

      default void writeFile(String path, byte[] content)
      Writes one file that belongs on no classpath -- a mapping file, part of an archive -- replacing any file already written at that path in this run. The plugin packages these files; it never compiles them or puts them on a classpath.

      path follows the rules of writeResource(String, String): /-separated, relative, and without empty, . or .. segments. Only an emitter whose Emitter.produces(java.util.Map) includes Output.FILES may call it.

      Parameters:
      path - the file's path within the emitter's files directory
      content - the file's bytes
      Throws:
      UnsupportedOperationException - when this context has nowhere to write files: a generation run without a files directory

    • writeFile

      default void writeFile(String path, String content)
      Writes one text file that belongs on no classpath, UTF-8 encoded, as writeFile(String, byte[]) does.
      Parameters:
      path - the file's path within the emitter's files directory
      content - the file's text

    • degraded

      String degraded(String className, String method, Finding finding)
      Records that a generated method cannot represent a construct, and returns the statement its body consists of instead: one that throws UnsupportedOperationException with the reason and, where there is one, the remedy. Every degraded method is reported at the end of generation.
      Parameters:
      className - the simple name of the class the method is in
      method - the method, as a reader would name it, such as body(String)
      finding - the construct it cannot represent
      Returns:
      a Java statement, without indentation

    • contractCases

      default List<ContractCase> contractCases(String location)
      The contract cases of an operation, in the order its generated CASES lists them: success, not found, not acceptable, unsupported media type, then invalid requests. What an emitter that renders cases shapes its code by. The core derives them before any other emitter runs.
      Parameters:
      location - the JSON pointer of the operation, such as /paths/~1v1~1users/get
      Returns:
      the cases; empty when the operation has none, or there is no such operation

    • responseBody

      default Optional<ResponseBody> responseBody(String location, String status)
      The body of a response an operation declares, in its first content type: the class that response's contract cases name, and the text its generated requiredBody() and fullBody() return, or why the core cannot build one. An emitter that writes a response as a file, which cannot call those methods, takes its text from here.
      Parameters:
      location - the JSON pointer of the operation, such as /paths/~1v1~1users/get
      status - the response's key as the contract declares it, such as 200
      Returns:
      the body; empty when the operation declares no such response, or it has no content or no generated body class

    • requestBodySchema

      default Optional<String> requestBodySchema(String location, String mediaType)
      The schema a request body of an operation must satisfy, as a self-contained JSON Schema 2020-12 document: every $ref bundled into $defs, strict as the core's own notion of validity is when strictRequests is on, and with format asserted only for the formats validateFormats names -- any other is written as the annotation x-format. It is exactly the schema the core generates valid bodies for and derives invalid ones against.
      Parameters:
      location - the JSON pointer of the operation
      mediaType - the request body's media type, as the operation declares it
      Returns:
      the schema's JSON text; empty when the operation declares no such body or its schema

    • parameterSchema

      default Optional<String> parameterSchema(String location, String in, String name)
      The schema a path, query or header parameter of an operation must satisfy, as a self-contained JSON Schema 2020-12 document, made as requestBodySchema(java.lang.String, java.lang.String) makes a body's. A value travels as a string: the schema is that of the value it stands for, so a stub matching a path segment by its pattern reads it here.
      Parameters:
      location - the JSON pointer of the operation
      in - where the parameter is: path, query or header
      name - the parameter's name
      Returns:
      the schema's JSON text; empty when the operation declares no such parameter or its schema