Docs

gradle.properties

@@ -18,7 +18,7 @@ kafkaVersion=""
 natsVersion=2.6.7
 apimicronaut=https://docs.micronaut.io/latest/api/io/micronaut/
 apinats=https://javadoc.io/doc/io.nats/jnats/
-testnats=nats/src/test/groovy/io/micronaut/docs/nats/docs
+testnats=nats/src/test/groovy/io/micronaut/nats/docs
 org.gradle.caching=true
 org.gradle.jvmargs=-Xmx2048M
 org.gradle.parallel=true

nats/build.gradle

@@ -1,4 +1,8 @@
 dependencies {
+    annotationProcessor platform("io.micronaut:micronaut-bom:$micronautVersion")
+    testAnnotationProcessor platform("io.micronaut:micronaut-bom:$micronautVersion")
+    implementation platform("io.micronaut:micronaut-bom:$micronautVersion")
+
     annotationProcessor "io.micronaut:micronaut-inject-java"
     // needed because otherwise IntelliJ integration broken
     implementation "io.micronaut:micronaut-inject-java"

nats/src/test/groovy/io/micronaut/nats/annotation/QueueSpec.groovy

@@ -25,7 +25,7 @@ import javax.annotation.Nullable
 
 class QueueSpec extends AbstractNatsTest {
 
-    void "test simple producing and consuming with a boolean"() {
+    void "test queue support"() {
         ApplicationContext applicationContext = startContext()
         PollingConditions conditions = new PollingConditions(timeout: 3)
         MyProducer producer = applicationContext.getBean(MyProducer)

src/main/docs/guide/consumer.adoc

@@ -0,0 +1,3 @@
+The quick start section presented a trivial example of what is possible with the ann:nats.annotation.NatsListener[] annotation.
+
+The implementation that powers `@NatsListener` (defined by the api:nats.intercept.NatsConsumerAdvice[] class) is, however, very flexible and offers a range of options for consuming NATS message.

src/main/docs/guide/consumer/consumerMethods.adoc

@@ -0,0 +1,45 @@
+All methods that consume messages from NATS must meet the following conditions:
+
+* The method must reside in a class annotated with ann:nats.annotation.NatsListener[].
+* The method must be annotated with ann:nats.annotation.Subject[].
+
+NOTE: In order for all of the functionality to work as `designed` in this guide your classes must be compiled with the parameters flag set to `true`.
+If your application was created with the Micronaut CLI, then that has already been configured for you.
+
+=== Simple Consumer
+
+The easiest way for defining a producer is the following:
+
+[source,java]
+----
+    @Subject("my-products")
+    public void receive(String name) {
+        System.out.println("Got Product - " + name);
+    }
+----
+
+=== Queue Support
+
+Subscribers may specify queue groups at subscription time. When a message is published to the group NATS will deliver it to a one-and-only-one subscriber.
+
+IMPORTANT: Queue groups do not persist messages. If no listeners are available, the message is discarded.
+
+[source,java]
+----
+    @Subject(value = "my-products", queue="my-queue")
+    public void receive(String name) {
+        System.out.println("Got Product - " + name);
+    }
+----
+
+=== Return Type and RPC
+
+IMPORTANT: If the consumer defines a return type, it automatically will use the RPC logic and will send the return value to the producer
+
+[source,java]
+----
+    @Subject(value = "my-products")
+    public Product receive(String name) {
+        return new Product(name);
+    }
+----

src/main/docs/guide/health.adoc

@@ -12,4 +12,4 @@ The information reported from the health indicator is under the `nats` key.
 }
 ----
 
-TIP: To disable the Nats health indicator entirely, add `endpoints.health.nats.enabled: false`.
+TIP: To disable the NATS health indicator entirely, add `endpoints.health.nats.enabled: false`.

src/main/docs/guide/introduction.adoc

@@ -1 +1,10 @@
 This project includes integration between Micronaut and nats.io. The standard link:https://github.com/nats-io/nats.java[Java Client] is used to do the actual publishing and consuming.
+
+=== Release History
+
+==== 1.0.0
+
+* Micronaut 1.2.x minimum version
+* Basic support for consumer and producers
+* RPC feature
+* Queue feature

src/main/docs/guide/producer.adoc

@@ -0,0 +1,4 @@
+The example in the quick start presented a trivial definition of an interface that be implemented automatically for you using the ann:nats.annotation.NatsClient[] annotation.
+
+The implementation that powers `@NatsClient` (defined by the api:nats.intercept.NatsIntroductionAdvice[] class) is, however, very flexible and offers a range of options for defining Kafka clients.
+

src/main/docs/guide/producer/producerMethods.adoc

@@ -0,0 +1,48 @@
+All methods that publish messages to NATS must meet the following conditions:
+
+* The method must reside in a interface annotated with ann:nats.annotation.NatsClient[].
+* The method or a method parameter must be annotated with ann:nats.annotation.Subject[].
+* The method must contain an argument representing the body of the message.
+
+NOTE: In order for all of the functionality to work as designed in this guide your classes must be compiled with the parameters flag set to `true`.
+If your application was created with the Micronaut CLI, then that has already been configured for you.
+
+=== Simple Producer
+
+The easiest way for defining a producer is the following:
+
+[source,java]
+----
+@Subject("my-products")
+void sendProduct(String name);
+----
+
+=== Dynamic subject
+
+[source,java]
+----
+void sendProduct(@Subject String topic, String name);
+----
+
+=== Publishing to Queues
+
+TIP: The NATS server will route the message to the queue and select a message receiver.
+
+=== Return Type and RPC
+
+IMPORTANT: If the producer defines a return type, it automatically will use the RPC logic and will wait for an answer from a consumer
+
+[source,java]
+----
+@Subject("product")
+Product sendProduct(String name);
+
+@Subject("product")
+Single<Product> sendProduct(String name);
+
+@Subject("product")
+Maybe<Product> sendProduct(String name);
+
+@Subject("product")
+Flowable<Product> sendProduct(String name);
+----

src/main/docs/guide/quickStart.adoc

@@ -1,4 +1,104 @@
-To add support for Nats.io to an existing project, you should first add the Micronaut Nats configuration to your build configuration. For example:
+To add support for NATS.io to an existing project, you should first add the Micronaut NATS configuration to your build configuration. For example:
 
 dependency:micronaut-nats[groupId="io.micronaut.nats"]
 
+=== Configuring NATS
+
+NOTE: Without any configuration the defaults in the link:{apinats}/{natsVersion}/io/nats/client/Options.html[Options] will be used.
+
+It is possible to configure multiple connections to the same server, different servers, or a single connection to one of a list of servers.
+
+[source,yaml]
+----
+nats:
+    server1:
+      addresses:
+        - "nats://localhost:4222"
+      username: guest
+      password: guest
+    server2:
+      addresses:
+        - "nats://randomServer:4222"
+      username: guest
+      password: guest
+----
+
+NATS also supports a fail over connection strategy where the first server that connects successfully will be used among a list of servers. To use this option in Micronaut, simply supply a list of `host:port` addresses.
+
+[source,yaml]
+----
+nats:
+    addresses:
+      - "nats://localhost:4222"
+      - "nats://randomServer:4222"
+    username: guest
+    password: guest
+----
+
+IMPORTANT: When the configuration option `nats.servers` is used, no other options underneath `nats` are read; for example `nats.username`.
+
+TIP: It is also possible to disable the integration entirely with `nats.enabled: false`
+
+=== Creating a NATS Producer with @NatsClient
+
+To create a NATS `Producer` that sends messages you can simply define an interface that is annotated with ann:nats.annotation.NatsClient[].
+
+For example the following is a trivial `@NatsClient` interface:
+
+.ProductClient.java
+[source,java]
+----
+import io.micronaut.nats.annotation.NatsClient;
+import io.micronaut.nats.annotation.Subject;
+import io.micronaut.messaging.annotation.Body;
+
+@NatsClient // <1>
+public interface ProductClient {
+
+    @Subject("my-products") // <2>
+    void send(String name);
+
+    void sendProduct(@Subject String brand, @Body String name); // <3>
+}
+----
+
+<1> The ann:nats.annotation.NatsClient[] annotation is used to designate this interface as a client
+<2> The ann:nats.annotation.Subject[] annotation indicates which subject the `Message` should be published to
+<3> It is also possible for the subject to be dynamic by making it a method argument
+
+At compile time Micronaut will produce an implementation of the above interface. You can retrieve an instance of `ProductClient` either by looking up the bean from the api:context.ApplicationContext[] or by injecting the bean with `@Inject`:
+
+.Using ProductClient
+[source,groovy]
+----
+ProductClient client = applicationContext.getBean(ProductClient.class);
+client.sendProduct("Nike", "Blue Trainers");
+----
+
+
+=== Creating a NATS Consumer with @NatsListener
+
+To listen to NATS messages you can use the ann:nats.annotation.NatsListener[] annotation to define a message listener.
+
+The following example will listen for messages published by the `ProductClient` in the previous section:
+
+.ProductListener.java
+[source,java]
+----
+import io.micronaut.messaging.annotation.Body;
+import io.micronaut.nats.annotation.NatsListener;
+import io.micronaut.nats.annotation.Subject;
+
+@NatsListener // <1>
+public class ProductListener {
+
+    @Subject("my-products") // <2>
+    public void receive(@Body String name) { // <3>
+        System.out.println("Got Product - " + name);
+    }
+}
+----
+
+<1> The ann:nats.annotation.NatsListener[] is used to designate this class as a listener.
+<2> The ann:nats.annotation.Subject[] annotation is again used to indicate which subject to subscribe to.
+<3> The `receive` method defines one argument, which will receive the value.

src/main/docs/guide/toc.yml

@@ -1,5 +1,9 @@
 introduction: Introduction
-whatsNew: What's New
-quickStart: Nats Quick Start
-config: Configuring The Connection
-health: Nats Health Indicator
+quickStart: NATS Quick Start
+producer:
+  title: NATS Producers Using @NatsClient
+  producerMethods: Defining @NatsClient Methods
+consumer:
+  title: NATS Consumers Using @NatsListener
+  consumerMethods: Defining @NatsListener Methods
+health: NATS Health Indicator