MINOR: Improve documentation to clarify preferred replica (#20890)

Improve documentation to clarify preferred replica

Reviewers: Chia-Ping Tsai <[email protected]>

Author: Rancho-7

clients/src/main/java/org/apache/kafka/common/PartitionInfo.java

@@ -70,7 +70,8 @@ public Node leader() {
     }
 
     /**
-     * The complete set of replicas for this partition regardless of whether they are alive or up-to-date
+     * The complete set of replicas for this partition regardless of whether they are alive or up-to-date. The preferred replica
+     * is the head of the list.
      */
     public Node[] replicas() {
         return replicas;

core/src/test/scala/unit/kafka/server/MetadataRequestTest.scala

@@ -204,6 +204,22 @@ class MetadataRequestTest extends AbstractMetadataRequestTest {
     }
   }
 
+  @Test
+  def testPartitionInfoPreferredReplica(): Unit = {
+    val replicaAssignment = Map(0 -> Seq(1, 2, 0))
+    val topic = "testPartitionInfoPreferredReplicaTopic"
+    createTopicWithAssignment(topic, replicaAssignment)
+
+    val response = sendMetadataRequest(new MetadataRequest.Builder(Seq(topic).asJava, true).build())
+    val cluster = response.buildCluster()
+    val partitionInfos = cluster.partitionsForTopic(topic).asScala
+    assertEquals(1, partitionInfos.size)
+
+    val partitionInfo = partitionInfos.head
+    val preferredReplicaId = replicaAssignment(partitionInfo.partition()).head
+    assertEquals(preferredReplicaId, partitionInfo.replicas().head.id())
+  }
+
   @Test
   def testReplicaDownResponse(): Unit = {
     val replicaDownTopic = "replicaDown"