Podręcznik referencyjny: Wskaźniki

Wprowadzenie

Wskaźniki mogą być używane do monitorowania kluczowych danych technicznych i biznesowych systemu. Wskaźniki biznesowe są dostarczane jako wskaźniki dynamiczne przy użyciu Workflow. Jednak nie wszystkie wymagania mogą być mapowane za pomocą wskaźników dynamicznych. Wymagania można spełnić za pomocą indywidualnie zaprogramowanych wskaźników. W artykule opisano podstawowe procedury implementacji wskaźnika i  instrukcje dotyczące korzystania z odpowiedniego interfejsu API, który jest udostępniany w tym celu.

Dodatkowo, zalecanym jest zapoznanie się z artykułem Definicje Rozwój oprogramowania.

Grupa docelowa

• programista aplikacji

Opracowanie wskaźników

Wskaźniki są tworzone w oparciu o technologię interfejsu hook:

• implementacja hook contract jako obiektu deweloperskiego
• implementacja hooka hook contract w postaci kodu Java
• rejestracja jednego lub więcej wskaźników zaimplementowanych w implementacji hooka.

Tworzenie obiektu deweloperskeigo XML typu Hook contract

Podstawowym warunkiem utworzenia w pełni zaimplementowanego wskaźnika jest przygotowanie obiektu deweloperskiego typu Hook Contract z podtypem HOOK_IMPLEMENTATION.

Element XML <contract> tego obiektu deweloperskiego musi odnosić się do następującej definicji hooka:

com.cisag.pgm.appserver.Server


Następnie należy zarejestrować odpowiedni interfejs oraz jego implementację dla danego hooka.

Jeśli wskaźnik ma być dostępny dla każdej bazy danych OLTP, to w elemencie XML <hook> należy umieścić element <interface> z wartością:

com.cisag.pgm.services.indicator.hook.OLTPIndicatorHook


Jeśli wskaźnik jest dostępny tylko dla bazy repozytorium, należy użyć następującego interfejsu dla hooka:

com.cisag.pgm.services.indicator.hook.RepositoryIndicatorHook


W jednej implementacji hook contract można zaimplementować zarówno OLTPIndicatorHook, jak i RepositoryIndicatorHook – w zależności od potrzeb systemowych.

Szczegółowy opis struktury elementów XML dla tego typu obiektów deweloperskich znajduje się w artykule Obiekty deweloperskie.

Tworzenie wskaźnika

Można udostępniać różne typy wskaźników. W przypadku dwóch z nich wymagana jest klasa pomocnicza, która dostarcza wartości wskaźników. Klasy pomocnicze są wymagane dla następujących typów wskaźników:

• Wskaźniki liczbowy

• Wskaźniki statusu

Podczas pobierania wartości wskaźnika dla wskaźnika typu OLTP, zgodnie z przyjętą praktyką, musi być otwarta transakcja dla odpowiedniej bazy danych OLTP.

W dalszej części opisane są interfejsy przeznaczone dla klas pomocniczych służących do dostarczania danych dla tych wskaźników.

Interfejs dla wskaźnika liczbowego

W przypadku wskaźnika liczbowego należy zapewnić logikę, która oblicza wartość wskaźnika. Aby obliczyć wartość, należy zaimplementować następujący interfejs:

interface com.cisag.pgm.services.indicator.ext.NumberIndicator
public CisDecimal getValue();
}

Metoda getValue() zwraca wartość liczbową wskaźnika. Użytkownik określa jednostkę wskaźnika podczas rejestracji.

Interfejs wskaźnika statusu

Dla wskaźnika statusu należy dostarczyć logikę, która oblicza jego wartość statusu. Aby obliczyć tę wartość, należy zaimplementować następujący interfejs:

interface com.cisag.pgm.services.indicator.ext.StateIndicator {
public StateIndicatorState getValue();
}

Metoda getValue() zwraca status wskaźnika jako kontener typu StateIndicatorState. Kontener StateIndicatorState składa się z dwóch metod getter:

