Das Interface ReferenceTransformationAgent

Package: de.espirit.firstspirit.client.access.editor

Das Interface ReferenceTransformationAgent stellt Funktionalität bereit, mit deren Hilfe Instanzen vom Typ ReferenceHolder in ihre Persistenzform (und umgekehrt) transformiert werden können. Ein ReferenceTransformationAgent kann ReferenceHolder auf FirstSpirit-Elemente (Typ IDProvider), Datensätze (Typ Dataset) und externe Ressourcen (z. B. URLs) behandeln (siehe Das Interface ReferenceHolder).

Eine Instanz vom Typ ReferenceTransformationAgent kann über einen SpecialistsBroker (Das Interface SpecialistsBroker siehe Das Interface SpecialistsBroker) mithilfe der Methode requireSpecialist(ReferenceTransformationAgent.TYPE) angefordert werden:

Listing: Referenzen - ReferenceTransformationAgent anfordern

...

final ReferenceTransformationAgent referenceTransformationAgent =
        _context.getBroker().requireSpecialist(ReferenceTransformationAgent.TYPE);

...

Eine neue Instanz vom Typ SpecialistsBroker wird über den ValueEngineerContext geholt (Beispiel siehe Listing 23: Referenzen – SpecialistsBroker über ValueEngineerContext anfordern). Dieser Kontext wird Objekten vom Typ ValueEngineer<T> während der Erzeugung übergeben. Um innerhalb der ValueEngineer-Implementierung Zugriff auf den Kontext zu haben, muss dieser bei der Erzeugung der ValueEngineer-Instanz innerhalb der ValueEngineerFactory-Implementierung weitergereicht werden (Listing 23: Referenzen - ValueEngineerContext übergeben (ValueEngineerFactory)).

Das Interface bietet den Zugriff auf folgende Methoden:

ReferenceHolder read(@NotNull Node node, final Language language, final boolean release): Die Methode ist zuständig für das Lesen der Werte aus der Persistenz und die Überführung in ein Objekt vom Typ ReferenceHolder (XML to Object). Dazu wird ein Objekt vom Typ Node übergeben, das die Informationen zum referenzierten Element enthält. Außerdem wird der Parameter language übergeben, der die Sprache definiert, für die ein Knoten gelesen werden soll, und der Parameter release, der definiert,  ob die Informationen im Freigabestand vorliegen. Ein Objekt vom Typ Node ist ein Daten-Container, der einen Namen, Attribute (optional) und entweder einen textuellen Wert oder weitere Objekte vom Typ Node (Kind-Knoten) enthält. Die für einen Knoten gespeicherten Werte werden als Instanz vom Typ ReferenceHolder zurückgeliefert (siehe Das Interface ReferenceHolder).    

Listing: Referenzen - ReferenceTransformationAgent – read(…)

@Nullable
public MyPersistencyObject read(@NotNull final List<Node> nodes) {
    final SpecialistsBroker broker = _context.getBroker();
    final ReferenceTransformationAgent agent =
            broker.requireSpecialist(ReferenceTransformationAgent.TYPE);
    ExternalReferenceHolder ref =
            agent.read(nodes.get(0), _context.getLanguage(),_context.isRelease());
    return new MyPersistencyObject(ref);
}

Analog zur Beispiel-Implementierung einer Text-Eingabekomponente in Beispiel: Implementierung einer Eingabekomponente kann der ReferenceHolder auch als Datentyp einer Eingabekomponente über die read-Methode der ValueEngineer-Implementierung zurückgeliefert werden (vgl. Beispiel ValueEngineer-Impl. – Methode read(…) – XML to Object), z. B.:

Listing: Referenzen - ReferenceTransformationAgent – read(…)

@Nullable
public ExternalReferenceHolder read(@NotNull final List<Node> nodes) {
    final SpecialistsBroker broker = _context.getBroker();
    final ReferenceTransformationAgent agent =
            broker.requireSpecialist(ReferenceTransformationAgent.TYPE);
    return (ExternalReferenceHolder)
            agent.read(nodes.get(0), _context.getLanguage(),_context.isRelease());
}

Node write(@NotNull String tag, @NotNull ReferenceHolder holder): Die Methode ist zuständig für die Übernahme der Werte aus der Instanz vom Typ ReferenceHolder in ihre Persistenzform (Object to XML). Die Methode konvertiert den übergebenen ReferenceHolder dazu in ein Objekt vom Typ Node. Ein Objekt vom Typ Node muss neben seinem textuellen Wert (oder weiteren Objekten vom Typ Node) auch einen Namen besitzen, der hier über den Parameter tag übergeben wird.

Analog zur Beispiel-Implementierung einer Text-Eingabekomponente in Beispiel: Implementierung einer Eingabekomponente kann der hier zurückgelieferte Node über die write-Methode der ValueEngineer-Implementierung zurückgeliefert werden (vgl. Beispiel ValueEngineer-Impl. – Methode write(…) –Object to XML), z. B.:

Listing: Referenzen - ReferenceTransformationAgent - write(…)

@NotNull
public List<Node> write(@NotNull final ExternalReferenceHolder value) {
    final SpecialistsBroker broker = _context.getBroker();
    final ReferenceTransformationAgent agent =
            broker.requireSpecialist(ReferenceTransformationAgent.TYPE);
    final Node node = agent.write("url", value);
    return Collections.singletonList(node);
}