GITBOOK-23: change request with no subject merged in GitBook

Author: Eisenbahnplatte

README.md

@@ -43,10 +43,10 @@ First, we need to select the Databus, where we want to get our data from. We tak
 
 To select data from a DBpedia Databus, you can perform queries. Databus provides two mechanisms for this, which are described in detail [here](https://dbpedia.gitbook.io/databus/#querying-metainformation). 
 
-We use the following query as selection for this example:
+We use the following query as selection for this example and write it to the file `test.sparql`:
 
 ```
-PREFIX dcat:   <http://www.w3.org/ns/dcat#>
+echo "PREFIX dcat:   <http://www.w3.org/ns/dcat#>
 PREFIX databus: <https://dataid.dbpedia.org/databus#>
 
 SELECT ?file WHERE
@@ -58,7 +58,7 @@ SELECT ?file WHERE
                 ?dataset dcat:distribution ?distribution .
                 ?distribution databus:file ?file .
         }
-}
+}" > test.sparql
 ```
 
 ### Download and convert selected data
@@ -67,20 +67,8 @@ In order to download the data we need to pass the query as the _`-s`_ argument.
 
 ```
 java -jar target/databus-client-v2.1-beta.jar \
--s "PREFIX dcat:   <http://www.w3.org/ns/dcat#>
-PREFIX databus: <https://dataid.dbpedia.org/databus#>
-
-SELECT ?file WHERE
-{
-        GRAPH ?g
-        {
-                ?dataset databus:artifact <https://dev.databus.dbpedia.org/tester/testgroup/testartifact> .
-                { ?distribution <http://purl.org/dc/terms/hasVersion> '2023-06-23' . }
-                ?dataset dcat:distribution ?distribution .
-                ?distribution databus:file ?file .
-        }
-}" \
--e "https://dev.databus.dbpedia.org/sparql" \
+-s test.sparql \
+-e https://dev.databus.dbpedia.org/sparql \
 -f nt
 ```
 

SUMMARY.md

@@ -3,12 +3,9 @@
 * [Overview](README.md)
   * [Features](docs/overview/features.md)
 * [Usage](docs/usage/README.md)
-  * [CLI](docs/usage/cli.md)
   * [JAR](docs/usage/jar.md)
-  * [Docker](docs/usage/docker2.md)
+  * [CLI](docs/usage/cli.md)
+  * [Docker](usage/docker.md)
   * [Scala/Java API](docs/usage/api.md)
 * [Examples](docs/examples/README.md)
-  * [Test](docs/examples/exampleCLI.md)
-  *
   * [Loading geocoordinates from Wikipedia into Virtuoso (Docker)](docs/examples/exampleDocker.md)
-  * [Docker Example 2](docs/examples/exampleDocker2.md)

docs/examples/exampleCLI.md

@@ -1,20 +1,25 @@
 # Usage
 
-## Download Queries
+## Databus Client Parameters
 
-Various datasets are registered on the DBpedia Databus in the form of files. A download query specifies an exact selection of these records of the [DBpedia Databus](https://databus.dbpedia.org/) to be processed by the Databus Client. Therefore, the download query is one of, if not the most important parameter of the client.
+<table><thead><tr><th width="322.3333333333333">Option</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td>-s, --source</td><td>Set the source you want to convert. A source can either be a <code>[file/directory]</code> to convert already existing files, or a <code>[query file/query string/collection URI]</code> to convert queried files. Notice that query files must have <code>.sparql</code>/<code>.query</code> as extension to be recognized.</td><td></td></tr><tr><td>-e, --endpoint</td><td>Set the sparql endpoint, where the query should be fired to. If you use a collection you don't need this parameter, because its detected automatically. Otherwise its mandatory.</td><td></td></tr><tr><td>-t, --target</td><td>Set the target directory for converted files</td><td><code>./files/</code></td></tr><tr><td>-c, --compression</td><td>Set the compression format of the output file</td><td><code>same</code></td></tr><tr><td>-f, --format</td><td>Set the file format of the output file</td><td><code>same</code></td></tr><tr><td>-m, --mapping</td><td>Set the mapping file for format-conversion to different format equivalence class</td><td></td></tr><tr><td>-d, --delimiter</td><td>Set the delimiter (only necessary for some formats)</td><td>,</td></tr><tr><td>-q, --quotation</td><td>Set the quotation (only necessary for some formats)</td><td>"</td></tr><tr><td>--createMapping</td><td>Do you want to create mapping files for mapped sources?</td><td>false</td></tr><tr><td>-g, --graphURI</td><td>Set the graph uri for mapping from rdf triples to rdf quads</td><td></td></tr><tr><td>-b, --baseURI</td><td>set the base URI to resolve relative URIs</td><td></td></tr><tr><td>-o, --overwrite</td><td>true -> overwrite files in cache, false -> use cache</td><td><code>true</code></td></tr><tr><td>--clear</td><td>true -> clear Cache</td><td><code>false</code></td></tr><tr><td>--help</td><td>Show this message</td><td></td></tr></tbody></table>
+
+## Queries
+
+Various datasets are registered on the DBpedia Databus in the form of files. A query specifies an exact selection of these records of the [DBpedia Databus](https://databus.dbpedia.org/) to be processed by the Databus Client. Therefore, the query is one of, if not the most important parameter of the client.
 
 ### Possible queries
 
-You can pass any query that selects the object of the predicate `dcat:downloadURL`, the name of the variable does not matter. The query should look like.\
-`SELECT ?o WHERE { ?s dcat:downloadURL ?o}`
+You can pass any query that selects the object of the predicate `databus:file`, the name of the variable does not matter. The query should look like.\
+`SELECT ?o WHERE { ?s databus:file ?o}`
 
 ### How to pass queries
 
 There are three different ways to pass a query to the Databus Client:
 
 1. Pass the query string directly as a parameter.
+   * **Note:** this option does not work for [cli.md](cli.md "mention")
 2. Save the query in a file and pass the file path as a parameter.
    * The file extension of the query file must be `.sparql` or `.query`.
 3. Collection URIs are also supported. The client receives the associated query itself.
-   * e.g. `https://databus.dbpedia.org/jfrey/collections/id-management_links`
+   * e.g. [https://dev.databus.dbpedia.org/testuser/collections/testcollection/](https://dev.databus.dbpedia.org/testuser/collections/testcollection/)

docs/examples/exampleDocker2.md

@@ -1,8 +1,31 @@
-# Quickstart - API
+# Scala/Java API
 
-The Databus Client also offers an [API](https://github.com/dbpedia/databus-client/blob/master/src/main/scala/org/dbpedia/databus/client/api/DatabusClient.scala) for easy integration into your project.
+The Databus Client also offers an [API](../../src/main/scala/org/dbpedia/databus/client/api/DatabusClient.scala) for easy integration into your project. Currently i\
+Currently there is no entry on mvn central for the Databus Client. But you can include the jar of the latest release in your project.
+
+## Installation
+
+#### download jar file
+
+* Download the `databus-client.jar` of the latest [Databus Client release](https://github.com/dbpedia/databus-client/releases/latest)
+* Move the file to `${project.basedir}/src/main/resources/databus-client.jar`
+
+#### include dependency (example for maven)
+
+```
+<dependency>
+    <groupId>com.sample</groupId>
+    <artifactId>sample</artifactId>
+    <version>1.0</version>
+    <scope>system</scope>
+    <systemPath>${project.basedir}/src/main/resources/databus-client.jar</systemPath>
+</dependency>
+```
+
+### Execution
+
+After you included the DatabusClient dependency, you can use it in your application.
 
-## Example 
 ```
 DatabusClient
     .source("./src/query/query1")
@@ -12,6 +35,6 @@ DatabusClient
     .execute()
 ```
 
-## Sample project
+## Sample project (outdated)
 
-We have also created a [sample project](https://github.com/dbpedia/databus-client/tree/master/examples/sample_project) that shows how the Databus Client can be integrated into a project.
+We have also created a [sample project](https://github.com/dbpedia/databus-client/tree/master/examples/sample\_project) that shows how the Databus Client can be integrated into a project.

docs/usage/README.md

@@ -2,6 +2,11 @@
 
 ## DBpedia Databus Client
 
+### Requirements
+
+* **Java:** `JDK 8` or `JDK 11`
+* Maven: `^3.6`
+
 ### Installation
 
 ```
@@ -12,8 +17,35 @@ mvn clean install
 
 ### Execution example
 
+#### Select Query
+
+First we need to specify, the data we want to download.
+
+**Note:** _It is best practice to write a query to a file and pass this file as source, instead of passing the query directly as a string._
+
+<pre><code><strong>echo "PREFIX dcat:   &#x3C;http://www.w3.org/ns/dcat#>
+</strong>PREFIX databus: &#x3C;https://dataid.dbpedia.org/databus#>
+
+SELECT ?file WHERE
+{
+        GRAPH ?g
+        {
+                ?dataset databus:artifact &#x3C;https://dev.databus.dbpedia.org/tester/testgroup/testartifact> .
+                { ?distribution &#x3C;http://purl.org/dc/terms/hasVersion> '2023-06-23' . }
+                ?dataset dcat:distribution ?distribution .
+                ?distribution databus:file ?file .
+        }
+}" > query.sparql 
+</code></pre>
+
+#### Execute Client
+
 ```
-bin/DatabusClient -s ./src/resources/queries/example.sparql -f jsonld -c gz
+bin/DatabusClient \
+-s query.sparql \
+-e https://dev.databus.dbpedia.org/sparql
+-f jsonld \
+-c gz
 ```
 
 You will find more information if you set the flag`-h` or in [CLI usage](cli.md).
@@ -27,32 +59,14 @@ The converter and downloader of the Databus Client can be used separately.
 Since the parameters `compression` and `format` both have the default value `equal`, the Databus Client is a pure downloader if you do not pass any arguments for compression and format.
 
 ```
-bin/DatabusClient -s ./src/resources/queries/example.sparql
+bin/DatabusClient -s query.sparql
 ```
 
 ### Compression and format converter
 
 If you select already existing files as the `source`, the client does not use the download module and behaves like a pure converter.
 
 ```
-bin/DatabusClient -s ./src/test/resources/databus-client-testbed/format-testbed/2019.08.30/ -f ttl -c gz
+bin/DatabusClient -s query.sparql -f ttl -c gz
 ```
 
-## CLI options
-
-| Option            | Description                                                                                                                                                                                                                                                                      | Default    |
-| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
-| -s, --source      | Set the source you want to convert. A source can either be a `[file/directory]` to convert already existing files, or a `[query file/query string/collection URI]` to convert queried files. Notice that query files must have `.sparql`/`.query` as extension to be recognized. |            |
-| -t, --target      | Set the target directory for converted files                                                                                                                                                                                                                                     | `./files/` |
-| -c, --compression | Set the compression format of the output file                                                                                                                                                                                                                                    | `same`     |
-| -f, --format      | Set the file format of the output file                                                                                                                                                                                                                                           | `same`     |
-| -m, --mapping     | Set the mapping file for format-conversion to different format equivalence class                                                                                                                                                                                                 |            |
-| -d, --delimiter   | Set the delimiter (only necessary for some formats)                                                                                                                                                                                                                              | ,          |
-| -q, --quotation   | Set the quotation (only necessary for some formats)                                                                                                                                                                                                                              | "          |
-| --createMapping   | Do you want to create mapping files for mapped sources?                                                                                                                                                                                                                          | false      |
-| -g, --graphURI    | Set the graph uri for mapping from rdf triples to rdf quads                                                                                                                                                                                                                      |            |
-| -b, --baseURI     | set the base URI to resolve relative URIs                                                                                                                                                                                                                                        |            |
-| -o, --overwrite   | true -> overwrite files in cache, false -> use cache                                                                                                                                                                                                                             | `true`     |
-| --clear           | true -> clear Cache                                                                                                                                                                                                                                                              | `false`    |
-| --help            | Show this message                                                                                                                                                                                                                                                                |            |
-

docs/usage/api.md

@@ -1,12 +1,44 @@
 # JAR
 
-Instead of cloning the whole repository, you can only download the`databus-client.jar` of the latest [Databus Client release](https://github.com/dbpedia/databus-client/releases/latest). 
+Instead of cloning the whole repository, you can only download the `databus-client.jar` of the latest [Databus Client release](https://github.com/dbpedia/databus-client/releases/latest). 
 
-The parameter options are similar to these ones shown in [#cli-options](cli.md#cli-options "mention")
+The parameter options are shown in [#databus-client-parameters](./#databus-client-parameters "mention")
 
-### Execution example
+### Requirements
+
+* **Java:** `JDK 11`
+
+## Execution example
+
+### Select Data
+
+First we need to specify, the data we want to download.
+
+**Note:** _It is best practice to write a query to a file and pass this file as source, instead of passing the query directly as a string._
 
 ```
-java -jar databus-client-1.0-SNAPSHOT.jar -s "https://databus.dbpedia.org/rogargon/collections/browsable_core"
+echo "PREFIX dcat:   <http://www.w3.org/ns/dcat#>
+PREFIX databus: <https://dataid.dbpedia.org/databus#>
+
+SELECT ?file WHERE
+{
+        GRAPH ?g
+        {
+                ?dataset databus:artifact <https://dev.databus.dbpedia.org/tester/testgroup/testartifact> .
+                { ?distribution <http://purl.org/dc/terms/hasVersion> '2023-06-23' . }
+                ?dataset dcat:distribution ?distribution .
+                ?distribution databus:file ?file .
+        }
+}" > query.sparql
 ```
 
+### Download and Convert Data
+
+Then we can download the selected data, and convert it to ntriple files.
+
+```
+java -jar databus-client.jar \
+-s "query.sparql" \
+-e "https://dev.databus.dbpedia.org/sparql" \
+-f nt
+```