Beispiel: Referenz-Implementierung AdvancedUrlFactory

Die UrlFactory-Implementierung AdvancedUrlFactory, die Bestandteil der Standard-FirstSpirit-Serverinstallation ist, setzt eine Pfadstrategie um, in der Pfad- und Dateinamenbestandteile der URL mittels sprachabhängiger Anzeigenamen gewählt werden. Somit ist es auch möglich, URLs zu erstellen, die Unicode-Zeichen beinhalten; beim Aufruf einer solchen URL muss ein Browser dementsprechend die Enkodierung solcher Sonderzeichen in UTF-8 beherrschen.

Die von der AdvancedUrlFactory generierten Pfade entsprechen folgenden Kriterien:

• Die Pfad- und Dateinamenbestandteile werden mittels der sprachabhängigen Anzeigenamen der Elemente gewählt.
• Sprachunabhängige Medienelemente sowie Ordner der Medien-Verwaltung werden anhand der Anzeigenamen in der Mastersprache des Projekts benannt.
• Für Seitenreferenzen, die mittels Content Projektion dafür konfiguriert sind, einzelne Datensätze pro Seite einzubinden, können Dateinamen basierend auf Inhalten der jeweiligen Tabelle verwendet werden. Hierzu muss im Feld „Variable für Text der Menü-Übersicht (Sitemap)“ in der Karteikarte „Daten“ der Seitenreferenz eine Spalte der Tabelle ausgewählt werden.
• Die URLs, die für Projektelemente gespeichert werden, entsprechen der finalen Verzeichnis- und Dateistruktur des generierten Projekts, relativ zum Generierungsverzeichnis.
• Da Anzeigenamen der Elemente zur Generierung der URLs verwendet werden, können sowohl Pfadelemente als auch Dateinamen UTF-8-Zeichen beinhalten. Zeichen, die in den meistverwendeten Dateisystemen für besondere Zwecke reserviert sind, werden in den Namensbestandteilen der URLs mit Bindestrichen (-) ersetzt. Die URL-Bestandteile werden in dieser Implementierung nicht in Kleinschreibung umgewandelt.

Da die Klasse AdvancedUrlFactory Bestandteil der Kernfunktionalität von FirstSpirit 5.0 ist, ist der Quellcode unter dem Namen UrlFactoryExample im Zip-Archiv zum Modul-Entwicklerhandbuch (MDEV_modexamples.zip - siehe Online-Dokumentation FirstSpirit, Seite „Dokumentation / Für Entwickler“) enthalten. In den nachfolgenden Beispielen wird der Name UrlFactoryExample verwendet.

Klassendefinition

Die Klasse UrlFactoryExample implementiert das Interface UrlFactory. Um Daten, die nur der Methode init(…) zur Verfügung gestellt werden, zu persistieren, werden klasseninterne Felder zur Speicherung eines PathLookup-Objekts sowie der Konfigurationseinstellung useWelcomeFilenames (gesetzt in der Datei module.xml) definiert.

public class UrlFactoryExample implements UrlFactory {

    // Felder für Persistenz während des Objektlebenslaufs.
    private PathLookup _pathLookup;
    private boolean _useWelcomeFilenames;

    // Methoden werden in nachfolgenden Abschnitten behandelt.

}

public void init(Map<String, String>, PathLookup):

Die Methode init(…) wird jeweils nach Instanziierung eines UrlFactory-Objekts aufgerufen, um das Objekt mit während einer Generierung unveränderlichen Daten zu initialisieren.

Beim Aufruf werden als Parameter ein Map-Objekt, mit in der Komponentendefinition in der Datei module.xml angegebenen Einstellungen sowie ein PathLookup-Objekt, das zur Abfrage von benutzerdefinierten URLs auf Store-Verzeichnissen verwendet werden kann, bereitgestellt.

public String getUrl(final ContentProducer contentProducer,
final TemplateSet templateSet, final Language language,
final PageParams pageParams):

Diese Variante der Methode getUrl(…) wird verwendet, um für Elemente der Struktur-Verwaltung, die Inhalte basierend auf Vorlagen erzeugen, URLs abzufragen. Beispielsweise verweisen Seitenreferenzen auf Seiten der Inhalte-Verwaltung, welche auf Vorlagen basieren und je Projektsprache und Vorlagensatz unterschiedliche Inhalte erzeugen können.

Dieser Methode werden als Parameter ein Store-Element vom Typ ContentProducer, der angefragte Vorlagensatz sowie die angefragte Projektsprache übergeben, für die eine URL erstellt werden soll. Zusätzlich werden—wenn verfügbar—Seitenparameter, die Informationen zu einer Content Projection beinhalten können, übergeben.

Im Verlauf des Algorithmus wird zunächst mittels des PathLookup-Objekts geprüft, ob für das Store-Element und die Kombination auf Vorlagensatz und Projektsprache eine gespeicherte URL vorliegt. Ist dem so, wird diese URL verwendet und zurückgegeben. Liegt keine gespeicherte URL vor, wird dieselbe Prüfung für das Elternobjekt—zumeist ein Ordner—durchgeführt; im Fall, dass auf dem Elternobjekt eine gespeicherte URL vorliegt, wird diese URL als Pfadbestandteil verwendet und dann per getName(…) ein passender Dateiname, später die aus dem Vorlagensatz stammende Dateityperweiterung angehängt. Kann weder auf dem Store-Element selbst noch auf dem Elternelement eine gespeicherte URL ausgemacht werden, wird der Pfad mittels collectPath(…) festgestellt und dann ebenfalls ein Dateiname per getName(…) und die Dateityperweiterung aus dem Vorlagensatz ermittelt und zu einer URL zusammengefügt.

