This is an internal documentation. There is a good chance you’re looking for something else. See Disclaimer.

Schema validation

Note

This is mostly a direct copy from an old package-info.java file from the ch.tocco.nice2.model.entity.api.schema package. Feel free to rewrite or expand this documentation.

The validate package provides functions to validate an existing database against the nice2 data model.

How it works

The entry point is SchemaModelValidator which provides the checkDataModel method. It takes a ValidationProgress to receive progress information from the running process. You can pass ValidationProgress#EMPTY if not interested or subclass ValidationProgressAdapter. Furthermore, an additional Reporter can be specified. There is a empty version, Reporter#EMPTY, too. There can be only one running validation at a time, if checkDataModel is called while a validation job is already running, its Future is returned and no other job is started.

A Reporter consumes events generated by SchemaModelValidator. Each CheckEvent represents a specific failed check and contains the data that has been checked as well as the result. Look at its subclasses to get an idea. ValidationProgress and Reporter can also be contributed to take part in every run, while the given arguments only apply to the specific run. For convenience there is DispatchingReporter that simplifies implementation of the Reporter interface.

CheckEvent instanced are generated by other contributions: SchemaCheck. A SchemaCheck takes an object that contains data to be checked. The SchemaModelValidator goes through all database objects and creates a CheckData object and hands it to all contributed SchemaCheck. The result is a list of CheckEvent that are in turn propagated to all contributed Reporter. As with Reporter, the DispatchingSchemaCheck can be subclassed to simplify implementation of SchemaCheck interface.

So, in short: SchemaModelValidator iterates through all database objects and creates an instance of CheckData. This is forwarded to all SchemaCheck contribtutions. The SchemaCheck contributions are responsible for inspecting the CheckData objects and transform them into CheckEvents. Each CheckEvent is a failure according to our data model. The validator collects the events and forwards them to all Reporter which can now log them, provide fixes etc. Each of these parts may happen on another thread, so the main validation loop is not blocked on each check or reporter.

Adding a new check

A new check can be added by simply adding another method to one of the existing subclasses of DispatchingSchemaCheck. Different kind of failures should result in different subclasses for CheckEvent. This should implement Descriptive to have a nicer output at devcon’s ui. Once this has been implemented, the new check is used and will show up in the devcon. In order to amend the “Try-fix” feature, add a corresponding method to SqlFixFactory and ChangesetFixFactory, respectively. Methods in these classes take a specific CheckEvent and provide a fix for it.

If the new check does not fit in one of the existing classes, create a new one (potentially subclassing DispatchingSchemaCheck.