Das Interface ReferenceHolder

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

Eine Instanz vom Typ ReferenceHolder ist ein Daten-Container, der benötigt wird, um interne oder externe Referenzen zu erzeugen. Instanzen vom Typ ReferenceHolder werden über einen ReferenceConstructionAgent erzeugt. Abhängig von den Übergabe-Parametern wird entweder eine Instanz vom Typ IDProviderReferenceHolder oder eine Instanz vom Typ ExternalReferenceHolder zurückgeliefert (siehe Das Interface ReferenceConstructionAgent):

• Eine Instanz vom Typ IDProviderReferenceHolder wird zurückgeliefert, wenn der create-Methode des Interfaces ReferenceConstructionAgent ein Objekt vom Typ IDProvider oder Dataset übergeben wird.
• Eine Instanz vom Typ ExternalReferenceHolder wird zurückgeliefert, wenn der create-Methode des Interfaces ReferenceConstructionAgent eine externe Ressource übergeben wird.

Das Interface bietet den Zugriff auf folgende Methoden:

Reference toReference(@Nullable ChangeCallback callback): Eine Instanz vom Typ ReferenceHolder hält nur die Informationen über das (interne oder externe) Objekt, das bei ihrer Erzeugung übergeben wurde. Die eigentliche Referenz wird erst durch den Aufruf der Methode toReference(…) auf dem ReferenceHolder erzeugt und als neue Instanz vom Typ Reference zurückgeliefert (zu Reference siehe Das Interface Reference). Bei diesen Referenzen handelt es sich ausschließlich um ausgehende Kanten, also Referenzen, die von der Eingabekomponente (bzw. von dem dort enthaltenen Wert) auf andere Objekte verweisen.

Die erzeugten Referenzen, werden bei der Implementierung des Aspekts ReferenceContaining benötigt (siehe Aspekt: ReferenceContaining).

Beim Ändern des referenzierten Objekts in der Eingabekomponente, wird der ReferenceHolder vom FirstSpirit-Framework automatisch mit der neuen Referenz aktualisiert. Die Implementierung einer Callback-Funktion ist in diesem Fall nicht notwendig, der betreffende Parameter muss daher nicht übergeben werden:

Listing: Referenzen - Erzeugen einer neuen Referenz (über ReferenceHolder)

final ExternalReferenceHolder referenceHolder = agent.create(value, "custom");
final Reference reference = referenceHolder.toReference(null);

Innerhalb des Beispiels (s.o.) wird der ExternalReferenceHolder über einen ReferenceConstructionAgent (hier: agent) erzeugt. Das genaue Vorgehen wird in Das Interface ReferenceConstructionAgent beschrieben.

Sind bei einer Änderung des referenzierten Objekts innerhalb der Eingabekomponente weitere Implementierungsschritte erforderlich, beispielsweise weil ein externes System (z. B. eine externe Bild-Datenbank) über die Änderung informiert werden muss, kann der Methode toReference(…) zusätzlich ein Objekt vom Typ ReferenceHolder.ChangeCallback übergeben werden. Über die Methode void onChange() wird diese zusätzliche Implementierung bei einer Änderung der Referenzinformation ausgeführt.

Listing: Referenzen - ChangeCallback bei der Änderung einer Referenz

@NotNull
public List<Reference>
        collectReferences(@NotNull final ExternalReferenceHolder value) {
    final String oldUrl = value.getResource();
    return Collections.singletonList(
        value.toReference(
            new ChangeCallback() {
                public void onChange() {
                    changeExternalReference(oldUrl, value.getResource());
                }
            }
        )
    );
}

private void changeExternalReference(final String oldUrl, final String newUrl) {
    // inform some external system...
}