Podręcznik referencyjny: Reorganizacje

Wprowadzenie

Podczas pracy systemu nieustannie generowane są dane, które powodują stopniowy wzrost rozmiaru baz danych. Większość z tych danych z czasem traci aktualność i może zostać usunięta z bazy danych w celu oszczędności miejsca oraz poprawy wydajności dostępu do danych.

W systemie do tego celu wykorzystywane są aplikacje reorganizacji, które umożliwiają archiwizację danych poprzez ich eksport, a następnie usunięcie.

Niniejszy dokument opisuje sposób tworzenia aplikacji reorganizacji tak, aby mogła być używana w aplikacji Zlecenia reorganizacji.

Podstawowe pojęcia związane z aplikacjami w tle można znaleźć w artykule: Definicje: Zarządzanie systemem.

Grupa docelowa

• Programiści
• Konsultanci techniczni

Warunki wstępne

Jeśli dane mają zostać zarchiwizowane poprzez eksport przed ich usunięciem musi być dostępny kontroler eksportu BIS.

Programowanie/Rozwój

Niniejszy rozdział opisuje tworzenie i integrację nowych aplikacji reorganizacyjnych dla aplikacji Zlecenia reorganizacji. Aplikacja reorganizacyjna to specjalna aplikacja działająca w tle. Tworzenie aplikacji reorganizacyjnej przebiega w kilku krokach:

1. Rejestrowanie obiektu deweloperskiego – Java class

2. Rejestrowanie obiektu deweloperskiego – Application

3. Tworzenie aplikacji reorganizacji

4. Testowanie aplikacji reorganizacji

5. Dokumentowanie aplikacji reorganizacji

Rejestrowanie obiektu deweloperskiego – Java class

Dla aplikacji reorganizacji wymagana jest klasa Java, która musi znajdować się w przestrzeni nazw, która kończy się na log. Powinna mieć taką samą nazwę jak aplikacja. Jednostka biznesowa powinna być rozpoznawalna na podstawie nazwy.

Rejestrowanie obiektu deweloperskiego – Application

Aby możliwe było zintegrowanie aplikacji reorganizacji ze zleceniem reorganizacji, należy utworzyć obiekt deweloperski typu Application. Ustawienie w polu Typ wartości W tle oraz Szczególne zastosowanie na Reorganizacja umożliwia dodanie aplikacji działającej w tle do zlecenia reorganizacji. To ustawienie powoduje również, że aplikacja reorganizacji nie może być uruchamiana z poziomu aplikacji Zlecenia przetwarzania.

Aplikacje działające w tle ze szczególnym zastosowaniem Reorganizacja otrzymują nazwę w formacie <Object>Reorganization oraz etykietę w formie Reorganizacja <obiektów> (w liczbie mnogiej).

Ustawienie pola Ustawienia prezentacji i utrzymania powinno mieć wartość Prezentacja, utrzymanie, aby aplikacja reorganizacyjna była widoczna w aplikacji Zlecenia reorganizacji.
Tryb uprawnień należy ustawić na Z kontrolą, ponieważ logika aplikacji reorganizacji nie zawiera własnych mechanizmów weryfikacji uprawnień.

W aplikacji Zlecenia reorganizacji weryfikowana jest również baza danych przypisana do aplikacji reorganizacji. W tym celu konieczne jest poprawne ustawienie parametru Wymagane aktywne bazy danych.

Uwaga:
Dla zastosowania standardowej implementacji należy podać Główna jednostka biznesowa.

Tworzenie aplikacji reorganizacji

Interfejs udostępniany do tworzenia aplikacji reorganizacji znajduje się w przestrzeni nazw com.cisag.pgm.base.reorg. Najważniejszą klasą jest CisReorganizationApplication. Wszystkie aplikacje reorganizacji muszą być klasami pochodnymi klasy bazowej.

Poniżej przedstawiono klasy Java dostępne w tej przestrzeni nazw:

