Mithilfe von Indikatoren können technische und betriebswirtschaftliche Kennzahlen eines Semiramis-Systems überwacht werden. Die betriebswirtschaftlichen Kennzahlen werden als dynamische Indikatoren mithilfe des Workflows bereit gestellt. Mit den dynamischen Indikatoren lassen sich nicht alle Anforderungen abbilden. Die Anforderungen können mit individuell programmierten Indikatoren erfüllt werden. Dieses Dokument erläutert grundlegenden Vorgehensweisen bei der Implementierung eines Indikators und gibt Hinweise für die Verwendung des entsprechenden API, die Semiramis hierfür bereitstellt.
1 Zielgruppe
Anwendungsentwickler
2 Begriffsbestimmung
Hook-Contract-Definitionen
Eine Hook-Contract-Definition enthält zusammengehörige Hooks, z.B. alle Hooks auf Business-Entity-Ebene eines bestimmten Business Entitys. Hooks aus der Logik- und der Dialogschicht für dasselbe Business Entity sollten jedoch in getrennten Hook-Contract-Definitionen enthalten sein.
Erst durch eine Hook-Contract-Definition sind die Hooks zur Implementierung freigegeben.
Hook-Contract-Definitionen sind Entwicklungsobjekte des Typs „Hook Contract“, Subtyp „Hook-Contract-Definition“ (XML: HOOK_DEFINITION). Es handelt sich um einen XML-Entwicklungsobjekttypen.
Hook-Contract-Implementierungen
Um einen Hook zu implementieren, ist neben der Hook-Implementierung (Java-Klasse) auch eine Hook-Contract-Implementierung nötig. In der Hook-Contract-Implementierung werden alle zu implementierenden Hooks und die jeweilige Implementierungsklasse angegeben.
Für eine Hook-Contract-Implementierung kann eine beliebige Untermenge der angebotenen Hooks implementiert werden. Es ist also nicht erforderlich, alle Hooks zu implementieren.
Eine Hook-Contract-Implementierung ist ein Entwicklungsobjekt vom Typ „Hook Contract“, Subtyp „Hook-Contract-Implementierung“ (XML: „HOOK_IMPLEMENTATION“).
Indikator
Ein Indikator repräsentiert eine technischer oder eine betriebswirtschaftliche Kennzahl, deren Wert überwacht werden soll. Ein Indikator wird durch ein Namensraum und einen Name eindeutig identifiziert. Innerhalb von einem Namensraum können sich mehrere Indikatoren befinden, die sich durch den Namen unterscheiden. Die Indikatoren unterscheiden sich nach Art der Operationen und Darstellung der Informationen zur Überwachung. Das Semiramis System-Engine stellt bereits zur Verfügung eine Reihe der Indikatoren – die Standard-Indikatoren. Weitere dynamische Indikatoren können vom Benutzer selbst angelegt werden. In diesem Fall wurden die anhang der Aktivitätsdefinitionen berechnet und mithilfe von Semiramis Workflow zugängig gemacht. Externe Überwachungswerkzeuge können auf Indikatoren als MBean zugreifen.
3 Entwicklung von Indikatoren
Die Indikatoren werden auf Basis von der Hooks- Schnittstellentechnologie entwickelt:
- Legen Sie Hook-Contract-Implementierung wird als Entwicklungsobjekt an.
- Implementieren Sie die Hooks des Hook-Contracts in Java-Code.
- Registrieren Sie in der Hook-Implementierung einen oder mehrere von Ihnen implementierte Indikatoren.
3.1 XML-Entwicklungsobjekttyp „Hook-Contract“ erfassen
Grundvoraussetzung einen ausprogrammierten Indikator ist ein Entwicklungsobjekt „Hook-Contract“ mit dem Subtyp „HOOK_IMPLEMENTATION“. Das XML-Element <contract> dieses Entwicklungsobjektes muss auf die folgende Hook-Definition verweisen:
com.cisag.pgm.appserver.Server
Des Weiteren müssen die Schnittstelle und deren Implementierung für den Hook eingetragen werden. Wenn die Entscheidung getroffen wurde, dass der ausprogrammierte Indikator für jede OLTP-Datenbank zur Verfügung stehen sollte, muss unterhalb von dem XML-Element <hook> das XML-Element <interface> mit dem OLTP-Schnittstellen-Hook angegeben werden:
com.cisag.pgm.services.indicator.hook.OLTPIndicatorHook
Falls der Indikator nur für Repository-Datenbank zur Verfügung stehen sollte, muss die folgende Schnittstelle für den Hook verwendet:
com.cisag.pgm.services.indicator.hook.RepositoryIndicatorHook
In einer Hook-Contract-Implementierung kann sowohl OLTP- als auch der RepositoryIndikatorHook implementiert werden.
Die genaue Beschreibung der XML-Elemente für dieses Entwicklungsobjekt ist in der Dokumentation „Entwicklungsobjekte“ enthalten.
3.2 Indikator erstellen
Es können verschiedene Indikatoren bereit gestellt werden. Bei zwei Indikatoren wird eine Hilfsklasse benötigt, die die Indikatorwerte liefert. Die Hilfskassen werden für folgende Indikatoren benötigt:
- Zahlindikatoren
- Zustandsindikatoren
Beim Abfragen der Indikatorwerte für einen OLTP-Indikator ist wie üblich eine Transaktion für die abgefragte OLTP-Datenbank offen.
Im Folgenden werden diese Schnittstellen für die Hilfsklassen beschrieben.
3.2.1 Schnittstelle für Zahlindikator
Für einen Zahlindikator müssen Sie eine Logik bereitstellen, die den Wert des Indikators berechnet. Um den Wert zu berechnen, implementieren Sie die folgende Schnittstelle:
interface com.cisag.pgm.services.indicator.ext.NumberIndicator
public CisDecimal getValue();
}
Die Methode getValue() liefert den numerischen Wert des Indikators zurück. Die Einheit des Indikators geben Sie bei der Registrierung an.
3.2.2 Schnittstelle für Zustandsindikator
Für einen Zustandsindikator müssen Sie eine Logik bereitstellen, die den Zustandswert des Indikators berechnet. Um den Zustandswert zu berechnen, implementieren Sie die folgende Schnittstelle:
interface com.cisag.pgm.services.indicator.ext.StateIndicator {
public StateIndicatorState getValue();
}
Die Methode getValue() liefert den Zustand des Indikators zurück als Container vom Typ StateIndicatorState zurück. Der Container StateIndicatorState besteht aus zwei Getter-Methoden:
public String getState(){
return state;
}
public String getDescription(){
return description;
}
Die Methode getState() liefert der Zustandsrepräsentation als die Zeichenkette, die Methode getDescription() liefert die Beschreibung des Zustandes als die Zeichenkette.
3.3 Hook-Contract implementieren
Wenn ein Indikator für jede OLTP-Datenbank bereit gestellt werden soll, muss die folgende Schnittstelle implementiert werden:
com.cisag.pgm.services.indicator.hook.OLTPIndicatorHook
Wenn ein Indikator für die Repository-Datenbank bereit gestellt werden soll, muss die folgende Schnittstelle implementiert werden:
com.cisag.pgm.services.indicator.hook.RepositoryIndicatorHook
Jeder der Schnittstelle hat die folgende Methode:
public void initialize(IndicatorRegistry registry).
In dieser Methode können die einzelnen Indikatoren registriert werden.
3.4 Indikator registrieren
Der erstellte Indikator muss registriert werden. Die Registrierung Hook-Contract-Implementierung vorgenommen. Die Registrierung erfolgt, in der Methode initialize(IndicatorRegistry registry). Die Indikatoren werden an der com.cisag.pgm.services.indicator.hook.IndicatorRegistry registriert.
Die Klasse IndicatorRegistry hat folgende Methoden zum Registrieren von Indikatoren:
- Für einen Aggregationsindikator:
public void registerAggregatorIndicator(
String name,
String description,
Datatype datatype,
String unit);
- Für einen Zahlindikator:
public void registerNumberIndicator(
String name,
String description,
NumberIndicator indicator,
String unit);
- Für eine Zählerindikator:
public void registerCounterIndicator(
String name,
String description);
- Für einen Zustandsindikator:
public void registerStateIndicator(
String name,
String description,
StateIndicator indicator);
| Parameter | Beschreibung |
| name | Durch den Parameter „name“ muss der vollqualifizierte Name des Indikators übergeben werden, bestehend aus dem Namensraum und Kurznamen des Indikators. Die Konventionen zur Namensgebung muss gehalten werden, die im Dokument „Einführung: Indikatoren“ beschrieben sind. |
| description | Der Parameter “description” soll die Bedeutung des Indikators beschreiben. Beachten Sie, dass die Beschreibung nicht mehrsprachig ist, d.h. nur in einer Sprache angegeben werden kann. Die Beschreibung sollte nicht länger als 100 Zeichen sein und für internationale Lösungen in Englisch sein. |
| datatype | Der Parameter “datatype” gibt den Datentyp eines Aggregationsindikators an. |
| indicator | Mit dem Parameter “indicator” übergeben Sie ein Objekt um den Wert eines Zahl- oder Zustandsindikators zu berechnen. |
| unit | Der Parameter “unit” ist die Einheit des Indikators. Beachten Sie, dass die Einheit nicht mehrsprachig ist, d.h. nur in einer Sprache angegeben werden kann. |
3.5 Indikator testen
Die Indikatoren können in der Anwendung „Indikatoren anzeigen“ geöffnet werden und so getestet werden. Bitte beachten Sie, dass die XML-Datei zu Hook-Contract-Implementierung im Java-Klassenpfad ist. Falls der vollqualifizierte Name des Indikators nicht der Namenskonventionen entspricht, wird eine IllegalArgumentException geworfen, wo u.a. auch das zu erwartendes Namensraum auftaucht.
3.6 Beispiel
XML-Entwicklungsobjekt com.cisag.app.services.indicator.log.OLTPIndicatorExt wird angelegt:
<?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>com.cisag.pgm.appserver.Server</contract>
<hook>
<interfce>com.cisag.pgm.services.indicator.hook.OLTPIndicatorHook
</interface>
<implementation>
com.cisag.app.services.indicator.log.OLTPIndicatorHookExtImpl</implementation>
</hook>
<
</HOOK_IMPLEMENTATION>
</HookContract>
Der Indikator wird wie folgt implementiert
private final class MyNumberIndicator implements NumberIndicator {
@Override
public CisDecimal getValue() {
return CisDecimal.valueOf(100);
}
}
Die Registrierung erfolgt in der Klasse com.cisag.app.services.indicator.log.OLTPIndicatorHookExtImpl, die im XML-Entwicklungsobjekt deklariert wurde:
public class OLTPIndicatorHookExtImpl implements OLTPIndicatorHook {
@Override
public void initialize(IndicatorRegistry registry) {
registy.registerNumberIndicator(“com.cisag.pgm.MyIndicator”,
new MyNumberIndicator(), “unit”);
}
}
4 Verwenden von CisSystemManager
Aggregationsindikatoren und Zählerindikatoren können am com.cisag.pgm.appserver.CisSystemManager programmatisch ausgelöst werden. Dafür stehen folgende Methoden zur Verfügung:
void fireCounterIndicator(
byte[] databaseGuid,
String name);
void fireAggregatorIndicator(
byte[] databaseGuid,
String name,
CisDecimal amount);
void fireAggregatorIndicator(
byte[] databaseGuid,
String name,
long amount);
Der Parameter databaseGuid entspricht der Datenbank-GUID, name ist der Name des Aggregations- bzw. Zählerindikators. Die verwendeten Indikatoren müssen in der Hook-Contract-Implementierung registriert worden sein. Der Parameter amount ist der Wert, der aggregiert wird. Sie können die Datenbank-GUID der in einer Session aktiven OLTP-Datenbank über CisEnvironment.getInstance().getDatabaseGuid() ermittelt.