Dokumentation in Arbeit: Inflator fertig dokumentiert, kleinere Anpassungen

ulrich

20 hours ago 7e5166a55fa459deab5579f764b7bb34719e5ec9

 src/de/uhilger/fm/package-info.java

@@ -1,72 +1,85 @@
/**
 * Klassen fuer das Dateimanagement. 
 * Klassen fuer das Dateimanagement mit <code>java.nio.file</code>. 
 * 
 * Die folgenden Funktionen sind enthalten:
 * 
 * <pre>
 * 
 * 
 * Dateiinhalt abrufen:       
 *    String json = new Lister().liste(ordnerName, ctx, basisOrdner);
 *
 * 
 * 
 * 
 * 
 * Ordnerinhalt auflisten:    
 *   GET http://localhost:[port]/[kontext]/pfad/zum/ordner/
 *    Catalog().list(relPathAndName, miniUrlBase, baseDir)
 * 
 * Dateiinhalt aendern (ueberschreiben) oder neu anlegen:       
 *   PUT http://localhost:[port]/[kontext]/pfad/zur/datei.txt  
 *   Body: Neuer Dateiinhalt
 * 
 * Datei neu anlegen (ohne Ueberschreiben):
 *   POST http://localhost:[port]/[kontext]/pfad/zur/datei.txt
 *   Body: Dateiinhalt
 *   Erzeugt eine neue Datei mit einer laufenden Nummer, falls
 *   die per URL angegebene Datei schon existiert
 * 
 * Ordner anlegen:
 *   POST http://localhost:[port]/[kontext]/pfad/zum/ordner/
 *   erzeugt einen HTTP-Fehler 422, wenn der Ordner schon existiert
 * Datei speichern:
 *    Writer().speichern(file, content)
 * 
 * Dateien und Ordner loeschen:
 *   DELETE http://localhost:[port]/[kontext]/pfad/zum/ordner/
 *   Body: Liste  mit Datei- und Ordnernamen, die aus dem im URL 
 *         angegebenen Ordner geloescht werden sollen, z.B. ["test.txt","dok"] 
 *         Hiermit werden die Datei test.txt und der Ordner dok geloescht. 
 *   Das Loeschen geschieht rekursiv, einschliesslich aller Unterordner
 *    Eraser().deleteFiles(relPfad, dateiname, basis)
 * 
 * Kopieren von Dateien und Ordnern:
 *   PUT http://localhost[port]/[kontext]/pfad/zum/zielordner/?copyFrom=/pfad/zum/quellordner/
 *   Body: Liste mit Datei- und Ordnernamen, die einschliesslich aller Unterordner 
 *         kopiert werden sollen, z.B. ["anleitung.adoc","dok","ordner-2","bild.jpg"]
 *    Mover().copyOrMoveFiles(quelle, ziel, dateiNamen, op, base)
 * 
 * Verschieben von Dateien und Ordnern:
 *   PUT http://localhost[port]/[kontext]/pfad/zum/zielordner/?moveFrom=/pfad/zum/quellordner/
 *   Body: Liste mit Datei- und Ordnernamen, die einschliesslich aller Unterordner 
 *         verschoben werden sollen, z.B. ["anleitung.adoc","dok","ordner-2","bild.jpg"]
 *    Mover().copyOrMoveFiles(quelle, ziel, dateiNamen, op, base)
 * 
 * Duplizieren einer Datei:
 *   PUT http://localhost:[port]/[kontext]/pfad/zur/datei.txt?duplicate=true
 *    Duplicator().duplizieren(base, fileName)
 * 
 * Umbenennen einer Datei oder eines Ordners:
 *   PUT http://localhost:[port]/[kontext]/pfad/zur/datei.txt?renameTo=neuer-name.txt
 *   PUT http://localhost:[port]/[kontext]/pfad/zum/ordner/?renameTo=neuer-ordnername
 *   Das Umbenennen erfolgt nur, wenn am betreffenden Ort eine Datei bzw. ein Ordner 
 *   mit dem neuen Namen noch nicht existiert.
 *    Renamer().umbenennen(exchange, fileName, params[1], file)
 * 
 * Packen eines Ordners:
 *   PUT http://localhost:[port]/[kontext]/pfad/zum/archiv/packdaten/?zip
 *   Packt (komprimiert) den Ordner mitsamt Inhalt. Mit obigem URL liegt 
 *   anschliessend im Ordner 'archiv' eine Datei 'packdaten.zip'.
 *    Deflator().packFolder(fileName, path, base)
 * 
 * Entpacken einer ZIP-Datei:
 *   PUT http://localhost:[port]/[kontext]/pfad/zu/dateien/archiv.zip?unzip
 *   Entpackt die im URL angegebene Datei. Mit obigem URL liegt anschliessend 
 *   der Inhalt der Datei 'archiv.zip' im Ordner 'dateien'.
 * 
 * 
 *    Inflator().extractZipfile(fileName, path, base)
 * </pre>
 * 
 * Die hier enthaltenen Funktionen beinhalten keine Massnahmen gegen Path Traversal o.&auml;. 
 * Dies ist beabsichtigt, um Pfadausdruecke wie z.B. '../' bei den hier implementierten 
 * Dateioperationen verarbeiten zu koennen. 
 * 
 * <b>Programme, die diese Klassenbibliothek einsetzen, muessen eigene Massnahmen gegen 
 * Path Traversal o.&auml;. beisteuern, sofern dies nicht gewuenscht ist.</b>
 * 
 * <p>Die folgenden Funktionalitaeten sind in dieser Auspraegung einer  
 * Dateiverwaltung fest angelegt. Sie sind damit Kandidaten fuer eine 
 * Erweiterung dieser Klassenbibliothek um andere evtl. benoetigte 
 * Auspraegungen.</p>
 * 
 * <p><b>Handhabung von Bilddateien</b></p>
 * 
 * Neben der Datei eines Bildes in Originalgroesse werden weitere Dateien als Varianten 
 * eines Bildes unterstuetzt.
 * 
 * In Dateilisten werden diese Varianten ausgeblendet und nur das Originalbild gezeigt. 
 * 
 * Die Dateinamen von Varianten eines Bildes muessen dazu einen mit Unterstrich beginnenden 
 * Namenszusatz enthalten wie bspw. <code>_tn</code> fuer thumbnail oder <code>_sm</code> 
 * fuer small usw. Gleichsam lassen sich damit Eigenschaften wie zum Beispiel 
 * eine Base64-Kodierung kombinieren. Hier waere der Namenszusatz dann eine Kombination 
 * aus Groesse und Kodierung wie mit <code>_sm_b64</code>, so dass sich fuer ein Bild stets 
 * eine ganze Gruppe von Dateien ergibt, z.B.:
 * 
 * <pre>
 * bild.jpg
 * bild_sm.jpg
 * bild_sm_b64.jpg
 * </pre>
 * 
 * Alle Dateioperationen dieser Klassenbibliothek wirken dennoch stets auf 
 * alle Varianten des Bildes, wie es auf der Kommandozeile mit einem Wildcard-Operator 
 * gemacht wuerde, z.B.
 * 
 * <pre>
 *   cp /pfad/zum/bild*.jpg /pfad/zum/zielordner
 * </pre>
 * 
 * Eine Dateiliste enthaelt aus diesem Grund fuer Bilddateien die beiden zusaetzlichen Angaben 
 * <code>miniurl</code> und <code>imgsrc</code>. 
 * 
 * <p><b>Ordnerliste im JSON-Format</b></p>
 * 
 * Die Liste mit Dateien eines Ordners wird im JSON-Format ausgegeben. Ueber eine 
 * entsprechende Erweiterung koennte die Ausgabe in verschiedenen waehlbaren Formaten 
 * erfolgen.
 * 
 */
package de.uhilger.fm;