Pub/Sub

Topic subscriptions and fan-out publish. See the Pub/Sub guide for delivery semantics and lifecycle.

See Pub/Sub for the full guide (delivery semantics, lifecycle, cross-SDK topics).

Method	Description
`subscribe(topic, Task<T>)` / `subscribe(topic, Task<T>, SubscriptionOptions)`	Wire `Task` into `topic`'s routing (durable by default). Register the handler on the worker separately, as for any task.
`publish(topic, payload)` / `publish(topic, payload, PublishOptions)` → `List<Job>`	Fan a message out to every active subscription — one job each. Empty list when nothing is subscribed.
`unsubscribe(topic, name)`	Remove a subscription; `false` if none matched.
`pauseSubscription(topic, name)` / `resumeSubscription(topic, name)`	Stop/resume deliveries without unregistering; `false` if none matched.
`listSubscriptions()` / `listSubscriptions(topic)`	Every subscription, or one topic's active ones.
`listTopics()`	Distinct topics with at least one subscription.
`topicStats()` / `topicStats(topic)` → `List<TopicStat>`	Backlog snapshot per subscription, across all topics or filtered to one: `topic`, `subscription`, `taskName`, `queue`, `active`, `durable`, `pending`, `running`, `dead`, `oldestPendingAgeMs`. Every registered subscription appears — paused and ephemeral ones included — even at zero backlog. Computed live off indexed columns, so it is safe to poll.
`subscribeLog(topic, name)`	Register a durable log subscription — a named cursor with no handler. Writes immediately, so register it before the publishes it should see.
`logConsumer(topic, name, payloadType, handler)` / `logConsumer(topic, name, payloadType, handler, options)`	Register a managed consumer: the durable log subscription plus, once a worker runs, a daemon thread that pulls messages, decodes each into `payloadType`, invokes `handler`, and advances the cursor. `LogConsumerOptions` sets `pollIntervalMs` (default 1000), `batchSize` (default 100), and `onError` (`"retry"` leaves a failed message un-acked to re-read, default; `"skip"` acks past it).
`declareTopic(name)` / `declareTopic(name, retention)`	Declare a log topic so its publishes are retained even with no subscriber (removing the late-join boundary). `retention` (a `Duration`) bounds a sub-less backlog. Idempotent.
`listDeclaredTopics()` → `List<Topic>`	List declared topics: `name`, `mode`, `retentionMs`, `createdAt`.
`readTopic(topic, name)` / `readTopic(topic, name, limit)` → `List<TopicMessage>`	Pull up to `limit` (default 100) messages after `name`'s cursor, oldest first and exclusive of it. Empty once caught up. At-least-once — process, then `ackTopic`.
`ackTopic(topic, name, cursor)`	Advance a log subscription's cursor to `cursor` (a message `id`) — a monotonic high-water mark. `false` if nothing moved.
`leaseTopic(topic, name)` / `leaseTopic(topic, name, limit, visibility)` → `List<TopicMessage>`	Per-message alternative to the cursor read: lease up to `limit` (default 100) messages for `visibility` (a `Duration`, default 30s), tracked individually so a nack or lease timeout redelivers just that message. Don't mix with `readTopic`/`ackTopic` on one subscription.
`ackMessage(topic, name, messageId)` / `nackMessage(topic, name, messageId)` → `boolean`	Ack (done, never redelivered) or nack (redeliver now) one leased message. `false` if there was no un-acked delivery.
`topicLogStats()` → `List<TopicLogStat>`	Lag snapshot for every log subscription: `topic`, `subscription`, `cursor`, `lag`, `oldestUnackedAgeMs`.

See Log topics for the cursor, at-least-once, and retention semantics.

`TopicMessage`

One message pulled from a log topic, returned by readTopic and leaseTopic.

