[HUDI-1190] Introduce @PublicAPIClass and @PublicAPIMethod annotations to mark public APIs (#1965)

- Maturity levels one of : evolving, stable, deprecated
- Took a pass and marked out most of the existing public API

hudi-common/src/main/java/org/apache/hudi/ApiMaturityLevel.java

@@ -0,0 +1,42 @@
+/*
+ * 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.hudi;
+
+/**
+ * Indicates how stable a given API method/class is, so user's can plan and set their expectations accordingly.
+ */
+public enum ApiMaturityLevel {
+    /**
+     * New APIs start out in this state. Although enough thought will be given to avoid
+     * breaking changes to the API in the future, sometimes it might need to change
+     * based on feedback.
+     */
+    EVOLVING,
+    /**
+     * Enough applications/users have picked up the API and we deem it stable. We will strive to never
+     * break the stability of such APIs within a given major version release.
+     */
+    STABLE,
+    /**
+     * New things are born, old things fade away. This holds true for APIs also. Once an API has been
+     * marked as deprecated, new APIs replacing them (if need be) would be in stable state for users
+     * to migrate to.
+     */
+    DEPRECATED
+}

hudi-common/src/main/java/org/apache/hudi/PublicAPIClass.java

@@ -0,0 +1,37 @@
+/*
+ * 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.hudi;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Annotates a type as a user facing class.
+ */
+@Inherited
+@Documented
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.CLASS)
+public @interface PublicAPIClass {
+  ApiMaturityLevel maturity();
+}

hudi-common/src/main/java/org/apache/hudi/PublicAPIMethod.java

@@ -0,0 +1,38 @@
+/*
+ * 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.hudi;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Annotates a method, as part of the public contract with user code.
+ */
+@Inherited
+@Documented
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.CLASS)
+public @interface PublicAPIMethod {
+  ApiMaturityLevel maturity();
+}
+

hudi-common/src/main/java/org/apache/hudi/common/model/HoodieRecordPayload.java

@@ -18,6 +18,9 @@
 
 package org.apache.hudi.common.model;
 
+import org.apache.hudi.ApiMaturityLevel;
+import org.apache.hudi.PublicAPIClass;
+import org.apache.hudi.PublicAPIMethod;
 import org.apache.hudi.common.util.Option;
 
 import org.apache.avro.Schema;
@@ -31,12 +34,14 @@ import java.util.Map;
  * Every Hoodie table has an implementation of the <code>HoodieRecordPayload</code> This abstracts out callbacks which
  * depend on record specific logic.
  */
+@PublicAPIClass(maturity = ApiMaturityLevel.STABLE)
 public interface HoodieRecordPayload<T extends HoodieRecordPayload> extends Serializable {
 
   /**
    * When more than one HoodieRecord have the same HoodieKey, this function combines them before attempting to
    * insert/upsert (if combining turned on in HoodieClientConfig).
    */
+  @PublicAPIMethod(maturity = ApiMaturityLevel.STABLE)
   T preCombine(T another);
 
   /**
@@ -50,6 +55,7 @@ public interface HoodieRecordPayload<T extends HoodieRecordPayload> extends Seri
    * @param schema Schema used for record
    * @return new combined/merged value to be written back to storage. EMPTY to skip writing this record.
    */
+  @PublicAPIMethod(maturity = ApiMaturityLevel.STABLE)
   Option<IndexedRecord> combineAndGetUpdateValue(IndexedRecord currentValue, Schema schema) throws IOException;
 
   /**
@@ -57,6 +63,7 @@ public interface HoodieRecordPayload<T extends HoodieRecordPayload> extends Seri
    * new value for the given HoodieKey, wherein there is no existing record in storage to be combined against. (i.e
    * insert) Return EMPTY to skip writing this record.
    */
+  @PublicAPIMethod(maturity = ApiMaturityLevel.STABLE)
   Option<IndexedRecord> getInsertValue(Schema schema) throws IOException;
 
   /**
@@ -64,6 +71,7 @@ public interface HoodieRecordPayload<T extends HoodieRecordPayload> extends Seri
    * {@code WriteStatus.markSuccess()} and {@code WriteStatus.markFailure()} in order to compute some aggregate metrics
    * using the metadata in the context of a write success or failure.
    */
+  @PublicAPIMethod(maturity = ApiMaturityLevel.STABLE)
   default Option<Map<String, String>> getMetadata() {
     return Option.empty();
   }