\chapter{Kommandozeilenschnittstelle}
\label{ch:cli-spec}

\section{Anwenderschnittstelle}
\label{sec:entrypoints}\label{sec:cli}

  \later{Use Cases (UML)}

WikiWord wird über eine klassische Kommandozeilenschnittstelle (\lingo{Command Line Interface, CLI}) bedient. Zur Extraktion eines Thesaurus aus Wikipedia-Dumps werden insbesondere die folgenden Programme (\lingo{Entry Points}) verwendet.% (\rrr[Abb.]{abb:usecases} zeigt ihre Abhängigkeiten):

\begin{description}
 \item[\cli{ImportConcepts}] liest Seiten aus einem Wikipedia-Dump, analysiert den Wiki-Text (\rr{transform:analyse}), überführt ihn zunächst in das Ressourcenmodell und dann weiter in einen lokalen Datensatz (\rr{transform:import}). Dieser Schritt ist der erste, der auf dem Weg zu einem Thesaurus für jeden Wikipedia-Dump ausgeführt werden muss.
 \item[\cli{BuildThesaurus}] führt die einzelnen lokalen Datensätze zusammen und erzeugt damit einen globalen Datensatz (\rr{transform:zusammenfuehren}). Dieser Schritt setzt natürlich voraus, dass die entsprechenden Dumps bereits importiert wurden. 
 \item[\cli{BuildStatistics}] berechnet Statistiken auf einem lokalen oder globalen Datensatz (\rr{sec:BuildStatistics}). Dabei werden vor allem die Knotengrade im Term-Konzept-Graphen auf ihre Verteilung hin untersucht. Das setzt voraus, dass die betreffenden lokalen Daten bereits importiert wurden \bzw der globale Datensatz bereits erstellt wurde.
 \item[\cli{BuildConceptInfo}] fasst die Eigenschaften und Relationen jedes Konzeptes in einem lokalen oder globalen Datensatz für einen effizienten Zugriff zusammen (\rr{sec:BuildConceptInfo}). Das setzt voraus, dass die Statistiken für den betreffenden Datensatz bereits erstellt wurden.
 \item[\cli{ExportRdf}] Erzeugt eine Repräsentation des Thesaurus in RDF/SKOS (\rr{model:thesaurus}). Dieser Schritt setzt voraus, dass die betreffenden lokalen Daten bereits importiert wurden \bzw der globale Datensatz bereits erstellt wurde.
\end{description}

Die Parameter und Optionen für den Aufruf der einzelnen Programme werden im Anhang  beschrieben (\rr{sec:cli-parameter}). Weitere Möglichkeiten zur Konfiguration bieten die sogenannten \lingo{Tweak-Werte}, siehe \rr{sec:tweaks}.

Die Durchführung aller Aufgaben wird über das \nom{Agenda}-System kontrolliert und protokolliert (siehe \rrr[Anhang]{sec:agenda}). Dadurch ist es einerseits möglich, den genauen Zeitaufwand einzelner Teilaufgaben zu ermitteln sowie andererseits unterbrochene Berechnungen wieder aufzunehmen. Das ist insbesondere deshalb wichtig, weil die Verarbeitung großer Datenmengen, wie zum Beispiel der englischsprachigen Wikipedia, mitunter mehrere Tage dauern kann.

Für das Erstellen eines Thesaurus werden die Programme \cli{BuildStatistics} und \cli{BuildConceptInfo} nicht benötigt --- es ist ausreichend, die Wiki-Dumps mit \cli{ImportConcepts} zu importieren, mit \cli{BuildThesaurus} zusammenzufassen und dann mit \cli{ExportRdf} zu exportieren. Die von \cli{BuildStatistics} generierten Statistiken können aber bei der weiteren Verarbeitung des Thesaurus nützlich sein, zum Beispiel für die Gewichtung \bzw das Ranking von Konzepten. Die Daten, die \cli{BuildConceptInfo} zur Verfügung stellt, werden immer dann benötigt, wenn nicht der Thesaurus als Ganzes, sondern einzelne Konzepte (oder kleine Mengen von Konzepten) verarbeitet werden sollen --- insbesondere also bei der Evaluation (\rr{ch:eval-import}).