Field	Type	Description
`id`	`String`	Message id — pass to `ackTopic` (cursor read) or to `ackMessage`/`nackMessage` (per-message lease).
`payload`	`byte[]`	Opaque publish payload. Unlike Python/Node, this is not decoded for you — Java is statically typed and there's no target type to infer it into, so decode it yourself with the same serializer the publisher used.
`metadata`	`Map<String, Object>`	Caller metadata, decoded, or `null` if none was set.
`notes`	`Map<String, Object>`	Structured notes, decoded, or `null` if none were set.
`createdAt`	`long`	Unix-millisecond publish time.

Method

Description

subscribe(topic, Task<T>) / subscribe(topic, Task<T>, SubscriptionOptions)

Wire Task into topic's routing (durable by default). Register the handler on the worker separately, as for any task.

publish(topic, payload) / publish(topic, payload, PublishOptions) → List<Job>

Fan a message out to every active subscription — one job each. Empty list when nothing is subscribed.

unsubscribe(topic, name)

Remove a subscription; false if none matched.

pauseSubscription(topic, name) / resumeSubscription(topic, name)

Stop/resume deliveries without unregistering; false if none matched.

listSubscriptions() / listSubscriptions(topic)

Every subscription, or one topic's active ones.

listTopics()

Distinct topics with at least one subscription.

topicStats() / topicStats(topic) → List<TopicStat>

Backlog snapshot per subscription, across all topics or filtered to one: topic, subscription, taskName, queue, active, durable, pending, running, dead, oldestPendingAgeMs. Every registered subscription appears — paused and ephemeral ones included — even at zero backlog. Computed live off indexed columns, so it is safe to poll.

subscribeLog(topic, name)

Register a durable log subscription — a named cursor with no handler. Writes immediately, so register it before the publishes it should see.

logConsumer(topic, name, payloadType, handler) / logConsumer(topic, name, payloadType, handler, options)

Register a managed consumer: the durable log subscription plus, once a worker runs, a daemon thread that pulls messages, decodes each into payloadType, invokes handler, and advances the cursor. LogConsumerOptions sets pollIntervalMs (default 1000), batchSize (default 100), and onError ("retry" leaves a failed message un-acked to re-read, default; "skip" acks past it).

declareTopic(name) / declareTopic(name, retention)

Declare a log topic so its publishes are retained even with no subscriber (removing the late-join boundary). retention (a Duration) bounds a sub-less backlog. Idempotent.

listDeclaredTopics() → List<Topic>

List declared topics: name, mode, retentionMs, createdAt.

readTopic(topic, name) / readTopic(topic, name, limit) → List<TopicMessage>

Pull up to limit (default 100) messages after name's cursor, oldest first and exclusive of it. Empty once caught up. At-least-once — process, then ackTopic.

ackTopic(topic, name, cursor)

Advance a log subscription's cursor to cursor (a message id) — a monotonic high-water mark. false if nothing moved.

leaseTopic(topic, name) / leaseTopic(topic, name, limit, visibility) → List<TopicMessage>

Per-message alternative to the cursor read: lease up to limit (default 100) messages for visibility (a Duration, default 30s), tracked individually so a nack or lease timeout redelivers just that message. Don't mix with readTopic/ackTopic on one subscription.

ackMessage(topic, name, messageId) / nackMessage(topic, name, messageId) → boolean

Ack (done, never redelivered) or nack (redeliver now) one leased message. false if there was no un-acked delivery.

topicLogStats() → List<TopicLogStat>

Lag snapshot for every log subscription: topic, subscription, cursor, lag, oldestUnackedAgeMs.

TopicMessage

One message pulled from a log topic, returned by readTopic and leaseTopic.

Field	Type	Description
`id`	`String`	Message id — pass to `ackTopic` (cursor read) or to `ackMessage`/`nackMessage` (per-message lease).
`payload`	`byte[]`	Opaque publish payload. Unlike Python/Node, this is not decoded for you — Java is statically typed and there's no target type to infer it into, so decode it yourself with the same serializer the publisher used.
`metadata`	`Map<String, Object>`	Caller metadata, decoded, or `null` if none was set.
`notes`	`Map<String, Object>`	Structured notes, decoded, or `null` if none were set.
`createdAt`	`long`	Unix-millisecond publish time.