Referenzhandbuch: Supplements

1                     Themenübersicht

In dieser Dokumentation wird beschrieben, was Supplements sind und wie sie im System eingesetzt werden. Mithilfe eines Business Objects desTyps „Supplement“ kann ein anderes Business Object anderen Typs mit betriebswirtschaftlichen Attributen erweitert werden. Dieses erweiterte Business Object ist in der Regel das Business Entity. Auch ein Dependent kann durch ein Supplement erweitert werden, jedoch kann ein Supplement nicht ein Supplement erweitern.

Die Erweiterung eines Business Entitys per Supplement hat im Vergleich zum Entwicklungsobjekt „Extension“ folgende Vorteile:

  • Zwischen dem Business Entity und dem Supplement entstehen keine technischen Abhängigkeiten. Somit kann sich der Umfang von Konfliktaufgaben und damit verbundener Entwicklungs- und Zeitaufwand verringern.
  • Business Objects der Apps können nicht per Extension erweitert werden, aber mithilfe von Supplements.
  • Ein Supplement erlaubt die Auslagerung von Daten und damit eine geringere Tabellenbreite.

Oft soll ein Supplement auch auf der Bedienungsoberfläche erscheinen und in Sucherweiterungen oder auch im Objektfilter in den Anwendungen „Daten exportieren“ und „Daten importieren“ verwendet werden. Dafür stehen vorbereitete Automatismen zur Verfügung. Alternativ zu Supplements können Sie in Ihrem Projekt auch ein eigenes Business Object verwenden. Wenn Sie z. B. stark von den im Folgenden beschriebenen Automatismen abweichen, dann ist dies sogar der bessere Weg.

In der Doku­mentation „Entwicklungsobjekt: Business Object“ finden Sie die allgemeinen Beschreibungen zur Erfassung und Bearbeitung von Business Objects.

Ein typischer Anwendungsfall für den Einsatz von Supplements ist, eine bestehende Dialog-Anwendung um ein Attribut zu erweitern. In dieser Dokumentation wird eine einfache Beispielentwicklung beschrieben, welche Objekte Sie wie dafür erfassen müssen.

2                     Zielgruppe

Entwickler

3                     Supplement erfassen

Ein Supplement erfassen Sie immer ausgehend von einem Business Object des Typs „Business Entity“ oder „Dependent“, auf das sich das Supplement beziehen soll. Der Bezug von Supplement zu Supplement ist ausgeschlossen.

Nutzen Sie zum Erfassen eines Supplements in der Anwendung „Entwicklungsobjekte“ die anwendungsbezogene Aktion „Dependent oder Supplement erzeugen…“. Gehen Sie dazu nach folgender Anleitung vor.

Anleitung
  1. Öffnen Sie die Anwendung „Entwicklungsobjekte“.
  2. Wählen Sie den Typ „Business Object“ und öffnen das Business Entity (oder Dependent), welches Sie um ein Supplement erweitern möchten.
  3. Wählen Sie in der Standard-Symbolleiste die Entwicklungsaufgabe, mit der Sie das Supplement erfassen möchten.
  4. Drücken Sie in der Standard-Symbolleiste unter dem Menü-Button „Zusätzliche Objekte erzeugen“ auf die Aktion „Dependent oder Supplement erzeugen…“.
  • Das Dialogfenster „Dependent oder Supplement erzeugen“ wird geöffnet.
  1. Wählen Sie im Feld „Typ“ den Eintrag „Supplement“.
  • In den Feldern „Name“ und „Bezeichnung“ werden geeignete Daten vorgeschlagen.
  1. Ändern Sie bei Bedarf die Vorschlagswerte in den Feldern „Name“ und „Bezeichnung“.
  2. Soll das Supplement in einer bestimmten Schnittstelle genutzt werden, dann erfassen Sie diese im Feld „Schnittstelle“.
  3. Drücken Sie auf den Button „OK“.
  • Das Dialogfenster schließt sich und ein Business Object des Typs „Supplement“ wird mit den erfassten Daten erzeugt. Es befindet sich im Status „Neu“ und wird der zuvor gewählten Entwicklungsaufgabe zugeordnet. Die Einstellungen werden vom Business Entity (oder Dependent) übernommen, auf das sich das Supplement beziehen soll.
  • Eine Beziehung „_businessObject“ auf das Business Entity wird erzeugt.
  • Der Primärschlüssel des Supplements wird gemäß dem Primärschlüssel des zugehörigen Business Entitys erzeugt.
  1. Erfassen Sie die Attribute, die das Business Entity erweitern sollen.
  2. Drücken Sie in der Standard-Symbolleiste auf den Speichern-Button.
  • Das Supplement wird in der gewählten Entwicklungsaufgabe gespeichert.

