Package org.apache.pulsar.client.admin

Interface ScalableTopics

public interface ScalableTopics
Admin interface for scalable topic management.

Scalable topics (topic:// domain) are composed of a DAG of hash-range segments that can be dynamically split and merged.

  • Method Details

    • listScalableTopics

      List<String> listScalableTopics(String namespace) throws PulsarAdminException
      Get the list of scalable topics under a namespace.
      Parameters:
      namespace - Namespace name in the format "tenant/namespace"
      Returns:
      list of scalable topic names
      Throws:
      PulsarAdminException

    • listScalableTopicsAsync

      CompletableFuture<List<String>> listScalableTopicsAsync(String namespace)
      Get the list of scalable topics under a namespace asynchronously.
      Parameters:
      namespace - Namespace name in the format "tenant/namespace"
      Returns:
      list of scalable topic names

    • listScalableTopicsByProperties

      List<String> listScalableTopicsByProperties(String namespace, Map<String,String> propertyFilters) throws PulsarAdminException
      Get the list of scalable topics under a namespace whose properties contain every key/value pair in propertyFilters (AND semantics).

      Backed by the secondary index registered on the topic properties at create/update time. On stores with native index support the lookup uses one filter to narrow the candidate set and verifies the rest on the loaded record; stores without index support fall back to a per-record check.

      Parameters:
      namespace - Namespace name in the format "tenant/namespace"
      propertyFilters - Property names and exact values that all must match
      Returns:
      list of matching scalable topic names; an empty filter returns the full namespace listing
      Throws:
      PulsarAdminException

    • listScalableTopicsByPropertiesAsync

      CompletableFuture<List<String>> listScalableTopicsByPropertiesAsync(String namespace, Map<String,String> propertyFilters)
      Async variant of listScalableTopicsByProperties(String, Map).

    • createScalableTopic

      void createScalableTopic(String topic, int numInitialSegments) throws PulsarAdminException
      Create a new scalable topic.
      Parameters:
      topic - Topic name in the format "tenant/namespace/topic"
      numInitialSegments - Number of initial segments (must be >= 1)
      Throws:
      PulsarAdminException

    • createScalableTopicAsync

      CompletableFuture<Void> createScalableTopicAsync(String topic, int numInitialSegments)
      Create a new scalable topic asynchronously.
      Parameters:
      topic - Topic name in the format "tenant/namespace/topic"
      numInitialSegments - Number of initial segments (must be >= 1)

    • createScalableTopic

      void createScalableTopic(String topic, int numInitialSegments, Map<String,String> properties) throws PulsarAdminException
      Create a new scalable topic with properties.
      Parameters:
      topic - Topic name in the format "tenant/namespace/topic"
      numInitialSegments - Number of initial segments (must be >= 1)
      properties - Key-value properties for the topic metadata
      Throws:
      PulsarAdminException

    • createScalableTopicAsync

      CompletableFuture<Void> createScalableTopicAsync(String topic, int numInitialSegments, Map<String,String> properties)
      Create a new scalable topic with properties asynchronously.
      Parameters:
      topic - Topic name in the format "tenant/namespace/topic"
      numInitialSegments - Number of initial segments (must be >= 1)
      properties - Key-value properties for the topic metadata

    • migrateToScalable

      void migrateToScalable(String topic, boolean force) throws PulsarAdminException
      Migrate an existing regular (partitioned or non-partitioned) topic to a scalable topic.

      The old partitions become sealed parent segments of the new scalable topic and the old topics are terminated; new active segments take over. Fails if the topic is already scalable, if it doesn't exist, or if any legacy v4 client is still connected (unless force is set).

      Parameters:
      topic - Topic name in the format "tenant/namespace/topic"
      force - Migrate even if legacy v4 clients are still connected
      Throws:
      PulsarAdminException

    • migrateToScalableAsync

      CompletableFuture<Void> migrateToScalableAsync(String topic, boolean force)
      Migrate an existing regular topic to a scalable topic asynchronously.
      Parameters:
      topic - Topic name in the format "tenant/namespace/topic"
      force - Migrate even if legacy v4 clients are still connected

    • getMetadata

      ScalableTopicMetadata getMetadata(String topic) throws PulsarAdminException
      Get scalable topic metadata.
      Parameters:
      topic - Topic name in the format "tenant/namespace/topic"
      Returns:
      the scalable topic metadata including segment DAG
      Throws:
      PulsarAdminException

    • getMetadataAsync

      CompletableFuture<ScalableTopicMetadata> getMetadataAsync(String topic)
      Get scalable topic metadata asynchronously.
      Parameters:
      topic - Topic name in the format "tenant/namespace/topic"
      Returns:
      the scalable topic metadata including segment DAG

    • setAutoScalePolicy

      void setAutoScalePolicy(String topic, AutoScalePolicyOverride override) throws PulsarAdminException
      Set the per-topic auto split/merge policy override (PIP-483). Overrides the namespace policy and the broker defaults for this topic; unset fields fall through.
      Parameters:
      topic - Topic name in the format "tenant/namespace/topic"
      override - the override to apply
      Throws:
      PulsarAdminException

    • setAutoScalePolicyAsync

      CompletableFuture<Void> setAutoScalePolicyAsync(String topic, AutoScalePolicyOverride override)
      Set the per-topic auto split/merge policy override asynchronously.
      Parameters:
      topic - Topic name in the format "tenant/namespace/topic"
      override - the override to apply

    • getAutoScalePolicy

      AutoScalePolicyOverride getAutoScalePolicy(String topic) throws PulsarAdminException
      Get the per-topic auto split/merge policy override.
      Parameters:
      topic - Topic name in the format "tenant/namespace/topic"
      Returns:
      the override, or null if none is set
      Throws:
      PulsarAdminException

    • getAutoScalePolicyAsync

      CompletableFuture<AutoScalePolicyOverride> getAutoScalePolicyAsync(String topic)
      Get the per-topic auto split/merge policy override asynchronously.
      Parameters:
      topic - Topic name in the format "tenant/namespace/topic"
      Returns:
      the override, or null if none is set

    • removeAutoScalePolicy

      void removeAutoScalePolicy(String topic) throws PulsarAdminException
      Remove the per-topic auto split/merge policy override, letting the namespace policy and broker defaults apply.
      Parameters:
      topic - Topic name in the format "tenant/namespace/topic"
      Throws:
      PulsarAdminException

    • removeAutoScalePolicyAsync

      CompletableFuture<Void> removeAutoScalePolicyAsync(String topic)
      Remove the per-topic auto split/merge policy override asynchronously.
      Parameters:
      topic - Topic name in the format "tenant/namespace/topic"

    • deleteScalableTopic

      void deleteScalableTopic(String topic, boolean force) throws PulsarAdminException
      Delete a scalable topic and all its underlying segment topics.
      Parameters:
      topic - Topic name in the format "tenant/namespace/topic"
      force - Force deletion even if topic has active subscriptions
      Throws:
      PulsarAdminException

    • deleteScalableTopicAsync

      CompletableFuture<Void> deleteScalableTopicAsync(String topic, boolean force)
      Delete a scalable topic and all its underlying segment topics asynchronously.
      Parameters:
      topic - Topic name in the format "tenant/namespace/topic"
      force - Force deletion even if topic has active subscriptions

    • deleteScalableTopic

      default void deleteScalableTopic(String topic) throws PulsarAdminException
      Delete a scalable topic and all its underlying segment topics.
      Parameters:
      topic - Topic name in the format "tenant/namespace/topic"
      Throws:
      PulsarAdminException

    • deleteScalableTopicAsync

      default CompletableFuture<Void> deleteScalableTopicAsync(String topic)
      Delete a scalable topic and all its underlying segment topics asynchronously.
      Parameters:
      topic - Topic name in the format "tenant/namespace/topic"

    • getStats

      ScalableTopicStats getStats(String topic) throws PulsarAdminException
      Get aggregated stats for a scalable topic.
      Parameters:
      topic - Topic name in the format "tenant/namespace/topic"
      Returns:
      stats including segment counts, per-segment layout info, and per-subscription consumer counts
      Throws:
      PulsarAdminException

    • getStatsAsync

      CompletableFuture<ScalableTopicStats> getStatsAsync(String topic)
      Get aggregated stats for a scalable topic asynchronously.

    • createSubscription

      void createSubscription(String topic, String subscription, ScalableSubscriptionType type) throws PulsarAdminException
      Create a subscription on a scalable topic. The controller leader propagates the subscription to all active segment topics.
      Parameters:
      topic - Topic name in the format "tenant/namespace/topic"
      subscription - Name of the subscription to create
      type - Subscription type: ScalableSubscriptionType.STREAM for controller-managed ordered subscriptions, or ScalableSubscriptionType.QUEUE for unordered per-segment fan-out.
      Throws:
      PulsarAdminException

    • createSubscriptionAsync

      CompletableFuture<Void> createSubscriptionAsync(String topic, String subscription, ScalableSubscriptionType type)
      Create a subscription on a scalable topic asynchronously.

    • deleteSubscription

      void deleteSubscription(String topic, String subscription) throws PulsarAdminException
      Delete a subscription from a scalable topic. Unregisters all consumers and removes the subscription from every segment topic.
      Parameters:
      topic - Topic name in the format "tenant/namespace/topic"
      subscription - Name of the subscription to delete
      Throws:
      PulsarAdminException

    • deleteSubscriptionAsync

      CompletableFuture<Void> deleteSubscriptionAsync(String topic, String subscription)
      Delete a subscription from a scalable topic asynchronously.

    • seekSubscription

      void seekSubscription(String topic, String subscription, long timestampMs) throws PulsarAdminException
      Reset a subscription's cursor across every segment to the given wall-clock timestamp. The controller uses each segment's recorded sealed-time window to dispatch the cheapest per-segment op.
      Parameters:
      topic - Topic name in the format "tenant/namespace/topic"
      subscription - Subscription name
      timestampMs - Wall-clock millis since the unix epoch
      Throws:
      PulsarAdminException

    • seekSubscriptionAsync

      CompletableFuture<Void> seekSubscriptionAsync(String topic, String subscription, long timestampMs)
      Reset a subscription's cursor across every segment, asynchronously.

    • clearBacklog

      void clearBacklog(String topic, String subscription) throws PulsarAdminException
      Skip every undelivered message on the subscription, across every segment in the DAG (advance each per-segment cursor to the end).
      Parameters:
      topic - Topic name in the format "tenant/namespace/topic"
      subscription - Subscription name
      Throws:
      PulsarAdminException

    • clearBacklogAsync

      CompletableFuture<Void> clearBacklogAsync(String topic, String subscription)
      Skip every undelivered message on the subscription, asynchronously.

    • splitSegment

      void splitSegment(String topic, long segmentId) throws PulsarAdminException
      Split a segment into two halves.
      Parameters:
      topic - Topic name in the format "tenant/namespace/topic"
      segmentId - ID of the segment to split
      Throws:
      PulsarAdminException

    • splitSegmentAsync

      CompletableFuture<Void> splitSegmentAsync(String topic, long segmentId)
      Split a segment into two halves asynchronously.
      Parameters:
      topic - Topic name in the format "tenant/namespace/topic"
      segmentId - ID of the segment to split

    • mergeSegments

      void mergeSegments(String topic, long segmentId1, long segmentId2) throws PulsarAdminException
      Merge two adjacent segments into one.
      Parameters:
      topic - Topic name in the format "tenant/namespace/topic"
      segmentId1 - First segment ID to merge
      segmentId2 - Second segment ID to merge
      Throws:
      PulsarAdminException

    • mergeSegmentsAsync

      CompletableFuture<Void> mergeSegmentsAsync(String topic, long segmentId1, long segmentId2)
      Merge two adjacent segments into one asynchronously.
      Parameters:
      topic - Topic name in the format "tenant/namespace/topic"
      segmentId1 - First segment ID to merge
      segmentId2 - Second segment ID to merge

    • createSegment

      void createSegment(String segmentTopic, List<String> subscriptions) throws PulsarAdminException
      Create a segment topic on the broker that owns its namespace bundle. Optionally creates subscriptions on the new segment.
      Parameters:
      segmentTopic - Full segment topic name (segment://tenant/namespace/topic/descriptor)
      subscriptions - Optional list of subscription names to create at earliest position
      Throws:
      PulsarAdminException

    • createSegmentAsync

      CompletableFuture<Void> createSegmentAsync(String segmentTopic, List<String> subscriptions)
      Create a segment topic asynchronously.

    • terminateSegment

      void terminateSegment(String segmentTopic) throws PulsarAdminException
      Terminate a segment topic so that no more messages can be published to it.
      Parameters:
      segmentTopic - Full segment topic name (segment://tenant/namespace/topic/descriptor)
      Throws:
      PulsarAdminException

    • terminateSegmentAsync

      CompletableFuture<Void> terminateSegmentAsync(String segmentTopic)
      Terminate a segment topic asynchronously.

    • deleteSegment

      void deleteSegment(String segmentTopic, boolean force) throws PulsarAdminException
      Delete a segment topic.
      Parameters:
      segmentTopic - Full segment topic name (segment://tenant/namespace/topic/descriptor)
      force - Force deletion even if topic has active producers/subscriptions
      Throws:
      PulsarAdminException

    • deleteSegmentAsync

      CompletableFuture<Void> deleteSegmentAsync(String segmentTopic, boolean force)
      Delete a segment topic asynchronously.

    • createSegmentSubscriptionAsync

      CompletableFuture<Void> createSegmentSubscriptionAsync(String segmentTopic, String subscription)
      Create a subscription cursor on the given segment topic at the earliest position. The call routes to the broker that owns the segment.

      Used internally by

      invalid reference 
      ScalableTopicController
      to fan a new scalable-topic subscription out across every active segment so a future consumer doesn't drop the backlog.
      Parameters:
      segmentTopic - Full segment topic name (segment://tenant/namespace/topic/descriptor)
      subscription - Subscription name

    • deleteSegmentSubscriptionAsync

      CompletableFuture<Void> deleteSegmentSubscriptionAsync(String segmentTopic, String subscription)
      Delete a subscription cursor on the given segment topic. The call routes to the broker that owns the segment.

      Used internally by

      invalid reference 
      ScalableTopicController
      when a scalable-topic subscription is deleted, so no orphan cursors remain on any segment in the DAG.
      Parameters:
      segmentTopic - Full segment topic name (segment://tenant/namespace/topic/descriptor)
      subscription - Subscription name

    • getSegmentSubscriptionBacklogAsync

      CompletableFuture<Long> getSegmentSubscriptionBacklogAsync(String segmentTopic, String subscription)
      Returns the number of unconsumed entries in the given subscription's cursor on the segment topic — i.e. the per-subscription backlog. The call routes to the broker that owns the segment topic, so it works whether the caller is colocated with the segment or not.

      Used internally by the

      invalid reference 
      SubscriptionCoordinator
      to detect when a sealed parent has been drained and its children can be unblocked. Callers can also use it for diagnostics; a returned 0 on a sealed segment indicates the subscription has nothing left to consume there.
      Parameters:
      segmentTopic - Full segment topic name (segment://tenant/namespace/topic/descriptor)
      subscription - Subscription name

    • seekSegmentSubscriptionAsync

      CompletableFuture<Void> seekSegmentSubscriptionAsync(String segmentTopic, String subscription, long timestampMs)
      Reset the segment topic's subscription cursor to the given wall-clock timestamp. Routes to the broker that owns the segment topic.

      Used internally by the parent-topic seek operation in

      invalid reference 
      ScalableTopicController
      : the controller classifies each segment by its [createdAtMs, sealedAtMs) window against the requested timestamp and dispatches per-segment seek / skip-all calls.
      Parameters:
      segmentTopic - Full segment topic name (segment://tenant/namespace/topic/descriptor)
      subscription - Subscription name
      timestampMs - Wall-clock millis since the unix epoch

    • clearSegmentSubscriptionBacklogAsync

      CompletableFuture<Void> clearSegmentSubscriptionBacklogAsync(String segmentTopic, String subscription)
      Skip every undelivered message on the segment topic's subscription — advance the cursor to the end of the segment.
      Parameters:
      segmentTopic - Full segment topic name (segment://tenant/namespace/topic/descriptor)
      subscription - Subscription name