demo/validator
1
0
Fork 0
mirror of https://github.com/itplr-kosit/validator.git synced 2026-05-25 16:55:39 +00:00
Code Issues Projects Releases Packages Wiki Activity

(chore) doc enhancements

Browse source
This commit is contained in:
Andreas Penski (init) 2020-03-24 08:37:14 +01:00
parent 03cf40f328
commit 3388eba1d2
2 changed files with 31 additions and 15 deletions
Download patch file Download diff file Expand all files Collapse all files

6
README.md
View file

@ -66,6 +66,10 @@ java -jar validationtool-<version>-standalone.jar --help
A concrete example with a specific validator configuration can be found on [GitHub](https://github.com/itplr-kosit/validator-configuration-xrechnung) A concrete example with a specific validator configuration can be found on [GitHub](https://github.com/itplr-kosit/validator-configuration-xrechnung)
### Application User Interface (API / embedded usage)
The validator can also be used in own Java Applications via the API. Details can be [found here](./docs/api.md).
### Daemon-Mode ### Daemon-Mode
You can also start the validator as an HTTP-Server. Just start it in _Daemon-Mode_ with the `-D` option. You can also start the validator as an HTTP-Server. Just start it in _Daemon-Mode_ with the `-D` option.
@ -86,6 +90,4 @@ You can HTTP-POST to `/` and the response will return the report document as de
Additionally there is the GET `/health` endpoint which can be used by monitoring systems. Additionally there is the GET `/health` endpoint which can be used by monitoring systems.
### Application User Interface (embedded usage)
The validator can also be used in own Java Applications via the API. Details can be [found here](./docs/api.md).

40
docs/api.md
View file

@ -4,7 +4,8 @@ The Validator offers an API which allows you to integrate Validator in your own
## Dependency Management ## Dependency Management
Currently, we *do not* deploy to Maven Central or similar. Hence you need to build and optionally deploy the Validator artifacts to your own shared repository (see for example [Maven Documentation](https://maven.apache.org/guides/mini/guide-3rd-party-jars-local.html)). Currently, we *do not* deploy to Maven Central or similar. Hence you need to build and optionally deploy the Validator artifacts to your own
shared (or local) repository (see for example [Maven Documentation](https://maven.apache.org/guides/mini/guide-3rd-party-jars-local.html)).
### Maven ### Maven
@ -28,7 +29,8 @@ dependencies {
## Usage ## Usage
Prerequisite for use is a valid [scenario definition](configurations.md) and the a folder with all necessary artifacts for validation (repository) either on the filesystem or on the classpath. Prerequisite for use is a valid [scenario definition](configurations.md) and the a folder with all necessary artifacts for validation
(repository) either on the filesystem or on the classpath.
The following example demonstrates loading scenario.xml and whole configuration from classpath and validating one XML document: The following example demonstrates loading scenario.xml and whole configuration from classpath and validating one XML document:
@ -81,14 +83,19 @@ public class StandardExample {
} }
``` ```
The `Result` interface has more methods to retrieve details about XSD validation errors and Schematron messages. The `Result` interface has convenience methods to retrieve details about XSD validation errors and Schematron messages and other processing results. See
[Result.java](https://github.com/itplr-kosit/validator/blob/master/src/main/java/de/kosit/validationtool/api/Result.java) for details.
Initializing all XML artifacts and XSLT-executables is expensive. The `Check` instance is *threadsafe* and keeps all artifacts. Therefore, we recommend the re-use of an `Check` instance. Initializing all XML artifacts and XSLT-executables is expensive. The `Check` instance is *threadsafe* and keeps all artifacts. Therefore,
we recommend the re-use of an `Check` instance.
* Batch use is serial and *not parallel*
The only input `de.kosit.validationtool.api.Input` which can be created by various methods of `de.kosit.validationtool.api.InputFactory`. The only input `de.kosit.validationtool.api.Input` which can be created by various methods of `de.kosit.validationtool.api.InputFactory`.
The `InputFactory` calculates a hash sum for each Input which is also written to the Report. _SHA-256_ from the JDK is the default algorithm. It can be changed using the `read`-methods of `InputFactory`. The `InputFactory` calculates a hash sum for each Input which is also written to the Report. _SHA-256_ from the JDK is the default algorithm.
It can be changed using the `read`-methods of `InputFactory`.
The main interface [Check.java](https://github.com/itplr-kosit/validator/blob/master/src/main/java/de/kosit/validationtool/api/Check.java)
allows using a batch interface (processing list of [Inputs](https://github.com/itplr-kosit/validator/blob/master/src/main/java/de/kosit/validationtool/api/Input.java)).
However, there is no parallel processing implemented at the moment.
## Accept Recommendation and Accept Match ## Accept Recommendation and Accept Match
@ -96,14 +103,21 @@ A tri-state Object `AcceptRecommendation` can be retrieved from the `Result` usi
The three defined states are: The three defined states are:
1. `UNDEFINED` i.e. the evaluation of the overall validation could not be computed. 1. `ACCEPTABLE` i.e. the recommendation is to accept input based on the evaluation of the overall validation.
2. `ACCEPTABLE` i.e. the recommendation is to accept input based on the evaluation of the overall validation. 1. `REJECT` i.e. the recommendation is to reject input based on the evaluation of the overall validation.
3. `REJECT` i.e. the recommendation is to reject input based on the evaluation of the overall validation. 1. `UNDEFINED` i.e. the evaluation of the overall validation could not be computed (overall processing is incomplete)
By default it is `UNDEFINED`. The accept recommendation is based on either:
1. schema and schematron validation result
1. if configured based on _acceptMatch_ configuration of the scenario (see below)
### Accept Match in Scenario Configuration ### Accept Match in Scenario Configuration
For your own configuration you can add an `acceptMatch` element in each scenario. It can contain in XPATH expression over your own defined `Report` to compute a boolean. An XPATH expression evaluating to true will lead to an `ACCEPTABLE` amd otherwise to a `REJECT` recommendation. For your own configuration you can add an `acceptMatch` element in each scenario. It can contain in XPATH expression over your own
defined `Report` to compute a boolean. An XPATH expression evaluating to true will lead to an `ACCEPTABLE` and otherwise to a `REJECT`
recommendation.
This allows to have own control over what validation result is to be considered acceptable for your own application context. This allows to have control over what validation result is to be considered _acceptable_ for your own application context. E.g. you can
overrule schematron validation errors with _acceptMatch_ configuration and consider certain errors as _acceptable_. Nevertheless you can *not*
overrule schema errors with accept match.