Struct AdminBuilder 

pub struct AdminBuilder { /* private fields */ }

Builder for creating and configuring admin clients

Examples

use rocketmq_admin_core::core::admin::AdminBuilder;

// Simple usage
let admin = AdminBuilder::new()
    .namesrv_addr("127.0.0.1:9876")
    .build_and_start()
    .await?;

// With custom configuration
let admin = AdminBuilder::new()
    .namesrv_addr("127.0.0.1:9876;127.0.0.1:9877")
    .instance_name("my-admin-tool")
    .timeout_millis(5000)
    .build_and_start()
    .await?;

Implementations

impl AdminBuilder

pub fn new() -> Self

Create a new builder with default configuration

Examples found in repository

examples/admin_builder_pattern.rs (line 50)

async fn example_builder() -> RocketMQResult<()> {
    println!("\n=== Example 2: Builder Pattern ===");

    let admin = AdminBuilder::new()
        .namesrv_addr("127.0.0.1:9876")
        .instance_name("example-admin")
        .timeout_millis(5000)
        .build_with_guard()
        .await?;

    // Get topic route info
    let route = admin.examine_topic_route_info("TestTopic".into()).await?;

    if let Some(route_data) = route {
        println!("Queue data count: {}", route_data.queue_datas.len());
        println!("Broker data count: {}", route_data.broker_datas.len());
    } else {
        println!("No route data found for TestTopic");
    }

    Ok(())
}

/// Example 3: Multiple NameServers with fallback
async fn example_multiple_namesrv() -> RocketMQResult<()> {
    println!("\n=== Example 3: Multiple NameServers ===");

    // Try primary NameServers
    let result = AdminBuilder::new()
        .namesrv_addr("127.0.0.1:9876;127.0.0.1:9877")
        .build_with_guard()
        .await;

    let _admin = match result {
        Ok(admin) => {
            println!("Connected to primary NameServer");
            admin
        }
        Err(e) => {
            eprintln!("Primary NameServer failed: {e}");
            eprintln!("Falling back to backup...");

            // Fallback to backup
            AdminBuilder::new()
                .namesrv_addr("127.0.0.1:9878")
                .build_with_guard()
                .await?
        }
    };

    println!("Admin client ready");

    Ok(())
}

/// Example 4: Early return with automatic cleanup
async fn example_early_return(topic: &str) -> RocketMQResult<()> {
    println!("\n=== Example 4: Early Return ===");

    let admin = AdminBuilder::new()
        .namesrv_addr("127.0.0.1:9876")
        .build_with_guard()
        .await?;

    // Get topic route
    let route = admin.examine_topic_route_info(topic.into()).await?;

    // Early return if no route data - admin still cleaned up!
    let Some(route_data) = route else {
        println!("Topic '{}' not found, exiting early", topic);
        return Ok(());
    };

    // Early return if no queues - admin still cleaned up!
    if route_data.queue_datas.is_empty() {
        println!("Topic '{}' has no queues, exiting early", topic);
        return Ok(());
    }

    println!("Topic '{}' has {} queues", topic, route_data.queue_datas.len());

    // Process queues...
    for queue in &route_data.queue_datas {
        println!(
            "  Broker: {}, ReadQueueNums: {}, WriteQueueNums: {}",
            queue.broker_name, queue.read_queue_nums, queue.write_queue_nums
        );
    }

    Ok(())
}

/// Example 5: Explicit shutdown for logging
async fn example_explicit_shutdown() -> RocketMQResult<()> {
    println!("\n=== Example 5: Explicit Shutdown ===");

    let admin = AdminBuilder::new()
        .namesrv_addr("127.0.0.1:9876")
        .instance_name("explicit-shutdown-example")
        .build_with_guard()
        .await?;

    // Use admin...
    println!("Admin client started successfully");

    // Explicit shutdown with logging
    println!("Shutting down admin client...");
    admin.shutdown().await;
    println!("Shutdown complete");

    Ok(())
}