• Java class: CisReorganizationApplication – klasa bazowa dla wszystkich aplikacji reorganizacji.
• Java class: CisReorganizationApplicationEditor – standardowy edytor parametrów; alternatywnie można zastosować klasę pochodną od CisBatchApplicationEditor do wprowadzania parametrów.
• Java class: CisReorganizationData – kontener danych zawierający dane uruchomieniowe.
• Java class: CisReorganizationInfo – klasa zawierająca metadane aplikacji reorganizacji.
• Java class: ReorganizationAction – zbiór wartości (ValueSet) wykorzystywany podczas zliczania przetworzonych instancji.
• Java class: ReorganizationActionResult – zbiór wartości (ValueSet) definiujący wartości zwracane przez metody.
• Java class: ReorganizationExportControllerMode – zbiór wartości (ValueSet) służący do sterowania metadanymi eksportu w kontekście archiwizacji.
• Java class: ReorganizationFilterMode – zbiór wartości (ValueSet) służący do sterowania eksportem danych do archiwum w czasie wykonywania aplikacji.

Klasa Java CisReorganisationInfo

Klasa CisReorganisationInfo zawiera metadane dla aplikacji reorganizacji. Po utworzeniu instancji klasy CisReorganisationInfo można wpływać na zachowanie eksportu i rozmiar transakcji.

Metoda createForBusinessEntity(Class businessEntityClass)

Instancję klasy CisReorganisationInfo można utworzyć tylko za pomocą metody createForBusinessEntity(Class). Parametr określa podmiot biznesowy, dla którego tworzona jest reorganizacja.

Metoda setTransactionBlockSize(int size)

W domyślnym zachowaniu aplikacja reorganizacji usuwa maksymalnie 1000 instancji w ramach jednej transakcji. Zachowanie to można dostosować, wywołując metodę setTransactionBlockSize().

Metoda setExportControllerMode(short mode)

Zachowanie eksportu w aplikacji reorganizacji może być sterowane za pomocą wywołania metody setExportControllerMode(short mode). Parametr mode określa, czy aplikacja reorganizacji obsługuje eksport danych. Jeśli eksportowanie jest wspierane, można rozróżnić, czy ma zostać użyty standardowy kontroler eksportu BIS, czy też specjalny kontroler eksportu dedykowany dla danej aplikacji reorganizacji. W przypadku użycia specjalnego kontrolera eksportu należy podać nazwę klasy Java tego kontrolera.

Klasa Java CisReorganisationData

Kontener danych dla środowiska uruchomieniowego zawierający dane konfiguracyjne.

• metoda GetDatabaseGuid() zwraca identyfikator bazy danych, na której wykonywana jest aplikacja reorganizacji.
• metoda getDatabaseName() zwraca nazwę bazy danych, na której wykonywana jest aplikacja do reorganizacji.
• metoda getMaximumRuntime()zwraca specyfikację czasu wykonywania ustawioną przez użytkownika w edytorze.
• metoda getParameterList() zwraca instancję klasy CisParameterList, która zawiera dane wejściowe użytkownika do konfiguracji aplikacji reorganizacji.
• metoda getReorganisationInfo() zwraca metadane aplikacji reorganizacji.

Klasa Java CisReorganisationApplicationEditor

Klasa CisReorganisationApplicationEditor jest implementacją klasy Java CisBatchApplicationEditor, szczegóły w rozdziale Klasa Java CisBatchApplicationEditor. Edytor udostępnia do czterech pól wejściowych. Klasa CisReorganisationApplicationEditor jest konfigurowana przy użyciu metadanych w klasie Java getReorganisationInfo (rozdział Klasa Java CisReorganisationInfo). Dostępne są nastepujące pola:

• Maksymalny czas działania – zawsze dostępny
• Folder docelowy – pole jest dostępne tylko wtedy, gdy eksportowanie jest wspierane i aplikacja reorganizacji została otwarta bezpośrednio.
  W aplikacji Zlecenia reorganizacji zapisywany jest pusty element.
• Eksport -w polu Eksport użytkownik może określić, czy i w jaki sposób dane mają być eksportowane.
• Filtr eksportu – w polu Filtr eksportu użytkownik może określić filtr eksportu, jeśli w polu Eksport wybrano wartość Filtr eksportu.

Aby rozszerzyć klasę CisReorganisationApplicationEditor należy nadpisać następujące metody:

• init(int visualisationType)

• dataFromUi

• dataToUi

• validate

Klasa Java CisBatchApplicationEditor

