From e76ddac4971a4dda659841b20f5b5cf02f23f1f1 Mon Sep 17 00:00:00 2001 From: itsankit-google Date: Tue, 20 Aug 2024 14:06:49 +0000 Subject: [PATCH] Introduce ProgramFailureException and WrappedStageException to be consumed by platform and plugins --- .../io/cdap/cdap/api/exception/ErrorType.java | 36 +++++ .../exception/ProgramFailureException.java | 153 ++++++++++++++++++ .../api/exception/WrappedStageException.java | 51 ++++++ 3 files changed, 240 insertions(+) create mode 100644 cdap-api-common/src/main/java/io/cdap/cdap/api/exception/ErrorType.java create mode 100644 cdap-api-common/src/main/java/io/cdap/cdap/api/exception/ProgramFailureException.java create mode 100644 cdap-api-common/src/main/java/io/cdap/cdap/api/exception/WrappedStageException.java diff --git a/cdap-api-common/src/main/java/io/cdap/cdap/api/exception/ErrorType.java b/cdap-api-common/src/main/java/io/cdap/cdap/api/exception/ErrorType.java new file mode 100644 index 000000000000..03d9454fd055 --- /dev/null +++ b/cdap-api-common/src/main/java/io/cdap/cdap/api/exception/ErrorType.java @@ -0,0 +1,36 @@ +/* + * Copyright © 2024 Cask Data, Inc. + * + * Licensed 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 io.cdap.cdap.api.exception; + +/** + * Enum representing different types of errors due to which a program can fail. + *

+ * This enum classifies errors into three broad categories: + *

+ * + */ +public enum ErrorType { + SYSTEM, + USER, + UNKNOWN +} diff --git a/cdap-api-common/src/main/java/io/cdap/cdap/api/exception/ProgramFailureException.java b/cdap-api-common/src/main/java/io/cdap/cdap/api/exception/ProgramFailureException.java new file mode 100644 index 000000000000..916901cbf01b --- /dev/null +++ b/cdap-api-common/src/main/java/io/cdap/cdap/api/exception/ProgramFailureException.java @@ -0,0 +1,153 @@ +/* + * Copyright © 2024 Cask Data, Inc. + * + * Licensed 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 io.cdap.cdap.api.exception; + +/** + * Exception class representing a program failure with detailed error information. + *

+ * This exception is used to indicate failures within the system and provides details about + * the error category, message, reason, and type. It uses the builder pattern to allow + * for flexible construction of the exception with optional fields. + *

+ *

+ * The following details can be provided: + *

+ * + **/ +public class ProgramFailureException extends RuntimeException { + private final String errorCategory; + private final String errorMessage; + private final String errorReason; + private final ErrorType errorType; + + // Private constructor to prevent direct instantiation + private ProgramFailureException(String errorCategory, String errorMessage, String errorReason, + ErrorType errorType) { + this.errorCategory = errorCategory; + this.errorMessage = errorMessage; + this.errorReason = errorReason; + this.errorType = errorType; + } + + /** + * Returns the category of the error. + *

+ * This typically provides a high-level classification of the error, + * such as plugin, provisioning, etc. + * If the category or reason is not known - it will be marked as ‘Others’. + * + * @return a {@String} representing the error category. + */ + public String getErrorCategory() { + return errorCategory == null ? "Others" : errorCategory; + } + + /** + * Returns the detailed message associated with the error. + * + * @return a {@String} representing the error message. + */ + public String getErrorMessage() { + return errorMessage; + } + + /** + * Returns the reason for the error. + *

+ * The reason usually explains why the error occurred, such as a specific validation failure + * or an unexpected condition. + * + * @return a {@String} representing the error reason. + */ + public String getErrorReason() { + return errorReason; + } + + /** + * Returns the type of the error. + *

+ * This method provides information on whether the error is classified as a + * system-level error, a user-caused error, or an unknown type of error. + * + * @return an {@ErrorType} enum value representing the type of the error. + */ + public ErrorType getErrorType() { + return errorType == null ? ErrorType.UNKNOWN : errorType; + } + + /** + * Builder class for ProgramFailureException. + */ + public static class Builder { + private String errorCategory; + private String errorMessage; + private String errorReason; + private ErrorType errorType; + + /** + * Sets the error category for the ProgramFailureException. + * @param errorCategory The category of the error. + * @return The current Builder instance. + */ + public Builder withErrorCategory(String errorCategory) { + this.errorCategory = errorCategory; + return this; + } + + /** + * Sets the error message for the ProgramFailureException. + * @param errorMessage The detailed error message. + * @return The current Builder instance. + */ + public Builder withErrorMessage(String errorMessage) { + this.errorMessage = errorMessage; + return this; + } + + /** + * Sets the error reason for the ProgramFailureException. + * @param errorReason The reason for the error. + * @return The current Builder instance. + */ + public Builder withErrorReason(String errorReason) { + this.errorReason = errorReason; + return this; + } + + /** + * Sets the error type for the ProgramFailureException. + * @param errorType The type of error (SYSTEM, USER, UNKNOWN). + * @return The current Builder instance. + */ + public Builder withErrorType(ErrorType errorType) { + this.errorType = errorType; + return this; + } + + /** + * Builds and returns a new instance of ProgramFailureException. + * @return A new ProgramFailureException instance. + */ + public ProgramFailureException build() { + return new ProgramFailureException(errorCategory, errorMessage, errorReason, errorType); + } + } + +} diff --git a/cdap-api-common/src/main/java/io/cdap/cdap/api/exception/WrappedStageException.java b/cdap-api-common/src/main/java/io/cdap/cdap/api/exception/WrappedStageException.java new file mode 100644 index 000000000000..e52836e2eb56 --- /dev/null +++ b/cdap-api-common/src/main/java/io/cdap/cdap/api/exception/WrappedStageException.java @@ -0,0 +1,51 @@ +/* + * Copyright © 2024 Cask Data, Inc. + * + * Licensed 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 io.cdap.cdap.api.exception; + +/** + * Exception class that wraps another exception and includes the name of the stage + * where the failure occurred. + *

+ * This class extends {@code RuntimeException} and is used to provide additional context when + * an error occurs during a specific stage of execution. + * The original cause of the error is preserved, and the stage name where the failure happened is + * included for better error tracking. + *

+ */ +public class WrappedStageException extends RuntimeException { + + private final String stageName; + + /** + * Constructs a new {@code WrappedStageException} with the specified cause and stage name. + * + * @param cause the original exception that caused the failure. + * @param stageName the name of the stage where the failure occurred. + */ + public WrappedStageException(Throwable cause, String stageName) { + super(cause); + this.stageName = stageName; + } + + /** + * Returns the name of the stage where the exception occurred. + * + * @return the stage name as a {@String}. + */ + public String getStageName() { + return stageName; + } +}