Java Spring Cloud Stream Generator Template

This template generates a Spring Cloud Stream (SCSt) microservice. It uses version 3 of SCSt which uses function names to configure the channels. See the reference. The generated microservice is a Maven project so it can easily be imported into your IDE.

This template has been tested with Kafka, RabbitMQ and Solace.

The Spring Cloud Stream microservice generated using this template will be an ready to run Spring Boot app. By default, the microservice will contain a java class, Application.java, which includes methods to publish or subscribe events as defined in the AsyncAPI document. These generated methods include Supplier, Consumer and Function functional interfaces from the java.util.function package. These methods will already be pre-configured to publish to and consume from the channels as defined in the AsyncAPI. This configuration is located in the spring.cloud.stream section of the generated application.yml file.

Note that this template ignores the 'Servers' section of AsyncAPI documents. The main reason for this is because SCSt does not directly work with messaging protocols. Protocols are implementation details specific to binders, and SCSt applications need not know or care which protocol is being used.

Technical requirements

• 1.9.4 =< Generator
• Generator specific requirements

Specification Conformance

Note that this template interprets the AsyncAPI document in conformance with the AsyncAPI Specification. This means that when the template sees a subscribe operation, it will generate code to publish to that operation's channel. It is possible to override this, see the 'view' parameter in the parameters section below.

Which Methods are created

The template works as follows:

• By default, for each channel in the AsyncAPI document, if there is a subscribe operation a Supplier method will be generated, and for a publish operation a Consumer method will get generated.
• To customize this default behavior, you can make use of the x-scs-function-name extension. If one publish operation and one subscribe operation share a x-scs-function-name attribute then a java.util.function.Function method will be created which uses the subscribe operation's message as the input and the publish operation's message as the output to the generated Function method. It will also wire up the proper channel information in the generated application.yaml file.
• Note that at this time the generator does not support the creation of functions that have more than one publish and/or more than one subscribe operation with the same x-scs-function-name attribute. This scenario will result in error.

• Additionally, if a channel has parameters and a subscribe operation, a send method will be generated that takes the payload and the parameters as function arguments, formats the topic from the parameters, and sends the message using the StreamBridge as described in the Spring Cloud Steam documentation. If you use x-scs-function-name to combine a subscribe and a publish operation and the subscribe operation has parameters, then this template will render a Consumer method that will receive a message and then call the generated send method to send out a new message through the StreamBridge.

  This behaviour may be modified by setting the dynamicType parameter to 'header'. This is to support binders that can route messages by putting the topic into a message header. In this case, a Supplier and a Function will set the header on the message rather than use the StreamBridge, however send methods will still be rendered for convenience.

Method Naming

The generated methods are named as follows:

• For each operation (i.e., publish or subscribe in each channel), the template looks for the specification extension x-scs-function-name. If present, it uses that to name the function.
• If using the same x-scs-function-name on one publish operation and one subscribe operation to create a Function the name of the generated method will be the x-scs-function-name
• If there is no x-scs-function-name attribute, the generator checks the operation's operationId value. If set, that is used as the function name.
• If there is no x-scs-function-name or operationId available, then a name will be generated by taking the channel name, removing non-alphanumeric characters, converting to camel case, and appending 'Supplier' or 'Producer.' For example, if there is a channel called store/process with a publisher operation with a payload called Order, the following method will get generated:

  @Bean
  public Supplier<Order> storeProcessSupplier () {
  // Add business logic here.
  return null;
  }

  Property Naming

When converting from property names to Java field names, the property names are first converted to camelCase, removing non-alphanumeric characters in the process. If the resulting name ends up being a Java keyword, it is prepended with an underscore.

Application vs Library

By default, this will generate a runnable Spring Boot application. If you set the artifactType parameter to library, then it will generate a project without a main Application class and without the main Spring Boot dependencies. That will produce a library that can be imported into another application as a Maven artifact. It will contain the model classes and the Spring Cloud Stream configuration.

Doing that allows you to have a clean separation between the generated code and your hand-written code, and ensures that regenerating the library will not overwrite your business logic.

How to Use This Template

1. Install the AsyncAPI Generator

   npm install -g @asyncapi/generator

2. Run the Generator using the Java Spring Cloud Stream Template

   ag ~/AsyncApiDocument.yaml @asyncapi/java-spring-cloud-stream-template

3. Run the Generator using the Java Spring Cloud Stream Template with Parameters

   ag -p binder=solace -p artifactId=ExampleArtifactId -p groupId=com.example -p javaPackage=com.example.foo -p solaceSpringCloudVersion=1.0.0 -p springCloudStreamVersion=Horsham.SR3 -p springCloudVersion=Hoxton.SR3 ~/AsyncApiDocument.yaml @asyncapi/java-spring-cloud-stream-template

Configuration Options

Please note that none of the parameters or specification extensions is required. All parameters have defaults as documented below.

Any parameters or specification extensions that include the name 'Solace' only have an effect when the Solace binder is specified. If and when other binder-specific parameters are added to this template, they will follow a similar naming pattern.

Destination Overrides

There are two specification extensions you can use to shape how the bindings are configured. You can add the following to a subscribe operation:

x-scs-destination : This overrides the destination value in a binder. This is useful when you are using the Solace binder and you are following the Solace pattern of publishing to topics and consuming from queues. In this case the x-scs-destination value would be treated as the name of the queue which your microservice will consume from.

x-scs-group : This will add the group value on a binding which configures your microservice to use Consumer Groups

Limitations

Currently any schemas that are used must be in the components/schemas part of the document. We do not support anonymous object-type schemas in the message/payload sections.

Parameters

Parameters can be passed to the generator using command line arguments in the form -p param=value -p param2=value2. Here is a list of the parameters that can be used with this template. In some cases these can be put into the AsyncAPI documents using the specification extensions feature. In those cases, the 'info' prefix means that it belongs in the info section of the document.

Specification Extensions

The following specification extensions are supported. In some cases, their value can be provided as a command line parameter. The 'info' prefix means that it belongs in the info section of the document.

Development

This project follows the all-contributors specification. Contributions of any kind are welcome!

If you do contribute, please run npm run lint and npm test before you submit your code.

Contributors

Thanks goes to these wonderful people (emoji key):

Michael Davis 💻 📖 👀 💬	Marc DiPasquale 📖	Fran Méndez 💻 🚇	Lukasz Gornicki 🚇 💻
blzsaa 💻