This is an automated email from the ASF dual-hosted git repository.
lhotari pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pulsar-site.git
The following commit(s) were added to refs/heads/main by this push:
new 3611551ac93 docs(tableview): clarify tombstone behaviour for forEach
and forEachAndListen (#1125)
3611551ac93 is described below
commit 3611551ac93c5a6d81925f8574917cb259d83482
Author: Vishal Kumar Singh <[email protected]>
AuthorDate: Wed Apr 22 14:19:44 2026 +0530
docs(tableview): clarify tombstone behaviour for forEach and
forEachAndListen (#1125)
Fixes #24007. The docs do not spell out how null-value (tombstone)
messages flow through TableView. The Java implementation
(pulsar-client/src/main/java/org/apache/pulsar/client/impl/TableViewImpl.java)
removes the key from the backing map and invokes every registered listener
with (key, null), so:
- forEach iterates only over the current map, therefore tombstoned keys
are skipped.
- forEachAndListen first does a forEach pass over the non-tombstoned
entries, then delivers every subsequent update (including tombstones)
to the listener as accept(key, null).
Add a note under 'Register listeners' across the next + 4.2.x/4.1.x/3.3.x
versioned docs so users writing compaction/cleanup consumers can rely on
the documented behaviour instead of guessing.
---
docs/client-libraries-tableviews.md | 9 +++++++++
versioned_docs/version-3.3.x/client-libraries-tableviews.md | 9 +++++++++
versioned_docs/version-4.1.x/client-libraries-tableviews.md | 9 +++++++++
versioned_docs/version-4.2.x/client-libraries-tableviews.md | 9 +++++++++
4 files changed, 36 insertions(+)
diff --git a/docs/client-libraries-tableviews.md
b/docs/client-libraries-tableviews.md
index 7a835e30e56..ad790ab3627 100644
--- a/docs/client-libraries-tableviews.md
+++ b/docs/client-libraries-tableviews.md
@@ -69,6 +69,15 @@ You can use the available parameters in the `loadConf`
configuration or the API
</Tabs>
````
+:::note Tombstone (null-value) messages
+
+`TableView` treats a message with a `null` payload as a **tombstone** - the
key is removed from the map.
+
+- `forEach(action)` iterates over the current map snapshot only, so it **does
not** surface keys that have been tombstoned.
+- `forEachAndListen(action)` first runs `forEach` over the current
non-tombstoned entries, then registers the action as a live listener. Every
subsequent update - **including tombstones** - is delivered to the listener as
`action.accept(key, null)`. If you need to react to deletions (for example, to
clean up downstream state), check for `value == null` in your listener.
+
+:::
+
## Register listeners
You can register listeners for both existing messages on a topic and new
messages coming into the topic by using `forEachAndListen`, and specify to
perform operations for all existing messages by using `forEach`.
diff --git a/versioned_docs/version-3.3.x/client-libraries-tableviews.md
b/versioned_docs/version-3.3.x/client-libraries-tableviews.md
index 7a835e30e56..ad790ab3627 100644
--- a/versioned_docs/version-3.3.x/client-libraries-tableviews.md
+++ b/versioned_docs/version-3.3.x/client-libraries-tableviews.md
@@ -69,6 +69,15 @@ You can use the available parameters in the `loadConf`
configuration or the API
</Tabs>
````
+:::note Tombstone (null-value) messages
+
+`TableView` treats a message with a `null` payload as a **tombstone** - the
key is removed from the map.
+
+- `forEach(action)` iterates over the current map snapshot only, so it **does
not** surface keys that have been tombstoned.
+- `forEachAndListen(action)` first runs `forEach` over the current
non-tombstoned entries, then registers the action as a live listener. Every
subsequent update - **including tombstones** - is delivered to the listener as
`action.accept(key, null)`. If you need to react to deletions (for example, to
clean up downstream state), check for `value == null` in your listener.
+
+:::
+
## Register listeners
You can register listeners for both existing messages on a topic and new
messages coming into the topic by using `forEachAndListen`, and specify to
perform operations for all existing messages by using `forEach`.
diff --git a/versioned_docs/version-4.1.x/client-libraries-tableviews.md
b/versioned_docs/version-4.1.x/client-libraries-tableviews.md
index 7a835e30e56..ad790ab3627 100644
--- a/versioned_docs/version-4.1.x/client-libraries-tableviews.md
+++ b/versioned_docs/version-4.1.x/client-libraries-tableviews.md
@@ -69,6 +69,15 @@ You can use the available parameters in the `loadConf`
configuration or the API
</Tabs>
````
+:::note Tombstone (null-value) messages
+
+`TableView` treats a message with a `null` payload as a **tombstone** - the
key is removed from the map.
+
+- `forEach(action)` iterates over the current map snapshot only, so it **does
not** surface keys that have been tombstoned.
+- `forEachAndListen(action)` first runs `forEach` over the current
non-tombstoned entries, then registers the action as a live listener. Every
subsequent update - **including tombstones** - is delivered to the listener as
`action.accept(key, null)`. If you need to react to deletions (for example, to
clean up downstream state), check for `value == null` in your listener.
+
+:::
+
## Register listeners
You can register listeners for both existing messages on a topic and new
messages coming into the topic by using `forEachAndListen`, and specify to
perform operations for all existing messages by using `forEach`.
diff --git a/versioned_docs/version-4.2.x/client-libraries-tableviews.md
b/versioned_docs/version-4.2.x/client-libraries-tableviews.md
index 7a835e30e56..ad790ab3627 100644
--- a/versioned_docs/version-4.2.x/client-libraries-tableviews.md
+++ b/versioned_docs/version-4.2.x/client-libraries-tableviews.md
@@ -69,6 +69,15 @@ You can use the available parameters in the `loadConf`
configuration or the API
</Tabs>
````
+:::note Tombstone (null-value) messages
+
+`TableView` treats a message with a `null` payload as a **tombstone** - the
key is removed from the map.
+
+- `forEach(action)` iterates over the current map snapshot only, so it **does
not** surface keys that have been tombstoned.
+- `forEachAndListen(action)` first runs `forEach` over the current
non-tombstoned entries, then registers the action as a live listener. Every
subsequent update - **including tombstones** - is delivered to the listener as
`action.accept(key, null)`. If you need to react to deletions (for example, to
clean up downstream state), check for `value == null` in your listener.
+
+:::
+
## Register listeners
You can register listeners for both existing messages on a topic and new
messages coming into the topic by using `forEachAndListen`, and specify to
perform operations for all existing messages by using `forEach`.