/// Example 6: Dynamic configuration from environment
async fn example_from_environment() -> RocketMQResult<()> {
    println!("\n=== Example 6: Environment Configuration ===");

    use std::env;

    // Read from environment with defaults
    let namesrv_addr = env::var("NAMESRV_ADDR").unwrap_or_else(|_| "127.0.0.1:9876".to_string());

    let instance_name = env::var("INSTANCE_NAME").unwrap_or_else(|_| "env-admin".to_string());

    println!("NameServer: {}", namesrv_addr);
    println!("Instance: {}", instance_name);

    let _admin = AdminBuilder::new()
        .namesrv_addr(namesrv_addr)
        .instance_name(instance_name)
        .build_with_guard()
        .await?;

    println!("Admin configured from environment");

    Ok(())
}

/// Example 7: Without RAII (manual cleanup)
async fn example_manual_cleanup() -> RocketMQResult<()> {
    println!("\n=== Example 7: Manual Cleanup ===");

    // Use build_and_start() instead of build_with_guard()
    let mut admin = AdminBuilder::new()
        .namesrv_addr("127.0.0.1:9876")
        .build_and_start() // Returns DefaultMQAdminExt directly
        .await?;

    // Use admin...
    println!("Admin started");

    // Manual shutdown required
    admin.shutdown().await;
    println!("Manually shut down");

    Ok(())
}

pub fn namesrv_addr(self, addr: impl Into<String>) -> Self

Set NameServer address

Supports multiple addresses separated by semicolon:

• Single: "127.0.0.1:9876"
• Multiple: "127.0.0.1:9876;127.0.0.1:9877"

Examples found in repository

examples/admin_builder_pattern.rs (line 51)

async fn example_builder() -> RocketMQResult<()> {
    println!("\n=== Example 2: Builder Pattern ===");

    let admin = AdminBuilder::new()
        .namesrv_addr("127.0.0.1:9876")
        .instance_name("example-admin")
        .timeout_millis(5000)
        .build_with_guard()
        .await?;

    // Get topic route info
    let route = admin.examine_topic_route_info("TestTopic".into()).await?;

    if let Some(route_data) = route {
        println!("Queue data count: {}", route_data.queue_datas.len());
        println!("Broker data count: {}", route_data.broker_datas.len());
    } else {
        println!("No route data found for TestTopic");
    }

    Ok(())
}

/// Example 3: Multiple NameServers with fallback
async fn example_multiple_namesrv() -> RocketMQResult<()> {
    println!("\n=== Example 3: Multiple NameServers ===");

    // Try primary NameServers
    let result = AdminBuilder::new()
        .namesrv_addr("127.0.0.1:9876;127.0.0.1:9877")
        .build_with_guard()
        .await;

    let _admin = match result {
        Ok(admin) => {
            println!("Connected to primary NameServer");
            admin
        }
        Err(e) => {
            eprintln!("Primary NameServer failed: {e}");
            eprintln!("Falling back to backup...");

            // Fallback to backup
            AdminBuilder::new()
                .namesrv_addr("127.0.0.1:9878")
                .build_with_guard()
                .await?
        }
    };

    println!("Admin client ready");

    Ok(())
}

/// Example 4: Early return with automatic cleanup
async fn example_early_return(topic: &str) -> RocketMQResult<()> {
    println!("\n=== Example 4: Early Return ===");

    let admin = AdminBuilder::new()
        .namesrv_addr("127.0.0.1:9876")
        .build_with_guard()
        .await?;

    // Get topic route
    let route = admin.examine_topic_route_info(topic.into()).await?;

    // Early return if no route data - admin still cleaned up!
    let Some(route_data) = route else {
        println!("Topic '{}' not found, exiting early", topic);
        return Ok(());
    };

    // Early return if no queues - admin still cleaned up!
    if route_data.queue_datas.is_empty() {
        println!("Topic '{}' has no queues, exiting early", topic);
        return Ok(());
    }

    println!("Topic '{}' has {} queues", topic, route_data.queue_datas.len());

    // Process queues...
    for queue in &route_data.queue_datas {
        println!(
            "  Broker: {}, ReadQueueNums: {}, WriteQueueNums: {}",
            queue.broker_name, queue.read_queue_nums, queue.write_queue_nums
        );
    }

    Ok(())
}

