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

[Pruthvirajj240]

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

• Builds locally:
  ./gradlew :pulsar-client-admin-api:compileJava :pulsar-client-admin-original:compileJava :pulsar-client-admin-original:compileTestJava
• 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)
• 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

• 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