Replace @IcebergApi with @CometPublicApi({"Iceberg"}) annotation

Adopts a pattern inspired by Hadoop's @InterfaceAudience.LimitedPrivate
where the annotation lists known external consumers. This makes it easy
to add future consumers without creating new annotation types.

Also addresses review feedback: removes redundant assertions in API
tests and clarifies doc references.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: andygrove

common/src/main/java/org/apache/arrow/c/AbstractCometSchemaImporter.java

@@ -23,7 +23,7 @@
 import org.apache.arrow.vector.FieldVector;
 import org.apache.arrow.vector.types.pojo.Field;
 
-import org.apache.comet.IcebergApi;
+import org.apache.comet.CometPublicApi;
 
 /** This is a simple wrapper around SchemaImporter to make it accessible from Java Arrow. */
 public abstract class AbstractCometSchemaImporter {
@@ -69,7 +69,7 @@ public FieldVector importVector(ArrowArray array, ArrowSchema schema) {
     return vector;
   }
 
-  @IcebergApi
+  @CometPublicApi({"Iceberg"})
   public void close() {
     provider.close();
   }

common/src/main/java/org/apache/comet/CometPublicApi.java

@@ -0,0 +1,50 @@
+/*
+ * 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.comet;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Indicates that the annotated element is part of the public API used by external projects.
+ *
+ * <p>The {@link #value()} lists the known consumers of this API element. Changes to annotated
+ * elements may break those consumers, so contributors should exercise caution and consider backward
+ * compatibility when modifying them.
+ *
+ * <p>Inspired by Hadoop's {@code @InterfaceAudience.LimitedPrivate}.
+ *
+ * <p>Example usage:
+ *
+ * <pre>
+ * &#64;CometPublicApi({"Iceberg"})
+ * public class FileReader { ... }
+ * </pre>
+ */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.TYPE, ElementType.METHOD, ElementType.CONSTRUCTOR, ElementType.FIELD})
+public @interface CometPublicApi {
+  /** Lists the external projects known to use this API element. */
+  String[] value();
+}

common/src/main/java/org/apache/comet/CometSchemaImporter.java

@@ -23,9 +23,9 @@
 import org.apache.arrow.memory.BufferAllocator;
 
 /** This is a simple wrapper around SchemaImporter to make it accessible from Java Arrow. */