Die von dieser Methode zurückgegebene URL soll eine relative Pfadangabe sowie einen Dateinamen inklusive Dateityperweiterung beinhalten, beginnend mit einem Schrägstrich, z. B.

/ordner1/ordner2/datei.ext

wobei in dieser URL datei den Anzeigenamen einer Seitenreferenz repräsentieren, ordner1 und ordner2 die Menünamen der beiden, der Seitenreferenz übergeordneten Seitenreferenzordner darstellen können. Die Dateityperweiterung ext stammt in diesem Beispiel aus der Definition des angefragten Vorlagensatzes.

public String getUrl(final Media node, @Nullable final Language language,
@Nullable final Resolution resolution):

Die auf Elemente aus der Medien-Verwaltung spezialisierte Variante der Methode getUrl(…) wird für Medien-Elemente aufgerufen und erhält neben dem Medienelement selbst die Projektsprache sowie - bei Bildelementen - die Zielauflösung, für deren Kombination eine URL erstellt werden soll.

Die Anforderungen an die zurückgegebene URL sind dieselben wie die der getUrl(…)-Variante für Seitenreferenzen.

private String getName(final ContentProducer contentProducer,
final TemplateSet templateSet, final Language language,
final PageParams pageParams):

Diese Methode generiert anhand eines ContentProducer-Objekts einen passenden Dateinamen für die Kombination aus Vorlagensatz, Projektsprache und Seitenparameter. Der Aufruf dieser Methode geschieht während der Ermittlung einer Seitenreferenz-URL, der zurückgelieferte Dateiname wird schliesslich in der von getUrl(ContentProducer, TemplateSet, Language, PageParams) erzeugten URL verwendet.

Wird durch das als Parameter übergebene PageParams-Objekt angedeutet, dass eine URL für eine Detailseite eines Datensatzes (Content-Projektion mit einem Datensatz pro Anzeigeseite) angefragt wird, so ermittelt diese Methode, ob auf der aktuellen Seitenreferenz eine Tabellenspalte in der Einstellung „Variable für Text der Menü-Übersicht (Sitemap)“ gewählt ist - in diesem Fall wird der Inhalt dieser Spalte für die angefragte Reihe der Tabelle zur Generierung eines Dateinamens erzeugt.

Wurde in der Datei module.xml der Konfigurationsparameter useWelcomeFilenames auf yes oder true gesetzt, wird für Seitenreferenzen, die als Startseite eines Ordners der Struktur-Verwaltung markiert sind, automatisch der Dateiname index zurückgegeben. So kann mit passender Webserver-Konfiguration z. B. die URL http://www.domain.de/produkte/ verwendet werden, um die Startseite des Ordners, die den Dateinamen index.html erhielt, anzufragen.

In dieser Implementation wird die Dateityperweiterung innerhalb der getUrl(…)-Methoden ermittelt; getName(…) ist also nur dafür zuständig, einen Dateinamen ohne Erweiterung zu ermitteln.

private String getName(final IDProvider node, final Language language):

Die Variante getName(IDProvider, Language) wird innerhalb der Klasse UrlFactoryExample dazu verwendet, anhand sprachabhängiger Anzeigenamen eines Store-Elements einen Dateinamen zurückzuliefern.

Wie die Methode getName(ContentProducer, TemplateSet, Language, PageParams) auch, ist diese Methode nur dafür zuständig einen Dateinamen ohne Dateityperweiterung zu liefern.

final void collectPath(final IDProvider folder, final Language language,
@Nullable final TemplateSet templateSet, final int length, final
StringBuilder collector):

Diese Methode ermittelt durch rekursive Aufrufe einen Pfad zum (in den Parametern) angegebenen Ordner folder. Hierbei wird die Elternkette des Ordners bis hin zum Stammelement der jeweiligen Verwaltung abgefragt. Kann für den behandelten Ordner eine gespeicherte URL festgestellt werden, wird die Rekursion abgebrochen, die gespeicherte URL wird daraufhin als Anfang des von der äusseren Methodeninstanz der Rekursion Pfades verwendet.

String getExtension(final Media media, @Nullable final Language lang,
@Nullable final Resolution resolution):

Die Methode getExtension(…) ermittelt eine passende Dateityperweiterung für Medienelemente.

final String cleanup(String name):

Um die Verwendung von reservierten (in den meistverwendeten Dateisystemen) oder in URLs nicht erlaubten Zeichen in der finalen URL zu vermeiden, bietet diese Methode die Möglichkeit, solche Zeichen durch jeweils einen Bindestrich (-) zu ersetzen. Dazu wird die in der Klasse definierte Konstante SPECIAL_CHARS verwendet.

private static String resolve(Entity entity, final String varName, final
Language language, final String defaultLabel):

Diese Methode bietet eine Hilfestellung, um den Inhalt einer im Parameter varName namentlich angegebenen Tabellenspalte auszulesen. Sie wird von getName(ContentProducer, TemplateSet, Language, PageParams) verwendet, um beim Vorliegen einer Sitemap-Variable, den Dateinamen für die Detailansicht eines Datensatzes auf dem von resolve(…) zurückgegebenen String zu basieren.