/// Example 5: Explicit shutdown for logging
async fn example_explicit_shutdown() -> RocketMQResult<()> {
    println!("\n=== Example 5: Explicit Shutdown ===");

    let admin = AdminBuilder::new()
        .namesrv_addr("127.0.0.1:9876")
        .instance_name("explicit-shutdown-example")
        .build_with_guard()
        .await?;

    // Use admin...
    println!("Admin client started successfully");

    // Explicit shutdown with logging
    println!("Shutting down admin client...");
    admin.shutdown().await;
    println!("Shutdown complete");

    Ok(())
}

/// Example 6: Dynamic configuration from environment
async fn example_from_environment() -> RocketMQResult<()> {
    println!("\n=== Example 6: Environment Configuration ===");

    use std::env;

    // Read from environment with defaults
    let namesrv_addr = env::var("NAMESRV_ADDR").unwrap_or_else(|_| "127.0.0.1:9876".to_string());

    let instance_name = env::var("INSTANCE_NAME").unwrap_or_else(|_| "env-admin".to_string());

    println!("NameServer: {}", namesrv_addr);
    println!("Instance: {}", instance_name);

    let _admin = AdminBuilder::new()
        .namesrv_addr(namesrv_addr)
        .instance_name(instance_name)
        .build_with_guard()
        .await?;

    println!("Admin configured from environment");

    Ok(())
}

/// Example 7: Without RAII (manual cleanup)
async fn example_manual_cleanup() -> RocketMQResult<()> {
    println!("\n=== Example 7: Manual Cleanup ===");

    // Use build_and_start() instead of build_with_guard()
    let mut admin = AdminBuilder::new()
        .namesrv_addr("127.0.0.1:9876")
        .build_and_start() // Returns DefaultMQAdminExt directly
        .await?;

    // Use admin...
    println!("Admin started");

    // Manual shutdown required
    admin.shutdown().await;
    println!("Manually shut down");

    Ok(())
}

pub fn instance_name(self, name: impl Into<String>) -> Self

Set custom instance name

If not set, defaults to "tools-{timestamp}"

Examples found in repository

examples/admin_builder_pattern.rs (line 52)

async fn example_builder() -> RocketMQResult<()> {
    println!("\n=== Example 2: Builder Pattern ===");

    let admin = AdminBuilder::new()
        .namesrv_addr("127.0.0.1:9876")
        .instance_name("example-admin")
        .timeout_millis(5000)
        .build_with_guard()
        .await?;

    // Get topic route info
    let route = admin.examine_topic_route_info("TestTopic".into()).await?;

    if let Some(route_data) = route {
        println!("Queue data count: {}", route_data.queue_datas.len());
        println!("Broker data count: {}", route_data.broker_datas.len());
    } else {
        println!("No route data found for TestTopic");
    }

    Ok(())
}

/// Example 3: Multiple NameServers with fallback
async fn example_multiple_namesrv() -> RocketMQResult<()> {
    println!("\n=== Example 3: Multiple NameServers ===");

    // Try primary NameServers
    let result = AdminBuilder::new()
        .namesrv_addr("127.0.0.1:9876;127.0.0.1:9877")
        .build_with_guard()
        .await;

    let _admin = match result {
        Ok(admin) => {
            println!("Connected to primary NameServer");
            admin
        }
        Err(e) => {
            eprintln!("Primary NameServer failed: {e}");
            eprintln!("Falling back to backup...");

            // Fallback to backup
            AdminBuilder::new()
                .namesrv_addr("127.0.0.1:9878")
                .build_with_guard()
                .await?
        }
    };

    println!("Admin client ready");

    Ok(())
}

/// Example 4: Early return with automatic cleanup
async fn example_early_return(topic: &str) -> RocketMQResult<()> {
    println!("\n=== Example 4: Early Return ===");

    let admin = AdminBuilder::new()
        .namesrv_addr("127.0.0.1:9876")
        .build_with_guard()
        .await?;

    // Get topic route
    let route = admin.examine_topic_route_info(topic.into()).await?;

    // Early return if no route data - admin still cleaned up!
    let Some(route_data) = route else {
        println!("Topic '{}' not found, exiting early", topic);
        return Ok(());
    };

    // Early return if no queues - admin still cleaned up!
    if route_data.queue_datas.is_empty() {
        println!("Topic '{}' has no queues, exiting early", topic);
        return Ok(());
    }

    println!("Topic '{}' has {} queues", topic, route_data.queue_datas.len());

    // Process queues...
    for queue in &route_data.queue_datas {
        println!(
            "  Broker: {}, ReadQueueNums: {}, WriteQueueNums: {}",
            queue.broker_name, queue.read_queue_nums, queue.write_queue_nums
        );
    }

    Ok(())
}

