Exception handling

KlumAST supports a hierarchy of Exception to signal problems in the various phases of the model lifecycle. The hierarchy is as follows:

KlumException

The KlumException is the base class for all exceptions thrown by KlumAST. It contains a reference to the phase in which the exception occurred.

KlumModelException

The KlumModelException is thrown when a problem occurs during the creation of the model. It contains a reference to the position in model setup where the exception was thrown: its construction path, a string that mimics methods and closures used in the DSL.

This is NOT the path of the object in the actual model tree, but the path in the DSL script that was used to create the model. This is useful to identify the location of the problem in the script. This also includes objects generated by Templates or nested scripts.

(See: ExceptionHandlingDocumentaryTest#'reports the DSL location for a model-creation error'.)

For example, configuring a single nested service twice with different keys reports the second DSL call as the source of the model-creation error:

try {
    Deployment.Create.With {
        service 'blue'
        service 'green'
    }
} catch (KlumModelException error) {
    assert error.breadCrumbPath.endsWith('/service(green)')
}

Examples:

A model created from a script (Using Foo.Create.From(File)) will result in the prefix: $/Foo.From:file(<filename>). If given filename contains a script with the following content, the various construction paths will be created:

name "bla"

// $/Foo.From:file(myFile)

bars {
    // $/Foo.From:file(myFile)/bars
    bar {
        // $/Foo.From:file(myFile)/bars/bar
        name "bar1"
    }
    bar {
        // $/Foo.From:file(myFile)/bars/bar[2]
        name "bar2"
    }
}

Besides being part of the exception, the construction path is transferred from the Builder into the completed object's serializable Model companion. The runtime's BreadcrumbCollector remains the internal mechanism that assembles it. A construction path is not a structural model path, traversal path, import source, validation location, or provenance/lineage record. Use public exception and path utilities rather than KlumInstanceProxy, which is now a Builder-only compatibility adapter.

KlumSchemaException

The KlumSchemaException is thrown when a problem occurs during realization of a model, but likely to be originated in the schema, as opposed to the actual model. Misplaced annotations or wrong types are the most common causes for this exception.

KlumVisitorException

The KlumVisitorException is thrown when a problem occurs during the traversal of the model tree, usually as part of the execution of a phase. It contains a reference to the object in the model tree that caused the exception.

KlumValidationException

A KlumValidationException is thrown when a validation fails. Import com.blackbuild.klum.ast.runtime.validation.KlumValidationException; the former com.blackbuild.klum.ast.runtime.KlumValidationException no longer exists in 4.0. The exception contains a list of KlumValidationResults, each holding the KlumValidationIssues for a single object, sorted by their occurring object.