Package org.apache.kafka.clients.admin

Interface Admin

All Superinterfaces:
AutoCloseable
All Known Implementing Classes:
AdminClient, ForwardingAdmin, KafkaAdminClient
public interface Admin extends AutoCloseable
The administrative client for Kafka, which supports managing and inspecting topics, brokers, configurations and ACLs.

Instances returned from the create methods of this interface are guaranteed to be thread safe. However, the KafkaFutures returned from request methods are executed by a single thread so it is important that any code which executes on that thread when they complete (using KafkaFuture.thenApply(KafkaFuture.BaseFunction), for example) doesn't block for too long. If necessary, processing of results should be passed to another thread.

The operations exposed by Admin follow a consistent pattern:

  • Admin instances should be created using create(Properties) or create(Map)
  • Each operation typically has two overloaded methods, one which uses a default set of options and an overloaded method where the last parameter is an explicit options object.
  • The operation method's first parameter is a Collection of items to perform the operation on. Batching multiple requests into a single call is more efficient and should be preferred over multiple calls to the same method.
  • The operation methods execute asynchronously.
  • Each xxx operation method returns an XxxResult class with methods which expose KafkaFuture for accessing the result(s) of the operation.
  • Typically an all() method is provided for getting the overall success/failure of the batch and a values() method provided access to each item in a request batch. Other methods may also be provided.
  • For synchronous behaviour use KafkaFuture.get()

Here is a simple example of using an Admin client instance to create a new topic: 

 
 Properties props = new Properties();
 props.put(AdminClientConfig.BOOTSTRAP_SERVERS_CONFIG, "localhost:9092");

 try (Admin admin = Admin.create(props)) {
   String topicName = "my-topic";
   int partitions = 12;
   short replicationFactor = 3;
   // Create a compacted topic
   CreateTopicsResult result = admin.createTopics(Collections.singleton(
     new NewTopic(topicName, partitions, replicationFactor)
       .configs(Collections.singletonMap(TopicConfig.CLEANUP_POLICY_CONFIG, TopicConfig.CLEANUP_POLICY_COMPACT))));

   // Call values() to get the result for a specific topic
   KafkaFuture<Void> future = result.values().get(topicName);

   // Call get() to block until the topic creation is complete or has failed
   // if creation failed the ExecutionException wraps the underlying cause.
   future.get();
 }

Bootstrap and balancing

The bootstrap.servers config in the Map or Properties passed to create(Properties) is only used for discovering the brokers in the cluster, which the client will then connect to as needed. As such, it is sufficient to include only two or three broker addresses to cope with the possibility of brokers being unavailable.

Different operations necessitate requests being sent to different nodes in the cluster. For example createTopics(Collection) communicates with the controller, but describeTopics(Collection) can talk to any broker. When the recipient does not matter the instance will try to use the broker with the fewest outstanding requests.

The client will transparently retry certain errors which are usually transient. For example if the request for createTopics() get sent to a node which was not the controller the metadata would be refreshed and the request re-sent to the controller.

Broker Compatibility

The minimum broker version required is 0.10.0.0. Methods with stricter requirements will specify the minimum broker version required.