Klasa Java CisBatchApplicationEditor zapewnia interfejs, za pomocą którego można tworzyć parametry wejściowe aplikacji działających w tle. W konstruktorze i deklaracjach edytora nie mogą występować żadne inicjalizacje. Aby utworzyć oddzielną podklasę CisBatchApplicationEditor, należy zaimplementować kilka metod:

• init(int visualisationType)

• getActionId()

• getVisualElement()

• applyDefaults()

• dataFromUi()

• dataToUi()

• validate()

Interfejs zawiera również metody wspierające implementację i wykonanie:

• areOutputOptionsEnabled()

• isOnlineSubmitEnabled()

• isBatchSubmitEnabled()

• getParameterList()

• isEditable()

• isEnabled()

• setVisualElementProperties()

Metody możliwe do nadpisania

init(int visualisationType)– instancja klasy CisBatchApplicationEditor jest inicjowana tylko przez wywołanie metody init(int). Wizualizacja zawsze odbywa się w układzie StandardLayout. Kolumny są definiowane poza edytorem. Parametr visualisationType odnosi się do stałych klasy CisBatchApplicationEditor i określa liczbę kolumn dla układu:

• VISUALISATION_TYPE_DIALOGUE – edytor jest wyświetlany w oknie dialogowym, a wszystkie pola muszą być dodane do kolumny 0.
• VISUALISATION_TYPE_APPLICATION – edytor jest wyświetlany w aplikacji, a pola muszą być dodawane naprzemiennie do kolumny 0 i kolumny 1.

getActionId() – zwraca actionId dla wywołania aplikacji w tle.
getVisualElement() – zwraca element, który można dodać do kontenera wywołującego.
applyDefaults() – edytor może ustawić wartości domyślne dla parametrów na liście parametrów w metodzie applyDefaults(). Wartości domyślne powinny prowadzić do pomyślnego sprawdzenia bez interakcji użytkownika.
dataFromUi() – w tej metodzie wartości z pól muszą zostać skopiowane do listy parametrów.
dataToUi() – metoda jest wywoływana, jeżeli dane z listy parametrów mają zostać umieszczone w polach. Możliwość edycji i aktywny wskaźnik muszą być ustawione dla każdego pola. Te właściwości pola można również ustawić poprzez wywołanie metody setVisualElementProperties().
validate() – metoda sprawdza wprowadzone przez użytkownika parametry.

Dodatkowe metody interfejsu

areOutputOptionsEnabled() – wartość zwracana przez metodę kontroluje widoczność zakładki [Ustawienia wydania]
isOnlineSubmitEnabled() – wartość zwracana przez metodę kontroluje widoczność przycisków [Natychmiast] lub [Pokaż].
isBatchSubmitEnabled() – wartość zwracana przez metodę kontroluje widoczność przycisków [W tle] lub [Drukuj]
getParameterList() – metoda dostępu do listy parametrów zawierającej dane konfiguracyjne.
isEditable() – zapytanie o możliwość zmiany danych.
isEnabled() – zapytanie o aktywację pól.
setVisualElementProperties() – ustawia zmienność i aktywny wskaźnik dla wszystkich przesyłanych elementów.

Klasa Java CisReorganizationApplication

Klasa Java CisReorganizationApplication jest podstawą dla wszystkich aplikacji reorganizacji. Najważniejszą metodą jest metoda reorganize(), która zawiera całą kontrolę procesu. Zachowanie aplikacji do reorganizacji można całkowicie zmienić poprzez nadpisanie tej metody. Jednak celem implementacji powinno być wykorzystanie jak największej ilości standardowych funkcji. Z tego powodu obiekt przekazywany do wszystkich metod jest typu java.lang.Object.

Minimalna implementacja

Podstawowa struktura została zaprojektowana tak, aby umożliwić tworzenie aplikacji reorganizacji przy minimalnym nakładzie pracy. Przetwarzany obiekt biznesowy (Business Entity) musi zawierać część UpdateInformation, a znacznik usunięcia musi być zrealizowany poprzez atrybut deleteTime w tej części. Aplikację reorganizacji dla takiego obiektu można utworzyć poprzez implementację metod createReorganizationInfo() oraz validateObject(). Aplikacja działa automatycznie w trybie blokowym.

