[Improve] Pulsar Admin: support custom `messagePosition` parameter in `Topics.peekMessages` Java client API

[Pruthvirajj240]

Search before asking

• I searched in the issues and found nothing similar.

Motivation

The Pulsar admin REST endpoint
/admin/v3/persistent/{tenant}/{namespace}/{topic}/subscription/{subName}/position/{messagePosition}
accepts an arbitrary message position. The Java admin client (Topics.peekMessages and peekMessagesAsync) currently hardcodes position 1, so callers can only peek from the head of the backlog.

The common use case affected is paginated display in admin UIs — to show the 91st–100th unacknowledged messages, callers have to fetch and discard the first 90, which is wasteful in bandwidth, memory, and time on both client and broker.

Solution

Add a messagePosition parameter to Topics.peekMessages and Topics.peekMessagesAsync in the Java admin client.

The new primary method signature:

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

All pre-existing peek overloads become default methods delegating to this primary, preserving source and binary compatibility.

Full design and compatibility analysis is captured in PIP-482:

• PIP markdown: https://github.com/Pruthvirajj240/pulsar/blob/pip-482-peek-messageposition/pip/pip-482.md
• Pull request: [improve][admin] PIP-482: Peek messages from topic subscription with messagePosition #25911

Alternatives

Two alternatives considered and discussed in the PIP under "Alternatives Considered":

• MessageId-based peek — more powerful but requires server-side changes; deferred to a future PIP.
• PeekOptions builder — more extensible but a larger API redesign; deferred to a future PIP.

Anything else?

No response

Are you willing to submit a PR?

• I'm willing to submit a PR! (PR [improve][admin] PIP-482: Peek messages from topic subscription with messagePosition #25911 already submitted)