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

further doc

Browse source
This commit is contained in:
Andreas Penski (init) 2020-05-18 09:22:35 +02:00
parent 06a88848db
commit 997f5073fe
4 changed files with 49 additions and 34 deletions
Download patch file Download diff file Expand all files Collapse all files

19
README.md
View file

@ -18,19 +18,17 @@ The validator distribution contains the following artifacts:
## Validation Configurations
The validator is just an engine and does not know anything about XML Documents and has no own validation rules.
Validation rules and details are defined in [validation scenarios](docs/configurations.md) which are used to fully configure the validation process.
All configurations are self-contained modules and deployed and developed on their own.
### Third Party Validation Configurations
Currently, there are two public third party validation configurations available.
* Validation Configuration for [XRechnung](http://www.xoev.de/de/xrechnung) is available on
* Validation Configuration for [XRechnung](http://www.xoev.de/de/xrechnung):
* Source code is available on [GitHub](https://github.com/itplr-kosit/validator-configuration-xrechnung)
* [Releases](https://github.com/itplr-kosit/validator-configuration-xrechnung/releases) can also be downloaded
* Validation Configuration for XGewerbeanzeige
* Validation Configuration for [XGewerbeanzeige](https://xgewerbeanzeige.de/)
* Source code is available on [GitHub](https://github.com/itplr-kosit/validator-configuration-xgewerbeanzeige)
* [Releases](https://github.com/itplr-kosit/validator-configuration-xgewerbeanzeige/releases) can also be downloaded
@ -50,7 +48,7 @@ The general way using the CLI is:
java -jar validationtool-<version>-standalone.jar -s <scenario-config-file> [OPTIONS] [FILE] [FILE] [FILE] ...
```
You can see more CLI options with
The help option displays further CLI options to customize the process:
```shell
java -jar validationtool-<version>-standalone.jar --help
@ -72,7 +70,7 @@ Result validationResult = validator.checkInput(document);
// examine the result here
```
Details and further configuration options can be [found here](./docs/api.md).
The [API documentation](./docs/api.md) shows further configuration options.
### Daemon-Mode
@ -82,13 +80,6 @@ You can also start the validator as an HTTP-Server. Just start it in _Daemon-Mod
java -jar validationtool-<version>-standalone.jar -s <scenario-config-file> -D
```
Per default the HTTP-Server listens on _localhost_ at Port 8080.
You can configure it with `-H` for IP Adress and `-P` for port number:
```shell
java -jar validationtool-<version>-standalone.jar -s <scenario-config-file> -D -H 192.168.1.x -P 8081
```
Usage details and further configuration options can be [found here](./docs/daemon.md).
The [daemon documentation](./docs/daemon.md) shows more usage details and further configuration options.

31
docs/api.md
View file

@ -1,6 +1,6 @@
# Validator API
The Validator offers an API which allows you to integrate Validator in your own applications.
The Validator offers an API which allows you to integrate the Validator in your own applications.
## Dependency Management
@ -87,11 +87,13 @@ The `Result` interface has convenience methods to retrieve details about XSD val
[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.
we recommend the re-use of a `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`.
Beside the validator's configuration the only input are instances of [Input](https://github.com/itplr-kosit/validator/blob/master/src/main/java/de/kosit/validationtool/api/Input.java)
which can be created by various methods of the [InputFactory](https://github.com/itplr-kosit/validator/blob/master/src/main/java/de/kosit/validationtool/api/InputFactory.java).
The [InputFactory](https://github.com/itplr-kosit/validator/blob/master/src/main/java/de/kosit/validationtool/api/InputFactory.java)
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 other `read`-methods of [InputFactory](https://github.com/itplr-kosit/validator/blob/master/src/main/java/de/kosit/validationtool/api/InputFactory.java).
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)).
@ -99,7 +101,8 @@ However, there is no parallel processing implemented at the moment.
## Accept Recommendation and Accept Match
A tri-state Object `AcceptRecommendation` can be retrieved from the `Result` using `getAcceptRecommendation()`.
A tri-state object [AcceptRecommendation](https://github.com/itplr-kosit/validator/blob/master/src/main/java/de/kosit/validationtool/api/AcceptRecommendation.java)
can be retrieved from the [Result](https://github.com/itplr-kosit/validator/blob/master/src/main/java/de/kosit/validationtool/api/Result.java) using `getAcceptRecommendation()`.
The three defined states are:
@ -112,7 +115,7 @@ 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` and otherwise to a `REJECT`
@ -132,7 +135,7 @@ a builder API. A valid configuration consists of the following:
* a valid report transformation configuration
* valid schematron validation configurations (optional)
* a valid accept match configuration to compute acceptance information (optional)
* valid a fallback scenario configuration
* a valid fallback scenario configuration
A simple configuration looks like this:
@ -160,10 +163,10 @@ public class MyValidator {
}
```
There a various methods provided by the builder API to configure your scenarios and the validation process.
There are various methods provided by the builder API to configure your scenarios and the validation process.
It is also possible to provide runtime artifacts like `XsltExecutable`, `XPathExecutalbe` or `Schema` to configure the validator.
This gives you complete control how to load these artifacts.
---
**Note:** Creating this objects requires usage of the same instance of the saxon `Processor` as used during validation later. So you
need to supply a custom `ResolvingConfigurationStrategy` or use the internal one to create these objects. See below.
@ -187,11 +190,11 @@ There are 3 implemenations available out of the box:
1. [StrictRelativeResolvingStrategy.java](https://github.com/itplr-kosit/validator/tree/master/src/main/java/de/kosit/validationtool/impl/xml/StrictRelativeResolvingStrategy.java)
which is the **default**, prevents known XML attacks and only allows loading from a specific local repository location
1. [StrictLocalResolvingStrategy.java](https://github.com/itplr-kosit/validator/tree/master/src/main/java/de/kosit/validationtool/impl/xml/StrictLocalResolvingStrategy.java)
which opens the first to load resource from local location
which opens the first to load resource from local locations
1. [RemoteResolvingStrategy.java](https://github.com/itplr-kosit/validator/tree/master/src/main/java/de/kosit/validationtool/impl/xml/RemoteResolvingStrategy.java)
which opens the first to load resource also from remote locations via http and https
which further opens the second to load resources also from remote locations via http and https
You can configure usage of one of this implemenations via
You can configure usage of one of this implemenations using the `ResolvingMode` via
````java
Conifuguration config = Configuration.load(URI.create("myscenarios.xml"))
@ -208,7 +211,7 @@ Conifuguration config = Configuration.load(URI.create("myscenarios.xml"))
````
---
**Attention:** If you decide to implement a custom strategy you need to handle xml security risk. Please make sure, that you prevent XXE attacks and
:warning: **Attention:** If you decide to implement a custom strategy you need to handle xml security risk. Please make sure, that you prevent XXE attacks and
other kind of attacks. Consider using [BaseResolvingStrategy.java](https://github.com/itplr-kosit/validator/tree/master/src/main/java/de/kosit/validationtool/impl/xml/BaseResolvingStrategy.java)
and the protected methods within to disable certain features.

25
docs/daemon.md
View file

@ -1,9 +1,11 @@
# Validator daemon
You can also start the validator as a HTTP-Server. This is based JDK http server functionality. Keep that mind, if you want to deploy this
You can also start the validator as a HTTP-Server. This is based [JDK http server](https://docs.oracle.com/javase/8/docs/jre/api/net/httpserver/spec/com/sun/net/httpserver/HttpServer.html) functionality
and should work with OpenJDK based Java distributions. Keep that mind, if you want to deploy this
in production scenarios with heavy load.
## Basic usage
To just use the validator daemon as is, start the _Daemon-Mode_ with the `-D` option.
To just use the validator daemon as is, start the _Daemon-Mode_ with the `-D` option and supply a suitable
[validator configuration](configurations.md)
```shell
java -jar validationtool-<version>-standalone.jar -s <scenario-config-file> -D
@ -11,7 +13,7 @@ java -jar validationtool-<version>-standalone.jar -s <scenario-config-file> -D
Per default the HTTP-Server listens on _localhost_ at Port 8080.
You can configure it with `-H` for IP Adress and `-P` for port number:
You can configure the daemon with `-H` for IP Adress and `-P` for port number:
```shell
java -jar validationtool-<version>-standalone.jar -s <scenario-config-file> -D -H 192.168.1.x -P 8081
@ -38,7 +40,7 @@ The possible customizations are:
## Access the http interface
The validation service listens to `POST`-requests to any server uri. You need to supply the xml/object to validate in the post body.
The service expects a single plain input in the post body, e.g. `multipart/form-data` is not supported.
The service expects a single xml input in the post body, e.g. `multipart/form-data` is not supported.
Examples:
@ -84,4 +86,17 @@ This can be done using infrastructural service like a forwarding proxy (e.g. `ng
## Monitoring and administration
The validation service can be integrated in monitoring solutions like `Icinga` or `Nagios`. There is a `health` endpoint exposed under `/server/health` wich returns
some basic information about the service like memory consumption, general information about the version and a status `UP` as an XML file.
some basic information about the service like memory consumption, general information about the version and a status `UP` as an XML file.
## GUI
The daemon provides a simple GUI when issuing `GET` requests providing the following:
1. usage information
1. information about the actual [validator configuration](configurations.md) used by this daemon
1. a simple form to test the daemon with custom inputs
The GUI can be disabled with using the API (see above) or via CLI
```shell script
java -jar validationtool-<version>-standalone.jar -s <scenario-config-file> -D --disable-gui
```

8
src/main/java/de/kosit/validationtool/cmd/CommandLineApplication.java
View file

@ -29,7 +29,6 @@ import java.util.Arrays;
import java.util.Collection;
import java.util.Collections;
import java.util.stream.Collectors;
import java.util.stream.StreamSupport;
import org.apache.commons.cli.CommandLine;
import org.apache.commons.cli.CommandLineParser;
@ -97,6 +96,9 @@ public class CommandLineApplication {
private static final Option WORKER_COUNT = Option.builder("T").longOpt("threads").hasArg()
.desc("Number of threads processing validation requests").build();
private static final Option DISABLE_GUI = Option.builder("G").longOpt("disable-gui").desc("Disables the GUI of the daemon mode")
.build();
public static final int DAEMON_SIGNAL = 100;
private static final Option PRINT_MEM_STATS = Option.builder("m").longOpt("memory-stats").desc("Prints some memory stats").build();
@ -175,6 +177,9 @@ public class CommandLineApplication {
warnUnusedOptions(cmd, unavailable, true);
final ConfigurationLoader config = Configuration.load(determineDefinition(cmd), determineRepository(cmd));
final Daemon validDaemon = new Daemon(determineHost(cmd), determinePort(cmd), determineThreads(cmd));
if (cmd.hasOption(DISABLE_GUI.getOpt())) {
validDaemon.setGuiEnabled(false);
}
validDaemon.startServer(config.build());
return DAEMON_SIGNAL;
}
@ -379,6 +384,7 @@ public class CommandLineApplication {
options.addOption(CHECK_ASSERTIONS);
options.addOption(PRINT_MEM_STATS);
options.addOption(WORKER_COUNT);
options.addOption(DISABLE_GUI);
return options;
}
}