apache / apache/pulsar

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

Open
#25,983 2 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.