Skip to content

Commit

Permalink
Introduce ProgramFailureException and WrappedStageException to be con…
Browse files Browse the repository at this point in the history
…sumed by platform and plugins
  • Loading branch information
itsankit-google committed Aug 21, 2024
1 parent cbcb4a9 commit 130de13
Show file tree
Hide file tree
Showing 3 changed files with 249 additions and 0 deletions.
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
/*
* 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.
* <p>
* This enum classifies errors into three broad categories:
* </p>
* <ul>
* <li><b>SYSTEM</b> - Represents system-level errors that are typically caused by infrastructure,
* network, or external dependencies, rather than user actions.</li>
* <li><b>USER</b> - Represents errors caused by user input or actions that violate expected rules
* or constraints.</li>
* <li><b>UNKNOWN</b> - Represents errors of an indeterminate type, where the cause cannot be
* classified as either system or user error.</li>
* </ul>
*/
public enum ErrorType {
UNKNOWN, // Default type for safety during deserialization
SYSTEM,
USER,
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,160 @@
/*
* 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.
* <p>
* 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.
* </p>
* <p>
* The following details can be provided:
* </p>
* <ul>
* <li><b>errorCategory:</b> A high-level classification of the error.</li>
* <li><b>errorMessage:</b> A detailed description of the error message.</li>
* <li><b>errorReason:</b> A reason for why the error occurred.</li>
* <li><b>errorType:</b> The type of error, represented by the {@ErrorType} enum,
* such as SYSTEM, USER, or UNKNOWN.</li>
* </ul>
**/
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.
*
* <p>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.
*
* <p>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.
*
* <p>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);
}
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
/*
* 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.
* <p>
* 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.
* </p>
*/
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;
}
}

0 comments on commit 130de13

Please sign in to comment.