Pruthvirajj240 opened a new pull request, #25911:
URL: https://github.com/apache/pulsar/pull/25911
### Motivation
Adds a `messagePosition` parameter to the Java admin client
`Topics.peekMessages` /
`peekMessagesAsync` API, enabling efficient pagination through a
subscription backlog without
fetching all preceding messages.
The underlying REST endpoint
`/admin/v3/persistent/{tenant}/{namespace}/{topic}/subscription/{subName}/position/{N}`
already accepts an arbitrary message position. The Java admin client has
historically
hardcoded `1`, so callers could only inspect the head of the backlog. The
most common use
case affected by this gap is UI pagination — to display the 91st–100th
messages on a backlog
page, a caller has to fetch and discard the first 90.
PIP-482 surfaces the existing server capability at the Java client level.
### Modifications
- **`pip/pip-482.md` (new)** — formal proposal document with motivation,
full API surface,
alternatives considered (`MessageId`-based, `PeekOptions` builder), and
binary-compatibility
analysis.
- **`pulsar-client-admin-api/.../Topics.java`** — adds the primary abstract
method
`peekMessages(topic, subName, messagePosition, numMessages,
showServerMarker, isolation)`
and its async variant. All pre-existing peek overloads become `default`
methods that
delegate to it, giving the interface a single source of Javadoc.
- **`pulsar-client-admin/.../internal/TopicsImpl.java`** — implements the
new primary abstract
method. The internal recursive helper already took the position as
`nthMessage` — the change
is to pass the caller-supplied `messagePosition` instead of hardcoded `1`.
Adds
`checkArgument(messagePosition >= 1)` for client-side validation.
- **`pulsar-client-admin/.../TopicsInterfaceDefaultsTest.java` (new)** —
unit tests covering
delegation of all six `peekMessages` / `peekMessagesAsync` overloads to
the primary abstract
method, with expected `messagePosition` and parameter forwarding asserted
via Mockito
`CALLS_REAL_METHODS`.
### Verifying this change
- [x] Builds locally:
`./gradlew :pulsar-client-admin-api:compileJava
:pulsar-client-admin-original:compileJava
:pulsar-client-admin-original:compileTestJava`
- [x] Unit tests pass:
`./gradlew :pulsar-client-admin-original:test --tests
"org.apache.pulsar.client.admin.TopicsInterfaceDefaultsTest"`
→ 6 tests, 0 failures, 0 errors
- [ ] Manual integration test against a local broker: produce 100 messages,
peek with
`messagePosition=91, numMessages=10`, verify the returned messages
match positions 91–100.
_(Reviewer note: I will add a broker integration test in a follow-up
if requested. The
change is fundamentally a client-side surface change — the REST
endpoint already supports
arbitrary positions and is exercised by existing broker tests.)_
**Note on test location:** The new unit test lives in
`pulsar-client-admin/src/test/` (not
`pulsar-client-admin-api/src/test/`) because the latter has no existing test
infrastructure
configured. The test still covers the `Topics` interface defaults (from the
api module) — it
runs in the admin module's test classpath where Mockito and TestNG are wired
up via the
convention plugin (`pulsar.public-java-library-conventions`).
### Does this pull request potentially affect one of the following parts:
If the box was checked, please highlight the changes:
- [ ] Dependencies (add or upgrade a dependency)
- [x] **The public API** — see PIP-482 for the full surface change and
compatibility analysis.
- [ ] The schema
- [ ] The default values of configurations
- [ ] The threading model
- [ ] The binary protocol
- [ ] The REST endpoints
- [ ] The admin CLI options
- [ ] The metrics
- [ ] Anything that affects deployment
The change extends the public Java admin client API with one new abstract
method per sync/async
variant and four new default-method overloads. All pre-existing call sites
remain source- and
behavior-compatible. See PIP-482 "Backward & Forward Compatibility" for full
analysis.
### Documentation
- [x] `doc-required`
Documentation update will follow as a separate PR to `apache/pulsar-site`
once this lands.
- [ ] `doc-not-needed`
- [ ] `doc`
- [ ] `doc-complete`
### Matching PR in forked repository
PR in forked repository: _to be filled after the fork branch is pushed_
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
