From c6703c96288333498846f71e79a5c532cc23e4c6 Mon Sep 17 00:00:00 2001 From: Torsten Friebe <torsten.friebe@gmail.com> Date: Thu, 1 Feb 2024 21:04:55 +0100 Subject: [PATCH] XPLANBOX-2624 updated user manual to reworked XPlanCLI Tools --- .../src/main/asciidoc/XPlanCLITools.adoc | 15 ++++ .../src/main/asciidoc/XPlanManager.adoc | 4 +- .../src/main/asciidoc/XPlanManager_CLI.adoc | 76 +++++++------------ .../src/main/asciidoc/XPlanTransform_CLI.adoc | 4 +- .../src/main/asciidoc/XPlanValidator.adoc | 4 +- .../src/main/asciidoc/XPlanValidator_CLI.adoc | 48 +++++------- .../src/main/asciidoc/index.adoc | 2 +- 7 files changed, 66 insertions(+), 87 deletions(-) create mode 100644 xplan-documentation/xplan-benutzerhandbuch/src/main/asciidoc/XPlanCLITools.adoc diff --git a/xplan-documentation/xplan-benutzerhandbuch/src/main/asciidoc/XPlanCLITools.adoc b/xplan-documentation/xplan-benutzerhandbuch/src/main/asciidoc/XPlanCLITools.adoc new file mode 100644 index 0000000000..257886ba00 --- /dev/null +++ b/xplan-documentation/xplan-benutzerhandbuch/src/main/asciidoc/XPlanCLITools.adoc @@ -0,0 +1,15 @@ +[[xplanclitools]] +== XPlanCLI Tools + +Die Hilfe für das XPlanCLI kann mit `xpb --help` aufgerufen werden. Das XPlanCLI unterstützt verschiedene Kommandos und die allgemeine Syntax ist: `xpb [options] <command> <subcommand> [parameters]`. +Folgende Kommandos werden unterstützt: `validate, manage, admin`. +Globale Optionen sind: + +- `workspace`: Pfad zum deegree Workspace `DEEGREE_WORKSPACE_ROOT` Verzeichnis +- `config`: Pfad zum `XPLAN_CONFIG` Verzeichnis + +include::XPlanValidator_CLI.adoc[] + +include::XPlanManager_CLI.adoc[] + +include::XPlanTransform_CLI.adoc[] \ No newline at end of file diff --git a/xplan-documentation/xplan-benutzerhandbuch/src/main/asciidoc/XPlanManager.adoc b/xplan-documentation/xplan-benutzerhandbuch/src/main/asciidoc/XPlanManager.adoc index 0b048227c3..7c1930f19c 100644 --- a/xplan-documentation/xplan-benutzerhandbuch/src/main/asciidoc/XPlanManager.adoc +++ b/xplan-documentation/xplan-benutzerhandbuch/src/main/asciidoc/XPlanManager.adoc @@ -5,6 +5,4 @@ include::XPlanManager_Grundlagen.adoc[] include::XPlanManager_Web.adoc[] -include::XPlanManager_API.adoc[] - -include::XPlanManager_CLI.adoc[] \ No newline at end of file +include::XPlanManager_API.adoc[] \ No newline at end of file diff --git a/xplan-documentation/xplan-benutzerhandbuch/src/main/asciidoc/XPlanManager_CLI.adoc b/xplan-documentation/xplan-benutzerhandbuch/src/main/asciidoc/XPlanManager_CLI.adoc index ef46de7b12..127656b9ca 100644 --- a/xplan-documentation/xplan-benutzerhandbuch/src/main/asciidoc/XPlanManager_CLI.adoc +++ b/xplan-documentation/xplan-benutzerhandbuch/src/main/asciidoc/XPlanManager_CLI.adoc @@ -1,22 +1,12 @@ [[xplanmanager-cli]] === XPlanManagerCLI -Die Komponente XPlanManagerCLI ist ein Kommandozeilenwerkzeug, welches -dem Fachadministrator der xPlanBox ermöglicht, die Datenhaltung zu -kontrollieren. Dabei ist das Kommandozeilenwerkzeug in der Lage, -XPlanGML-Dokumente in die Datenhaltung zu Laden, zu Löschen, -Listenausgaben zu erzeugen sowie Service-Metadaten für den XPlanWerkWMS zu erzeugen. +Mit den XPlanCLI `manage` Kommando können XPlanGML-Dateien und XPlanArchive in die XPlanDB verwaltet werden, sowie Service-Metadaten für den XPlanWerkWMS zu erzeugt werden. [[xplanmanager-cli-benutzungsanleitung]] ==== Benutzungsanleitung -Beim XPlanManagerCLI handelt es sich um ein Kommandozeilenwerkzeug, das -parametrisiert aufgerufen wird. Da diese Anwendung bei der Installation -in die PATH Variable aufgenommen wird, ist diese von einem beliebigen -Ort aufrufbar. - -Das Basisverzeichnis mit dem Workspace `xplan-manager-workspace` muss über -die Umgebungsvariable _DEEGREE_WORKSPACE_ROOT_ gesetzt werden. +Das Kommando wird mit `xpb manage [COMMAND]` aufgerufen. [[xplanmanager-cli-konfiguration-ueber-datei]] ===== Konfiguration über Datei @@ -34,50 +24,38 @@ Konfigurationsdatei in dem referenzierten Verzeichnis befinden. ===== Hilfe Die Hilfe mit den Angaben zu den möglichen Eingabeparametern lässt sich -mit dem Parameter `help` ausgeben. +mit dem Kommando `help` ausgeben. Aufruf: ---- -./XPlanManager --help +xpb manage help ---- Ausgabe: ---- -Usage: XPlanManager <options> - - --help - --list - --import <xplanarchiv> [<xplanarchiv>..] [--force] [--crs=<CRS>] - <xplanarchiv> Die absolute oder relative Referenz auf den Plan, der importiert werden soll (verpflichtend). Mehrere Plaene koennen durch ein Leerzeichen getrennt angegeben werden. - --force Erzwingen des Imports eines Plans mit Geomtriefehlern oder Validierungsfehlern (optional). EMPFOHLEN ist die Behebung der Fehler! - --crs Angabe des Koordinatenreferenzsystems in dem die Daten vorliegen (optional). - --export <planid> [<planid>..] [--target=<verzeichnis>] - <planid> Die ID des Plans der exportiert werden soll (verpflichtend). Mehrere IDs koennen durch ein Leerzeichen getrennt angegeben werden. - --target Angabe des Verzeichnis in dem die exportierten XPlanArchive abgelegt werden sollen (optional). - --delete <planid> [<planid>..] - <planid> Die ID des Plans der geloescht werden soll (verpflichtend). Mehrere IDs koennen durch ein Leerzeichen getrennt angegeben werden. - --createMetadata <planid> [<planid>..] - <planid> Die ID des Plans zu dem der Service-Metadatensatz generiert werden soll (optional). Mehrere IDs koennen durch ein Leerzeichen getrennt angegeben werden. Wenn keine ID angegeben ist, werden fuer alle Plaene Metadatensaetze erstellt. - -Allgemeine Parameter: - --v Ausgabe der Systemeigenschaften - -Allgemeine Hinweise: - Das Verzeichnis in dem die Konfigurationsdatei managerConfiguration.properties liegt, muss durch Angabe des Verzeichnis in der Datei etc/application.properties oder durch Setzen der Umgebungsvariablen _XPLANBOX_CONFIG_ erfolgen. Andernfalls wird die Konfiguration aus etc/managerConfiguration.properties verwendet. - Der Workspace `xplan-manager-workspace` muss im Verzeichnis _.deegree/_ des Home-Verzeichnis des Nutzers liegen, der das XPlanManagerCLI aufruft. Alternativ kann das Verzeichnis, in dem der Workspace liegt, durch Angabe der Umgebungsvariablen _DEEGREE_WORKSPACE_ROOT_ gesetzt werden. +Usage: xpb manage [COMMAND] +Manage plans +Commands: + help Display help information about the specified command. + list List all plans that are available in the data storage. + import Import a single or multiple XPlanArchive(s) or XPlanGML file + (s). + export Export a single or multiple plan(s). + delete Delete a single or multiple plan(s). + create-metadata Create service metadata records. ---- [[xplanmanager-cli-auflistung]] ===== Auflistung -Der Parameter `list` gibt die Liste der Pläne aus, die im XPlanManager importiert sind. +Das Kommando `list` gibt die Liste der Pläne aus, die im XPlanManager importiert sind. Aufruf: ---- -./XPlanManager --list +xpb manage list ---- Beispiel Ausgabe: @@ -98,15 +76,15 @@ Anzahl Plaene: 24 [[xplanmanager-cli-import]] ===== Import -Ein Import kann durch Angabe des Parameters `import` gefolgt vom Pfad -zum XPlanArchiv angestoßen werden. Bei dem Import können +Ein Import kann durch das Kommando `import`, gefolgt vom Pfad +zum XPlanArchiv, angestoßen werden. Bei dem Import können XPlanGML-Vektordaten und XPlanGML-Rasterdaten ohne zusätzlichen Parameter in die Datenhaltung geladen werden. Mehrere Pläne können durch Leerzeichen getrennt angegeben werden. Beispiel Aufruf: ---- -./XPlanManager --import ../Input-Planverzeichnis/Infrastruktur.zip +xpb manage import planwerk.zip ---- Während des Imports finden zahlreiche Konsistenz- und @@ -131,7 +109,7 @@ CAUTION: Bitte beachten Sie, dass dabei vorliegenden Geometriefehler o.ä. über Auswirkungen können von einer fehlerhaften Darstellung des Plans bis hin zu unerwarteten Verhalten der xPlanBox reichen. ---- -./XPlanManager --import --force ../Input-Planverzeichnis/Infrastruktur.zip +xpb import --force planwerk.zip ---- _-–crs_ @@ -142,7 +120,7 @@ dieses mit dem Parameter `crs` übergeben werden. Beispiel Aufruf: ---- -./XPlanManager --import ../Input-Planverzeichnis/Infrastruktur.zip --crs=EPSG:25832 +xpb manage import planwerk.zip --crs=EPSG:25832 ---- Beispiel Ausgabe für erfolgreichen Import @@ -184,7 +162,7 @@ Die Prüfung beinhaltet das CRS des Rasterplans, sowie das Format. Beispiel Aufruf: ---- -./XPlanManager --import ~/test-data/BPlan002_5-2.zip +xpb import planwerk.zip ---- Beispiel Ausgabe: @@ -218,14 +196,14 @@ Aufgrund invalider Rasterdaten wird der Import abgebrochen. Sie können den Impo [[xplanmanager-cli-export]] ===== Export -Der Export eines Planes erfolgt unter Angabe des Parameters `export` +Der Export eines Planes erfolgt mit dem Kommando `export`, gefolgt von der PlanID (diese kann zuvor mit dem Parameter `list` herausgefunden werden) und dem Ausgabeverzeichnis. Mehrere PlanIDs können durch Leerzeichen getrennt angegeben werden. Beispiel Aufruf: ---- -./XPlanManager --export 9 --target=outputverzeichnis +xpb manage export 9 --target=../ausgabeverzeichnis ---- Beispiel Ausgabe für erfolgreichen Export: @@ -238,13 +216,13 @@ Plan 9 wurde nach 'xplan-exported-9.zip' exportiert. [[xplanmanager-cli-loeschen]] ===== Löschen -Beim Löschen wird dem Parameter `delete` die PlanID (diese kann zuvor mit +Beim Löschen wird dem Kommando `delete` die PlanID (diese kann zuvor mit `list` herausgefunden werden) übergeben. Mehrere PlanIDs können durch Leerzeichen getrennt angegeben werden. Beispiel Aufruf: ---- -./XPlanManager --delete 21 +xpb manage delete 21 ---- Beispiel Ausgabe: @@ -268,7 +246,7 @@ Für einzelne Pläne können Metadatensätze durch Angabe der PlanID (diese kann Beispiel Aufruf: ---- -./XPlanManager --createMetadata 1 +xpb manage create-metadata 1 ---- [[xplanmanager-cli-troubleshooting]] diff --git a/xplan-documentation/xplan-benutzerhandbuch/src/main/asciidoc/XPlanTransform_CLI.adoc b/xplan-documentation/xplan-benutzerhandbuch/src/main/asciidoc/XPlanTransform_CLI.adoc index fc23267902..c0cccab42a 100644 --- a/xplan-documentation/xplan-benutzerhandbuch/src/main/asciidoc/XPlanTransform_CLI.adoc +++ b/xplan-documentation/xplan-benutzerhandbuch/src/main/asciidoc/XPlanTransform_CLI.adoc @@ -7,7 +7,7 @@ Die transformierten Pläne können entweder syntaktisch validiert und das Validi NOTE: Unterstützt wird derzeit die Transformation von XPlanGML 4.1 nach XPlanGML 5.1 -IMPORTANT: Das XPlanTransformCLI ist veraltet und wird in zukünftigen Versionen der xPlanBox entfernt +IMPORTANT: Das XPlanTransformCLI ist veraltet und wird in zukünftigen Versionen der xPlanBox entfernt! [[xplantransform-cli-installation]] === Installation @@ -62,4 +62,4 @@ Beispiel für das initiale Einspielen der in XPlanGML 4.1 vorliegenden Pläne in ./XPlanTransformCLI --type ALL ------- -Empfohlen ist zunächst einmalig die Ausführung der Option *ALL* und anschließend regelmäßig (z. B. nachts mit Hilfe eines Cron-Jobs) die Option *SYNC* um einen tagesaktuellen Stand der über den XPlanWFS 5.1 anfragbaren Pläne zu erreichen. +Empfohlen ist zunächst einmalig die Ausführung der Option *ALL* und anschließend regelmäßig (z. B. nachts mit Hilfe eines Cron-Jobs) die Option *SYNC*, um einen aktualisierten Stand der über den XPlanWFS 5.1 anfragbaren Pläne zu erreichen. \ No newline at end of file diff --git a/xplan-documentation/xplan-benutzerhandbuch/src/main/asciidoc/XPlanValidator.adoc b/xplan-documentation/xplan-benutzerhandbuch/src/main/asciidoc/XPlanValidator.adoc index 58c6e4d053..56136b0897 100644 --- a/xplan-documentation/xplan-benutzerhandbuch/src/main/asciidoc/XPlanValidator.adoc +++ b/xplan-documentation/xplan-benutzerhandbuch/src/main/asciidoc/XPlanValidator.adoc @@ -8,6 +8,4 @@ include::XPlanValidator-Einleitung.adoc[] include::XPlanValidator_Web.adoc[] -include::XPlanValidator_API.adoc[] - -include::XPlanValidator_CLI.adoc[] \ No newline at end of file +include::XPlanValidator_API.adoc[] \ No newline at end of file diff --git a/xplan-documentation/xplan-benutzerhandbuch/src/main/asciidoc/XPlanValidator_CLI.adoc b/xplan-documentation/xplan-benutzerhandbuch/src/main/asciidoc/XPlanValidator_CLI.adoc index 1c17ccee03..d126d51fa2 100644 --- a/xplan-documentation/xplan-benutzerhandbuch/src/main/asciidoc/XPlanValidator_CLI.adoc +++ b/xplan-documentation/xplan-benutzerhandbuch/src/main/asciidoc/XPlanValidator_CLI.adoc @@ -1,15 +1,12 @@ [[xplanvalidator-cli]] -=== XPlanValidatorCLI +=== XPlanCLI - Validate Kommando -Analog zum XPlanManagerWeb können XPlanGML-Dokumente mit der Komponente XPlanValidatorCLI über ein Kommandozeilenwerkzeug validiert werden. +Mit den XPlanCLI `validate` Kommando können XPlanGML-Dateien und XPlanArchive validiert werden. [[xplanvalidator-cli-benutzungsanleitung]] ==== Benutzungsanleitung -Beim XPlanValidatorCLI handelt es sich um ein Kommandozeilenwerkzeug, das -parametrisiert aufgerufen wird. Da diese Anwendung bei der Installation -in die PATH Variable aufgenommen wird, ist diese von einem beliebigen -Ort aufrufbar. +Das Kommando wird mit `xpb validate [COMMAND]` aufgerufen. [[xplanvalidator-cli-konfiguration-ueber-datei]] ===== Konfiguration über Datei @@ -38,38 +35,31 @@ mit dem Parameter `help` ausgeben. Aufruf: ---- -./XPlanValidator --help +xpb validate help ---- Ausgabe: ---- -Validates XPlanGML files. - -usage: XPlanValidator [-name <arg>] -validate <arg> [-vo <arg>] [-vtype <arg>] - - -name <arg> name of the validation - -validate <arg> zip file path - -vo <arg> validation options, possible values are: - skip-flaechenschluss=true, skip-geltungsbereich=true, - skip-laufrichtung=true. Each value must be passed as - single options, e.g: -vo skip-geltungsbereich=true -vo - skip-laufrichtung=true - -vtype <arg> values: syntax, geometric, semantic. multiple types must - be comma separated +Usage: xpb validate [COMMAND] +Validate a plan or all plans in a database +Commands: + help Display help information about the specified command. + file Validate a XPlanArchive or XPlanGML file. + db Validate XPlanGML in xPlanBox database. ---- [[xplanvalidator-cli-auswahl-planarchiv]] ===== Auswahl XPlanArchiv -Über den Parameter `validate <planarchiv>` kann der Pfad zum XPlanArchiv - auswählt werden, welcher validiert werden soll. Die Angabe +Über das Kommando `validate` und Angabe des Pfads zum XPlanArchiv + kann ausgewählt werden, welches Planwerk validiert werden soll. Die Angabe des Parameters ist obligatorisch. Aufruf: ---- -./XPlanValidator -validate Plan.zip +xpb validate planwerk.zip ---- [[xplanvalidator-cli-bezeichnung-der-validierung]] @@ -82,7 +72,7 @@ Fehlt dieser Parameter, wird der Name des XPlanArchivs verwendet. Aufruf: ---- -./XPlanValidator -validate Plan.zip -name Validierung +xpb validate planwerk.zip -name Report_Planwerk_1 ---- [[xplanvalidator-cli-validierungsart]] @@ -95,7 +85,7 @@ Parameters `-vtype` ist optional. Aufruf: ---- -./XPlanValidator -validate Plan.zip -vtype [syntax|geometric|semantic] +xpb validate planwerk.zip -vtype [syntax|geometric|semantic] ---- Zuordnung der Werte: @@ -152,14 +142,14 @@ Angabe des Parameters `-vo` ist optional. Aufruf: ---- -./XPlanValidator -validate Plan.zip -vo skip-flaechenschluss=true -vo skip-geltungsbereich=true -vo skip-laufrichtung=true +xpb validate planwerk.zip -vo skip-flaechenschluss=true -vo skip-geltungsbereich=true -vo skip-laufrichtung=true ---- Zuordnung der Werte: - * skip-flaechenschluss -> Geometrische Überprüfung der Flächenschlussbedingung (2.2.1.1) überspringen [ja] - * skip-geltungsbereich -> Geometrische Überprüfung des Geltungsbereich (2.2.3.1) überspringen [ja] - * skip-laufrichtung -> Geometrische Überprüfung Laufrichtung (2.2.2.1) überspringen + * `skip-flaechenschluss`: Geometrische Überprüfung der Flächenschlussbedingung (2.2.1.1) überspringen [ja] + * `skip-geltungsbereich`: Geometrische Überprüfung des Geltungsbereich (2.2.3.1) überspringen [ja] + * `skip-laufrichtung`: Geometrische Überprüfung Laufrichtung (2.2.2.1) überspringen [[xplanvalidator-cli-validierungsergebnis]] ===== Validierungsergebnis diff --git a/xplan-documentation/xplan-benutzerhandbuch/src/main/asciidoc/index.adoc b/xplan-documentation/xplan-benutzerhandbuch/src/main/asciidoc/index.adoc index bdc8ae533e..26e67f0cc9 100644 --- a/xplan-documentation/xplan-benutzerhandbuch/src/main/asciidoc/index.adoc +++ b/xplan-documentation/xplan-benutzerhandbuch/src/main/asciidoc/index.adoc @@ -26,7 +26,7 @@ include::XPlanManager.adoc[] include::XPlanDokumentenAPI.adoc[] -include::XPlanTransform_CLI.adoc[] +include::XPlanCLITools.adoc[] include::XPlanWMS.adoc[] -- GitLab