You don't have to copy so much code here, which does not focus on the key change. The only thing that matters is that what will replace the following existing code:

                        return getBrokerService().pulsar().getNamespaceService()
                                .getListOfUserTopics(namespaceName, mode)

Simplified pseudocode

This design is a bit over-abstraction. IMO, the following design could be simpler and clearer.

public record TopicListingResult(List<String> topics, boolean filtered) {}

    /**
     * @return the future of the result, if it's empty, fall back to the built-in implementation to list all topics
     */
    default CompletableFuture<Optional<TopicListingResult>> interceptGetTopicsOfNamespace(

Since the built-in implementation is very simple that calls method directly on the NamespaceService, I think the fallback logic is unnecessary.

Since we allow the configuration of multiple interceptors, the return here means that the result of current interception is not processed this method. If all the interceptors do not process the method, the default logic will be used.

In addition, the interception configuration is empty by default. In this case, we still need to fall back to the default logic.

default CompletableFuture<Optional<TopicListingResult>> interceptGetTopicsOfNamespace()

Applied this suggestion

Spelling/grammar: The sentence ends with "list all topic" but should be "list all topics" (plural).

Inconsistent quote style: The CLI example uses a double quote at the end but no opening quote. Either remove the trailing quote or add both opening and closing quotes around the entire command for consistency.

Incorrect Javadoc reference syntax: The Javadoc reference {@code Optional#empty} should be {@code Optional.empty()} or {@link Optional#empty()} to follow proper Javadoc conventions. The hash symbol is correct for linking to methods, but when using @code, it should show the actual method call syntax with parentheses, or use @link for proper cross-referencing.

Inconsistent wrapping behavior: The code shows wrapping the default namespace service result in TopicListingResult(topics, false) at line 152, but the interceptor is expected to return Optional<TopicListingResult>. The logic then unwraps this at line 144-154, but the code flow shows that line 152 returns a TopicListingResult directly, not wrapped in an Optional. This should return Optional.of(new TopicListingResult(topics, false)) to maintain type consistency.

Type inconsistency in chain: The return type handling is problematic. Line 142 shows interceptorFuture.thenCompose(interceptorResult -> {...}) where interceptorResult is of type Optional<TopicListingResult>. Lines 146 and 152 appear to return different types - line 146 returns CompletableFuture.completedFuture(interceptorResult) (a CompletableFuture<Optional<TopicListingResult>>), while line 152 returns a TopicListingResult directly without Optional wrapping. Then line 154 expects listingResult to be a TopicListingResult. This type chain is broken and needs to be fixed.

Grammar issue: The parenthetical remark should be clearer. Consider revising to "These properties may be related to topic properties" or better yet, clarify what type of properties are being referenced and their relationship to topic properties.

Missing import statement: The code snippet references Map interface but doesn't include the required import statement. Add import java.util.Map; to the imports section.

Missing method accessor: The code calls listingResult.getTopics(), but TopicListingResult is defined as a Java record with a field named topics (line 73). For Java records, the accessor method should be topics() not getTopics().

Missing method accessor: The code calls listingResult.isFiltered(), but TopicListingResult is defined as a Java record with a field named filtered (line 73). For Java records, the accessor method should be filtered() not isFiltered(). Note that for boolean fields in records, the accessor is simply the field name, not prefixed with 'is' or 'get'.

Unclear API design: The REST API format shows properties=k1=v1,k2=v2 at line 54, but it's not clear how this query parameter should be parsed. Is it a single parameter with comma-separated key-value pairs, or multiple parameters? The CLI example at line 59 shows -p k1=v1 -p k2=v2 which suggests multiple parameters. The REST API documentation should clarify the expected format and whether URL encoding is required for values.