Initialisierung der eigenen Anwendung

Die folgende Anleitung geht davon aus, dass eine neue Anwendung mit dem Namen skeleton eingerichtet werden soll.

Installation

1. CLI erstellen

Im Arbeitsverzeichnis wird mit dem Kommando mvn clean install die Skeleton Anwendung erstmals gebaut.

Danach steht im Verzeichnis skeleton-cli/target ein zip bzw. tar.gz für die MyCoRe-Kommandozeile zur Verfügung. Das zip bzw. tar.gz kann nun in einem beliebigen Projektverzeichnis auf dem Anwendungsserver entpackt werden.

Befindet man sich bereits auf dem Server kann man die CLI auch aus dem Verzeichnis skeleton-cli/target/appassembler heraus starten.

2. Konfigurieren

Konfigurationsverzeichnis generieren

Zuerst wechselt man in das CLI-Verzeichnis der gerade entpackten Anwendung, z.B.:

cd c:\...\skeleton\skeleton-cli

und ruft das folgende Kommando auf:

Linux:

bin/skeleton.sh create configuration directory

Windows:

bin\skeleton.bat create configuration directory

Linux:

~/.mycore/skeleton

Windows:

c:\Users\<userName>\AppData\Local\MyCoRe\skeleton\

Es ist darauf zu achten, dass der Name des Konfigurationsverzeichnisses dem Namen der MyCoRe-Anwendung entspricht, in diesem Beispiel also skeleton.

Solr konfigurieren

Für die Suche und Recherche in der Anwendung wird ein Solr-Server benötigt.
Dessen Konfigutation wird im Abschnitt Solr Nutzung ausführlicher beschrieben.

Die beiden benötigten Solr-Cores sollten (wie die Anwendung) skeleton_main und skeleton_classs benannt und mit folgenden Kommandos angelegt werden:

 .../solr/bin/solr create -c skeleton_main -d mycore_main
 .../solr/bin/solr create -c skeleton_class -d mycore_classification

Abschließend wird in der Datei mycore.properties im MyCoRe-Konfigurationsverzeichnis der Core definiert:

  MCR.Solr.ServerURL=http://localhost:8983/
  MCR.Solr.Core.main.Name=skeleton_main
  MCR.Solr.Core.main.ServerURL=%MCR.Solr.ServerURL%
  MCR.Solr.Core.classification.Name=skeleton_class
  MCR.Solr.Core.classification.ServerURL=%MCR.Solr.ServerURL%

Solr im Entwicklermodus (Alternative)

Wer einen Solr-Server nur zur Entwicklungs- oder Demonstrationszwecken nutzen möchte, kann ihn über das MyCoRe Solr-Runner-Maven-Plugin konfigurieren und starten.

Dazu können im skeleton-webpp-Verzeichnis die folgenden Maven Kommandos ausgeführt werden:

  mvn solr-runner:copyHome
  mvn solr-runner:installConfigSet@cs_main
  mvn solr-runner:installConfigSet@cs_classification

Der Solr-Server wird mit mvn solr-runner:start gestartet, später mit mvn solr-runner:stop angehalten und ist über die URL http://localhost:8983/solr/ erreichbar.

Datenbank konfigurieren

Zur Konfiguration der Datenbank muss die Datei resources/META-INF/persistence.xml im MyCoRe-Konfigurationsverzeichnis angepasst werden. Weitere Hinweise dazu befinden sich im Abschnitt Datenbank-JPA.

Soll zu Entwicklungs- und Demonstrationszwecken mit der Datenbank H2 gearbeitet werden, muss die Konfigurationsdatei nicht geändert werden. Dann wird während der folgenden JPA-Konfiguration der Pfad zur H2-Datei im Data-Verzeichnis automatisch gesetzt.

Mit dem folgenden Kommando, das im CLI-Verzeichnis der MyCoRe-Anwendung ausgeführt wird, wird die Datenbank konfiguriert.
Abhängig von den verwendeten MyCoRe-Modulen werden Mappings zu Datenbanktabellen in die Datei persistence.xml eingetragen:

Linux:

bin/skeleton.sh reload mappings in jpa configuration file

Windows:

bin\skeleton.bat reload mappings in jpa configuration file

3. Anwendung initialisieren

Nun können die Klassifikationen, Nutzer und Rechte in die MyCoRe-Anwendung geladen werden. Dazu wird folgendes Kommando verwendet:

Linux:

