diff --git a/docs/2-validators/validator.md b/docs/2-validators/validator.md index f0fad71..ee3b57f 100644 --- a/docs/2-validators/validator.md +++ b/docs/2-validators/validator.md @@ -5,42 +5,30 @@ title: Validation system # Validation system -## Command Reference - -@APP_NAME@'s CLI currently supports the following launch-arguments: - -- `--https` Attempt to serve the API via HTTPS (default is false), searching for certificates as specified in the current environment. -- `-p, --port` Port in which the API will listen for requests. Values must be in range 1-65535 (default is 8080). -- `-s, --silent` Enable silent mode in order not to log any output to console (default is false) -- `-v, --verbose` Show additional logging information (use cumulative times for additional info, like: `-vvv`) -- `--version` Print the version of the program -- `--help` Print the help menu - -## Verbosity levels - -When using the `-v, --verbose` CLI argument, the following logging messages are shown on console at each time: - -- `No verbose argument` **ERROR** level messages -- `-v` **WARN** level messages and upwards -- `-vv` **INFO** level messages and upwards (includes client connections and requests) -- `-vvv` **DEBUG** level messages and upwards - -## JVM Custom Arguments - -In case @APP_NAME@ is having trouble to generate permalinks due to an SSL issue, try adding the following argument: - -- `-Djdk.tls.client.protocols=TLSv1.2` - -## Examples - -1. Launching @APP_NAME@ in port 8081: - -- `rdfshape -p 8081` - -2. Launching @APP_NAME@ in port 80, try to use the HTTPS configuration from the environment: - -- `rdfshape -p 80 --https` - -3. Launching @APP_NAME@ in port 8080, with the maximum verbosity level: - -- `rdfshape -vvv` +[Validators](https://ulitol97.github.io/comet/scaladoc/org/ragna/comet/validation/Validator.html) +are @APP_NAME@'s core. A validator instance produces a stream of validation +results which can be further processed if necessary. + +The following are required to create a validator instance: + +1. +A _[ValidatorConfiguration](https://ulitol97.github.io/comet/scaladoc/org/ragna/comet/validation/configuration/ValidatorConfiguration.html)_: +contains the information on how the validator must perform validations and when +it should stop. +2. +A _[StreamExtractor](https://ulitol97.github.io/comet/scaladoc/org/ragna/comet/stream/extractors/StreamExtractor.html)_: +reference to the extractor from which the validator will get its input RDF data +stream. This input data stream is transformed to a results stream by validating +each incoming piece of data. +3. A template type: + type of the items expected by the extractor (see next sections) + +> Signature of the Validator class: +> ```scala +> class Validator[A]( +> configuration: ValidatorConfiguration, +> private val extractor: StreamExtractor[A] +> ) +> ``` + +Once created, simply invoke `Validator#validate` to get the results stream. \ No newline at end of file diff --git a/docs/2-validators/validator_config.md b/docs/2-validators/validator_config.md index e6e200d..0f973fd 100644 --- a/docs/2-validators/validator_config.md +++ b/docs/2-validators/validator_config.md @@ -5,42 +5,47 @@ title: Validator configuration # Validator configuration -## Command Reference +@APP_NAME@ validators need some manual configuration in order to work. -@APP_NAME@'s CLI currently supports the following launch-arguments: +## Parameters -- `--https` Attempt to serve the API via HTTPS (default is false), searching for certificates as specified in the current environment. -- `-p, --port` Port in which the API will listen for requests. Values must be in range 1-65535 (default is 8080). -- `-s, --silent` Enable silent mode in order not to log any output to console (default is false) -- `-v, --verbose` Show additional logging information (use cumulative times for additional info, like: `-vvv`) -- `--version` Print the version of the program -- `--help` Print the help menu +The following parameters must be passed down to create a _ +ValidatorConfiguration_ instance: -## Verbosity levels +### Mandatory parameters -When using the `-v, --verbose` CLI argument, the following logging messages are shown on console at each time: +#### Schema -- `No verbose argument` **ERROR** level messages -- `-v` **WARN** level messages and upwards -- `-vv` **INFO** level messages and upwards (includes client connections and requests) -- `-vvv` **DEBUG** level messages and upwards +SHaclEX Schema against which the validation will be performed for all items processed by +this validator -## JVM Custom Arguments +#### Trigger -In case @APP_NAME@ is having trouble to generate permalinks due to an SSL issue, try adding the following argument: +SHaclEX ValidationTrigger against which the validation will be performed for all items +processed by this validator -- `-Djdk.tls.client.protocols=TLSv1.2` +### Optional parameters -## Examples +Some parameters needn't be specified by the user because they already have a +default value that makes sense for most cases. -1. Launching @APP_NAME@ in port 8081: +#### Halt on Invalid -- `rdfshape -p 8081` +- **Purpose**: Whether if the validator should halt and raise an error when + some RDF data is invalid or just emit an `INVALID` validation result and keep + on processing. +- **Default value**: `false` -2. Launching @APP_NAME@ in port 80, try to use the HTTPS configuration from the environment: +#### Halt on Errored -- `rdfshape -p 80 --https` +- **Purpose**: Whether if the validator should halt and raise an error when an + unexpected error occurs or just emit an `ERRORED` validation result and keep + on processing. +- **Default value**: `false` -3. Launching @APP_NAME@ in port 8080, with the maximum verbosity level: +#### Concurrent Items -- `rdfshape -vvv` +- **Purpose**: Define the maximum number of items than the validator can + validate in parallel. +- **Default value**: + See _[ValidatorConfiguration$$Defaults](https://ulitol97.github.io/comet/scaladoc/org/ragna/comet/validation/configuration/ValidatorConfiguration$$Defaults$.html)_ diff --git a/docs/2-validators/validator_results.md b/docs/2-validators/validator_results.md new file mode 100644 index 0000000..1e3b6cd --- /dev/null +++ b/docs/2-validators/validator_results.md @@ -0,0 +1,19 @@ +--- +id: validator_results +title: Validation results +--- + +# Validation results + +@APP_NAME@ validators emit a stream +of _[ValidationResult](https://ulitol97.github.io/comet/scaladoc/org/ragna/comet/validation/result/ValidationResult.html)_ +instances. + +Each result contains a: + +- _[ResultStatus](https://ulitol97.github.io/comet/scaladoc/org/ragna/comet/validation/result/ResultStatus.html)_: + represents whether if the validation was successful, unsuccessful or couldn't + be performed. + +- _result_: the inner _ValidationReport_, as returned by SHaclEX (if available). + Will be empty if the validation could not complete. \ No newline at end of file diff --git a/website/sidebars.js b/website/sidebars.js index c0f00dc..aeb9ed9 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -39,7 +39,7 @@ const sidebars = { { type: "category", label: "Validators", - items: ["validators/validator", "validators/validator_config"], + items: ["validators/validator", "validators/validator_config", "validators/validator_results"], collapsed: false },