public String getState(){
return state;
}

public String getDescription(){
return description;
}

Metoda getState() zwraca reprezentację statusu jako ciąg znaków, metodagetDescription() zwraca opis statusu jako ciąg znaków.

Implementowanie hook contract

Jeśli wskaźnik ma być dostępny dla każdej bazy danych OLTP, należy zaimplementować następujący interfejs:

com.cisag.pgm.services.indicator.hook.OLTPIndicatorHook


Jeśli wskaźnik ma być dostarczony dla bazy repozytorium, należy zaimplementować następujący interfejs:

com.cisag.pgm.services.indicator.hook.RepositoryIndicatorHook


Każdy z interfejsów ma następującą metodę:

public void initialise(IndicatorRegistry registry).


Poszczególne wskaźniki mogą być rejestrowane w tej metodzie.

Rejestrowanie wskaźnika

Utworzony wskaźnik musi zostać zarejestrowany w implementacji hook contract. Rejestracja odbywa się w metodzie initialise(IndicatorRegistry registry). Wskaźniki są rejestrowane w klasie com.cisag.pgm.services.indicator.hook.IndicatorRegistry.
Klasa IndicatorRegistry posiada następujące metody rejestracji wskaźników:

• dla wskaźnika agregacyjnego:

public void registerAggregatorIndicator(
String name,
String description,
Datatype datatype,
String unit);

• dla wskaźnika liczbowego:

public void registerNumberIndicator(
String name,
String description,
NumberIndicator indicator,
String unit);

• dla wskaźnika licznikwoego:

public void registerCounterIndicator(
String name,
String description);

• dla wskaźnika statusu:

public void registerStateIndicator(
String name,
String description,
StateIndicator indicator);

Testowanie wskaźnika

Wskaźniki można otworzyć i przetestować w aplikacji Wyświetl wskaźniki.

Należy upewnić się, że plik XML z implementacją hook contract znajduje się w klasie ścieżki (Java classpath).

Jeśli w pełni kwalifikowana nazwa wskaźnika nie odpowiada przyjętej konwencji nazewnictwa, zostanie zgłoszony wyjątek typu: IllegalArgumentException.

Przykład

Tworzony jest obiekt deweloperski XML com.cisag.app.services.indicator.log.OLTPIndicatorExt:

<?xml version="1.0" encoding="UTF-16"?>
<HookContract xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="HookXMLSchema.xsd">
<!-- Nie zmieniaj tej linii i linii powyżej! -->
<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>

Wskaźnik jest zaimplementowany w następujący sposób

private final class MyNumberIndicator implements NumberIndica-tor {

@Override
public CisDecimal getValue() {
return CisDecimal.valueOf(100);
}

}

Rejestracja odbywa się w klasie com.cisag.app.services.indicator.log.OLTPIndicatorHookExtImpl, która została zadeklarowana w obiekcie deweloperskim XML:

public class OLTPIndicatorHookExtImpl implements OLTPIndicatorHook {

@Override
public void initialise(IndicatorRegistry registry) {
regis-ty.registerNumberIndicator("com.cisag.pgm.MyIndicator",
new MyNumberIndicator(), "unit");
}
}

Korzystanie z CisSystemManager

Wskaźniki agregacji i wskaźniki licznika mogą być wyzwalane programowo w com.cisag.pgm.appserver.CisSystemManager. W tym celu dostępne są następujące metody:

void fireCounterIndicator(
byte[] databaseGuid,
String name);

void fireAggregatorIndicator(
byte[] databaseGuid,
String name,
CisDecimal amount);

void fireAggregatorIndicator(
byte[] databaseGuid,
String name,
long amount);

Opis parametrów:

• databaseGuid – odpowiada identyfikatorowi GUID bazy danych. Identyfikator GUID bazy danych OLTP aktywnej w sesji można określić za pomocą CisEnvironment.getInstance().getDatabaseGuid()

  name – jest nazwą wskaźnika agregacji lub licznika.

• amount – to wartość, która jest agregowana.