KubeMQ
Client SDKsJavaHow-to guidesQueues

Delay Policy

Field-level reference for delayInSeconds, the QueueMessage builder option that configures delivery delay in the Java SDK.

Which to use

For the task-oriented how-to, see Delayed Messages. This page focuses on the delayInSeconds delay-policy option itself — its evaluation point and interaction with redelivery.

Overview

.delayInSeconds(delay) is the builder option on QueueMessage that defers when a queued message becomes visible to consumers — set it before sending, and the broker excludes the message from delivery until the countdown expires. It starts the moment the broker accepts the message, not when the client sends it, and is evaluated once, at send time.

Gotchas: the delay is a floor, not a guarantee — the message becomes eligible when the timer expires, but actual delivery still waits for a consumer to poll, so don't rely on it for precise scheduling. It's one-shot: there's no recurrence or cron-like behavior, so long or repeating delays need application logic on top. And it's independent of redelivery — a delayed message that's later nacked or times out after delivery follows normal visibility-timeout/retry rules, not the original send-time delay.

Prerequisites

  • KubeMQ server running on localhost:50000
  • Java SDK installed (implementation 'io.kubemq.sdk:kubemq-sdk-Java:3.1.1' (Gradle) or Maven dependency from Getting Started)

Code

DelayPolicyExample.java
package io.kubemq.example.queuesstream;

import io.kubemq.sdk.queues.*;
import java.util.UUID;

/**
 * DelayPolicyExample for Queues Stream
 */
public class DelayPolicyExample {
    private static final String ADDRESS = "localhost:50000";
    private static final String CLIENT_ID = "java-queues-delay-policy-client";
    private static final String CHANNEL = "java-queues.delay-policy";

    /**
     * Demonstrates sending multiple messages with different delay values
     * to implement scheduled delivery policies.
     */
    public static void main(String[] args) throws InterruptedException {
        // Create a client connected to the KubeMQ server
        try (QueuesClient client = QueuesClient.builder().address(ADDRESS).clientId(CLIENT_ID).build()) {
            // Create the queue channel
            client.createQueuesChannel(CHANNEL);

            // Send messages with different delay values (scheduled delivery)
            int[] delays = {1, 3, 5};
            for (int delay : delays) {
                client.sendQueueMessage(QueueMessage.builder()
                        .id(UUID.randomUUID().toString()).channel(CHANNEL)
                        .body(("Delay " + delay + "s").getBytes())
                        .delayInSeconds(delay).build());
                System.out.println("Sent message with " + delay + "s delay.");
            }

            // Poll as messages become available after their delay
            System.out.println("\nPolling as messages become available...");
            for (int i = 0; i < 3; i++) {
                QueuesPollResponse response = client.receiveQueueMessages(QueuesPollRequest.builder()
                        .channel(CHANNEL).pollMaxMessages(1).pollWaitTimeoutInSeconds(10).autoAckMessages(true).build());
                if (!response.getMessages().isEmpty()) {
                    System.out.println("  Received: " + new String(response.getMessages().get(0).getBody()));
                }
            }

            // Clean up resources
            client.deleteQueuesChannel(CHANNEL);
        }
    }
}

How It Works

  • Three messages are sent with delayInSeconds(1), delayInSeconds(3), and delayInSeconds(5); they become available at staggered times.
  • The poll loop uses pollWaitTimeoutInSeconds(10) so each iteration waits up to 10 seconds for the next message to become available as its delay expires.
  • Messages are received in delay-expiry order (1s first, then 3s, then 5s), demonstrating scheduled delivery policy across a single channel.

Was this page helpful?

On this page