Wprowadzenie
W artykule opisano podstawową procedurę pobierania numerów dla schematów numeracji oraz unikalnych liczników przy użyciu menedżera schematów numerów.
Grupa docelowa
- Programiści aplikacji
- Administratorzy systemu
- Konsultanci techniczni
Definicje
Menedżer schematów numeracji – to interfejs programistyczny dla deweloperów, którzy chcą używać schematów numeracji i unikalnych liczników w swoich aplikacjach. Służy do określania następnego wolnego numeru dla schematów numeracji i unikalnych liczników.
Unikalny licznik – to licznik, którego aplikacja może używać do generowania numerów identyfikacyjnych typu danych long. Użycie liczników unikalnych jest zależne od aplikacji.
Usługa schematów numeracji – pobiera numery dla schematów numeracji i liczników unikalnych. Jest używana przez menedżera schematów numeracji i działa na serwerze komunikatów.
Właściwość rosnąca – wszystkie liczby przypisane do schematów numeracji lub unikatowego licznika są trwałe w odniesieniu do ich kolejności, tj. żadna większa liczba nie jest zapisywana wcześniej niż mniejsza liczba w odniesieniu do określonego punktu w czasie.
Właściwość ciągła – wszystkie liczby schematu numeracji lub unikalne liczniki przechowywane w bazie danych są kolejne, bez luk. Ta właściwość domyślnie spełnia właściwość rosnąca.
Pobieranie numerów
Menedżer schematów numeracji jest używany do pobierania nowych numerów dla schematów numeracji i unikalnych liczników. Menedżer schematów numeracji używa usługi schematów numeracji serwera komunikatów do pobierania numerów. Usługa schematów numeracji pobiera numery blokowo, więc pobranie numeru za pomocą menedżera schematów numeracji zwykle nie wymaga ani dostępu do bazy danych, ani wyłącznych blokad Persistence service na liczniku schematów numeracji.
Dostęp do menedżera schematów numeracji
Aplikacja może uzyskać dostęp do menedżera schematów numeracji za pośrednictwem środowiska:
com.cisag.pgm.appserver.CisNumberRangeManager nrm= CisEnviron-ment.getInstance().getNumberRangeManager();
Interfejs com.cisag.pgm.appserver.CisNumberRangeManager zapewnia wymagane metody do pobierania liczb dla schematów i liczników unikalnych.
Schematy numeracji
Menedżer schematów numeracji może być używany tylko do pobierania numerów, które nie muszą spełniać właściwości ciągłej i rosnącej. W takim przypadku mówi się o jawnym pobieraniu numerów. Jeśli schemat numeracji musi spełniać właściwości ciągłej lub rosnącej, jego numery muszą być pobierane niejawnie przez Persistence service podczas zapisywania Instancji Obiektu Biznesowego. Niejawne pobieranie numerów opisano w artykule Persistence service.
Metoda getNextNumber() może być użyta do określenia następnego wolnego numeru dla schematu numeracji przekazanego jako argument.
Następny wolny numer pozycji można określić za pomocą metody getNextDetailNumber().
Unikalny licznik
Za pośrednictwem menedżera schematów numeracji mogą być pobierane tylko numery dla unikalnych liczników, które nie muszą spełniać właściwości ciągłej i rosnącej. Oferuje on jednak możliwość zapewnienia, że unikalny licznik spełnia właściwość rosnącą w określonym momencie. Wszystkie numery pobrane do tego momentu są albo utrwalone, albo odrzucone.
Metoda:
- getNextUniqueCounter() może być użyta do określenia następnego wolnego numeru dla unikalnego identyfikatora licznika przekazanego jako argument.
- getNextUniqueCounterBlock() może być użyta do określenia następnych n wolnych numerów dla unikalnego identyfikatora licznika przekazanego jako argument.
- getLastUniqueCounter() może być użyta do określenia ostatniego pobranego numeru dla unikalnego identyfikatora licznika przekazanego jako argument.
Zapewnienie właściwości rosnącej
W celu umożliwienia właściwości rosnącej, menedżer schematów numeracji używa blokad Persistence service podczas pobierania numerów. Dla każdego inikalnego licznika istnieje inny obiekt blokujący, dla którego żądane są blokady Persistence service. Z tego powodu, aby zapewnić właściwość rosnącą, wywołanie pobrania nowego numeru lub nowego bloku numerów musi nastąpić w ramach transakcji, w której zapisywana jest również instancja obiektu biznesowego z unikalnym licznikiem.
Wywołując metody getNextUniqueCounter() lub getNextUniqueCounterBlock(), blokada odczytu jest utrzymywana na obiekcie blokady. Jest ona niejawnie anulowana, gdy transakcja najwyższego poziomu, w której wykonano wywołanie, zostanie zakończona. Jeśli nie ma kontekstu transakcji, gdy wywoływane są metody, blokada odczytu jest utrzymywana tylko podczas wywoływania metody.
Metoda getLastUniqueCounter() może być użyta do zapytania o ostatni przypisany numer. W ramach tej metody wyłączna blokada obiektu blokady jest wymagana w oddzielnej transakcji najwyższego poziomu. Jest ona przyznawana tylko wtedy, gdy nie ma więcej blokad odczytu na obiekcie blokady. Oznacza to, że wszystkie pobrane numery muszą zostać przetworzone. Właściwość rosnąca jest zatem spełniona aż do zwróconego numeru; wszystkie mniejsze liczby są albo trwałe, albo reprezentują luki. Zazwyczaj zadanie przetwarzania lub aplikacja reorganizacji określi, do którego numeru przetwarzanie powinno odbywać się w ten sposób po uruchomieniu.
Limity czasu blokady
Dopóki blokady odczytu są utrzymywane, nie można przyznać blokady wyłącznej, a w konsekwencji również blokad odczytu żądanych później. Z tego powodu metody pobierania nowych numerów powinny być wywoływane w ramach transakcji najwyższego poziomu tak późno, jak to możliwe, aby blokady odczytu trwały jak najkrócej.
Programista musi obsłużyć wszelkie wyjątki LockExceptions, które wystąpią z powodu przekroczenia limitu czasu blokady. Zalecaną procedurą jest kilkukrotne powtórzenie odpowiedniego wywołania metody.
Dodawanie nowego unikalnego licznika
Jeśli ma zostać wprowadzony nowy unikalny typ licznika, należy rozszerzyć ValueSet com.cisag.app.general.CounterType. Metoda isValidCounterType() klasy com.cisag.app.general.log.NumberRangeLogic sprawdza, czy określony typ licznika unikatowego, dla którego ma zostać wylosowana liczba, jest prawidłowy. Kontrola ta musi zostać dostosowana tak, aby nowy unikalny typ licznika był rozpoznawany jako prawidłowy.
Należy postępować w następujący sposób:
- Należy utworzyć nowy obiekt deweloperski Java class
- Aby odpowiednia Klasa Java została użyta przez system, należy w polu Zastąpiona klasa Java tego obiektu deweloperskiego wpisać klasę com.cisag.app.general.log.NumberRangeLogic.
- Nowa Klasa Java musi dziedziczyć z klasy com.cisag.app.general.log.NumberRangeLogic, w której jest metoda adaptableIsValidUniqueCounterType().
- W tej metodzie należy zaimplementować sprawdzenie dodanego typu unikalnego licznika. Jeśli jest to nowy typ, metoda musi zwrócić true, w przeciwnym razie false. Metoda adaptableIsValidUniqueCounterType() jest wywoływana przez metodę isValidCounterType() klasy bazowej do sprawdzania typu.
public class NumberRangeLogicAdapted extends
com.cisag.app.general.log.NumberRangeLogic {
public boolean adaptableIsValidUniqueCounterType(short type) {
switch (type) {
case CounterType.NEW_UNIQUE_COUNTER:
return true;
default:
return false;
}
}
- Aby klasa pochodna została użyta przez system, musi zostać zarejestrowana. Następuje to w klasie com.cisag.app.Replacements. W metodzie register () musi zostać określone, że klasa com.cisag.app.general.log.NumberRangeLogic jest zastępowana przez klasę pochodną.
public static void register(Map replacements) {
...
replacements.put("com.cisag.app.general.log.NumberRangeLogic",
"com.<Prefix>.app.general.log.NumberRangeLogicAdapted");
}
Usługa schematów numeracji
Na serwerze komunikatów działa usługa schematów numeracji, która dostarcza następny wolny numer dla funkcji numeracja schematu numeracji lub unikalnego licznika. Sama usługa pobiera numery blokowo dla każdego schematu numeracji lub unikalnego licznika, tzn. określany jest blok numerów, a jego największy numer jest zapisywany w odpowiednim liczniku. Wolne numery bloku są przechowywane w pamięci głównej. Z tego następnie zwracany jest najmniejszy nieprzypisany numer na żądanie nowego numeru przez menedżera schematów numeracji. Dzięki utrzymywaniu dodatkowych numerów w pamięci głównej, nowy numer jest zazwyczaj określany bez dostępu do bazy danych.
Jeśli serwer komunikatów zostanie nieprawidłowo zamknięty, nieprzypisane numery przechowywane w pamięci głównej zostaną utracone.
Jeśli serwer komunikatów zostanie zamknięty prawidłowo, nieprzypisane numery nie zostaną utracone. Największy numer przechowywany w bazie danych jest korygowany do ostatniego przypisanego numeru bloku w pamięci głównej. Jeśli licznik schematów numeracji lub unikalny licznik został zmieniony przez inne logiki poza usługą zakresu numerów, numery nie mogą zostać przywrócone.
