Exception Handling

Traditionally, two mechanisms are employed to structure errors: exception classes and error codes. AsterixDB takes a hybrid approach that makes use of the two mechanisms through assigning error codes to each exception and grouping errors in a structured exceptions classes. Following are some technical details on exception handling in AsterixDB.

1. "Root" exception classes are HyracksDataException for runtime errors and AlgebricksException for compilation errors.
2. Exeptions declared in throws clause in method signatures must be of those types to avoid wrapping of exceptions to satisfy interfaces.
3. Every exception should contain an error code that uniquely identifies the error and the error message template. In addition to the error code each exception has a fixed set of parameters that are used to parameterize the error message.  Error messages should not be defined in the source code but be in configuration files. The goal of the error code is to enable error messages in different languages, evolution of error messages without breaking error identifiers, and the ability to easily search for problems (and solutions) in search engines.
4. Subclasses of the root exceptions can be used to simplify the construction of exception objects and to increase readability of the code.

Here are the key designs that we want to achieve:

• None of the exceptions defined in AsterixDB supports a zero-parameter constructor nor a single string-parameter constructor;
• In all constructors of the root level exception classes, there should be an error code parameter;
• Usually, no further exceptions should be thrown for a caught exception that is defined in AsterixDB. Otherwise, the exception handling will be complicated. But there is one outlier scenario, i.e., you want to make end users feel more comfortable with the error messages.
• All message templates should be tested.

• Any exceptions that are thrown from the codebase below the asterixdb directory should be RuntimeDataException or CompilationException, or their derivatives.

• New error messages should not be defined in the source code. Instead, they should live in properties files that map error codes to error messages. Existing error messages that are defined in the source code should be migrated to properties files gradually.
  
  • For error message templates used in the codebase below the hyracks/algebricks directories, please put their templates into hyracks-fullstack/hyracks/hyracks-api/src/main/resources/errormsg/en.properties.
  • For error message templates used in the codebase below the asterixdb directory, please put their templates into asterixdb/asterix-common/src/main/resources/asx_errormsg/en.properties.
  • Multiple error codes (using comma to separate them) can be mapped to the same error message templates.
  • The text in the two properties files should follow the Java properties file format.

AsterixDB Error code range:

0 --- 999: runtime errors

1000 ---- 1999: compilation errors

2000 ---- 2999: storage errors

3000 ---- 3999: feed errors

4000 ---- 4999: lifecycle management (including extension lifecycles) errors