\section{Parameter und Optionen}
Die möglichen Parameter und Optionen für den Aufruf von WikiWord-Programmen sind:
\label{sec:cli-parameter}
\begin{description}
  \item[\cliv{Kollektion}:] Name der Kollektion von Datensätzen. Dieser Name wird zur Bestimmung des Präfixes für die zu verwendenden Datenbanktabellen benutzt (siehe \rr{p:db-prefix}). Wird typischerweise als erstes Glied in einem Paar von \cli{\cliv{Kollektion}:\cliv{Datensatzname}} angegeben.
  \item[\cliv{Datensatzname}:] Name des zu bearbeitenden (lokalen oder globalen) Datensatzes. Dieser Name wird zur Bestimmung des Präfixes für die zu verwendenden Datenbanktabellen benutzt (siehe \rr{p:db-prefix}). Wird typischerweise als zweites Glied in einem Paar von \cli{\cliv{Kollektion}:\cliv{Datensatzname}} angegeben.
  \item[\cliv{Wikiname}:] Ein \cliv{Datensatzname} eines lokalen Datensatzes --- in der Regel wird hier ein Sprach-Code nach ISO 639-1 erwartet \q{ISO:639-1}.
  \item[\cliv{Thesaurusname}:] Ein \cliv{Datensatzname} eines globalen Datensatzes. 
  \item[\cliv{Datenbank-Konfigurationsdatei}:] eine Datei, die die Zugangsdaten für die Datenbankverbindung enthält (siehe \rr{sec:db-config}).
  \item[\cliv{Dump-Datei}:] ein Wikipedia XML-Dump, wie in \q{MW:XML} beschrieben und auf \q{WM:DOWNLOAD} verfügbar. Die angegebene Datei wird mit der Klasse \javaid{DumpImportDriver} verarbeitet (\rr{sec:frameworkklassen}), die ihrerseits die \javaid{mwdumper}-Bibliothek von Wikimedia verwendet \q{MW:DUMPER}.
   \item[\cliv{RDF-Datei}:] ein RDF-Datei für die Ausgabe des Thesaurus \rr{sec:rdf}.
   \item[\cliv{Sprachen}:] eine Liste von Sprach-Codes, separiert durch Kommata ("`,"').
      
  Aus dem Dateinamen wird automatisch auf den Wiki-Namen geschlossen, und damit auf den zu verwendenden Tabellenpräfix (siehe \rr{p:db-prefix}): Der Teil des Namens vor dem ersten "`-"' und vor dem ersten "`."' wird als Wiki-Name angenommen. Der automatisch erkannte Name kann mit der Option \cli{{--}{--}dataset} überschrieben werden.
  
  Die angegebene XML-Datei kann mit GZip oder BZip2 komprimiert sein (dann muss der Dateiname auf "`\cli{.gz}"' \bzw "`\cli{.bz2}"' enden). Beginnt der Dateiname mit "`\cli{http://}"' so wird der Dump direkt per HTTP geladen und verarbeitet --- das ist vor allem im Testbetrieb nützlich und sollte nicht für große Datenmengen verwendet werden. 
%  \item[\cli{{--}{--}collection \cliv{N}}:] bestimmt den Namen \cliv{N} der Kollektion, auf der gearbeitet werden soll. Dieser Name wird zur Bestimmung des Präfixes für die zu verwendenden Datenbanktabellen benutzt (siehe \rr{p:db-prefix}). Falls nicht angegeben, wird die Default-Kollektion verwendet (also ohne Präfix gearbeitet).
%  \item[\cli{{--}{--}dataset \cliv{N}}:] überschreibt den automatisch erkannten Namen des zu bearbeitenden Datensatzes mit dem Namen \cliv{N}. Dieser Name wird zur Bestimmung des Präfixes für die zu verwendenden Datenbanktabellen benutzt (siehe \rr{p:db-prefix}). Falls nicht angegeben, wird der Name des Datensatzes aus dem Namen der Dump-Datei bestimmt.
  \item[\cli{{--}{--}loglevel \cliv{L}}:] bestimmt den Log-Level \cliv{L}, also die Menge und Granularität von angezeigten Nachrichten. Der Wert muss eine positive ganze Zahl sein; Nachrichten, deren Level größer oder gleich dem hier angegebenen Level ist, werden angezeigt. Vordefinierte Werte (übernommen aus der Standardklasse \javaid{java.util.logging.Level}) sind 0 (\nospell{All}), 400 (\nospell{Trace}), 500 (\nospell{Debug}), 800 (\nospell{Info}), 900 (\nospell{Warnung}) und 1000 (\nospell{Fehler}). Der Standard-Wert ist 800.
  \item[\cli{{--}{--}db \cliv{F}}:] verweist auf die Datei \cliv{F}, die die Spezifikation der Datenbankverbindung enthält (\rr{sec:db-config}). Falls nicht angegeben, wird die Datei an vier Orten gesucht: \cli{/etc/wikiword/db.properties}, \cli{/etc/wikiword.db.properties}, \cli{\cliv{HOME}/.wikiword/db.properties} und \cli{\cliv{HOME}/.wikiword.db.properties}. Wenn keine solche Datei gefunden werden konnte, kann keine Datenbankverbindung aufgebaut werden.
  \item[\cli{{--}{--}tweaks \cliv{F}}:] verweist auf eine Datei \cliv{F}, aus der zusätzliche Konfigurationsparameter (\textit{Tweaks}) geladen werden sollen (siehe \rr{sec:tweaks}). Falls nicht angegeben, wird die Datei an vier Orten gesucht: \cli{/etc/wikiword/tweaks.properties}, \cli{/etc/wikiword.tweaks.properties}, \cli{\cliv{HOME}/.wikiword/tweaks.properties} und \cli{\cliv{HOME}/.wikiword.tweaks.properties}. Wenn keine solche Datei gefunden werden konnte, werden Default-Werte verwendet.
  \item[\cli{{--}{--}tweak.\cliv{NNN}=\cliv{VVV}}:] setzt die Tweak-Option \cliv{NNN} auf den Wert \cliv{VVV}. So definierte Optionen überschreiben solche, die aus einer mit \cli{{--}{--}tweaks} angegebenen Datei geladen wurden.
  \item[\cli{{--}{--}fresh, {--}{--}continue}:] erzwingen den Neustart \bzw das Fortsetzen eines unterbrochenen Vorgangs (\rr{sec:agenda}). Das heißt, sie unterdrücken die Rückfrage, die bei Aufruf des Programms gestellt wird, wenn erkannt wurde, das der vorherige Aufruf nicht korrekt beendet wurde.
\end{description}

\section{Aufruf der einzelnen Programme}
\label{sec:cli-call}

\begin{description}
 \item[\javaid{ImportConcepts}] liest Seiten aus einem Wikipedia-Dump, analysiert den Wiki-Text (\rr{entwurf:analyse}), überführt ihn zunächst in das Ressourcenmodell und dann weiter in einen lokalen Datensatz (\rr{entwurf:import}). Aufruf:
 
 \cli{\footnotesize > java ImportConcepts [\cliv{Optionen}] <\cliv{Kollektion}:\cliv{Wikiname}> <\cliv{Dump-Datei}>}
% \item[\javaid{ExtractText}] \later{implement, test, document?} \later{synopsis}
 \item[\javaid{BuildThesaurus}] führt die einzelnen lokalen Datensätze zusammen und erzeugt einen globalen Datensatz (\rr{entwurf:zusammenfuehren}). Aufruf:

 \cli{\footnotesize > java BuildThesaurus [\cliv{Optionen}] [{--}{--}languages \cliv{Sprachen}] <\cliv{Kollektion}:\cliv{Thesaurusname}> }
 
 \item[\javaid{BuildStatistics}] berechnet Statistiken auf einem lokalen oder globalen Datensatz (\rr{sec:BuildStatistics}). Aufruf:

 \cli{\footnotesize > java BuildStatistics [\cliv{Optionen}] <\cliv{Kollektion}:\cliv{Datensatzname}>}
 
 \item[\javaid{BuildConceptInfo}] berechnet zusammengefasste Datensätze für einen effizienten Zugriff auf einen lokalen oder globalen Datensatz (\rr{sec:BuildConceptInfo}). Aufruf:

  \cli{\footnotesize > java BuildStatistics [\cliv{Optionen}] <\cliv{Kollektion}:\cliv{Datensatzname}>}

 \item[\javaid{ExportRdf}] Erzeugt (\rr{transform:export}) eine Repräsentation des Thesaurus in SKOS (siehe \rr{ch:export}). Aufruf:
 
  \cli{\footnotesize > java ExportRdf [\cliv{Optionen}] <\cliv{Kollektion}:\cliv{Datensatzname}> <\cliv{RDF-Datei}>  }
  
Dabei unterstützt \cli{ExportRdf} die zusätzliche Option \cli{{--}{--}skos}, die bewirkt, dass möglichst "`reines"' SKOS ausgegeben und auf das WikiWord-Vokabular verzichtet wird. Das kann die Kompatibilität mit bestehenden Systemen verbessern, führt aber dazu, dass weniger Informationen in den Export übernommen werden. Die Option \cli{{--}{--}assoc} dagegen aktiviert die Ausgabe aller "`losen Assoziationen"' zwischen Konzepten, also der \rdfid{ww:assoc}-Relation, die die Hyperlinks zwischen Wiki-Seiten wiedergibt. Für weitere Parameter siehe \rr{export:parameter}.
  
\end{description}

Um den Aufruf der WikiWord-Programme zu erleichtern, insbesondere in Hinblick auf das Auflisten aller benötigten Bibliotheksdateien (\lingo{JAR-Dateien}) in Java-Classpath, steht das \lingo{Shell-Skript} \cli{ww.sh} zur Verfügung. Es wird wie folgt aufgerufen:

\cli{\footnotesize > ww.sh <\cliv{Klassenname}> [<\cliv{parameter}>]}

Dabei kann der Präfix \javaid{de.brightbyte.wikiword.} am Klassennamen weggelassen werden. Das folgende Kommando führt also die Klasse \javaid{de.brightbyte.wikiword.builder.ImportConcepts} aus und importiert die Artikel aus der Datei \cli{enwiki-dump.xml} in den Datensatz \cli{full:en}

\cli{\footnotesize > ww.sh builder.ImportConcepts full:en enwiki-dump.xml}

Das Verhalten von \cli{ww.sh} kann über Konfigurationsdateien angepasst werden. Die folgenden Arten von Konfigurationsvariablen sind möglich:

\begin{itemize}
  \item \textbf{Optionen für die Java-VM} können in den folgenden Dateien angegeben werden: \cli{/etc/wikiword/vm.options}, \cli{/etc/wikiword.vm.options}, \cli{\cliv{HOME}/.wikiword/vm.options} und \cli{\cliv{HOME}/vm.options}. Typischerweise wird hier die zu verwendende Menge an Arbeitsspeicher definiert, indem die Java-VM Option \cli{-Xmx} gesetzt wird, zum Beispiel mit \cli{-Xmx8G}  auf acht Gigabyte, um ausreichend Speicherplatz für eine Verwaltung aller Konzept-IDs zu haben (vergleiche \rr{transform:import-finish}).
  \item \textbf{Optionen für WikiWord} können in den folgenden Dateien angegeben werden: \cli{/etc/wikiword/vm.options}, \cli{/etc/wikiword.vm.options}, \cli{\cliv{HOME}/.wikiword/vm.options} und \cli{\cliv{HOME}/vm.options}.
  \item Der \textbf{Java Classpath} kann in den folgenden Dateien angegeben werden: \cli{/etc/wikiword/classpath}, \cli{/etc/wikiword.classpath}, \cli{\cliv{HOME}/.wikiword/classpath} und \cli{\cliv{HOME}/classpath}. Dabei ist darauf zu achten, dass der Pfad in einer einzigen Zeile angegeben wird, keine Leerzeichen enthält und die einzelnen Elemente durch "`\cli{:}"' getrennt sind.
\end{itemize}

Alle Konfigurationsdateien können selbst auch \lingo{Shell-Skripte} sein: wenn an den Dateinamen die Endung \cli{.sh} angehängt und die Datei als ausführbar markiert ist, ruft \cli{ww.sh} sie als Skript auf und betrachtet den ausgegebenen Text als die zu verwendende Konfiguration. So könnte zum Beispiel \cli{\cliv{HOME}/.wikiword/classpath.sh} ein Skript sein, dass programmatisch einen geeigneten Classpath erzeugt, indem es alle JAR-Dateien in einem bestimmten Verzeichnis auflistet (in einer Zeile, durch "`\cli{:}"' getrennt).

\section{Datenbank-Konfiguration}
\label{sec:db-config}
Die Konfigurationsdatei für den Datenbankzugriff folgt dem Java-Standard für Property-Dateien, wie von der Standard-Java-Klasse \javaid{java.util.Properties} definiert. Sie enthält die folgenden Schlüssel-Wert-Paare:

\begin{description}
  \item[\cli{driver}] ist der Klassenname des zu verwendenden JDBC-Treibers; Für WikiWord sollte das ein Treiber für MySQL sein, entwickelt und getestet wurde WikiWord mit \lingo{jconnector} (Version 3.1), anzugeben als \javaid{com.mysql.jdbc.Driver}.
  \item[\cli{url}] ist eine JDBC-URL \q{JDBC}, die die zu verwendende Datenbank angibt. Das Format der URL muss zu der angegebenen Treiberklasse passen --- für \lingo{jconnector} folgt sie der Form \cli{mysql://\cliv{server}/\cliv{datenbank}?characterEncoding=utf8}, wobei der zu verwendende Zeichensatz immer explizit als "`\cli{utf8}"' angegeben werden sollte.
  \item[\cli{user}] ist der Benutzername für die Datenbankverbindung
  \item[\cli{password}] ist das Passwort für die Datenbankverbindung
\end{description} 

Diese Datei muss entweder im Benutzerverzeichnis unter dem Namen \cli{.wikiword.db.properties} abgelegt oder über die Option \cli{{--}{--}db} explizit angegeben werden.

\later{beispiel}

\section{Konfiguration (Tweaks)}
\label{sec:tweaks}
WikiWord unterstützt diverse Parameter zur Feineinstellung des Import-Prozesses, sogenannte "`\textit{Tweaks}"'; diese dienen vor allem der Anpassung an eine konkrete Systemumgebung (verfügbarer Arbeitsspeicher, Anzahl von Prozessoren, etc). Eine Beispielkonfiguration mit Erläuterungen zu den einzelnen Konfigurationsparametern ist unter \reporef{WikiWord/WikiWordBuilder/tweaks.properties} verfügbar.

Werden die Tweak-Optionen in einer Konfigurationsdatei gespeichert, so dass sie über den Parameter \cli{{--}{--}tweaks} geladen werden können, so gilt für diese Datei die Syntax für Java Property-Dateien, wie von der Standard-Klasse \javaid{java.util.Properties} definiert, mit einer speziellen Syntax für die Werte: diese müssen die Syntax für Java-Literale des entsprechenden Typs verwenden. Insbesondere müssen String-Werte in Anführungszeichen stehen.

\section{Ablaufsteuerung (Agenda)}
\label{sec:agenda}
WikiWord unterteilt die Ausführung in rekursiv geschachtelte Schritte, die mittels der Klasse \javaid{de.brightbyte.application.Agenda} einzeln protokolliert werden. Dieses Protokoll kann dazu verwendet werden, einen Import-Prozess, der unterbrochen wurde, später an der fraglichen Stelle fortzusetzen. 
\later{einzelne funktionen}
\later{beispiel (pseudocode)}

Neben dem Vorzug, langwierige Importprozesse nicht komplett neu starten zu müssen, falls sie unerwartet unterbrochen wurden, erlaubt dieses System auch eine detaillierte Protokollierung darüber, welche Schritte wieviel Zeit in Anspruch nehmen. 

\section{Anpassung an einzelne Wikis}
\label{usage:wiki-config}

WikiWord arbeitet zwar weitgehend Sprachunabhängig, aber es benötigt doch Informationen über die Konfiguration der einzelnen Wikis sowie über Konventionen und Muster, die dort verwendet werden. Diese Wiki-spezifischen Konfigurationen werden im Package \javaid{de.brightbyte.wikiword.wikis} definiert (vergleiche \rr{ch:analyse}). Insbesondere können dort die folgenden Klassen \bzw Dateien angelegt werden:

\begin{description}
  \item[\javaid{LanguageConfiguration_\textit{x}}] dient der Angabe sprachspezifischer Eigenschaften für die Sprache \var{x}. Hier wird insbesondere das Muster definiert, das dazu dient, gebräuchliche Abkürzungen zu erkennen. Diese Information wird für die Erkennung von Satzenden benötigt, siehe \rr{alg:extractFirstSentence}.
  \item[\javaid{WikiConfiguration_\textit{x}wiki}] dient der Angabe projektspezifischer Eigenschaften für \domain{\textit{x}.wikipedia.org}. Die meisten Muster und Sensoren, die zur Analyse des Wiki-Textes (\rr{ch:analyse}) verwendet werden, werden hier definiert. In \rr{sec:analyse:mechanismen} werden die Objekttypen beschrieben, die für die Konfiguration zur Verfügung stehen.
  \item[\javaid{Namespace_\textit{x}wiki.properties}] ist eine Java Property-Datei, die die Namen für die Namensräume in der Sprache \var{x} angibt. Die lokalisierten Namen der Namensräume sind wichtig, um zum Beispiel Wiki-Links auf Bilder identifizieren zu können (\rr{sec:wikitext:links}). Allerdings werden die Namen der Namensräume auch in jedem Wiki-Dump mit angegeben.
\end{description}

Über diese Klassen \bzw Dateien lässt sich WikiWord an verschiedene Sprachen und Wiki-Projekte anpassen.