bin/skeleton.sh process config/setup-commands.txt

Windows:

bin\skeleton.bat process config\setup-commands.txt

Später kann die Datei setup-commands.txt um anwendungsspezifische Nutzer, Rechte und Klassifikationen ergänzt werden.

4. Anwendung deployen

Abschließend wird die Webanwendung online gestellt.

Wenn Änderungen am Source-Code oder Konfiguration vorgenommen worden sind, dann muss die Anwendung nocheinmal im Arbeitsverzeichnis mit dem Kommando mvn clean install neu gebaut werden.

Dadurch wird die Datei skeleton-webapp\target\skeleton-{version}.war erzeugt oder aktualisiert. Diese wird in skeleton.war umbenannt und dann in das \webapps-Verzeichnis des Servlet-Containers (Tomcat) kopiert. Der Servlet-Container entpackt und startet die Anwendung.

Jetty-Webserver im Entwicklermodus (Alternative)

Zu Entwicklungs- und Demonstrationszwecken kann auch ein vorkonfigurierter Jetty-Webserver verwendet werden. Dieser wird im skeleton-webpp-Verzeichnis mit den Maven Kommandos mvn jetty:run gestartet und mit <Strg> + <C> gestoppt.

Herzlichen Glückwunsch!
Ihre MyCoRe-Anwendung ist jetzt online: http://localhost:8080/skeleton

Schritt-für-Schritt zur eigenen Anwendung

Nachdem das Anwendungsskelett eingerichtet und initial gebaut wurde, ist es an der Zeit einen genaueren Blick auf die Verzeichnisse und Dateien zu werfen. Um nun ausgehend von diesem Anwendungsskelett zur eigenen Anwendung zu kommen, ist es notwendig zu verstehen, wo was steht.

In der nachfolgenden Schritt-für-Schritt-Anleitung wird genauer in die einzelnen Bereiche geschaut. Grob kann man jedoch sagen:

skeleton-cli

erstellt die CLI und enthält die Basis-Konfiguration inkl. ACL-Spezifikation, Solr-Konfiguration und den nötigen Klassifikationen

skeleton-module

umfasst die gesamte Anwendungslogik

skeleton-webapp

erstellt das Webarchiv

1. Datenmodell erstellen

Im ersten Schritt muss das eigene Datenmodell basierend auf den MyCoRe-Datentypen spezifiziert werden. Diese Spezifikation erfolgt im skeleton-module unter src/main/datamodel/def. Die dort hinterlegte simpledoc.xml soll als Vorlage für eigene MyCoRe-Objektdefinitionen dienen. Für jedes MyCoRe-Objekt ist eine eigene Datei anzulegen.

Neue Datenmodelldefinitionen müssen in der Konfigurationsdatei src/main/resources/config/skeleton/mycore.properties über das Property MCR.Metadata.Type.{objecttype-name}=true registriert werden. Dabei entspricht der {objecttype-name} dem Dateinamen, der die MyCoRe-Objektdefinition enthält und dem im name-Attribut angegebenen String (wie hier am Beispiel der simpledoc.xml).

1
2
3
4
5
6
7
8

<?xml version="1.0" encoding="UTF-8"?>
<objecttype ...
            name="simpledoc"
            ...>
  <metadata>
    [...]
  </metadata>
</objecttype>

1
2

# in mycore.properties
MCR.Metadata.Type.simpledoc=true

Abschließend muss die Anwendung inkl. der CLI mit mvn clean install neu gebaut werden.

2. Erfassungsmasken

Um eigene Erfasssungsmasken zu erstellen, muss als erstes das HTML-Formular nach eigenen Anforderungen erstellt werden. Dies kann z.B. mit Bootstrap und unter Verwendung des FormBuilder für Bootstrap 3 realisiert werden.

Achtung: Der Formbuilder setzt name-Attribute für Buttons, Input-Felder, etc. Diese kann der XEditor nicht verarbeiten und produziert Fehler. Diese Attribute also bitte unbedingt entfernen!

Nachdem das HTML-Formular fertig ist, muss dies mit den entsprechenden XEditor-Bestandteilen angereichert werden. Alle Details dazu finden sich in der XEditor-Dokumentation.

Die Definitionsdatei für die Erfassungsmaske für simpledoc befindet sich im skeleton-module unter src/main/resources/META-INF/resources/content/publish/simpledoc.xed

3. Anzeige der Daten

