Migrationsanleitung von 2.0 auf 2.1

Transkript

1 Die wichtigste Neuerung von 2.0 auf 2.1 aus Sicht der Anwendungs- Migration ist die Verwendung von Maven. Mit Maven holt sich die Anwendung alle notwendigen Bibliotheken in den jeweils angegebenen Versionen selbst. Auch MyCoRe wird als eine solche Bibliothek eingebunden und muss nun nicht mehr mit heruntergeladen und kompiliert werden. Table of contents 1 Allgemeine Schritte zur Anwendungsmigration Umstellung auf Maven Modularisierung - zweite Runde Weitere Schritte Datenmigration Offline-Migration Online-Migration Abschluss Integration des neuen Bildbetrachters (IView2) Vorbereitung Kacheln der Bilder Webanwendung... 6

2 Hinweis Die Migrationsanleitung geht von MyCoRe 2.0-fixes oder höher als Ausgangsbasis aus. 1 Allgemeine Schritte zur Anwendungsmigration Die eigene Anwendung muss auf den Codestand des Release 2.1 gebracht werden. Dies kann am besten mit Hilfe der aktuellen DocPortal-Version realisiert werden. Da jede Anwendung verschieden ist, und mehr oder weniger stark von DocPortal abweicht, kann an dieser Stelle nicht im Detail auf die jeweilige Vorgehensweise eingegangen werden. Es wird jedoch auf wichtige Änderungen hingewiesen, um Anhaltspunkte für die eigene Migration zu geben. Bei Fragen kann die Community am besten jeweils direkt helfen - einfach mal nachfragen! 1.1 Umstellung auf Maven Für die Umstellung auf Maven muss auf Anwendungsseite nicht viel getan werden. Relevant wird dies vor allem, wenn für die eigene Anwendung auch Anpassungen am MyCoRe-Kern gemacht wurden. Da MyCoRe nun via Maven als mycore.jar eingebunden wird, muss hier ein anderer Weg beschritten werden, um diese Anpassungen einzupflegen. Fragen Sie hierzu am besten direkt auf der Mailingliste nach. Als Vorlage für die eigene Anwendung ist DocPortal 2.1-fixes zu verwenden. Um die eigene Anwendung Maven-fähig zu machen, sind folgende Schritte notwendig: 1. altes lib-verzeichnis löschen und aus neuer DocPortal-Version übernehmen (enthält nur noch maven-ant-tasks jar) 2. pom.xml.template aus docportal/config in das config-verzeichnis der eigenen Anwendung übernehmen und nach pom.xml kopieren - hier können später eigene Anpassungen vorgenommen werden 3. aktuelle build.xml aus docportal übernehmen und ggf. wieder an eigenen Build- Prozess anpassen 4. mit dem Aufruf ant resolve wird nun Maven angestossen und holt alle in der pom.xml angegebenen notwendigen Bibliotheken (inkl. der mycore.jar) - dies kann beim ersten Aufruf mehrere Minuten dauern 1.2 Modularisierung - zweite Runde Im Modul-Verzeichnis von DocPortal 2.1-fixes befinden sich nun neben dem Anwendungsmodul docportal weitere Module, deren Bedeutung hier kurz aufgelistet wird: Modul Beschreibung common enthält Stylesheets, Skripte, Code und XML- Dateien, die für alle Anwendungen, unabhängig Seite 2 von 6

