@asyncapi/java-spring-cloud-stream-template

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.

Parameter	Extension	Default	Description
actuator		false	If true, it adds the dependencies for spring-boot-starter-web, spring-boot-starter-actuator and micrometer-registry-prometheus.
artifactId	info.x-artifact-id	project-name	The Maven artifact id.
artifactType		application	The type of project to generate, application or library. When generating an application, the pom.xml file will contain the complete set of dependencies required to run an app, and it will contain an Application class with a main function. Otherwise the pom file will include only the dependencies required to compile a library.
binder		kafka	The name of the binder implementation, one of kafka, rabbit or solace. Default: kafka. If you need other binders to be supported, please let us know!
dynamicType		streamBridge	If you publish to a channel with parameters, i.e. a topic that can change with every message, the standard way to do this is to use StreamBridge. But some binders such as Solace can do the dynamic routing using just a message header. If you use such a binder, then you can set this value to 'header' and the generated code will set the topic on the header rather than use StreamBridge.
groupId	info.x-group-id	com.company	The Maven group id.
host		tcp://localhost:55555	The host connection property. Currently this only works with the Solace binder. When other binders are used this parameter is ignored.
javaPackage	info.x-java-package		The Java package of the generated classes. If not set then the classes will be in the default package.
msgVpn		default	The message vpn connection property. Currently this only works with the Solace binder. When other binders are used this parameter is ignored.
password		default	The client password connection property. Currently this only works with the Solace binder. When other binders are used this parameter is ignored.
parametersToHeaders		false	If true, this will create headers on the incoming messages for each channel parameter. Currently this only works with messages originating from Solace (using the solace_destination header) and RabbitMQ (using the amqp_receivedRoutingKey header.)
reactive		false	If true, the generated functions will use the Reactive style and use the Flux class.
solaceSpringCloudVersion	info.x-solace-spring-cloud-version	2.1.0	The version of the solace-spring-cloud-bom dependency used when generating an application.
springBootVersion	info.x-spring-boot-version	2.4.7	The version of Spring Boot used when generating an application.
springCloudVersion	info.x-spring-cloud-version	2020.0.3	The version of the spring-cloud-dependencies BOM dependency used when generating an application.
springCloudStreamVersion	info.x-spring-cloud-stream-version	3.1.3	The version of the spring-cloud-stream dependency specified in the Maven file, when generating a library. When generating an application, the spring-cloud-dependencies BOM is used instead
username		default	The client username connection property. Currently this only works with the Solace binder. When other binders are used this parameter is ignored.
view	info.x-view	client	By default, this template generates publisher code for subscribe operations and vice versa. You can switch this by setting this parameter to 'provider'.
useServers		false	This parameter only works when the binder parameter is kafka. It takes all the urls under the server section and concatenates them to a set of brokers.

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.

Extension	Parameter	Default	Description
info.x-artifact-id	artifactId	project-name	The Maven artifact id.
info.x-group-id	groupId	com.company	The Maven group id.
info.x-java-package	javaPackage		The Java package of the generated classes. If not set then the classes will be in the default package.
info.x-solace-spring-cloud-version	solaceSpringCloudVersion	1.0.0	The version of the solace-spring-cloud BOM dependency used when generating an application.
info.x-spring-boot-version	info.x-spring-boot-version	2.2.6.RELEASE	The version of the Spring Boot used when generating an application.
info.x-spring-cloud-version	info.x-spring-cloud-version	Hoxton.SR3	The version of the spring-cloud-dependencies BOM dependency used when generating an application.
info.x-spring-cloud-stream-version	springCloudStreamVersion	3.0.3.RELEASE	The version of the spring-cloud-stream dependency specified in the Maven file, when generating a library. When generating an application, the spring-cloud-dependencies BOM is used instead.
info.x-view	view	client	By default, this template generates publisher code for subscribe operations and vice versa. You can switch this by setting this parameter to 'provider'.
operation.x-scs-function-name			This specifies the base function name to use on a publish or subscribe operation. If the same name is used on one subscribe operation and one publish operation, a processor function will be generated.
channel.subscription.x-scs-destination			This overrides the destination on an incoming binding. It can be used to specify, for example, the name of a queue to subscribe to instead of a topic.
channel.subscription.x-scs-group			This is used to specify the group property of an incoming binding.

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 💻