Um die Daten auf der Webseite präsentieren, wird mittels XSLT das XML des MyCoRe-Objektes zu HTML transformiert.

Ein Beispiel für die Transformation eines simpledoc-MyCoRe-Objektes befindet sich im skeleton-module unter src/main/resources/xsl/simpledoc.xsl

Eigene Transformationsdateien müssen in der Konfigurationsdatei des skeleton-module, den src/main/resources/config/skeleton/mycore.properties durch Komma separiert ergänzt werden.

1
2
3
4
5
6

##############################################################################
# Datamodel                                                                  #
##############################################################################
MCR.Metadata.Type.simpledoc=true
MCR.Metadata.Type.{objecttype-name}=true
MCR.URIResolver.xslIncludes.objectTypes=%MCR.URIResolver.xslIncludes.objectTypes%,simpledoc.xsl,{objecttype-name}.xsl

4. Konfiguration der Suche

An dieser Stelle können natürlich nicht die vielfältigen Möglichkeiten, die Solr bietet vorgestellt und dokumentiert werden. Dazu verweisen wir auf die Literatur und die Solr Homepage.

Die Informationen hier sollen als Einstiegspunkt dienen und helfen, sich bei der Konfiguration zurechtzufinden. Vor allem sollen die MyCoRe-spezifischen Besonderheiten dargestellt werden.

Suchfeld-Definition im Solr Core

Die Definition erfolgt in der Datei schema.xml im Solr Core Konfigurationsverzeichnis. Wir empfehlen jedoch alle Änderungen im Skeleton Konfigurationsverzeichnis vorzunehmen und die Dateien bei Änderungen in den Solr Core zu kopieren. Dadurch lassen sich auch die Solr Konfigurationsdateien mit den anderen Dateien des eigenen Projektes unter Versionskontrolle verwalten. Die Schema Datei befindet sich unter: skeleton-cli\src\main\config\solr-home\skeleton\conf\schema.xml Die Syntax der Suchfelddefinitionen entnehme man dem Solr Wiki oder einem guten Solr Buch.

1
2

<field name="ds.title" type="text_general" multiValued="true" stored="true" />
            

Das Attribut type referenziert eine an anderer Stelle im Schema definierte Typ-Definition. In dieser ist festgelegt, wie Solr die Daten beim Import und die Terme von Suchanfragen verarbeiten sollen (z.B: Tokenisierung (Zerlegung in Worte), Normalisierung (Umlaute), Stammformreduktion, ...)
Mit dem Attribut multiValued wird angegeben, ob das Indexfeld wiederholbar ist. ID-Werte und Felder nach denen sortiert werden soll, sollte nicht mehrfach vorkommen.
Mit dem Attribut stored wird angegeben, ob neben der Solr-internen Form auch noch die Ausgangsform des Feldwertes gespeichert werden soll. Gespeicherte Felder können z.B. dazu genutzt werden, Trefferlisten direkt aus der XML-Rückgabe einer Solr Anfrage zu generieren, ohne nochmal auf das MyCoRe Datenobjekt zugreifen zu müssen.

Suchfeld-Mapping per XSLT

Die Werte der Suchfelder werden mittels XSLT generiert.

Um ein eigenes XSLT-Stylesheet in die Verabeitungskette zu integrieren, muss in der Datei jspdocportal-module\src\main\resources\config\jspdocportal\mycore.properties das entsprechende Property erweitert werden:

1
2

MCR.URIResolver.xslImports.solr-document
  =%MCR.URIResolver.xslImports.solr-document%,solr/skeleton-solr.xsl

Die XSLT-Transformationen werden in der Datei skeleton-module\src\main\resources\xsl\solr\skeleton-solr.xsl vorgenommen. Diese Datei produziert XML nach folgendem Vorbild:

1

  <field name="feldname">feldwert</field>

Die Feldnamen beziehen sich auf die in der Solr Konfiguration (schema.xml) definierten Felder.

1
2
3

  <xsl:for-each select="mods:titleInfo/*">
    <field name="ds.title"><xsl:value-of select="text()" /></field>
</xsl:for-each> 

5. Anpassung der Suchmasken und Trefferanzeige

Suchmasken können ebenfalls mit dem XEditor-Framework erstellt werden.

Ein Beispiel für die Definition einer einfachen Suchmasken befindet sich im skeleton-module unter:
src/main/resources/META-INF/resources/content/search/simple.xed

TODO: Trefferlisten per XSLT