-@IcebergApi
+@CometPublicApi({"Iceberg"})
 public class CometSchemaImporter extends AbstractCometSchemaImporter {
-  @IcebergApi
+  @CometPublicApi({"Iceberg"})
   public CometSchemaImporter(BufferAllocator allocator) {
     super(allocator);
   }

common/src/main/java/org/apache/comet/IcebergApi.java

@@ -19,26 +19,13 @@
 
 package org.apache.comet;
 
-import java.lang.annotation.Documented;
-import java.lang.annotation.ElementType;
-import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
-import java.lang.annotation.Target;
-
 /**
- * Indicates that the annotated element is part of the public API used by Apache Iceberg.
- *
- * <p>This annotation marks classes, methods, constructors, and fields that form the contract
- * between Comet and Iceberg. Changes to these APIs may break Iceberg's Comet integration, so
- * contributors should exercise caution and consider backward compatibility when modifying annotated
- * elements.
+ * Convenience constant for use with {@link CometPublicApi}.
  *
- * <p>The Iceberg integration uses Comet's native Parquet reader for accelerated vectorized reads.
- * See the contributor guide documentation for details on how Iceberg uses these APIs.
- *
- * @see <a href="https://iceberg.apache.org/">Apache Iceberg</a>
+ * <p>Usage: {@code @CometPublicApi({IcebergApi.ICEBERG})}
  */
-@Documented
-@Retention(RetentionPolicy.RUNTIME)
-@Target({ElementType.TYPE, ElementType.METHOD, ElementType.CONSTRUCTOR, ElementType.FIELD})
-public @interface IcebergApi {}
+public final class IcebergApi {
+  public static final String ICEBERG = "Iceberg";
+
+  private IcebergApi() {}
+}

common/src/main/java/org/apache/comet/parquet/AbstractColumnReader.java

@@ -28,11 +28,11 @@
 import org.apache.spark.sql.types.TimestampNTZType$;
 
 import org.apache.comet.CometConf;
-import org.apache.comet.IcebergApi;
+import org.apache.comet.CometPublicApi;
 import org.apache.comet.vector.CometVector;
 
 /** Base class for Comet Parquet column reader implementations. */
-@IcebergApi
+@CometPublicApi({"Iceberg"})
 public abstract class AbstractColumnReader implements AutoCloseable {
   protected static final Logger LOG = LoggerFactory.getLogger(AbstractColumnReader.class);
 
@@ -63,7 +63,8 @@ public abstract class AbstractColumnReader implements AutoCloseable {
   protected int batchSize;
 
   /** A pointer to the native implementation of ColumnReader. */
-  @IcebergApi protected long nativeHandle;
+  @CometPublicApi({"Iceberg"})
+  protected long nativeHandle;
 
   AbstractColumnReader(
       DataType type,
@@ -98,7 +99,7 @@ String getPath() {
   /**
    * Set the batch size of this reader to be 'batchSize'. Also initializes the native column reader.
    */
-  @IcebergApi
+  @CometPublicApi({"Iceberg"})
   public void setBatchSize(int batchSize) {
     assert nativeHandle == 0
         : "Native column reader shouldn't be initialized before " + "'setBatchSize' is called";
@@ -116,7 +117,7 @@ public void setBatchSize(int batchSize) {
   /** Returns the {@link CometVector} read by this reader. */
   public abstract CometVector currentBatch();
 
-  @IcebergApi
+  @CometPublicApi({"Iceberg"})
   @Override
   public void close() {
     if (nativeHandle != 0) {

common/src/main/java/org/apache/comet/parquet/BatchReader.java

@@ -64,8 +64,8 @@
 import org.apache.spark.util.AccumulatorV2;
 
 import org.apache.comet.CometConf;
+import org.apache.comet.CometPublicApi;
 import org.apache.comet.CometSchemaImporter;
-import org.apache.comet.IcebergApi;
 import org.apache.comet.shims.ShimBatchReader;
 import org.apache.comet.shims.ShimFileFormat;
 import org.apache.comet.vector.CometVector;
@@ -88,7 +88,7 @@
  *   }
  * </pre>
  */
-@IcebergApi
+@CometPublicApi({"Iceberg"})
 public class BatchReader extends RecordReader<Void, ColumnarBatch> implements Closeable {
   private static final Logger LOG = LoggerFactory.getLogger(FileReader.class);
   protected static final BufferAllocator ALLOCATOR = new RootAllocator();
@@ -191,7 +191,7 @@ public BatchReader(
    * @deprecated since 0.10.0, will be removed in 0.11.0.
    * @see <a href="https://github.com/apache/datafusion-comet/issues/2079">Comet Issue #2079</a>
    */
-  @IcebergApi
+  @CometPublicApi({"Iceberg"})
   public BatchReader(AbstractColumnReader[] columnReaders) {
     // Todo: set useDecimal128 and useLazyMaterialization
     int numColumns = columnReaders.length;
@@ -390,7 +390,7 @@ public void init() throws URISyntaxException, IOException {
    * @deprecated since 0.10.0, will be removed in 0.11.0.
    * @see <a href="https://github.com/apache/datafusion-comet/issues/2079">Comet Issue #2079</a>
    */
-  @IcebergApi
+  @CometPublicApi({"Iceberg"})
   public void setSparkSchema(StructType schema) {
     this.sparkSchema = schema;
   }
@@ -399,7 +399,7 @@ public void setSparkSchema(StructType schema) {
    * @deprecated since 0.10.0, will be removed in 0.11.0.
    * @see <a href="https://github.com/apache/datafusion-comet/issues/2079">Comet Issue #2079</a>
    */
-  @IcebergApi
+  @CometPublicApi({"Iceberg"})
   public AbstractColumnReader[] getColumnReaders() {
     return columnReaders;
   }
@@ -503,7 +503,7 @@ public boolean nextBatch() throws IOException {
     return nextBatch(batchSize);
   }
 
-  @IcebergApi
+  @CometPublicApi({"Iceberg"})
   public boolean nextBatch(int batchSize) {
     long totalDecodeTime = 0, totalLoadTime = 0;
     for (int i = 0; i < columnReaders.length; i++) {
@@ -530,7 +530,7 @@ public boolean nextBatch(int batchSize) {
     return true;
   }
 
-  @IcebergApi
+  @CometPublicApi({"Iceberg"})
   @Override
   public void close() throws IOException {
     if (columnReaders != null) {

common/src/main/java/org/apache/comet/parquet/ColumnReader.java

@@ -43,15 +43,15 @@
 import org.apache.spark.sql.types.DataType;
 
 import org.apache.comet.CometConf;
+import org.apache.comet.CometPublicApi;
 import org.apache.comet.CometSchemaImporter;
-import org.apache.comet.IcebergApi;
 import org.apache.comet.vector.CometDecodedVector;
 import org.apache.comet.vector.CometDictionary;
 import org.apache.comet.vector.CometDictionaryVector;
 import org.apache.comet.vector.CometPlainVector;
 import org.apache.comet.vector.CometVector;
 
-@IcebergApi
+@CometPublicApi({"Iceberg"})
 public class ColumnReader extends AbstractColumnReader {
   protected static final Logger LOG = LoggerFactory.getLogger(ColumnReader.class);
   protected final BufferAllocator ALLOCATOR = new RootAllocator();
@@ -116,7 +116,7 @@ public class ColumnReader extends AbstractColumnReader {
    * @deprecated since 0.10.0, will be removed in 0.11.0.
    * @see <a href="https://github.com/apache/datafusion-comet/issues/2079">Comet Issue #2079</a>
    */
-  @IcebergApi
+  @CometPublicApi({"Iceberg"})
   public void setPageReader(PageReader pageReader) throws IOException {
     this.pageReader = pageReader;
 
@@ -132,7 +132,7 @@ public void setPageReader(PageReader pageReader) throws IOException {
   }
 
   /** This method is called from Apache Iceberg. */
-  @IcebergApi
+  @CometPublicApi({"Iceberg"})
   public void setRowGroupReader(RowGroupReader rowGroupReader, ParquetColumnSpec columnSpec)
       throws IOException {
     ColumnDescriptor descriptor = Utils.buildColumnDescriptor(columnSpec);

common/src/main/java/org/apache/comet/parquet/ConstantColumnReader.java

@@ -27,13 +27,13 @@
 import org.apache.spark.sql.types.*;
 import org.apache.spark.unsafe.types.UTF8String;
 
-import org.apache.comet.IcebergApi;
+import org.apache.comet.CometPublicApi;
 
 /**
  * A column reader that always return constant vectors. Used for reading partition columns, for
  * instance.
  */
-@IcebergApi
+@CometPublicApi({"Iceberg"})
 public class ConstantColumnReader extends MetadataColumnReader {
   /** Whether all the values in this constant column are nulls */
   private boolean isNull;
@@ -59,15 +59,15 @@ public class ConstantColumnReader extends MetadataColumnReader {
    * @deprecated since 0.10.0, will be removed in 0.11.0.
    * @see <a href="https://github.com/apache/datafusion-comet/issues/2079">Comet Issue #2079</a>
    */
-  @IcebergApi
+  @CometPublicApi({"Iceberg"})
   public ConstantColumnReader(
       DataType type, ColumnDescriptor descriptor, Object value, boolean useDecimal128) {
     super(type, descriptor, useDecimal128, true);
     this.value = value;
   }
 
   // Used by Iceberg
-  @IcebergApi
+  @CometPublicApi({"Iceberg"})
   public ConstantColumnReader(
       DataType type, ParquetColumnSpec spec, Object value, boolean useDecimal128) {
     super(type, spec, useDecimal128, true);

common/src/main/java/org/apache/comet/parquet/FileReader.java

@@ -90,7 +90,7 @@
 import org.apache.parquet.schema.PrimitiveType;
 import org.apache.spark.sql.execution.metric.SQLMetric;
 
-import org.apache.comet.IcebergApi;
+import org.apache.comet.CometPublicApi;
 
 import static org.apache.parquet.hadoop.ParquetFileWriter.EFMAGIC;
 import static org.apache.parquet.hadoop.ParquetFileWriter.MAGIC;
@@ -103,7 +103,7 @@
  * A Parquet file reader. Mostly followed {@code ParquetFileReader} in {@code parquet-mr}, but with
  * customizations & optimizations for Comet.
  */
-@IcebergApi
+@CometPublicApi({"Iceberg"})
 public class FileReader implements Closeable {
   private static final Logger LOG = LoggerFactory.getLogger(FileReader.class);
 
@@ -138,7 +138,7 @@ public class FileReader implements Closeable {
   }
 
   /** This constructor is called from Apache Iceberg. */
-  @IcebergApi
+  @CometPublicApi({"Iceberg"})
   public FileReader(
       WrappedInputFile file,
       ReadOptions cometOptions,
@@ -262,7 +262,7 @@ public void setRequestedSchema(List<ColumnDescriptor> projection) {
   }
 
   /** This method is called from Apache Iceberg. */
-  @IcebergApi
+  @CometPublicApi({"Iceberg"})
   public void setRequestedSchemaFromSpecs(List<ParquetColumnSpec> specList) {
     paths.clear();
     for (ParquetColumnSpec colSpec : specList) {
@@ -341,7 +341,7 @@ public long getFilteredRecordCount() {
   }
 
   /** Skips the next row group. Returns false if there's no row group to skip. Otherwise, true. */
-  @IcebergApi
+  @CometPublicApi({"Iceberg"})
   public boolean skipNextRowGroup() {
     return advanceToNextBlock();
   }
@@ -350,7 +350,7 @@ public boolean skipNextRowGroup() {
    * Returns the next row group to read (after applying row group filtering), or null if there's no
    * more row group.
    */
-  @IcebergApi
+  @CometPublicApi({"Iceberg"})
   public RowGroupReader readNextRowGroup() throws IOException {
     if (currentBlock == blocks.size()) {
       return null;
@@ -871,7 +871,7 @@ public void closeStream() throws IOException {
     }
   }
 
-  @IcebergApi
+  @CometPublicApi({"Iceberg"})
   @Override
   public void close() throws IOException {
     try {