From 7e5166a55fa459deab5579f764b7bb34719e5ec9 Mon Sep 17 00:00:00 2001 From: ulrich Date: Thu, 14 Nov 2024 11:06:34 +0000 Subject: [PATCH] Dokumentation in Arbeit: Inflator fertig dokumentiert, kleinere Anpassungen --- src/de/uhilger/fm/package-info.java | 109 ++++++++++++++++++++++++++++++------------------------ 1 files changed, 61 insertions(+), 48 deletions(-) diff --git a/src/de/uhilger/fm/package-info.java b/src/de/uhilger/fm/package-info.java index 8df813f..aa832be 100644 --- a/src/de/uhilger/fm/package-info.java +++ b/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.ä. + * 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.ä. 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; \ No newline at end of file -- Gitblit v1.9.3