Skip to content

Commit 4953195

Browse files
vinishjail97vinishjail97
committed
Introduce maturity-level in xtable-api and Refactor SyncStatusCode into separate class
1 parent d6ea384 commit 4953195

File tree

17 files changed

+213
-36
lines changed

17 files changed

+213
-36
lines changed

‎xtable-api/src/main/java/org/apache/xtable/annotations/Evolving.java

+42
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
/*
2+
* Licensed to the Apache Software Foundation (ASF) under one
3+
* or more contributor license agreements. See the NOTICE file
4+
* distributed with this work for additional information
5+
* regarding copyright ownership. The ASF licenses this file
6+
* to you under the Apache License, Version 2.0 (the
7+
* "License"); you may not use this file except in compliance
8+
* with the License. You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
package org.apache.xtable.annotations;
20+
21+
import java.lang.annotation.Documented;
22+
import java.lang.annotation.ElementType;
23+
import java.lang.annotation.Retention;
24+
import java.lang.annotation.RetentionPolicy;
25+
import java.lang.annotation.Target;
26+
27+
/**
28+
* New APIs start out in this state. Although enough thought will be given to avoid breaking changes
29+
* to the API in the future, sometimes it might need to change based on feedback.
30+
*/
31+
@Documented
32+
@Retention(RetentionPolicy.RUNTIME)
33+
@Target({
34+
ElementType.TYPE,
35+
ElementType.FIELD,
36+
ElementType.METHOD,
37+
ElementType.PARAMETER,
38+
ElementType.CONSTRUCTOR,
39+
ElementType.LOCAL_VARIABLE,
40+
ElementType.PACKAGE
41+
})
42+
public @interface Evolving {}

‎xtable-api/src/main/java/org/apache/xtable/annotations/Stable.java

+42
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
/*
2+
* Licensed to the Apache Software Foundation (ASF) under one
3+
* or more contributor license agreements. See the NOTICE file
4+
* distributed with this work for additional information
5+
* regarding copyright ownership. The ASF licenses this file
6+
* to you under the Apache License, Version 2.0 (the
7+
* "License"); you may not use this file except in compliance
8+
* with the License. You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
package org.apache.xtable.annotations;
20+
21+
import java.lang.annotation.Documented;
22+
import java.lang.annotation.ElementType;
23+
import java.lang.annotation.Retention;
24+
import java.lang.annotation.RetentionPolicy;
25+
import java.lang.annotation.Target;
26+
27+
/**
28+
* Enough applications/users have picked up the API and we deem it stable. We will strive to never
29+
* break the stability of such APIs within a given major version release.
30+
*/
31+
@Documented
32+
@Retention(RetentionPolicy.RUNTIME)
33+
@Target({
34+
ElementType.TYPE,
35+
ElementType.FIELD,
36+
ElementType.METHOD,
37+
ElementType.PARAMETER,
38+
ElementType.CONSTRUCTOR,
39+
ElementType.LOCAL_VARIABLE,
40+
ElementType.PACKAGE
41+
})
42+
public @interface Stable {}

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

