[Improve] Pulsar Admin: support custom `messagePosition` parameter in `Topics.peekMessages` Java client API
- Dominant language
- Java
- Stars
- 15.3k
- Forks
- 3.8k
- Avg merge
- 1d 14h
- Merged PRs (30d)
- 160
Description
### Search before asking
- [X] I searched in the [issues](https://github.com/apache/pulsar/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:
```java
List> 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: https://github.com/apache/pulsar/pull/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?
- [X] I'm willing to submit a PR! (PR #25911 already submitted)
Contributor guide
Research direction
Start with the existing Java admin client Topics.peekMessages and peekMessagesAsync APIs, then read PIP-482 for the compatibility requirements and compare the already-submitted PR #25911. Done means the new messagePosition form is supported while pre-existing overloads remain compatible.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- api
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 25/100