MyCoRe-LPZ Developer Guide zur Umsetzung von Projekten gültig für alle MyCoRe-Projekte in Leipzig von Jens Kupferschmidt (Uni Leipzig) Stefan Freitag (Uni Leipzig) u. a. Leipzig, 17/01/2014 Version 1.0
Abstrakt Diese Dokumentation beschreibt alle Vorschriften zur einheitlichen Gestaltung von MyCoRe- Applikationen in Leipzig. Sie ist bestmöglich in allen Anwendungen aus Leipzig umzusetzen. Teile des Textes sind aus Kompatibilitätsgründen dem MyCoRe Developer Guide entnommen, jedoch wegen der Verwandtschaft der Teilprojekte nicht gesondert als Zitat gekennzeichnet. Als Grundlage der Datenhaltung wird eine Applikation verwendet, die auf dem MyCoRe-Projekt (http://www.mycore.de), Release 2.1 basiert und hierfür eine Referenzanwendung darstellt. MyCoRe ist eine Arbeitsgruppe verschiedener deutscher Universitäten, die einen Open Source Kern und darauf aufbauende Anwendungen zur Lösung von Aufgaben aus den Bereichen digitale Bibliotheken und Sammlungen bereitstellt. Diese Komponenten bieten für das Projekt zur Digitalisierung langfristig die erforderliche Sicherheit bezüglich Soft- und Hardware-Anpassung. Der Einsatz dieser Software gestattet auch eine Erweiterung des Projektes im In- und Ausland. Die Anwendung unterliegt der GNU GENERAL PUBLIC LICENSE Version 2. Version 1.0.4 Seite 2
Änderungen Version Datum Autor 1.0.0 23.02.2011 Jens Kupferschmidt, URZ der Uni Leipzig 1.0.1 23.02.2011 Jens Kupferschmidt, URZ der Uni Leipzig 1.0.2 23.02.2011 Jens Kupferschmidt, URZ der Uni Leipzig 1.0.3 09.06.2011 Jens Kupferschmidt, URZ der Uni Leipzig 1.0.4 22.06.2011 Jens Kupferschmidt, URZ der Uni Leipzig 1.0.5 12.03.2012 Jens Kupferschmidt, URZ der Uni Leipzig 1.0.6 17.01.2014 Jens Kupferschmidt, URZ der Uni Leipzig Version 1.0.4 Seite 3
Inhaltsverzeichnis 1Allgemeines... 5 Maven Grundsystem...5 Nutzung von Eclipse...5 2MyCoRe der Community...6 1 Subversion-Server...6 3MyCoRe in Leipzig...7 Festlegung für die Code-Entwicklung...7 Encoding... 7 Java-Code Formatierung...7 XML-Code Formatierung...7 Kommentare...8 Logging... 9 Integration von JavaScript...9 Namenskonventionen...10 Benennung der Properties...10 Benennung von I18N Übersetzungen...10 4Versionsnummerierung...11 Version 1.0.4 Seite 4
1 Allgemeines Maven Grundsystem Neben der Installation von Subversion für die Arbeit mit einem zentralen Code-Repository ist ab Version 2.1 auch das Produkt Maven (http://maven.apache.org/) erforderlich, um an den Kernkomponenten zu arbeiten. Installieren Sie Maven gemäß Anleitung der Homepage und setzen Sie die Umgebungsvariablen M2_HOME und MAVEN_OPTS. Binden Sie das mvn-kommando in den Suchpfad mit ein. Die Funktion von Maven kann mit dem Kommando mvn --version getestet werden. Unter Linux- Systemen wird im Wurzelverzeichnis des Nutzers ein Verzeichnis.m2 angelegt, worin sich alle relevanten Maven-Daten befinden. Nutzung von Eclipse Die Entwicklungsumgebung Eclipse leistet nicht nur hilfreiche Dienste bei der Formatierung des Java- Codes. Mit ihr kann auch die Syntaxprüfung der Java-Klasse wie auch ihre Einbettung in das Gesamtprojekt leicht überwacht werden. Dazu sind einige Installationen und Einstellungen erforderlich. Diese werden dann sowohl für die Kernanwendung wie auch für die Applikationen genutzt. Zuerst ist das Eclipse Grundsystem zu installieren. Aktuell wird von den Entwicklern die Version Galileo verwendet. Soll die Eclipse-Umgebung mehreren Nutzern eines Linux-Systems zur Verfügung stehen (Installation als ROOT), so müssen auch die Plugins mit als Nutzer root installiert werden! Die Installation hat dann unter /usr/local/src zu stehen. Zuerst ist das Plugin für die Integration von Subversion zu installieren. Für Leipzig ist Subclipse zu verwenden. Bei Subclipse kann es jedoch kleine Probleme bei der Nutzung von Subversion via Kommandozeile geben. Im nächsten Schritt ist dann die Maven-Integration zu installieren. Hierfür empfehlen wir Eclipse IAM unter http://eclipse.org/iam/. Weiterhin haben sich die Plugins XMLBuddy zum Bearbeiten der XML-Dateien und ResourceBundelEditor zur Bearbeitung von I18N-Sprachdateien (besonders für Sprachen außerhalb des Lateinischen Alphabets) bewährt. Um Dateien mit der Endung *.xed mit einem XML-Editor zu bearbeiten ist die Zuweisung der Endung in Eclipse zu konfigurieren: Windows Preferences General Editors File Associations Version 1.0.4 Seite 5
2 MyCoRe der Community 1 Subversion-Server Der Quellcode der MyCoRe-Kerns und einiger Anwendungen, z.b. der Beispielanwendung DocPortal, wird auf einem Subversion-Server an der Universität Duisburg-Essen verwaltet. Aktuell gib es zwei Zugangsmöglichkeiten: über HTTP im lesenden Zugriff und über SSH mit Schreibrechten (sofern der Entwickler Zugang zum System hat [der Server wird von Frank Lützenkirchen verwaltet]). http://www.mycore.de/svn/ Hinweis für Kommandozeilen-Nutzer: svn+ssh://server.mycore.de/svn/ Dateien in der SVN-Arbeitskopie nie direkt mit Betriebssystemmitteln kopieren, löschen und verschieben. Stattdessen auf jeden Fall die svn-kommandos cp, rm, mv verwenden. Hinweis für Eclipse-Nutzer: Ab sofort sollten Dateien nicht mehr mit Cut & Paste sondern vielmehr über die Team- Funktionen kopiert werden, damit die Histories nicht verloren gehen! MIME-Typ für alle neuen Dateien: Alle neuen Dateien, die bei MyCoRe mit Subversion verwaltet werden müssen das SVN Property svn:mime-type ausgefüllt haben. Bei Mime-Typ text/* muss zusätzlich noch das Property svn:eol-style beschrieben sein. Für die häufigsten Dateiarten gibt es eine Konfiguration zum herunterladen, die ans Ende der Datei config im Verzeichnis.subversion des Nutzerverzeichnisses angefügt wird. Der entsprechende Bereich trägt den Namen [autoprops]. Version 1.0.4 Seite 6
3 MyCoRe in Leipzig Festlegung für die Code-Entwicklung Encoding Allgemeines Grundsätzlich geht MyCoRe davon aus, dass alle Dateien, die nicht sprachabhängig sind, mit UTF-8 kodiert wurden. Dies gestattet eine gute Nutzung auch über die Grenzen des deutschsprachigen Raumes hinaus. Dies betrifft vor allem die Dateitypen: Java-Code - *.java XML-/XSL-Dateien - *.xml Konfiguration unter Eclipse Die Einstellung erfolgt in Eclipse im jeweiligen Projekt unter: 1. Properties -> Info -> Text file encoding -> UTF-8 Java-Code Formatierung Allgemeines Um bei der Arbeit mit dem Subversion-System nur inhaltliche Änderungen zu erfassen und diese nicht mit Umformatierungen zu verwechseln, wird der gesamte Code einheitlich nach folgenden Regeln erstellt: Formatierung gemäß den Java-Konventionen Tabulatoren werden durch Leerzeichen ersetzt Einrückung mit vier Zeichen Zeilenumbruch und maximale Zeilenlänge 120 Kommenare nicht umfomatieren Konfiguration unter Eclipse Die Einstellung erfolgt in Eclipse im jeweiligen Projekt unter: 1. Properties -> Java code style -> Formatter 2. dort Java Conventions als Vorlage wählen 3. Indentation -> Tab Policy -> Spaces only 4. Indentation -> Indentation size -> 4 5. Indentation -> Tab size -> 4 6. Line wrapping -> Maximum line width -> 120 7. Comments -> alle Markierungen entfernen 8. Die Vorlage wird dann als mycore gespeichert. XML-Code Formatierung Allgemeines Auch für die Gestaltung der XML-Dateien wurde eine einheitliche Formatierung festgelegt: Zeilenumbruch und maximale Zeilenlänge 120 Für Einrückungen sind nur Leerzeichen zu verwenden. Pro Tab sind 2 Zeichen Einrückung vorgesehen. Konfiguration unter Eclipse Die Einstellung erfolgt in Eclipse im jeweiligen Projekt unter: Version 1.0.4 Seite 7
1. Window -> Preferences -> XML -> XML Files -> Editor 2. dort wählen 3. Line width -> 120 4. Indent using spaces 5. Indentation size -> 2 6. Window -> Preferences -> XML Buddy -> Formatter 7. dort wählen 8. Tab width -> 2 9. Use space for tab 10.Wrap margin -> 120 11. Window -> Preferences -> ANT -> Editor -> Formatter 12.dort wählen 13.Tab size 2 14.Use tab character instead of spaces OFF 15.Maximum line width 120 Kommentare Allgemeines Alle Kommentare sind in Englisch zu verfassen. Dabei ist auf allgemein verständliche Sprachkonstrukte zu achten. Der Kommentar soll die kodierten Vorgänge gut beschreiben und für andere nachvollziehbar machen. Kommentare im Java-Code Jede Java-Quelltext-Datei hat das nachfolgende Aussehen. Das gestattet ein einheitliches Auftreten des Projektes. Da für alle Dateien mittels JavaDoc automatisch eine Dokumentation generiert wird, ist es Pflicht, die erstellte Klasse mit einer allgemeinen Beschreibung zum Zweck und Einsatz der Klasse zu versehen. Weiterhin sind alle public oder protected Methoden mit einer Beschreibung zu versehen. Hierzu gehört auch die Dokumentation der übergebenen Parameter, der Rückgabewerte und ggf. der geworfenen Exceptions. /** * This file is part of *** M y C o R e *** * See http://www.mycore.de/ for details. * * This program is free software; you can use it, redistribute it * and / or modify it under the terms of the GNU General Public License * (GPL) as published by the Free Software Foundation; either version 2 * of the License or (at your option) any later version. * * This program is distributed in the hope that it will be useful, but * WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program, in a file called gpl.txt or license.txt. * If not, write to the Free Software Foundation Inc., * 59 Temple Place Suite 330, Boston, MA 02111 1307 USA */ package org.mycore.datamodel.metadata; <br/> import java.io.file; <br/> /** * This class implements all methode for... * * @author Jens Kupferschmidt * @version $Revision: 1.49 $ $Date: 2006/05/17 11:49:32 $ */ Version 1.0.4 Seite 8
final public class MCR... {... Logging Alle Logging-Informationen werden, sofern nicht eine Umsetzung mittels der Internationalisierung I18N erfolgt, in Englisch notiert. Für MyCoRe ist das log4j-paket des Apache-Projektes zu verwenden. Es gib 4 definierte Log-Level mit nachfolgenden Bestimmungen. Es ist davon auszugehen, dass eine normale Anwendung allgemein auf den Level INFO gesetzt ist. ERROR Gibt Informationen zu nicht behebbaren Fehlern, z.b. Exceptions, zurück. WARN Gibt Informationen zu Fehlern zurück, welche die Weiterarbeit der Anwendung nicht ausschließen. In der Regel wird mit Standardwerten weitergearbeitet. INFO Gibt allgemeine Informationen für den normalen Anwender bzw. die Log-Datei aus. Diese Nachrichten haben nur informativen Charakter. DEBUG Gibt zusätzliche Informationen, die gezielt durch Einschalten dieses Levels abgerufen werden, aus. Integration von JavaScript Allgemeines Es ist beabsichtigt hauptsächlich das JQuery-Paket (z. Z. 1.6.1) einzusetzen. Dieses ist bereits in der Leipziger Version von MyCoRe integriert. Dieses Paket und alle allgemeinen JavaScript Teile befinden sich in der Komponente mycore-common-parts und können von dort referenziert werden. Einbindung Leipziger JavaScript-Erweiterungen werden im HTML-Code in einem div-tag mit der ID js_lpz_common eingeschlossen. Die JavaScripte stehen unter web/js. Folgenden Funktionalitäten sind darüber hinaus nachfolgende CSS-Klassen zugeordnet: js_classification_list Auswahlliste der Klassifikationen js_spelling_list Auswahlliste von Wortergänzungen / -ersetzungen js_link_list Auswahlliste möglicher Verlinkungen Namenskonventionen Benennung der Properties MyCoRe-Properties beginnen immer mit MCR, darauf folgt ein Punkt und dann der Komponentenname (z.b. ACL, IFS...). Alle weiteren Bezeichner sind mit Punkt voneinander getrennt und beginnen mit einem Großbuchstaben. Properties von Drittanbietern (z.b. Log4j, Hibernate) behalten ihre Konventionen bei. Beispiel: MCR.IFS.FileMetadataStore.Class Version 1.0.4 Seite 9
Benennung von I18N Übersetzungen Alle Übersetzungsvariablen erhalten ein einheitliches Namensschema. Alle Übersetzungen von Texten des Kerns enthalten den Anfang component und den Komponentennamen. Texte aus Modulen beginnen mit module und dem Modulnamen. Beispiel: component.common-parts.button.cancel = Abbrechen component.swf.object.edit = Editieren Objekt module.dptserv.title.label = Titel Für Such- und Editormasken sind weiterhin folgende Namensteile festgelegt: Nachrichtentext für Eingabefehler Hilfetext in der Editormaske Hilfetext in der Suchmaske Text in der Editormaske Text in der Suchmaske Text der Anzeige module.mymodule.mytype.myfield.cond module.mymodule.mytype.myfield.help module.mymodule.mytype.myfield.helps module.mymodule.mytype.myfield.label module.mymodule.mytype.myfield.labels module.mymodule.mytype.myfield.view Version 1.0.4 Seite 10
4 Versionsnummerierung Projektname MyCoRe Basis Version Anwend. Version Beschreibung MyCoRe 2.1.13-LPZ xlink:label zu xlink:title migration-20-21 entfernt migration-21-22 hinzugefügt DptBase 2.1.01-LPZ dptbase 2.1.1 Anpassung an MyCoRe Snapshot 2.0.92 2.1.03-LPZ dptbase 2.1.3 Anpassung an MyCoRe Snapshot 2.0.93 2.1.05-LPZ dptbase 2.1.5 Anpassung an MyCoRe Release 2.1 2.1.06-LPZ dptbase 2.1.6 Bugfixes Essen 2.1 + Änderung Inventory 2.1.07-LPZ dptbase 2.1.7 Änderungen nach 2.1 Release Integration JavaScript Erweiterungen 2.1.09-LPZ dptbase 2.1.9 Prerelease MyCoRe 2.2 NS-Raubgut 2.1.03-LPZ dptbase 2.1.5 nsraubgut 1.0 Grundsystem 2.1.05-LPZ dptbase 2.1.6 nsraubgut 1.1 Anpassung an MyCoRe Release 2.1 2.1.09-LPZ dptbase 2.1.9 nsraubgut 1.2 Prerelease MyCoRe 2.2 Bach 2.1.12-LPZ bach 2.2 Anpassung an MyCoRe Release 2.1 2.1.13-LPZ bach 2.3 Anpassung der xlink-verweise Papyri 2.0 papyri 4.1 MyCoRe Release 2.0 2.1.03-LPZ papyri 4.2 Anpassung an MyCoRe Snapshot 2.0.93 2.1.06-LPZ papyri 4.3 Anpassung an MyCoRe Release 2.1 neues Design 2.1.07-LPZ papyri 4.4 Bugfixes Essen 2.1 + Änderung Inventory 2.1.11-LPZ papyri 4.5 Prerelease MyCoRe 2.2 2.1.13-LPZ papyri 4.6 Anpassung der xlink-verweise papyri 4.7 Papyrus-Portal 2.1.03-LPZ portal 1.3 MyCoRe Release 2.0 2.1.11-LPZ portal 1.4 Prerelease MyCoRe 2.2 + Giessen MyIHS 2.1.03-LPZ myihs 2.2 Anpassung an MyCoRe Snapshot 2.0.93 2.1.07-LPZ myihs 2.3 Anpassung an MyCoRe Release 2.1 2.1.09-LPZ myihs 2.4 Prerelease MyCoRe 2.2 2.1.13-LPZ myihs 2.5 Prerelease MyCoRe 2.2 autofillreferencelist Reduce turfanms Add language regions Anpassung der xlink-verweise Entfernen der Help Button myihs 2.6 Version 1.0.4 Seite 11