[DISCUSS] PIP-482: Peek messages from topic subscription with messagePosition

[Pruthviraj Chandru <pr...@boomi.com>]

Hi all,

I'd like to propose PIP-482, which adds a messagePosition parameter to the
Java admin client's Topics.peekMessages and peekMessagesAsync methods.

The underlying REST endpoint:

/admin/v3/persistent/{tenant}/{namespace}/{topic}/subscription/{subName}/position/{N}

already accepts an arbitrary message position. The current Java admin
client hardcodes 1, so callers can only peek from the head of the backlog.

The most common use case affected is paginated display in admin UIs. To
show the 91st–100th unacknowledged messages, callers currently have to
fetch and discard the first 90.

This PIP surfaces the existing server capability at the Java client level.

API surface (summary)

The new primary abstract method:

List<Message<byte[]>> peekMessages(
    String topic,
    String subName,
    int messagePosition,
    int numMessages,
    boolean showServerMarker,
    TransactionIsolationLevel transactionIsolationLevel)
    throws PulsarAdminException;

All pre-existing peekMessages overloads become default methods that
delegate to this primary method, giving the interface a single source of
Javadoc.

Compatibility

This change is source- and behavior-compatible for all existing call sites.
The pre-existing 5-argument abstract peekMessages(..., numMessages,
showServerMarker, isolation) method becomes a default method, which is
binary-compatible according to the Java Language Specification.

References

Pull request:
https://github.com/apache/pulsar/pull/25911

PIP markdown:
https://github.com/Pruthvirajj240/pulsar/blob/pip-482-peek-messageposition/pip/pip-482.md

Looking forward to feedback on the API shape, parameter naming, and
backward-compatibility approach.

Thanks,

Pruthviraj

Re: [DISCUSS] PIP-482: Peek messages from topic subscription with messagePosition

[Pruthviraj Chandru <pr...@boomi.com>]

Hi all,

An update on PIP-482, and a request for review so it can move toward a vote.

Based on review feedback, I've revised the API approach from my original
email:

  - Original proposal: make the position-aware 6-arg peekMessages(...,
messagePosition, ...) the new abstract method, and demote the existing
overloads to default.
  - Revised proposal: leave the existing peekMessages(..., numMessages,
showServerMarker, isolation) abstract method (and its async form)
unchanged, and add the position-aware capability as a new default overload.

Why: the revised approach adds, changes, and removes no abstract method, so
it's strictly additive and fully source- and binary-compatible — existing
Topics implementors and mocks are unaffected. The new default delegates to
the existing method when messagePosition == 1 (identical head-of-backlog
behavior) and throws UnsupportedOperationException otherwise; the in-tree
TopicsImpl overrides it to support arbitrary positions. I've also added an
end-to-end test that peeks page 1 then page 2 and asserts the second call
starts at the requested offset without re-reading the first page.

New API surface (the additive overload):

default List<Message<byte[]>> peekMessages(
String topic, String subName, int messagePosition, int numMessages,
boolean showServerMarker, TransactionIsolationLevel
transactionIsolationLevel)
throws PulsarAdminException;

The parameter is named messagePosition and typed int to mirror the REST
path param (.../position/{messagePosition}); happy to switch to a dedicated
type if preferred.

PIP:
https://github.com/Pruthvirajj240/pulsar/blob/pip-482-peek-messageposition/pip/pip-482.md
PR: https://github.com/apache/pulsar/pull/25911

I'd appreciate a review — particularly from a PMC member — so this can
proceed to a [VOTE]. Happy to address any concerns on the API shape,
naming, or compatibility.

Thanks,
Pruthviraj

Re: [DISCUSS] PIP-482: Peek messages from topic subscription with messagePosition

[Pruthviraj Chandru <pr...@boomi.com>]

  Bumping this for visibility — happy to address any concerns
  about the API shape, parameter naming, or compatibility approach.

  If anyone has time to take a look at the PR
  (https://github.com/apache/pulsar/pull/25911), feedback would
  be much appreciated.

  Thanks,
  Pruthviraj

On Mon, Jun 1, 2026 at 12:41 PM Pruthviraj Chandru
<pr...@boomi.com> wrote:
>
> Hi all,
>
> I'd like to propose PIP-482, which adds a messagePosition parameter to the Java admin client's Topics.peekMessages and peekMessagesAsync methods.
>
> The underlying REST endpoint:
>
> /admin/v3/persistent/{tenant}/{namespace}/{topic}/subscription/{subName}/position/{N}
>
> already accepts an arbitrary message position. The current Java admin client hardcodes 1, so callers can only peek from the head of the backlog.
>
> The most common use case affected is paginated display in admin UIs. To show the 91st–100th unacknowledged messages, callers currently have to fetch and discard the first 90.
>
> This PIP surfaces the existing server capability at the Java client level.
>
> API surface (summary)
>
> The new primary abstract method:
>
> List<Message<byte[]>> peekMessages(
>     String topic,
>     String subName,
>     int messagePosition,
>     int numMessages,
>     boolean showServerMarker,
>     TransactionIsolationLevel transactionIsolationLevel)
>     throws PulsarAdminException;
>
> All pre-existing peekMessages overloads become default methods that delegate to this primary method, giving the interface a single source of Javadoc.
>
> Compatibility
>
> This change is source- and behavior-compatible for all existing call sites. The pre-existing 5-argument abstract peekMessages(..., numMessages, showServerMarker, isolation) method becomes a default method, which is binary-compatible according to the Java Language Specification.
>
> References
>
> Pull request:
> https://github.com/apache/pulsar/pull/25911
>
> PIP markdown:
> https://github.com/Pruthvirajj240/pulsar/blob/pip-482-peek-messageposition/pip/pip-482.md
>
> Looking forward to feedback on the API shape, parameter naming, and backward-compatibility approach.
>
> Thanks,
>
> Pruthviraj