Hinweis:

Sie können das Supplement auch direkt erfassen, ohne die Aktion „Dependent oder Supplement erzeugen…“ zu nutzen. Prüfungen stellen sicher, dass die manuelle Erfassung konsistent ist. Das Feld „Schnittstelle“ finden Sie unter unter dem Karteireiter „Editor“, Karteireiter „Einstellungen“ am unten Karteireiterrand, in der Rubrik „Sonstige Einstellungen“.

4                     Objektsicht erfassen

In der Regel sollen die Attribute eines Supplements auch auf der Bedienungsoberfläche in der entsprechenden Anwendung bearbeitbar sein. Für eine anpassbare Anwendung steht der „Designmodus“ zur Verfügung, über den Sie das Layout Ihren Bedürfnissen anpassen können. Damit Sie die Attribute im Designmodus der Anwendung einfach hinzufügen können, ist ein Entwicklungsobjekt des Typs „Objektsicht“ erforderlich. Für die Erzeugung einer Objektsicht wird eine Namenskonvention angeboten, wie das folgende Beispiel zeigt:

Beispiel:

Vollqualifizierter Name des Supplements:

com.<Entwicklungspräfix>.app.general.obj.ItemSupplement

Hat eine Objektsicht für das Supplement den folgenden vollqualifizierten Namen, dann wird dies automatisch im Designmodus der entsprechenden Anwendung im andockbaren Fenster „Designmodus“ z. B. unter dem Kareitereiter „Struktur“ angeboten, weil der Namensbestandteil „obj“ durch „model“ ersetzt wurde:

com.<Entwicklungspräfix>.app.general.model.ItemSupplement.

Werden also Supplement und Objektsicht mit den identischen vollqualifizierten Namen mit Ausnahme der Bestandteile „obj“ und „model“ gespeichert, dann wird die Objektsicht automatisch im Designmodus der anpassbaren Anwendung mit ihren Attributen zur Auswahl angeboten.

Ihre Objektsicht benötigt noch die Information der implementierenden Klasse. Nutzen Sie dazu beispielsweise folgende Oberklasse:

com.cisag.pgm.base.DataSupplement

Im Konstruktor können Sie als „parent“ die Objektsicht angeben, die damit effektiv erweitert wird und somit auch andere ausschließen. Außerdem erben die Objektsichten so die Einstellungen von der spezifizierten Hauptsicht. Ist beispielsweise die Hauptsicht unter bestimmten Bedingungen nicht editierbar, dann wirkt sich diese Bedingung auch auf die Objektsicht des Supplements automatisch aus. Je nach Anforderungen in Ihrem Projekt kann auch sinnvoll sein, als „DataObject“ das normale pgm-DataObject zu verwenden. Weitere Informationen zu Objektsichten finden Sie in der Dokumentation „Entwicklungsobjekt: Objektsicht“.

Wenn Sie die Namenskonvention eingehalten oder per Hooks Ihr Supplement eingebunden haben, dann steht Ihre Objektsicht im Designmodus der Anwendung zur Verfügung. Sie finden es darin gemäß folgendem Namensmuster (mit den vorherigen Beispieldaten): „<Entwicklungspräfix>_ItemSupplement“

Hinweis:

