Das Interface ValueEngineer<T>

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

Um die Entwicklung im Bereich der EditorValues zu vereinfachen und eine stabile Entwicklungsumgebung zu gewährleisten (vgl. Das Interface EditorValue), wurde das neue Interface ValueEngineer<T> extends Aspectable eingeführt. Das Interface ValueEngineer<T> stellt Basisfunktionalitäten bereit, die für die Implementierung kundenspezifischer Eingabekomponenten benötigt werden, hauptsächlich das Lesen und Schreiben des Persistenzwertes einer Eingabekomponente. Es bildet damit eine übersichtliche und stabile Schnittstelle zum Interface EditorValue<T> (siehe Das Interface EditorValue).

Das Interface ValueEngineer<T> erbt vom Interface Aspectable und unterstützt die Methode <T> T getAspect(@NotNull AspectType<T> aspect). Das heißt, neue Funktionalität, die über die Basisfunktion des Interfaces  ValueEngineer<T> hinausgeht, muss nicht von der ValueEngineer-Implementierung selber umgesetzt werden, sondern kann als Aspekt angefragt werden (siehe Aspekte (ValueEngineer)). Die bisherige Implementierung bleibt kompatibel und muss nicht angepasst werden.

Das Interface ValueEngineer<T> ist typisiert, d. h. der zu verwaltende Wertetyp (Persistenztyp) wird über die (Java 5) Generics-Funktionalität innerhalb der einzelnen Implementierungen festgelegt. Der zurückgelieferte Persistenztyp muss zum Daten-Container-Typ des EditorValue<T> und zu den Wertetypen der zugehörigen SwingGadget- und ValueEngineerFactory-Implementierungen passen (siehe auch Wertetypen).

Es müssen die folgenden Methoden implementiert werden:

• T read(@NotNull List<Node> nodes): Die Methode ist zuständig für das Laden der EditorValues (XML to Object). Dazu wird eine Liste von Knoten (Nodes) übergeben. 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 jeden Knoten gespeicherten Werte werden als String zurückgeliefert und müssen geeignet konvertiert werden. Über die Methode void setValue(@Nullable T value) aus dem Interface ValueHolder<T> (vgl. Aspekt: ValueHolder<T>) wird dieser Wert typsicher an das SwingGadget geliefert.    
  Sind die übergebenen Werte sprachabhängig, muss die korrekte Zielsprache auch bei der weiteren Implementierung (basierend auf dem Rückgabewert) berücksichtigt werden. Die Zielsprache kann über den über den Aufruf von ValueEngineerContext.getLanguage() ermittelt werden (siehe Das Interface ValueEngineerContext<F extends GomFormElement>).
• List<Node> write(@NotNull T value): Über die Methode T getValue() aus dem Interface ValueHolder<T> (vgl. Aspekt: ValueHolder<T>) werden die Werte aus dem SwingGadget gelesen. Der zurückgelieferte Wert vom Typ T wird an die Methode List<Node> write(@NotNull T value) übergeben.Die Methode konvertiert den übergebenen Wert in ein (oder mehrere) Objekte vom Typ Node und liefern diese innerhalb einer Liste von Knoten (Nodes) zurück (Object to XML). Ein Node kann neben dem textuellen Wert (oder weiteren Objekten vom Typ Node) noch einen Namen, der der Spezifikation entsprechen muss, und optionale Attribute enthalten. Die Methode List<Node> write(@NotNull T value) wird bei jedem Speichervorgang im SiteArchitect aufgerufen.
• T getEmpty(): Die Methode erzeugt eine neue, leere Instanz eines Persistenztyps (Leerwert). Dieser wird insbesondere bei komplexen Werten benötigt, beispielsweise um eine leere Liste zu erzeugen. Für einfache Persistenztypen, beispielsweise String, kann null zurückgeliefert werden (siehe auch Wertetypen).
• boolean isEmpty(@NotNull T value): Komplexe Wertetypen sind nie null, möglicherweise jedoch leer (s.o.). Diese Methode prüft, ob die Instanz eines komplexen Persistenztyps, beispielsweise eine Liste, leer ist oder nicht.
• T copy(@NotNull T original): Die Methode erzeugt eine neue Instanz des übergebenen Persistenztyps mit identischen Inhalten (Kopie). Für einfache, unveränderliche Datentypen (beispielsweise Strings), kann an dieser Stelle auch die Original-Instanz zurückgeliefert werden, für alle komplexeren Wertetypen sollte aber darauf geachtet werden, dass eine Änderung der Original-Instanz keine Auswirkung auf die Kopie hat:
  
  original != copy 
  
  Ist der übergebene Wertetyp sprachabhängig, muss die korrekte Zielsprache auch bei der weiteren Implementierung (basierend auf dem Rückgabewert) berücksichtigt werden. Die Zielsprache kann über den über den Aufruf von ValueEngineerContext.getLanguage() ermittelt werden (siehe Das Interface ValueEngineerContext<F extends GomFormElement>).
• <T> T getAspect(@NotNull ValueEngineerAspectType<T> aspect): Das Interface ValueEngineer<T> erbt vom Interface Aspectable und unterstützt die Methode <T> T getAspect(@NotNull AspectType<T> aspect). Neue Funktionalität, die über die Basisfunktion des Interfaces  ValueEngineer<T> hinausgeht, muss nicht von der ValueEngineer-Implementierung selber umgesetzt werden, sondern steht als Interface (Aspekt-Typ) zur Verfügung. Die ValueEngineer-Implementierung muss nur noch die entsprechenden Methoden des Interfaces implementieren, das umliegende FirstSpirit-Framework behandelt dann automatisch alle weiteren Funktionen. Die Methode <T> T getAspect(@NotNull AspectType<T> aspect) erzeugt eine aspektorientierte Instanz des Persistenztyps. Die unterschiedlichen Aspekt-Typen stellen spezielle Anforderungen an die ValueEngineer-Implementierung, die im Abschnitt Aspekte (ValueEngineer) erläutert werden.

Ein Beispiel für die Verwendung eines Aspekts innerhalb der ValueEngineer-Implementierung befindet sich im Abschnitt ValueEngineer - Werte eines SwingGadgets behandeln.