Metoda createReorganizationInfo() – tworzy metadane dla aplikacji reorganizacji. W tym celu wywoływana jest metoda createForBusinessEntity(Class businessEntityClass) w klasie Java CisReorganizationInfo. Następnie należy jeszcze ustawić tryb dla kontrolera eksportu (rozdział Metoda setExport-ControllerMode(short mode)).
Metoda validateObject() – musi być użyta do sprawdzenia, czy przekazana instancja nie jest już używana i czy może zostać usunięta.

Rozszerzenie o większej złożoności

Prawie wszystkie metody mogą być zaimplementowane dla bardziej złożonych zadań. Na przykład, aby zrealizować przetwarzanie blok po bloku samych obiektów, rozmiar transakcji musi być ustawiony na 1 (rozdział Metoda setTransactionBlockSize(int size)). Ponadto należy nadpisać następujące metody:
createIterator() – należy utworzyć osobną instancję z interfejsem Iterator, która jako przykład udostępnia instancję z interfejsem java.util.List. Lista ta zawiera obiekty do przetworzenia.
validateObject() – musi teraz akceptować listę jako parametr. Wszystkie instancje, których nie można zreorganizować, muszą zostać usunięte z listy i powinny zostać policzone jako pominięte instancje poprzez wywołanie metody increaseCount().
archiveObject() – musi iterować po liście i dla każdej instancji może wywołać metodę archiveObject() z klasy bazowej.

deleteObject() – musi iterować po liście i dla każdej instancji może wywołać metodę deleteObject() z klasy bazowej.
releaseObject() – może wyczyścić listę. Zasoby związane z obiektem, np. blokady, mogą zostać zwolnione w tej metodzie.
getCount() – musi zwracać liczbę instancji na liście.

Metoda createIterator() 

Metoda zwraca instancję z interfejsem Iterator(), który zwraca instancje do przetworzenia. Standardowa implementacja to:

CisObjectIterator result = om.getObjectIterator( "select from " + businessEntityClass + " be where be:updateInfo.deleteTime<>?" );
result.setTimestamp( 1, CisTimeStampUtility.UNDEFINED_TIME_STAMP );
return result;

Metoda archiveObject()

Metoda jest wywoływana w celu zarchiwizowania danych poprzez ich wyeksportowanie. Standardowa implementacja otwiera plik docelowy, eksportuje dane i ponownie zamyka plik:

short result;
if (openExportFile( getObjectIdentifier( cisObject ) )) {
result = exportObject( cisObject );
closeExportFile();
}
else {
result = ReorganisationActionResult.ERROR;
}
return result;

Metoda deleteObject()

Obiekt jest usuwany w metodzie deleteObject(). Standardowa implementacja wywołuje bezpośrednio om.deleteObject().

Metody nadpisywalne

exit()– wszystkie zasoby mogą zostać zwolnione w metodzie exit(). Zasoby, które zostały przydzielone w metodzie init() powinny zostać zwolnione.
exitDatabase() – metoda jest wywoływana w celu zwolnienia zasobów specyficznych dla bazy danych, które zostały przydzielone w metodzie initDatabase().
getDatabaseGuids() – ta metoda wysyła zapytanie o identyfikatory GUID baz danych, dla których ma zostać wykonana aplikacja reorganizacji. Standardowa implementacja zwraca identyfikatory GUID baz danych, które są dostępne w bieżącej sesji i dla których istnieje jednostka biznesowa.
getObjectDescriptionDisplayName() – metoda zwraca wyświetlaną nazwę jednostki biznesowej. Jest to wymagane dla komunikatów zakończenia.
getObjectIdentifier() – zwraca nazwę instancji. Standardowa implementacja używa tego samego algorytmu, którego używa BIS.
init() – służy do inicjalizacji aplikacji reorganizacji. Zasoby powinny zostać zwolnione w metodzie exit().
initDatabase() – może być używana przez aplikację do reorganizacji do inicjalizacji specyficznej dla bazy danych. Zasoby powinny zostać zwolnione w metodzie exitDatabase().
reorganize() – zawiera logikę sterującą przebiegiem działania aplikacji reorganizacji dla wszystkich baz danych, których identyfikatory GUID zostały określone w metodzie getDatabaseGuids().