/// Example 5: Explicit shutdown for logging
async fn example_explicit_shutdown() -> RocketMQResult<()> {
    println!("\n=== Example 5: Explicit Shutdown ===");

    let admin = AdminBuilder::new()
        .namesrv_addr("127.0.0.1:9876")
        .instance_name("explicit-shutdown-example")
        .build_with_guard()
        .await?;

    // Use admin...
    println!("Admin client started successfully");

    // Explicit shutdown with logging
    println!("Shutting down admin client...");
    admin.shutdown().await;
    println!("Shutdown complete");

    Ok(())
}

/// Example 6: Dynamic configuration from environment
async fn example_from_environment() -> RocketMQResult<()> {
    println!("\n=== Example 6: Environment Configuration ===");

    use std::env;

    // Read from environment with defaults
    let namesrv_addr = env::var("NAMESRV_ADDR").unwrap_or_else(|_| "127.0.0.1:9876".to_string());

    let instance_name = env::var("INSTANCE_NAME").unwrap_or_else(|_| "env-admin".to_string());

    println!("NameServer: {}", namesrv_addr);
    println!("Instance: {}", instance_name);

    let _admin = AdminBuilder::new()
        .namesrv_addr(namesrv_addr)
        .instance_name(instance_name)
        .build_with_guard()
        .await?;

    println!("Admin configured from environment");

    Ok(())
}

pub fn timeout_millis(self, timeout: u64) -> Self

Set timeout in milliseconds

Examples found in repository

examples/admin_builder_pattern.rs (line 53)

async fn example_builder() -> RocketMQResult<()> {
    println!("\n=== Example 2: Builder Pattern ===");

    let admin = AdminBuilder::new()
        .namesrv_addr("127.0.0.1:9876")
        .instance_name("example-admin")
        .timeout_millis(5000)
        .build_with_guard()
        .await?;

    // Get topic route info
    let route = admin.examine_topic_route_info("TestTopic".into()).await?;

    if let Some(route_data) = route {
        println!("Queue data count: {}", route_data.queue_datas.len());
        println!("Broker data count: {}", route_data.broker_datas.len());
    } else {
        println!("No route data found for TestTopic");
    }

    Ok(())
}

pub fn unit_name(self, name: impl Into<String>) -> Self

Set unit name for namespace isolation

pub async fn build_and_start(self) -> RocketMQResult<DefaultMQAdminExt>

Build and start the admin client

This will:

1. Create a new DefaultMQAdminExt instance
2. Apply all configuration
3. Start the client (establish connections)

Errors

Returns error if:

• NameServer address is invalid
• Connection cannot be established
• Network I/O fails

Examples found in repository

examples/admin_builder_pattern.rs (line 192)

async fn example_manual_cleanup() -> RocketMQResult<()> {
    println!("\n=== Example 7: Manual Cleanup ===");

    // Use build_and_start() instead of build_with_guard()
    let mut admin = AdminBuilder::new()
        .namesrv_addr("127.0.0.1:9876")
        .build_and_start() // Returns DefaultMQAdminExt directly
        .await?;

    // Use admin...
    println!("Admin started");

    // Manual shutdown required
    admin.shutdown().await;
    println!("Manually shut down");

    Ok(())
}

pub async fn build_with_guard(self) -> RocketMQResult<AdminGuard>

Build the admin client with RAII auto-cleanup

Returns an AdminGuard that automatically calls shutdown when dropped.

Examples

{
    let admin = AdminBuilder::new()
        .namesrv_addr("127.0.0.1:9876")
        .build_with_guard()
        .await?;

    // Use admin...
    let clusters = TopicService::get_topic_cluster_list(&admin, "MyTopic").await?;
} // admin automatically cleaned up here

Examples found in repository

examples/admin_builder_pattern.rs (line 54)

