org.apache.pulsar.client.admin.Brokers Maven / Gradle / Ivy
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package org.apache.pulsar.client.admin;
import java.util.List;
import java.util.Map;
import java.util.concurrent.CompletableFuture;
import org.apache.pulsar.client.admin.PulsarAdminException.NotAuthorizedException;
import org.apache.pulsar.client.admin.PulsarAdminException.NotFoundException;
import org.apache.pulsar.common.conf.InternalConfigurationData;
import org.apache.pulsar.common.naming.TopicVersion;
import org.apache.pulsar.common.policies.data.BrokerInfo;
import org.apache.pulsar.common.policies.data.NamespaceOwnershipStatus;
/**
* Admin interface for brokers management.
*/
public interface Brokers {
/**
* Get the list of active brokers in the local cluster.
*
* Get the list of active brokers (broker ids) in the local cluster.
*
* Response Example:
*
*
* ["prod1-broker1.messaging.use.example.com:8080", "prod1-broker2.messaging.use.example.com:8080"
* * * "prod1-broker3.messaging.use.example.com:8080"]
*
*
* @return a list of broker ids
* @throws NotAuthorizedException
* You don't have admin permission to get the list of active brokers in the cluster
* @throws PulsarAdminException
* Unexpected error
*/
List getActiveBrokers() throws PulsarAdminException;
/**
* Get the list of active brokers in the local cluster asynchronously.
*
* Get the list of active brokers (broker ids) in the local cluster.
*
* Response Example:
*
*
* ["prod1-broker1.messaging.use.example.com:8080", "prod1-broker2.messaging.use.example.com:8080",
* "prod1-broker3.messaging.use.example.com:8080"]
*
*
* @return a list of broker ids
*/
CompletableFuture> getActiveBrokersAsync();
/**
* Get the list of active brokers in the cluster.
*
* Get the list of active brokers (broker ids) in the cluster.
*
* Response Example:
*
*
* ["prod1-broker1.messaging.use.example.com:8080", "prod1-broker2.messaging.use.example.com:8080"
* * * "prod1-broker3.messaging.use.example.com:8080"]
*
*
* @param cluster
* Cluster name
* @return a list of broker ids
* @throws NotAuthorizedException
* You don't have admin permission to get the list of active brokers in the cluster
* @throws NotFoundException
* Cluster doesn't exist
* @throws PulsarAdminException
* Unexpected error
*/
List getActiveBrokers(String cluster) throws PulsarAdminException;
/**
* Get the list of active brokers in the cluster asynchronously.
*
* Get the list of active brokers (broker ids) in the cluster.
*
* Response Example:
*
*
* ["prod1-broker1.messaging.use.example.com:8080", "prod1-broker2.messaging.use.example.com:8080",
* "prod1-broker3.messaging.use.example.com:8080"]
*
*
* @param cluster
* Cluster name
* @return a list of broker ids
*/
CompletableFuture> getActiveBrokersAsync(String cluster);
/**
* Get the information of the leader broker.
*
* Get the information of the leader broker.
*
* Response Example:
*
*
* {serviceUrl:"prod1-broker1.messaging.use.example.com:8080"}
*
*
* @return the information of the leader broker.
* @throws PulsarAdminException
* Unexpected error
*/
BrokerInfo getLeaderBroker() throws PulsarAdminException;
/**
* Get the service url of the leader broker asynchronously.
*
* Get the service url of the leader broker.
*
* Response Example:
*
*
* {serviceUrl:"prod1-broker1.messaging.use.example.com:8080"}
*
*
* @return the service url of the leader broker
* @throws PulsarAdminException
* Unexpected error
*/
CompletableFuture getLeaderBrokerAsync() throws PulsarAdminException;
/**
* Get the map of owned namespaces and their status from a single broker in the cluster.
*
* The map is returned in a JSON object format below
*
* Response Example:
*
*
* {"ns-1":{"broker_assignment":"shared","is_active":"true","is_controlled":"false"},
* "ns-2":{"broker_assignment":"primary","is_active":"true","is_controlled":"true"}}
*
*
* @param cluster
* @param brokerId
* @return
* @throws PulsarAdminException
*/
Map getOwnedNamespaces(String cluster, String brokerId)
throws PulsarAdminException;
/**
* Get the map of owned namespaces and their status from a single broker in the cluster asynchronously.
*
* The map is returned in a JSON object format below
*
* Response Example:
*
*
* {"ns-1":{"broker_assignment":"shared","is_active":"true","is_controlled":"false"},
* "ns-2":{"broker_assignment":"primary","is_active":"true","is_controlled":"true"}}
*
*
* @param cluster
* @param brokerId
* @return
*/
CompletableFuture> getOwnedNamespacesAsync(String cluster, String brokerId);
/**
* Update a dynamic configuration value into ZooKeeper.
*
* It updates dynamic configuration value in to Zk that triggers watch on
* brokers and all brokers can update {@link ServiceConfiguration} value
* locally
*
* @param configName
* @param configValue
* @throws PulsarAdminException
*/
void updateDynamicConfiguration(String configName, String configValue) throws PulsarAdminException;
/**
* Update a dynamic configuration value into ZooKeeper asynchronously.
*
* It updates dynamic configuration value in to Zk that triggers watch on
* brokers and all brokers can update {@link ServiceConfiguration} value
* locally
*
* @param configName
* @param configValue
*/
CompletableFuture updateDynamicConfigurationAsync(String configName, String configValue);
/**
* It deletes dynamic configuration value into ZooKeeper.
*
* It will not impact current value in broker but next time when
* broker restarts, it applies value from configuration file only.
*
* @param configName
* @throws PulsarAdminException
*/
void deleteDynamicConfiguration(String configName) throws PulsarAdminException;
/**
* It deletes dynamic configuration value into ZooKeeper asynchronously.
*
* It will not impact current value in broker but next time when
* broker restarts, it applies value from configuration file only.
*
* @param configName
*/
CompletableFuture deleteDynamicConfigurationAsync(String configName);
/**
* Get list of updatable configuration name.
*
* @return
* @throws PulsarAdminException
*/
List getDynamicConfigurationNames() throws PulsarAdminException;
/**
* Get list of updatable configuration name asynchronously.
*
* @return
*/
CompletableFuture> getDynamicConfigurationNamesAsync();
/**
* Get values of runtime configuration.
*
* @return
* @throws PulsarAdminException
*/
Map getRuntimeConfigurations() throws PulsarAdminException;
/**
* Get values of runtime configuration asynchronously.
*
* @return
*/
CompletableFuture> getRuntimeConfigurationsAsync();
/**
* Get values of all overridden dynamic-configs.
*
* @return
* @throws PulsarAdminException
*/
Map getAllDynamicConfigurations() throws PulsarAdminException;
/**
* Get values of all overridden dynamic-configs asynchronously.
*
* @return
*/
CompletableFuture> getAllDynamicConfigurationsAsync();
/**
* Get the internal configuration data.
*
* @return internal configuration data.
*/
InternalConfigurationData getInternalConfigurationData() throws PulsarAdminException;
/**
* Get the internal configuration data asynchronously.
*
* @return internal configuration data.
*/
CompletableFuture getInternalConfigurationDataAsync();
/**
* Manually trigger backlogQuotaCheck.
*
* @throws PulsarAdminException
*/
void backlogQuotaCheck() throws PulsarAdminException;
/**
* Manually trigger backlogQuotaCheck asynchronously.
* @return
*/
CompletableFuture backlogQuotaCheckAsync();
/**
* Run a healthcheck on the broker.
*
* @throws PulsarAdminException if the healthcheck fails.
*/
@Deprecated
void healthcheck() throws PulsarAdminException;
/**
* Run a healthcheck on the broker asynchronously.
*/
@Deprecated
CompletableFuture healthcheckAsync();
/**
* Run a healthcheck on the broker.
*
* @throws PulsarAdminException if the healthcheck fails.
*/
void healthcheck(TopicVersion topicVersion) throws PulsarAdminException;
/**
* Run a healthcheck on the broker asynchronously.
*/
CompletableFuture healthcheckAsync(TopicVersion topicVersion);
/**
* Trigger the current broker to graceful-shutdown asynchronously.
*
* @param maxConcurrentUnloadPerSec the maximum number of topics to unload per second.
* This helps control the speed of the unload operation during shutdown.
* @param forcedTerminateTopic if true, topics will be forcefully terminated during the shutdown process.
*/
CompletableFuture shutDownBrokerGracefully(int maxConcurrentUnloadPerSec,
boolean forcedTerminateTopic);
/**
* Get version of broker.
* @return version of broker.
*/
String getVersion() throws PulsarAdminException;
}