foreach ( databaseGuid ) {
reorganize(byte[] databaseGuid)

}
exit();

reorganize((byte[] databaseGuid) – zawiera logikę sterującą przebiegiem działania aplikacji reorganizacyjnej dla jednej bazy danych.

initDatabase()

beginReadTransation {

beginWriteTransationIfNeeded {

createIterator();

while( iterator.hasNext() && noError ) {

Object object = iterator.next();

increaseCount( READ, SUCCESSFULL, object );

 

if ( validateObject( object ) == SUCCESS ) {

increaseCount( VALIDATE, state, object );

 

if ( archiveObject( object ) == SUCCESS ) {

increaseCount( EXPORT, state, object );

 

deleteObject( object );

increaseCount( DELETE, state, object );

writeTransactionCount++;

}

}

releaseObject( object );

 

if ( writeTransaction && writeTransactionCount > transactionSize ) {

commit( writeTransaction )

beginWriteTransationWhenNeeded

}

 

if ( isMaximumRuntimeExceeded() ) {

setTimeout();

}

}

}

 

rollback( readTransaction )

}

exitDatabase();

Inne metody interfejsu

Poniższe metody są integralną częścią interfejsu i nie mogą zostać nadpisane:
closeExportFile() – wywołanie tej metody powoduje zamknięcie pliku docelowego, do którego wyeksportowano dane.
exportObject() – przesłany obiekt jest przekazywany do kontrolera eksportu w metodzie process().
GetData() – metoda pozwala na sprawdzenie parametrów aplikacji reorganizacji
IncreaseCount() – wywołanie metody zwiększa liczniki liczby obiektów, które zostały przetworzone pomyślnie, z błędami lub nie zostały przetworzone podczas działania.
isMaximumRuntimeExceeded()– moteoda może być użyta do określenia, czy czas określony przez użytkownika został przekroczony, czy nie.
openExportFile()– metoda tworzy i otwiera plik docelowy, który ma zostać wyeksportowany. Plik należy następnie zamknąć, wywołując metodę closeExportFile()


run() – metoda jest standardową metodą wywoływania aplikacji. Kontener danych jest inicjowany, a następnie wywoływane są metody init()
reorganize()
exit()

sendProcessMessage() – metoda wysyła wiadomość, w której wyświetlany jest stan aplikacji reorganizacji oraz wartości poszczególnych liczników.
ResetCount() – resetuje liczniki liczby obiektów, które zostały przetworzone pomyślnie, z błędami lub nie zostały przetworzone podczas akcji do 0.

Testowanie aplikacji reorganizacji

Aby przetestować aplikację reorganizacji, należy nadpisać metodę deleteObject(), aby zapobiec usuwaniu danych. Dzięki temu dane pozostaną niezmienione. Klasa Java CisReorganizationApplication wspiera logowanie poprzez interfejs com.cisag.pgm.util.Debug. Komunikaty logowania można aktywować za pomocą polecenia Toolshell dbgcls –class:com.cisag.pgm.base.reorg.CisReorganizationApplication.

Aplikację reorganizacji można otworzyć bezpośrednio z aplikacji Obiekty deweloperskie, jeśli pole Ustawienia prezentacji i utrzymania posiada wartość Prezentacja, utrzymanie. Po prawej stronie pola Typ znajduje się przycisk [Otwórz aplikację]. jego naciśnięcie otwiera okno dialogowe w tle. Do wprowadzania parametrów wykorzystywany jest edytor aplikacji reorganizacji. Układ formularza jest jednokolumnowy. Okno to pojawia się również w przypadku otwierania aplikacji reorganizacji z poziomu menu ulubione.

Aplikację reorganizacji można również testować w ramach zlecenia reorganizacji. Można ją dodać w aplikacji Zlecenia reorganizacji. W tym przypadku formularz do wprowadzania parametrów ma układ dwukolumnowy.

Dokumentowanie aplikacji reorganizacji

Aby udokumentować aplikację reorganizacji, należy utworzyć obiekt deweloperski typu Help object. Powinien on mieć taką samą nazwę jak aplikacja reorganizacji. Na podzakładce Obiekty deweloperskie aplikacja reorganizacji musi zostać przypisana do obiektu pomocy z wagą Standardowy.