diff --git a/README.md b/README.md index d02d2d5..4168738 100644 --- a/README.md +++ b/README.md @@ -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--standalone.jar -s [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--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--standalone.jar -s -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--standalone.jar -s -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. diff --git a/docs/api.md b/docs/api.md index 14add56..bea4a12 100644 --- a/docs/api.md +++ b/docs/api.md @@ -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. diff --git a/docs/daemon.md b/docs/daemon.md index 577a4c8..5be8c75 100644 --- a/docs/daemon.md +++ b/docs/daemon.md @@ -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--standalone.jar -s -D @@ -11,7 +13,7 @@ java -jar validationtool--standalone.jar -s -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--standalone.jar -s -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. \ No newline at end of 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--standalone.jar -s -D --disable-gui +``` \ No newline at end of file diff --git a/src/main/java/de/kosit/validationtool/cmd/CommandLineApplication.java b/src/main/java/de/kosit/validationtool/cmd/CommandLineApplication.java index ba0e9aa..2e254aa 100644 --- a/src/main/java/de/kosit/validationtool/cmd/CommandLineApplication.java +++ b/src/main/java/de/kosit/validationtool/cmd/CommandLineApplication.java @@ -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; } }