Aus technischen Gründen müssen hierfür sowohl das Supplement als auch die Objektsicht einmal aktiviert sein. Der Namenszusatz <Entwicklungspräfix> sorgt dafür, dass eine Namenskollision mit Supplements aus anderen Systemen ausgeschlossen ist.

5                     Implementierung

Die empfohlene Minimal-Implementierung ist für neue Supplements, die Vorschlagswertermittlung durchzuführen und die erfassten Daten zu prüfen. Dies können Sie typischerweise durch folgende Hooks erfüllen:

  • applyDefaults
  • validate

Im Folgenden wird beispielhaft die Anwendung „Artikel“ durch ein Supplement ergänzt. Der Name dieses Supplements ist „ItemSupplement“. Diesem wurde das Attribut „yourAttribute“ hinzugefügt.

Für andere Business Objects gilt ein entsprechendes Vorgehen.

5.1               DataObject

Um eine Objektsicht erfassen zu können, benötigen Sie ein DataObject. Im einfachsten Fall sieht die Implementierung wie folgt aus:

public class ItemSupplementDataObject extends DataSupplement<ItemSupplement, ItemView> {

public ItemSupplementDataObject(ItemSupplement obj, ItemView parentView) {

super(obj, parentView);

}

}

5.2               Hooks

Um die Anwendung „Artikel“ mithilfe eines Supplements zu erweitern, müssen Sie in Ihrem Projekt die entsprechenden Hooks implementieren.

Hook Contract

Sie benötigen in diesem Fall den folgenden Hook Contract. Hierbei müssen Sie <Entwicklungspräfix> durch das Entwicklungspräfix Ihres Systems ersetzen.

<?xml version=”1.0″ encoding=”UTF-16″?>

<HookContract xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” xsi:noNamespaceSchemaLocation=”HookXMLSchema.xsd”>

<!– Don’t change this line and the lines above! –>

<HOOK_IMPLEMENTATION>

<contract>

<hook>

<interface>

com.cisag.app.general.item.hook.log.ItemApplyDefaultsHook

</interface>

<implementation>

com.<Entwicklungspräfix>.app.general.ItemHookImpl

</implementation>

</hook>

<hook>

<interface>

com.cisag.app.general.item.hook.log.hook.ItemValidateHook

</interface>

<implementation>

com.<Entwicklungspräfix>.app.general.ItemHookImpl

</implementation>

</hook>

</contract>

</HOOK_IMPLEMENTATION>

</HookContract>

applyDefaults

Im Folgenden eine Beispiel-Implementierung des „applyDefaults“-Hooks.

import com.cisag.pgm.base.Path;

public class ItemHookImpl implements ItemApplyDefaultsHook<Item, ItemAccess.Full>{

public void applyDefaults(Full full, ItemView itemView){

ItemSupplement suppObj = ItemSupplement.newTransientInstance();

suppObj.setYourAttribute(…) // your attribute

byte[] org = Company.getCompanyGuid();

CisObjectInitializer.getInstance(ItemSupplement.class).init(suppObj, org);

ItemSupplementDataObject itemSupplementDataObject =

new ItemSupplementDataObject(suppObj, itemView);

CisDataViewManager dvm = CisEnvironment.getInstance().getDataViewManager();

ItemSupplementAccess access = dvm.create(ItemSupplementView.class, itemSupplementDataObject);

Path suppPath = Path.getSupplementInstance(ItemView.class, ItemSupplementView.class);

full.setValue(suppPath, access);

}

}

validate

Im Folgenden eine Beispiel-Implementierung des „validate“-Hooks:

import com.cisag.pgm.base.Path;

public class ItemHookImpl implements ItemValidateHook<Item, ItemAccess.Full>

public void validate(ItemView itemView){

Path suppPath = Path.getSupplementInstance(ItemView.class, ItemSupplementView.class);

Path append = suppPath.append(ItemSupplementView.Attribute.$yourAttribute);

ItemSupplementView value = itemView.getValue(suppPath);

CisMessageManager mm = CisEnvironment.getInstance().getMessageManager();

mm.setProgramMessagePath(suppPath);

if (value.getYourAttribute()!=null){

// insert validation here

}

}