+48
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
/*
2+
* Licensed to the Apache Software Foundation (ASF) under one
3+
* or more contributor license agreements. See the NOTICE file
4+
* distributed with this work for additional information
5+
* regarding copyright ownership. The ASF licenses this file
6+
* to you under the Apache License, Version 2.0 (the
7+
* "License"); you may not use this file except in compliance
8+
* with the License. You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
package org.apache.xtable.model.sync;
20+
21+
import lombok.Builder;
22+
import lombok.Value;
23+
24+
import org.apache.xtable.annotations.Evolving;
25+
26+
@Value
27+
@Builder
28+
@Evolving
29+
public class ErrorDetails {
30+
// error Message if any
31+
String errorMessage;
32+
// Readable description of the error
33+
String errorDescription;
34+
// Can the client retry for this type of error (Transient error=true, persistent error=false)
35+
boolean canRetryOnFailure;
36+
37+
public static ErrorDetails create(Exception e, String errorDescription) {
38+
if (e == null) {
39+
return null;
40+
}
41+
42+
return ErrorDetails.builder()
43+
.errorMessage(e.getMessage())
44+
.errorDescription(errorDescription)
45+
.canRetryOnFailure(true)
46+
.build();
47+
}
48+
}

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

+3
Original file line numberDiff line numberDiff line change
@@ -18,11 +18,14 @@
1818

1919
package org.apache.xtable.model.sync;
2020

21+
import org.apache.xtable.annotations.Stable;
22+
2123
/**
2224
* Mode of a sync
2325
*
2426
* @since 0.1
2527
*/
28+
@Stable
2629
public enum SyncMode {
2730
// Full sync will create a checkpoint of ALL the files relevant at a certain point in time
2831
FULL,

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

+5-18
Original file line numberDiff line numberDiff line change
@@ -20,18 +20,22 @@
2020

2121
import java.time.Duration;
2222
import java.time.Instant;
23+
import java.util.Collections;
2324
import java.util.List;
2425

2526
import lombok.Builder;
2627
import lombok.Value;
2728

29+
import org.apache.xtable.annotations.Evolving;
30+
2831
/**
2932
* Result of a sync operation
3033
*
3134
* @since 0.1
3235
*/
3336
@Value
3437
@Builder(toBuilder = true)
38+
@Evolving
3539
public class SyncResult {
3640
// Mode used for the sync
3741
SyncMode mode;
@@ -44,13 +48,7 @@ public class SyncResult {
4448
// The Sync Mode recommended for the next sync (Usually filled on an error)
4549
SyncMode recommendedSyncMode;
4650
// The sync status for each catalog.
47-
List<CatalogSyncStatus> catalogSyncStatusList;
48-
49-
public enum SyncStatusCode {
50-
SUCCESS,
51-
ABORTED,
52-
ERROR
53-
}
51+
@Builder.Default List<CatalogSyncStatus> catalogSyncStatusList = Collections.emptyList();
5452

5553
/** Represents the status of a Sync operation. */
5654
@Value
@@ -75,15 +73,4 @@ public static class CatalogSyncStatus {
7573
// errorDetails if any
7674
ErrorDetails errorDetails;
7775
}
78-
79-
@Value
80-
@Builder
81-
public static class ErrorDetails {
82-
// error Message if any
83-
String errorMessage;
84-
// Readable description of the error
85-
String errorDescription;
86-
// Can the client retry for this type of error (Transient error=true, persistent error=false)
87-
boolean canRetryOnFailure;
88-
}
8976
}

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

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
/*
2+
* Licensed to the Apache Software Foundation (ASF) under one
3+
* or more contributor license agreements. See the NOTICE file
4+
* distributed with this work for additional information
5+
* regarding copyright ownership. The ASF licenses this file
6+
* to you under the Apache License, Version 2.0 (the
7+
* "License"); you may not use this file except in compliance
8+
* with the License. You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
package org.apache.xtable.model.sync;
20+
21+
import org.apache.xtable.annotations.Evolving;
22+
23+
/** Enum representing the status of a synchronization operation. */
24+
@Evolving
25+
public enum SyncStatusCode {
26+
27+
/** Indicates that the sync was successful. */
28+
SUCCESS,
29+
30+
/** Indicates that the sync was aborted before completion. */
31+
ABORTED,
32+
33+
/** Indicates that an error occurred during sync. */
34+
ERROR
35+
}

‎xtable-api/src/main/java/org/apache/xtable/spi/extractor/CatalogConversionSource.java

+2
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@
2020

2121
import org.apache.hadoop.conf.Configuration;
2222

23+
import org.apache.xtable.annotations.Evolving;
2324
import org.apache.xtable.conversion.ExternalCatalogConfig;
2425
import org.apache.xtable.conversion.SourceTable;
2526
import org.apache.xtable.model.catalog.CatalogTableIdentifier;
@@ -29,6 +30,7 @@
2930
* catalog to SourceTable object {@link SourceTable}, can be used by downstream consumers for
3031
* syncing it to multiple {@link org.apache.xtable.conversion.TargetTable}
3132
*/
33+
@Evolving
3234
public interface CatalogConversionSource {
3335
/** Returns the source table object present in the catalog. */
3436
SourceTable getSourceTable(CatalogTableIdentifier tableIdentifier);

‎xtable-api/src/main/java/org/apache/xtable/spi/extractor/ConversionSource.java

+2
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@
2121
import java.io.Closeable;
2222
import java.time.Instant;
2323

24+
import org.apache.xtable.annotations.Evolving;
2425
import org.apache.xtable.model.CommitsBacklog;
2526
import org.apache.xtable.model.InstantsForIncrementalSync;
2627
import org.apache.xtable.model.InternalSnapshot;
@@ -32,6 +33,7 @@
3233
* source system. The client uses {@link Instant} to represent the point in time a commit was made
3334
* to be as generic as possible across source table formats.
3435
*/
36+
@Evolving
3537
public interface ConversionSource<COMMIT> extends Closeable {
3638
/**
3739
* Extracts the {@link InternalTable} definition as of the provided commit.

‎xtable-api/src/main/java/org/apache/xtable/spi/extractor/ExtractFromSource.java

+2
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@
2323
import lombok.AllArgsConstructor;
2424
import lombok.Getter;
2525

26+
import org.apache.xtable.annotations.Stable;
2627
import org.apache.xtable.model.CommitsBacklog;
2728
import org.apache.xtable.model.IncrementalTableChanges;
2829
import org.apache.xtable.model.InstantsForIncrementalSync;
@@ -31,6 +32,7 @@
3132

3233
@AllArgsConstructor(staticName = "of")
3334
@Getter
35+
@Stable
3436
public class ExtractFromSource<COMMIT> {
3537
private final ConversionSource<COMMIT> conversionSource;
3638

‎xtable-api/src/main/java/org/apache/xtable/spi/sync/CatalogSync.java

+5-3
Original file line numberDiff line numberDiff line change
@@ -34,8 +34,10 @@
3434

3535
import org.apache.xtable.model.InternalTable;
3636
import org.apache.xtable.model.catalog.CatalogTableIdentifier;
37+
import org.apache.xtable.model.sync.ErrorDetails;
3738
import org.apache.xtable.model.sync.SyncResult;
3839
import org.apache.xtable.model.sync.SyncResult.CatalogSyncStatus;
40+
import org.apache.xtable.model.sync.SyncStatusCode;
3941

4042
/** Provides the functionality to sync metadata from InternalTable to multiple target catalogs */
4143
@Log4j2
@@ -118,17 +120,17 @@ private <TABLE> CatalogSyncStatus syncCatalog(
118120
}
119121
return CatalogSyncStatus.builder()
120122
.catalogId(catalogSyncClient.getCatalogId())
121-
.statusCode(SyncResult.SyncStatusCode.SUCCESS)
123+
.statusCode(SyncStatusCode.SUCCESS)
122124
.build();
123125
}
124126

125127
private CatalogSyncStatus getCatalogSyncFailureStatus(
126128
String catalogId, String catalogImpl, Exception e) {
127129
return CatalogSyncStatus.builder()
128130
.catalogId(catalogId)
129-
.statusCode(SyncResult.SyncStatusCode.ERROR)
131+
.statusCode(SyncStatusCode.ERROR)
130132
.errorDetails(
131-
SyncResult.ErrorDetails.builder()
133+
ErrorDetails.builder()
132134
.errorMessage(e.getMessage())
133135
.errorDescription("catalogSync failed for " + catalogImpl)
134136
.build())

‎xtable-api/src/main/java/org/apache/xtable/spi/sync/CatalogSyncClient.java

+2
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@
2020

2121
import org.apache.hadoop.conf.Configuration;
2222

23+
import org.apache.xtable.annotations.Evolving;
2324
import org.apache.xtable.conversion.ExternalCatalogConfig;
2425
import org.apache.xtable.model.InternalTable;
2526
import org.apache.xtable.model.catalog.CatalogTableIdentifier;
@@ -30,6 +31,7 @@
3031
*
3132
* @param <TABLE>
3233
*/
34+
@Evolving
3335
public interface CatalogSyncClient<TABLE> extends AutoCloseable {
3436
/**
3537
* Returns the user-defined unique identifier for the catalog, allows user to sync table to

‎xtable-api/src/main/java/org/apache/xtable/spi/sync/ConversionTarget.java

+2
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@
2323

2424
import org.apache.hadoop.conf.Configuration;
2525

26+
import org.apache.xtable.annotations.Stable;
2627
import org.apache.xtable.conversion.TargetTable;
2728
import org.apache.xtable.model.InternalTable;
2829
import org.apache.xtable.model.metadata.TableSyncMetadata;
@@ -32,6 +33,7 @@
3233
import org.apache.xtable.model.storage.PartitionFileGroup;
3334

3435
/** A client that provides the major functionality for syncing changes to a target system. */
36+
@Stable
3537
public interface ConversionTarget {
3638

3739
/**

‎xtable-api/src/main/java/org/apache/xtable/spi/sync/TableFormatSync.java

+7-2
Original file line numberDiff line numberDiff line change
@@ -33,13 +33,16 @@
3333
import lombok.NoArgsConstructor;
3434
import lombok.extern.log4j.Log4j2;
3535

36+
import org.apache.xtable.annotations.Stable;
3637
import org.apache.xtable.model.IncrementalTableChanges;
3738
import org.apache.xtable.model.InternalSnapshot;
3839
import org.apache.xtable.model.InternalTable;
3940
import org.apache.xtable.model.TableChange;
4041
import org.apache.xtable.model.metadata.TableSyncMetadata;
42+
import org.apache.xtable.model.sync.ErrorDetails;
4143
import org.apache.xtable.model.sync.SyncMode;
4244
import org.apache.xtable.model.sync.SyncResult;
45+
import org.apache.xtable.model.sync.SyncStatusCode;
4346

4447
/** Provides the functionality to sync from the InternalTable format to the target format. */
4548
@Log4j2
@@ -58,6 +61,7 @@ public static TableFormatSync getInstance() {
5861
* @param snapshot the snapshot to sync
5962
* @return the result of the sync process
6063
*/
64+
@Stable
6165
public Map<String, SyncResult> syncSnapshot(
6266
Collection<ConversionTarget> conversionTargets, InternalSnapshot snapshot) {
6367
Instant startTime = Instant.now();
@@ -91,6 +95,7 @@ public Map<String, SyncResult> syncSnapshot(
9195
* @param changes the changes from the source table format that need to be applied
9296
* @return the results of trying to sync each change
9397
*/
98+
@Stable
9499
public Map<String, List<SyncResult>> syncChanges(
95100
Map<ConversionTarget, TableSyncMetadata> conversionTargetWithMetadata,
96101
IncrementalTableChanges changes) {
@@ -192,9 +197,9 @@ private SyncResult buildResultForError(SyncMode mode, Instant startTime, Excepti
192197
.mode(mode)
193198
.tableFormatSyncStatus(
194199
SyncResult.SyncStatus.builder()
195-
.statusCode(SyncResult.SyncStatusCode.ERROR)
200+
.statusCode(SyncStatusCode.ERROR)
196201
.errorDetails(
197-
SyncResult.ErrorDetails.builder()
202+
ErrorDetails.builder()
198203
.errorMessage(e.getMessage())
199204
.errorDescription("Failed to sync " + mode.name())
200205
.canRetryOnFailure(true)

0 commit comments

Comments
 (0)