diff --git a/docs/guide/src/docs/asciidoc/usage.adoc b/docs/guide/src/docs/asciidoc/usage.adoc index 96c4ec74..d496fbcc 100644 --- a/docs/guide/src/docs/asciidoc/usage.adoc +++ b/docs/guide/src/docs/asciidoc/usage.adoc @@ -126,10 +126,14 @@ arguments they have and their return value. ==== Quick Start -You can use two conventional annotations `@QueueProducer` and `@QueueConsumer` to publish and consume messages from a queue. +You can use three conventional annotations `@QueueProducer`, `@QueueListener` and `@QueueConsumer` to publish and consume messages from a queue. + +`@QeueProducer` is used to publish messages to a queue, `@QueueListener` is used to poll messages from a queue and `@QueueConsumer` is used to consume messages from a queue. The difference between `@QueueListener` and `@QueueConsumer` is that the `@QueueListener` is triggered once using `initialDelay` and then polls the queue indefinitely until the application is terminated. The `@QueueConsumer` is triggered periodically using `fixedRate` and polls the queue for messages, at most `maxMessages` in a single job run. + +TIP: If you are in doubts, use `@QueueListener` to consume the messages from the queue as fast as possible. If you need more fine-grained control, use `@QueueConsumer`. [source,java] -.Queue Producer and Consumer +.Queue Quick Start ---- include::{root-dir}/libs/micronaut-worker/src/test/groovy/com/agorapulse/worker/convention/QueueListenerAndProducerSpec.groovy[tag=quickstart,indent=0] ---- @@ -137,8 +141,10 @@ include::{root-dir}/libs/micronaut-worker/src/test/groovy/com/agorapulse/worker/ <2> The producer jobs must have some scheduled trigger associated with them, for example cron or fixed rate <3> Use the `@QueueProducer` annotation with the name of the queue to publish messages <4> The producer job must return some value, ideally a `Publisher` of given messages -<5> Use the `@QueueConsumer` annotation with the name of the queue to consume messages +<5> Use the `@QueueListener` annotation with the name of the queue to poll the messages. <6> The consumer job must have a single parameter of the same type as the producer job returns +<7> Use the `@QueueConsumer` annotation with the name of the queue to consume messages +<8> The consumer job must have a single parameter of the same type as the producer job returns TIP: The value for `@Fork` is the same as the number of `maxMessages` for `@QueueConsumer` annotation. The value of `waitingTime` in `@QueueConsumer` is the same as the associated `@FixedRate` value. diff --git a/libs/micronaut-worker-tck/src/main/groovy/com/agorapulse/worker/tck/queue/NonBlockingJob.java b/libs/micronaut-worker-tck/src/main/groovy/com/agorapulse/worker/tck/queue/NonBlockingJob.java index 7db8662f..79326165 100644 --- a/libs/micronaut-worker-tck/src/main/groovy/com/agorapulse/worker/tck/queue/NonBlockingJob.java +++ b/libs/micronaut-worker-tck/src/main/groovy/com/agorapulse/worker/tck/queue/NonBlockingJob.java @@ -1,3 +1,20 @@ +/* + * SPDX-License-Identifier: Apache-2.0 + * + * Copyright 2021-2025 Agorapulse. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ package com.agorapulse.worker.tck.queue; import com.agorapulse.worker.annotation.FixedRate; diff --git a/libs/micronaut-worker/src/test/groovy/com/agorapulse/worker/convention/QueueListenerAndProducerSpec.groovy b/libs/micronaut-worker/src/test/groovy/com/agorapulse/worker/convention/QueueListenerAndProducerSpec.groovy index 8175b281..45586068 100644 --- a/libs/micronaut-worker/src/test/groovy/com/agorapulse/worker/convention/QueueListenerAndProducerSpec.groovy +++ b/libs/micronaut-worker/src/test/groovy/com/agorapulse/worker/convention/QueueListenerAndProducerSpec.groovy @@ -41,10 +41,15 @@ class QueueListenerAndProducerSpec extends Specification { return Flux.just("Hello", "World").map(Message::new); } - @QueueConsumer("my-queue") // <5> + @QueueListener("my-queue") // <5> public void listenToMyQueue(Message message) { // <6> // your code here } + + @QueueConsumer("my-queue") // <7> + public void consumeToMyQueue(Message message) { // <8> + // your code here + } // end::quickstart[] @com.agorapulse.worker.annotation.Job('queue-listener-job')