6                     Programmier-Schnittstelle

Wenn Sie passende Hooks implementieren, dann besteht normalerweise keinerlei Notwendigkeit eines programmatischen Eingriffs. Sollte aber z. B. eine Anwendung nicht anpassbar oder die zur Verfügung stehenden Hooks für Ihre Zwecke nicht ausreichend sein, dann können Sie auch selbst auf das Supplement zugreifen.

Wenn Sie direkt programmatisch zugreifen möchten, dann stehen Ihnen folgende Methoden im CisObject zur Verfügung:

  • get_Supplement(Supplement.class)

Damit erhalten Sie das am CisObject gespeicherte Supplement-Object, wenn es vorhanden ist.

Ist kein Supplement-Object vorhanden, dann wird „null“ zurückgegeben.

  • set_Supplement(Supplement.instanz)

Damit wird eine Supplement-Instanz in das CisObject gesetzt.

7                     Persistenz

Wir empfehlen, ein Supplement nur über das Business Entity zu öffnen und zu speichern. Über die erfassten Meta-Daten in der Anwendung „Entwicklungsobjekte“, d. h. die Beziehung „_businessObject“, wird erkannt, welche Supplements zu einem Business Entity (oder Dependent) gehören. Diese werden dann automatisch geöffnet und in die Instanz des Business Entitys aufgenommen. Dort können Sie diese mit folgender Methode abfragen:

get_Supplement(Supplement.class)

Sollte zu dieser Instanz des Business Entitys keine Supplement-Instanz gehören, dann wird „null“ zurückgegeben.

Das gilt ebenso beim Speichern: Sie speichern das Business Object. In diesem Zuge wird mit dem Persistenzdienst überprüft, ob zu dieser Instanz eine Supplement-Instanz gehört. Falls ja, dann wird diese Instanz ebenfalls in derselben Transaktion gespeichert.

8                     Auswirkungen

Wenn Sie wie oben beschrieben die Namenskonvention für Supplements einhalten, dann steht Ihnen das Supplement bzw. eine darauf basierende Objektsicht im Designmodus zur Verfügung.

Zudem stehen Ihnen folgende Automatismen zur Verfügung:

In den Anwendungen „Daten importieren“ und „Daten exportieren“ steht Ihnen das Supplement automatisch zur Verfügung. Sie müssen dafür nicht den Controller erweitern. Wenn Ihr Supplement wie im Beispiel „ItemSupplement“ heißt und zum Business Object „Item“ gehört, dann erscheint im Filter für das Business Object „Item“ eine Beziehung zum Supplement. Der Name der Beziehung lautet „<Entwicklungspräfix>_ItemSupplement“, analog zum Designmodus. Hierbei ist <Entwicklungspräfix> das Entwicklungspräfix Ihres Systems.

Auf entsprechende Weise steht Ihnen Ihr Supplement in anpassbaren Suchen sowie in den Cockpit-Anwendungen zur Verfügung.

Weiterhin benötigen Sie keinen selbst programmierten „National Language Support“ (NLS). Wenn Sie für ein Supplement ein NLS-fähiges Attribut erfassen, dann wird mit der Standard-Implementierung dieser NLS angeboten.

Hinweis:

Technisch gesehen ist auch ein Supplement ein Business Object, so wie jedes andere. Der Zweck eines Supplements ist, eine Erweiterung des Business Entitys. Hierfür stehen verschiedene Automatismen zur Verfügung, wie das automatische Öffnen und Speichern, Einbindung in den Filter beim Datenimport etc. Sollten Sie stark in den Automatismus eingreifen oder ihn gar nicht nutzen, dann empfiehlt sich, kein Supplement, sondern ein Business Object des Typs „Business Entity“ zu verwenden.

Czy ten artykuł był pomocny?

Wyślij opnie