chap 5: Umsetzung — 11 Abschnitte + module-components/zip-stream/race-condition diagrams

chapters/execution/url-files.tex

@@ -1,6 +1,38 @@
-\section{Support für URL-Dateien}
+\section{Unterstützung von URL-Dateien}
 \label{sec:url-files}
 
-% TODO: PBI 9301 — .url-Dateien parsen, Verlinkung beliebiger URLs (Teams, SharePoint)
-% Zum Parsen einfach schnell einen eigenen INI Parser selber geschrieben als auf eine 3rd party dependency einzubinden.
-% Abbildung~\ref{fig:url-file-parsing}
+\subsection{Anwendungsfall}
+
+Nicht alle Unterlagen, die für einen Kunden relevant sind, lassen sich sinnvoll in den Speicher kopieren. Ein fortlaufend gepflegtes Dokument in einem Dokumentenverwaltungssystem oder ein Kanal in einem Kollaborationswerkzeug soll verlinkt und nicht dupliziert werden — eine Kopie wäre sofort veraltet.
+
+Für diesen Zweck werden \texttt{.url}-Dateien unterstützt. Dabei handelt es sich um ein etabliertes Format für Verknüpfungen: eine kleine Textdatei, die im INI-Format die Zieladresse und optional ein Symbol enthält. Legt ein Kundenbetreuer eine solche Datei im Speicher ab, erscheint sie in der Dokumentenliste wie ein gewöhnliches Dokument, führt beim Anklicken jedoch auf die hinterlegte Adresse.
+
+Der Anwendungsfall war zunächst missverständlich formuliert und wurde in der Feature-Analyse geklärt: Gemeint ist das Einbetten \emph{externer} Ressourcen in den Dokumentenbereich, nicht das Teilen von Houston-Dokumenten nach außen (siehe Abschnitt~\ref{sec:feature-analysis}).
+
+\subsection{Auswertung des Dateiformats}
+
+Für das Auswerten des INI-Formats wurde bewusst keine externe Bibliothek eingebunden, sondern eine kleine eigene Auswertung geschrieben. Der Grund ist das Verhältnis von Aufwand zu Nutzen: Benötigt wird ein einziger Wert aus einem einzigen Abschnitt. Eine allgemeine Bibliothek für ein Format, von dem ein sehr kleiner Ausschnitt gebraucht wird, brächte eine dauerhaft zu pflegende Abhängigkeit mit sich — samt Aktualisierungen, Lizenzprüfung und einer weiteren Position in der Abhängigkeitsliste — für Funktionalität, die in wenigen Zeilen selbst geschrieben ist.
+
+Hinzu kommt, dass eine allgemeine Bibliothek in diesem Fall gar nicht das gewünschte Verhalten böte. Sie würde bei fehlerhaften Dateien vermutlich einen Fehler melden, während hier ein stiller Rückfall erforderlich ist (siehe unten). Die eigene Auswertung ist auf genau dieses Verhalten hin geschrieben.
+
+\subsection{Rückfall auf normales Verhalten}
+
+Kann in einer \texttt{.url}-Datei keine gültige Adresse erkannt werden, wird sie wie eine gewöhnliche Datei behandelt und zum Herunterladen angeboten. Dieses Verhalten war ausdrücklich gefordert.
+
+Die Überlegung dahinter ist, dass eine fehlerhafte Verknüpfungsdatei kein Grund sein darf, das Dokument unzugänglich zu machen. Der Kunde erhält im schlechtesten Fall eine kleine Textdatei statt einer Weiterleitung — ein nachvollziehbares Ergebnis, aus dem sich zudem ablesen lässt, was schiefgegangen ist. Die Alternative, einen Fehler anzuzeigen oder den Eintrag auszublenden, wäre für den Kunden weniger hilfreich.
+
+\subsection{Anzeigename}
+
+Der Dateiname einer Verknüpfung endet auf \texttt{.url}. Diese Endung ist für den Kunden bedeutungslos und würde in der Liste lediglich stören. Sie wird deshalb für die Anzeige entfernt.
+
+Im Review wies \emph{Robin Noack} darauf hin, dass die dafür verwendete Zeichenzahl als unmittelbare Zahl im Code stand, und schlug vor, stattdessen die Länge der Endung selbst zu verwenden. Der Hinweis ist auf den ersten Blick eine Kleinigkeit, trifft aber einen realen Fehlerfall: Zahl und Endung stehen an verschiedenen Stellen, und wird die eine geändert, bleibt die andere unbemerkt zurück.
+
+\subsection{Symbole für Verknüpfungen}
+
+Das INI-Format sieht die Angabe eines Symbols vor. Da benutzerdefinierte Symbole aus den in Abschnitt~\ref{sec:pdf-preview} genannten Gründen nicht ausgeliefert werden, wurde ein anderer Weg gewählt: Es stehen benannte Voreinstellungen zur Verfügung, die auf Symbole der in Houston vorhandenen Bibliothek verweisen. Für die häufigsten Ziele — die Dateiablage, das Dokumentenverwaltungssystem und das Kollaborationswerkzeug des Unternehmens — wurden eigene Symbole ergänzt.
+
+Damit erhält ein Kundenbetreuer die gewünschte visuelle Unterscheidung, ohne dass Dateiinhalt an einer nicht authentifizierten Stelle verarbeitet werden muss. Da diese Voreinstellungen nur nützen, wenn sie bekannt sind, wurden die verfügbaren Namen im internen Wiki dokumentiert und im Pull Request darauf verwiesen.
+
+\subsection{Ausschluss vom ZIP-Download}
+
+Verknüpfungsdateien erhalten keine Auswahlbox und können damit nicht Teil eines Archivs werden. Der Grund ist, dass ein Archiv sonst eine Datei enthielte, die beim Öffnen nicht das erwartete Dokument liefert, sondern eine Verknüpfung, die möglicherweise nur innerhalb des Unternehmensnetzes auflösbar ist. Da eine Verknüpfung fachlich kein Dokument ist, sondern ein Verweis, wäre ihre Aufnahme in ein Dokumentenarchiv irreführend.