3 Modul Beschreibung vom speziellen Datenmodell oder Layout relevant sind docportal alle anwendungsspezifischen Dateien - üblicherweise durch eigene Anwendung zu ersetzen maven myliwi sampleusers ist zur Erstellung von eigenen Anwendungsmodulen, z.b. wie IView2; es bietet also eine zusätzliche Ebene um jar-dateien zu kopieren Beispielmodul als Vorlage für eine mögliche Erweiterung der eigenen Anwendung auf Basis von DocPortal Beispielnutzer, wie sie in DocPortal verwendet werden, können entsprechend durch eigene Nutzer ersetzt bzw. als Vorlage genutzt werden Table 1: Modulverzeichnis docportal/modules Im Zuge dieser stärkeren Auftrennung ist auch die searchfields.xml modularisiert worden. Die searchfields.xml wurde aufgeteilt in Suchfelder für Metadaten und Derivate und sind nun im Verzeichnis modules/docportal/config zu finden. Auf diese Art können für jedes Modul weitere Suchfelder definiert werden. Ein Beispiel dafür bietet das myliwi-modul. Zur Anpassung der eigenen Anwendung an diese fein-granularere Modulstruktur empfehlen wir das Modulverzeichnis von DocPortal 2.1-fixes zu übernehmen und die eigenen Dateien entsprechend des docportal-modules als Vorlage im eigenen Anwendungsmodul abzulegen. 1.3 Weitere Schritte Seit dem letzten Release wurde vor allem viel im MyCoRe-Kern überarbeitet. Dadurch ändern sich teilweise auch Schnittstellen. Ein vollständiger Überblick kann an dieser Stelle leider nicht gegeben werden. Sollten Dinge nach der Umstellung nicht mehr funktionieren, bitten wir um Rückmeldung an die MyCoRe-User-Liste. Wir ergänzen die Punkte dann an dieser Stelle. Bereits bekannte nötige Anpassungen sind: Bei Benutzung des xsl-parameters: CurrentGroups dieser existiert mehr nicht, stattdessen ist die xsl-funktion iscurrentuserinrole() zu verwenden. Dazu muss xmlns:mcrxsl="xalan:// org.mycore.common.xml.mcrxmlfunctions" in (documents).xsl definiert sein. Beispiel: xsl:if test="mcrxsl:iscurrentuserinrole('admingroup')" Seite 3 von 6

4 2 Datenmigration Es gibt zwei Möglichkeiten die Daten einer bestehenden Anwendung zu migrieren. Läuft die MyCoRe-Anwendung als WAR im Webserver, kann das Update via Kommandozeile eingespielt und erst später die Anwendung selbst auf Version 2.1 und somit den Zugriff auf die migrierten Daten aktualisiert werden (offline). Wird keine WAR-Datei genutzt oder sind viele Daten zu migrieren und während des Migrationsvorganges soll die Anwendung nicht nur lesend ("read only") nutzbar sein, ist die Online-Migration eine Alternative. 2.1 Offline-Migration Während die 2.0er-Web-Anwendung läuft wird via Kommandozeile der Datenbestand auf 2.1 aktualisiert. Dazu muss in den mycore.private.properties der Eintrag MCR.Components.Exclude "migration20-21" entfernt werden, damit die Migrations-Kommandos verfügbar sind. Die Anwendung danach wie gehabt bauen (ant create.jar create.scripts create.webapp). Nun kann die MyCoRe-Kommandozeile (CLI) aufgerufen und die Migrationskommandos genutzt werden. Dort kann die Web-Anwendung in den Nur-Lese-Modus versetzt werden: set website read only Datenmigration wird aktuell durchgeführt Im nächsten Schritt, kann die Datenmigration gestartet werden: migrate xmltable Dies kann je nach Datenbestand einige Zeit dauern! Wenn das Kommando erfolgreich abgeschlossen wurde, kann nun auch die Webanwendung aktualisiert werden (neu erstelltes WAR einspielen). Zum Abschluss der Migration kann man, wie im letzten Abschnitt beschrieben, aufräumen. 2.2 Online-Migration Die Online-Migration erfolgt wie die Offline-Migration, nur mit folgenden Unterschieden: In der mycore.private.properties muss das Kommentarzeichen vor folgender Anweisung entfernt werden: #MCR.Metadata.Store.DefaultClass=org.mycore.datamodel.MCRMigratingXMLStore Damit werden Metadaten, sowohl in der Datenbank als auch im IFS gesucht und ggf. migriert (auf den IFS-Store mit Versionierung). Diese Migration kann durch den Befehl migrate xmltable beschleunigt werden, der dann viele Warnungen erzeugt. Diese können in dem Fall ignoriert werden. Sind alle Daten migriert, befinden sich selbige im IFS2 und man kann das Property wieder deaktivieren. Seite 4 von 6

