Refactor SyncStatusCode and ErrorDetails into seperate classes, introduce MaturtityLevel in xtable-api

Author: vinishjail97

xtable-api/src/main/java/org/apache/xtable/MaturityLevel.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.xtable;
+
+public enum MaturityLevel {
+  /**
+   * 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
+}

xtable-api/src/main/java/org/apache/xtable/PublicAPIClass.java

@@ -0,0 +1,35 @@
+/*
+ * 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.xtable;
+
+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 public class, used in user code. */
+@Inherited
+@Documented
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.CLASS)
+public @interface PublicAPIClass {
+  MaturityLevel maturity();
+}

xtable-api/src/main/java/org/apache/xtable/PublicAPIMethod.java

@@ -0,0 +1,35 @@
+/*
+ * 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.xtable;
+
+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 public method, used in user code. */
+@Inherited
+@Documented
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.CLASS)
+public @interface PublicAPIMethod {
+  MaturityLevel maturity();
+}

xtable-api/src/main/java/org/apache/xtable/model/sync/ErrorDetails.java

@@ -0,0 +1,49 @@
+/*
+ * 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.xtable.model.sync;
+
+import lombok.Builder;
+import lombok.Value;
+
+import org.apache.xtable.MaturityLevel;
+import org.apache.xtable.PublicAPIClass;
+
+@Value
+@Builder
+@PublicAPIClass(maturity = MaturityLevel.EVOLVING)
+public class ErrorDetails {
+  // error Message if any
+  String errorMessage;
+  // Readable description of the error
+  String errorDescription;
+  // Can the client retry for this type of error (Transient error=true, persistent error=false)
+  boolean canRetryOnFailure;
+
+  public static ErrorDetails create(Exception e, String errorDescription) {
+    if (e == null) {
+      return null;
+    }
+
+    return ErrorDetails.builder()
+        .errorMessage(e.getMessage())
+        .errorDescription(errorDescription)
+        .canRetryOnFailure(true)
+        .build();
+  }
+}

xtable-api/src/main/java/org/apache/xtable/model/sync/SyncResult.java

@@ -20,18 +20,23 @@
 
 import java.time.Duration;
 import java.time.Instant;
+import java.util.Collections;
 import java.util.List;
 
 import lombok.Builder;
 import lombok.Value;
 
+import org.apache.xtable.MaturityLevel;
+import org.apache.xtable.PublicAPIClass;
+
 /**
  * Result of a sync operation
  *
  * @since 0.1
  */
 @Value
 @Builder(toBuilder = true)
+@PublicAPIClass(maturity = MaturityLevel.EVOLVING)
 public class SyncResult {
   // Mode used for the sync
   SyncMode mode;
@@ -44,13 +49,7 @@ public class SyncResult {
   // The Sync Mode recommended for the next sync (Usually filled on an error)
   SyncMode recommendedSyncMode;
   // The sync status for each catalog.
-  List<CatalogSyncStatus> catalogSyncStatusList;
-
-  public enum SyncStatusCode {
-    SUCCESS,
-    ABORTED,
-    ERROR
-  }
+  @Builder.Default List<CatalogSyncStatus> catalogSyncStatusList = Collections.emptyList();
 
   /** Represents the status of a Sync operation. */
   @Value
@@ -75,15 +74,4 @@ public static class CatalogSyncStatus {
     // errorDetails if any
     ErrorDetails errorDetails;
   }
-
-  @Value
-  @Builder
-  public static class ErrorDetails {
-    // error Message if any
-    String errorMessage;
-    // Readable description of the error
-    String errorDescription;
-    // Can the client retry for this type of error (Transient error=true, persistent error=false)
-    boolean canRetryOnFailure;
-  }
 }

xtable-api/src/main/java/org/apache/xtable/model/sync/SyncStatusCode.java

@@ -0,0 +1,32 @@
+/*
+ * 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.xtable.model.sync;
+
+/** Enum representing the status of a synchronization operation. */
+public enum SyncStatusCode {
+
+  /** Indicates that the sync was successful. */
+  SUCCESS,
+
+  /** Indicates that the sync was aborted before completion. */
+  ABORTED,
+
+  /** Indicates that an error occurred during sync. */
+  ERROR
+}