diff --git a/README.md b/README.md index 50e3354..cf6d9f7 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ # KoSIT Validator + - [Introduction](#introduction) - [Validation Configurations](#validation-configurations) * [Third Party Validation Configurations](#third-party-validation-configurations) @@ -9,17 +10,18 @@ - [Packages](#packages) ## Introduction -The validator is an XML validation engine to validate and process XML files in various formats. It basically does the following in order: -1. identify actual xml format -1. validate the xml file (using schema and schematron rules) -1. generate a custom report / extract custom data from the xml file +The validator is an XML validation engine to validate and process XML files in various formats. It basically does the following in order: + +1. identify actual XML format +1. validate the XML file (using schema and schematron rules) +1. generate a custom report / extract custom data from the XML file 1. compute an acceptance status (according the supplied schema and rules) -The validator depends on self defined [scenarios](docs/configurations.md) which are used to fully configure the process. -It always creates a [validation report in XML](docs/configurations.md#validators-report). The actual content of this is controlled by the scenario. +The validator depends on self defined [scenarios](docs/configurations.md) in order to fully configure the whole process. +It always creates a [validation report in XML](docs/configurations.md#validators-report). The actual content of the report can also be controlled by the scenario. -See [architecture](docs/architecture.md) for information about the actual validation process. +See [architecture](docs/architecture.md) for information about the whole validation process. ## Validation configurations @@ -30,7 +32,7 @@ All configurations are self-contained modules which are deployed and developed o ### Third party validation configurations -Currently, there are two public third party validation configurations available. +Here are two public third party validation configurations available which might serve as examples: * Validation Configuration for [XRechnung](http://www.xoev.de/de/xrechnung): * Source code is available on [GitHub](https://github.com/itplr-kosit/validator-configuration-xrechnung) @@ -43,29 +45,31 @@ Currently, there are two public third party validation configurations available. The validator can be used in three different ways: -* as standalone application running from the cli +* as standalone application running from the CLI * as library embedded within a custom application * as a daemon providing a http interface -### Standalone Command-Line Interface +### Standalone Command Line Interface (CLI) + +**Important hint**: since v1.5.1 the filename has been changed from `validationtool-*` to `validator-*` The general way using the CLI is: ```shell -java -jar validationtool--standalone.jar -s -r +java -jar validator--standalone.jar -s -r [OPTIONS] [FILE] [FILE] [FILE] ... ``` The help option displays further CLI options to customize the process: ```shell -java -jar validationtool--standalone.jar --help +java -jar validator--standalone.jar --help ``` A concrete example with a specific validator configuration can be found on [GitHub](https://github.com/itplr-kosit/validator-configuration-xrechnung) -The [CLI documentation](./docs/cli.md) shows further configuration options. +The [CLI documentation](./docs/cli.md) shows further configuration options. ### Application User Interface (API / embedded usage) @@ -93,7 +97,7 @@ will thus not be resolved transitively. You can also start the validator as a HTTP-Server. Just start it in _Daemon-Mode_ with the `-D` option. ```shell -java -jar validationtool--standalone.jar -s -D +java -jar validator--standalone.jar -s -D ``` @@ -103,7 +107,7 @@ The [daemon documentation](./docs/daemon.md) shows more usage details and furthe The validator distribution contains the following artifacts: -1. **validationtool-``.jar**: Java library for embedded use within an application -1. **validationtool-`-standalone.jar**: Uber-JAR for standalone usage containing all dependencies in one jar file. This file comes with JAXB *embedded* and can be used with Java 8 and Java >= 11) -1. **validationtool-`-java8-standalone.jar**: Uber-JAR for standalone usage with Java JDK 8 containing all dependencies in one jar file. This file file *does not* contain JAXB and depends on the bundled version of the JDK. +1. **validator-``.jar**: Java library for embedded use within an application +1. **validator-`-standalone.jar**: Uber-JAR for standalone usage containing all dependencies in one jar file. This file comes with JAXB *embedded* and can be used with Java 8 and Java >= 11) +1. **validator-`-java8-standalone.jar**: Uber-JAR for standalone usage with Java JDK 8 containing all dependencies in one jar file. This file file *does not* contain JAXB and depends on the bundled version of the JDK. 1. **libs/***: directory containing all (incl. optional) dependencies of the validator diff --git a/docs/cli.md b/docs/cli.md index 071f6da..492bedc 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -1,27 +1,29 @@ -# Validator CLI +# Validator Command Line Interface (CLI) -The validator comes with a commandline interface (CLI) which allows validating any number of input xml files. +The `validator` comes with a command line interface (CLI) which allows validating any number of input XML files. + +**Important hint**: since v1.5.1 the filename has been changed from `validationtool-*` to `validator-*` The general way using the CLI is: ```shell -java -jar validationtool--standalone.jar -s [OPTIONS] [FILE] [FILE] [FILE] ... +java -jar validator--standalone.jar -s [OPTIONS] [FILE] [FILE] [FILE] ... ``` -The validator can also read the xml file from the standard input - -```shell script -# via redirection -java -jar validationtool--standalone.jar -s [OPTIONS] < my-input.xml - -# read from pipe -cat my-input.xml | validationtool--standalone.jar -s [OPTIONS] -``` - -The help option displays further CLI options to customize the process: +The validator can also read the XML file from the standard input ```shell -java -jar validationtool--standalone.jar --help +# via redirection +java -jar validator--standalone.jar -s [OPTIONS] < my-input.xml + +# read from pipe +cat my-input.xml | validator--standalone.jar -s [OPTIONS] +``` + +The help option displays further CLI options: + +```shell +java -jar validator--standalone.jar --help ``` You can also use multiple scenario configurations and multiple repositories with resources for these. The validator either supports @@ -29,17 +31,17 @@ supplying the parameters in order or using named configuration. Valid usages are ```shell # multiple scenarios, implicit repository -java -jar validationtool--standalone.jar -s -s [OPTIONS] [FILE] +java -jar validator--standalone.jar -s -s [OPTIONS] [FILE] # multiple scenarios, single defined repository -java -jar validationtool--standalone.jar -s -s -r [OPTIONS] [FILE] +java -jar validator--standalone.jar -s -s -r [OPTIONS] [FILE] # multiple scenarios, multiple repositories ordered -java -jar validationtool--standalone.jar -s -r -s -r [OPTIONS] [FILE] -java -jar validationtool--standalone.jar -s -s -r -r [OPTIONS] [FILE] +java -jar validator--standalone.jar -s -r -s -r [OPTIONS] [FILE] +java -jar validator--standalone.jar -s -s -r -r [OPTIONS] [FILE] # multiple scenarios, multiple repositories (named) -java -jar validationtool--standalone.jar -s "NAME1=" -s "NAME2=" -r "NAME1=" -r "NAME2=" [OPTIONS] [FILE] +java -jar validator--standalone.jar -s "NAME1=" -s "NAME2=" -r "NAME1=" -r "NAME2=" [OPTIONS] [FILE] ``` ## Special features @@ -57,7 +59,7 @@ generated reports. This is mainly useful for scenario developers. Ask KoSIT for | code | description | |-|-| -| 0 | All validated xml files are acceptable according to the scenario configurations | +| 0 | All validated xml files are acceptable according to the scenario configurations or application usage was requested | | positive integer | Number of rejected (e.g. not acceptable) xml files according to the scenario configurations| | -1 | Parsing error. The commandline arguments specified are incorrect | -| -2 | Configuration error. There is an error loading the configuration and/or validation targets | +| -2 | Configuration error. There is an error loading the configuration and/or validation targets | diff --git a/docs/daemon.md b/docs/daemon.md index 04f3b92..a0f8f66 100644 --- a/docs/daemon.md +++ b/docs/daemon.md @@ -8,8 +8,10 @@ and should work with OpenJDK based distributions. Keep this in mind, if you want To use the validator daemon as is, start the _Daemon-Mode_ with the `-D` option and supply a suitable [validator configuration](configurations.md). +**Important hint**: since v1.5.1 the filename has been changed from `validationtool-*` to `validator-*` + ```shell -java -jar validationtool--standalone.jar -s -D +java -jar validator--standalone.jar -s -D ``` Per default the HTTP-Server listens on _localhost_ at Port 8080. @@ -17,7 +19,7 @@ Per default the HTTP-Server listens on _localhost_ at Port 8080. You can configure the daemon with `-H` for IP Adress and `-P` for port number: ```shell -java -jar validationtool--standalone.jar -s -D -H 192.168.1.x -P 8081 +java -jar validator--standalone.jar -s -D -H 192.168.1.x -P 8081 ``` ## Customized usage @@ -135,5 +137,5 @@ The daemon provides a simple GUI when issuing `GET` requests providing the follo The GUI can be disabled using the API (see above) or via CLI: ```shell script -java -jar validationtool--standalone.jar -s -D --disable-gui +java -jar validator--standalone.jar -s -D --disable-gui ```