5 2.3 Abschluss Nach der Migration kann man bei MCR.Components.Exclude wieder "migration20-21" eintragen, die Anwendung neu bauen und starten und dann in der Datenbank die Tabelle MCRXMLTABLE löschen. Weiterhin muss im "data"-verzeichnis der Anwendung das "ehcache"-verzeichnis gelöscht werden, weil mit Version 2.1 eine neuere Version als Second-Level-Cache benutzt wird, die mit dem alten Cache-Format Probleme hat und Warnungen erzeugt. 3 Integration des neuen Bildbetrachters (IView2) Im Gegensatz zur ersten Version des Bildbetrachters, bietet die Version 2 keine Option zum Deaktivieren des Image-Caches mehr an. Es werden für alle Bilder Kacheln angelegt, auf deren Basis der deutlich schnellere und funktional umfangreichere Bildbetrachter arbeitet. Damit der neue Bildbetrachter genutzt werden kann, muss dieser aktiviert und die bereits erfassten Bilder neu gekachelt werden. 3.1 Vorbereitung Damit die IView2-Komponente von MyCoRe zur Verfügung steht, muss der folgende Abschnitt in der pom.xml (zu finden im config-verzeichnis der Anwendung) vorhanden sein: <dependencies>... <dependency> <groupid>org.mycore</groupid> <artifactid>iview2- preview</artifactid> <version>${project.version}</version> </dependency> </ dependencies> Im zweiten Schritt muss die mycore.properties.private dahin gehend erweitert werden, dass das maven-modul verwendet und die (veraltete) iview-komponente ausgeschlossen wird. MCR.Modules.Application=common,docportal,sampleusers,maven #exclude these mycore components MCR.Components.Exclude=migration20-21,iview Hinweis Bei der Angabe der Module ist die Reihenfolge relevant, da Inhalte bewusst überschrieben werden! Das Maven-Modul muss daher nach dem common- und docportal-modul (bzw. dem eigenen Anwendungs-Modul) stehen. Dadurch wird sichergestellt, dass die entsprechenden Bibliotheken geladen werden und der Anwendung bei Betrieb zur Verfügung stehen. Der Aufruf ant resolve zeigt nun, dass IView2 als "application module" geladen wurde. Weiterhin sollte am Ende des Aufrufes ein BUILD SUCCESSFUL das erfolgreiche Laden aller benötigten Bibliotheken bestätigen. Ist dem nicht so, prüfen Sie, ob ein Zugang zum Internet vorhanden ist, da die Anwendung die nötigen Quellen von verschiedenen Servern bezieht. Falls kein Zugang zum Netz möglich ist, muss das.m2-verzeichnis von einem anderen Seite 5 von 6

6 Rechner mit Netzzugang, auf dem die gleiche Anwendung bzw. ein DocPortal läuft, kopiert werden. Hier hilft auch gerne die Community weiter! 3.2 Kacheln der Bilder Nach erfolgreicher Konfiguration müssen nun Skripte und Webanwendung neu erstellt werden: ant create.jar create.scripts create.webapp Daraufhin kann die MyCoRe-Kommandozeile gestartet werden, um die in MyCoRe abgelegten Bilder für den neuen Bildbetrachter aufzubereiten. Konkret bedeutet dies, dass Kacheln für die verschiedenen Auflösungen erstellt werden: build/bin/mycore.sh bzw. build/bin/mycore.bat help tile Der Tile-Befehl erstellt die Kacheln. Für alle Derivate lautet der Aufruf dann entsprechend tile images of all derivates Pro Bild benötigt dieser Vorgang ca. 2-3 Sekunden. Da das Kacheln asynchron abläuft, kann die Kommandozeile jederzeit mit exit verlassen werden. In diesem Fall wird der Vorgang unterbrochen und arbeitet im Hintergrund weiter, sobald zum Beispiel die Webanwendung (neu) gestartet wird. Wird ein Bild aufgerufen, für das noch keine Kacheln erstellt wurden, wird der IView2 nicht dargestellt. Die Anwendung kann aber trotzdem ganz normal genutzt werden. Um den alten Imagecache zu löschen muss in der MyCoRe-Kommandozeile der Befehl delete image cache for all derivates aufgerufen werden. Danach kann in den mycore.properties.private die imaging-komponente ausgeschlossen werden. #exclude these mycore components MCR.Components.Exclude=migration20-21,imaging,iview 3.3 Webanwendung Gegebenenfalls müssen noch Stylesheets (XSL) angepasst werden. Einige Templates wurden übernommen, z.b. derivateview, andere werden nicht mehr unterstützt (alt iview.getsupport, neu iview2.getsupport). Die Einbindung kann z.b. wie folgt aussehen: <xsl:call-template name="derivateview"> <xsl:with-param name="derivateid" select="$deriv" /> </xsl:call-template> Weitere Informationen dazu entnehmen Sie bitte der Dokumentation zum Bildbetrachter (../../documentation/index.html/../archiv/version21/ programmerguide/03_components.html#bildbetrachter). SyntaxHighlighter.all() Seite 6 von 6