Enhance PulsarResourcesExtended interface with detailed documentation and flexible topic listing method

Author: coderzc

pip/pip-452.md

@@ -100,11 +100,24 @@ import org.apache.pulsar.common.api.proto.CommandGetTopicsOfNamespace;
 import org.apache.pulsar.common.naming.NamespaceName;
 import org.jspecify.annotations.Nullable;
 
+/**
+ * Extended PulsarResources that provides additional functionality beyond PulsarResources.
+ *
+ * <p>This interface is designed to be pluggable, allowing custom implementations
+ * to provide extended PulsarResources capabilities such as custom topic listing strategies</p>
+ *
+ * <p>Implementations of this interface can be registered with PulsarService to
+ * provide extended resource management capabilities.</p>
+ */
+@InterfaceStability.Evolving
 public interface PulsarResourcesExtended {
 
     /**
      * Lists topics in a namespace with optional property-based filtering.
      *
+     * <p>This method provides a flexible way to list topics in a namespace,
+     * supporting property-based filtering through the properties parameter.</p>
+     *
      * @param namespaceName the namespace to list topics from
      * @param mode the listing mode (ALL, PERSISTENT, NON_PERSISTENT)
      * @param properties optional property filters for topic listing
@@ -116,9 +129,14 @@ public interface PulsarResourcesExtended {
 
     /**
      * Initializes this extended resources instance with the PulsarService.
+     *
+     * <p>This method is called during broker startup to provide the implementation
+     * with access to the PulsarService and its dependencies.</p>
+     *
+     * @param pulsarService the PulsarService instance
      */
     void initialize(PulsarService pulsarService);
-    
+
     /**
      * Closes this extended resources instance and releases any resources.
      *