From 3388eba1d22af5b175b1b483ce25033d7a9760d8 Mon Sep 17 00:00:00 2001 From: "Andreas Penski (init)" Date: Tue, 24 Mar 2020 08:37:14 +0100 Subject: [PATCH] (chore) doc enhancements --- README.md | 6 ++++-- docs/api.md | 40 +++++++++++++++++++++++++++------------- 2 files changed, 31 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 832ddf6..483ba8b 100644 --- a/README.md +++ b/README.md @@ -66,6 +66,10 @@ java -jar validationtool--standalone.jar --help 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 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. -### 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). diff --git a/docs/api.md b/docs/api.md index e537f83..31d05ab 100644 --- a/docs/api.md +++ b/docs/api.md @@ -4,7 +4,8 @@ The Validator offers an API which allows you to integrate Validator in your own ## 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 @@ -28,7 +29,8 @@ dependencies { ## 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: @@ -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. - -* Batch use is serial and *not parallel* +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. 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 @@ -96,14 +103,21 @@ A tri-state Object `AcceptRecommendation` can be retrieved from the `Result` usi The three defined states are: -1. `UNDEFINED` i.e. the evaluation of the overall validation could not be computed. -2. `ACCEPTABLE` i.e. the recommendation is to accept 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. `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. +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 -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.