async fn example_builder() -> RocketMQResult<()> {
    println!("\n=== Example 2: Builder Pattern ===");

    let admin = AdminBuilder::new()
        .namesrv_addr("127.0.0.1:9876")
        .instance_name("example-admin")
        .timeout_millis(5000)
        .build_with_guard()
        .await?;

    // Get topic route info
    let route = admin.examine_topic_route_info("TestTopic".into()).await?;

    if let Some(route_data) = route {
        println!("Queue data count: {}", route_data.queue_datas.len());
        println!("Broker data count: {}", route_data.broker_datas.len());
    } else {
        println!("No route data found for TestTopic");
    }

    Ok(())
}

/// Example 3: Multiple NameServers with fallback
async fn example_multiple_namesrv() -> RocketMQResult<()> {
    println!("\n=== Example 3: Multiple NameServers ===");

    // Try primary NameServers
    let result = AdminBuilder::new()
        .namesrv_addr("127.0.0.1:9876;127.0.0.1:9877")
        .build_with_guard()
        .await;

    let _admin = match result {
        Ok(admin) => {
            println!("Connected to primary NameServer");
            admin
        }
        Err(e) => {
            eprintln!("Primary NameServer failed: {e}");
            eprintln!("Falling back to backup...");

            // Fallback to backup
            AdminBuilder::new()
                .namesrv_addr("127.0.0.1:9878")
                .build_with_guard()
                .await?
        }
    };

    println!("Admin client ready");

    Ok(())
}

/// Example 4: Early return with automatic cleanup
async fn example_early_return(topic: &str) -> RocketMQResult<()> {
    println!("\n=== Example 4: Early Return ===");

    let admin = AdminBuilder::new()
        .namesrv_addr("127.0.0.1:9876")
        .build_with_guard()
        .await?;

    // Get topic route
    let route = admin.examine_topic_route_info(topic.into()).await?;

    // Early return if no route data - admin still cleaned up!
    let Some(route_data) = route else {
        println!("Topic '{}' not found, exiting early", topic);
        return Ok(());
    };

    // Early return if no queues - admin still cleaned up!
    if route_data.queue_datas.is_empty() {
        println!("Topic '{}' has no queues, exiting early", topic);
        return Ok(());
    }

    println!("Topic '{}' has {} queues", topic, route_data.queue_datas.len());

    // Process queues...
    for queue in &route_data.queue_datas {
        println!(
            "  Broker: {}, ReadQueueNums: {}, WriteQueueNums: {}",
            queue.broker_name, queue.read_queue_nums, queue.write_queue_nums
        );
    }

    Ok(())
}

/// Example 5: Explicit shutdown for logging
async fn example_explicit_shutdown() -> RocketMQResult<()> {
    println!("\n=== Example 5: Explicit Shutdown ===");

    let admin = AdminBuilder::new()
        .namesrv_addr("127.0.0.1:9876")
        .instance_name("explicit-shutdown-example")
        .build_with_guard()
        .await?;

    // Use admin...
    println!("Admin client started successfully");

    // Explicit shutdown with logging
    println!("Shutting down admin client...");
    admin.shutdown().await;
    println!("Shutdown complete");

    Ok(())
}

/// Example 6: Dynamic configuration from environment
async fn example_from_environment() -> RocketMQResult<()> {
    println!("\n=== Example 6: Environment Configuration ===");

    use std::env;

    // Read from environment with defaults
    let namesrv_addr = env::var("NAMESRV_ADDR").unwrap_or_else(|_| "127.0.0.1:9876".to_string());

    let instance_name = env::var("INSTANCE_NAME").unwrap_or_else(|_| "env-admin".to_string());

    println!("NameServer: {}", namesrv_addr);
    println!("Instance: {}", instance_name);

    let _admin = AdminBuilder::new()
        .namesrv_addr(namesrv_addr)
        .instance_name(instance_name)
        .build_with_guard()
        .await?;

    println!("Admin configured from environment");

    Ok(())
}

Trait Implementations

impl Clone for AdminBuilder

fn clone(&self) -> AdminBuilder

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for AdminBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for AdminBuilder

fn default() -> AdminBuilder

Returns the “default value” for a type.