Interfejs CORBA

Wprowadzenie

Interfejs CORBA systemu Comarch ERP Enterprise stanowi infrastrukturę dla zdalnej, bezpośredniej i synchronicznej komunikacji między systemem Comarch ERP Enterprise a klientami CORBA. Klienci CORBA mogą wywoływać za pośrednictwem tego interfejsu specjalne funkcje w systemie Comarch ERP Enterprise. Funkcje te są zawsze implementowane w systemie Comarch ERP Enterprise jako aplikacje działające w tle i mogą być wywoływane niezależnie od konkretnego kanału wejścia-wyjścia, czyli niezależnie od danej technologii interfejsu lub komunikacji. Implementujący aplikację działającą w tle jest odizolowany od konkretnej technologii wywołania. Zapewnia to możliwość ponownego wykorzystania przy późniejszej rozbudowie lub zmianach technologii komunikacyjnych. Jedną z technologii zintegrowanych w systemie Comarch ERP Enterprise jest CORBA.

Niniejszy artykuł zawiera opis interfejsu CORBA systemu Comarch ERP Enterprise oraz zdalnego interfejsu BIS przez CORBA.

Za pośrednictwem interfejsu CORBA systemu Comarch ERP Enterprise, system Comarch ERP Enterprise jest zawsze wywoływany z zewnątrz. Kierunek odwrotny, polegający na wywoływaniu innych serwerów CORBA z poziomu systemu Comarch ERP Enterprise, nie jest objęty interfejsem CORBA systemu Comarch ERP Enterprise i w związku z tym nie został tutaj opisany. Jest on zasadniczo określony przez serwer CORBA, który ma zostać użyty, oraz jego interfejsy. W takich przypadkach celowe jest stosowanie implementacji ORB JacORB dostarczanej wraz z systemem Comarch ERP Enterprise.

Grupa docelowa

Użytkownicy interfejsu serwera CORBA, twórcy zdalnie wywoływanych aplikacji działających w tle. Zakładana jest znajomość CORBA i jej działania.

Definicje terminów

CORBA – skrót od Common Object Request Broker Architecture. Umożliwia częściom programów (obiektom) komunikację z obiektami innych programów. Komunikacja ta jest możliwa nawet w przypadku, gdy programy zostały napisane w różnych językach programowania lub działają na różnych platformach. W tym celu zdefiniowano niezależny od platformy język opisu interfejsu IDL (Interface Definition Language). Dzięki CORBA program żąda obiektów za pomocą ORB (Object Request Broker). Znajomość struktur programu, z którego pochodzi obiekt, nie jest wymagana. CORBA została opracowana do użytku w środowiskach zorientowanych obiektowo.

Logowanie (Sesja) – wykonanie aplikacji działających w tle jest uzależnione od obecności środowiska wykonawczego Comarch ERP Enterprise, w którym dostępne są wszystkie funkcje silnika systemowego (np. Persistence service). Przy zdalnym uruchamianiu aplikacji działających w tle, środowisko takie musi zostać jawnie utworzone poprzez proces logowania. Parametrami logowania są: nazwa użytkownika Comarch ERP Enterprise, jego hasło oraz nazwa aktywnej bazy danych OLTP (opcjonalnie). Parametry te nie mogą być zmieniane w czasie trwania sesji logowania.

Wywołanie bezstanowe – zdalne wywołanie aplikacji działającej w tle to proces, na początku którego tworzona jest nowa instancja aplikacji, następnie wywoływana jest metoda run(), a po zakończeniu operacji instancja ta jest ponownie zwalniana.

Wywołanie stanowe – stanowe wywołanie aplikacji działającej w tle to sekwencja zdalnych wywołań, która rozpoczyna się od utworzenia nowej instancji aplikacji, obejmuje wielokrotne wywołania metody run() i kończy się jawnym poleceniem zwolnienia zasobów aplikacji.

Klienci CORBA

Obsługiwane implementacje CORBA

Interfejs CORBA wykorzystuje implementację ORB JacORB po stronie serwera. Jest to implementacja ORB typu open source dla języka Java, która oferuje wysoką wydajność i stabilność przy niskim zużyciu zasobów. Jednak klienci CORBA nie są ograniczeni do korzystania z JacORB; w zasadzie można również
używać innych implementacji. Poniższa tabela wskazuje, które implementacje CORBA są oficjalnie
obsługiwane dla klientów, w zależności od systemów operacyjnych, na których działa klient lub serwer  CORBA.
JDK-ORB odnosi się do implementacji CORBA dostarczanej wraz z JDK.

Inne implementacje CORBA, zwłaszcza dla języków programowania innych niż Java, nie zostały przetestowane i nie są oficjalnie obsługiwane.

Składniki systemu klienta

Klient CORBA wymaga odpowiedniej implementacji CORBA oraz klas wygenerowanych na podstawie IDL. Wymagane komponenty zależą od zastosowanej implementacji CORBA. Poniżej opisano je na przykładzie JacORB.

JacORB

Klient Java wykorzystujący JacORB wymaga następujących komponentów:

• Biblioteki jacorb.jar, avalon-framework.jar oraz logkit.jar w ścieżce klas
  (zawarte w instalacji Comarch ERP Enterprise; wymagane pliki JAR mogą się różnić dla wersji JacORB wyższych niż 2.2.1)

• Plik konfiguracyjny JacORB jacorb.properties w ścieżce klas (w Comarch ERP Enterprise stanowi część kodu aplikacji)

• Klasy interfejsów CORBA w ścieżce klas
  (klasy wygenerowane z pliku IDL; dostępne w System Engine w pakiecie com.cisag.pgm.external.corba lub możliwe do wygenerowania z pliku IDL)

Dla klientów wykorzystywanych produkcyjnie zaleca się instalację opisanych komponentów niezależnie od Comarch ERP Enterprise, aby uniknąć zależności od tej instalacji. Klienci testowi mogą natomiast bezpośrednio korzystać z wersji JacORB dostępnej w instalacji Comarch ERP Enterprise.

Dodatkowe informacje dotyczące JacORB dostępne są pod adresem http://www.jacorb.org.

Serwer Comarch ERP Enterprise CORBA

endscs [-waitForCompletion:<boolean>]

-waitForCompletion:<boolean> oczekiwanie na zakończenie wszystkich żądań; domyślnie: true

Uruchomienie automatyczne

Aby uruchomić serwer CORBA razem z serwerem aplikacji Comarch ERP Enterprise, dostępne są następujące właściwości, które w razie potrzeby można dodać do pliku server.properties serwera aplikacji Comarch ERP Enterprise:

• cisag.sys.kernel.corba.CorbaServerAutostart=true, false, domyślnie: false
  Określa, czy serwer CORBA ma być uruchamiany automatycznie.

• cisag.sys.kernel.corba.CorbaServerHost=<Host>
  Host serwera CORBA przy uruchamianiu automatycznym.

• cisag.sys.kernel.corba.CorbaServerPort=<Port>
  Port serwera CORBA przy uruchamianiu automatycznym.

• cisag.sys.kernel.corba.CorbaServerTimeoutIntervalSeconds=<czas>, domyślnie: 30
  Czas trwania interwału (w sekundach), po którym sprawdzana jest dostępność klienta, który otworzył sesję. Parametr ma zastosowanie wyłącznie przy uruchamianiu automatycznym.

Szczegółowe informacje dotyczące powyższych oraz innych właściwości znajdują się w artykule Właściwości ERP.

Dostępne porty

Na każdym systemie operacyjnym obowiązują ograniczenia dotyczące portów, które mogą być wykorzystywane przez serwer CORBA Comarch ERP Eneterprise. Należy je uwzględnić przy wyborze portów.

Interfejs Comarch ERP Enterprise CORBA

Klienci CORBA mogą korzystać z interfejsu CORBA systemu Comarch ERP Eneterprise w celu wywoływania funkcji systemu poprzez CORBA. Możliwe jest wywoływanie zarówno standardowo dostarczanych aplikacji wsadowych, jak i aplikacji utworzonych w ramach dostosowań.

Opis interfejsu IDL

IDL interfejsu CORBA systemu Comarch ERP Eneterprise jest przechowywany jako obiekt deweloperski typu plik pod nazwą com.cisag.pgm.external.corba.Corba-IDL. W systemie plików instalacji Semiramis IDL znajduje się w pliku: $SEMIRAMIS_HOME/files/com/cisag/pgm/external/corba/Corba.idl

W Comarch ERP Eneterprise System Engine klasy Java wygenerowane na podstawie IDL znajdują się w przestrzeni nazw com.cisag.pgm.external.corba. Klasy te mogą być wykorzystywane przez zewnętrznego klienta CORBA napisanego w języku Java, korzystającego z wersji JacORB dostarczanej wraz z Comarch ERP Eneterprise. W przypadku użycia innych implementacji ORB lub ich wersji konieczne jest ponowne wygenerowanie klas na podstawie IDL. W tym celu należy skorzystać z narzędzi dostarczanych przez daną implementację ORB. W przypadku języków programowania innych niż Java należy postępować zgodnie z dokumentacją danej implementacji ORB.

IDL zawiera techniczny opis interfejsu CORBA i stanowi punkt wyjścia do tworzenia zewnętrznego klienta CORBA.

IDL jest bardzo stabilny w ramach jednego wydania Comarch ERP Eneterprise. Przyszłe zmiany tego interfejsu będą dotyczyć głównie rozszerzeń oraz optymalizacji wydajności i nie będą wpływać na podstawowy sposób działania (SessionManager, Session, Application).

Mapowanie typów danych

Interfejs CORBA obsługuje część typów danych, które są wspierane po stronie serwera Comarch ERP Eneterprise dla wywoływanych aplikacji wsadowych.

Aplikacje wsadowe tworzone specjalnie na potrzeby wywołań zewnętrznych mogą wykorzystywać wyłącznie obsługiwane typy danych. Istniejące aplikacje wsadowe mogą być sensownie wywoływane z zewnątrz tylko wtedy, gdy typy danych wszystkich wymaganych parametrów są obsługiwane.

Obsługiwane typy danych dla wywołań aplikacji wsadowych przez CORBA oraz ich odwzorowanie w IDL oraz dla klienta CORBA w języku Java są następujące:

Typy danych po stronie klienta, o ile nie są zdefiniowane w IDL lub w Java, znajdują się w pakiecie com.cisag.pgm.external.corba.

Typy danych niewymienione nie są obsługiwane przez interfejs CORBA systemu Comarch ERP Eneterprise, nawet jeśli są wykorzystywane po stronie serwera jako parametry aplikacji wsadowych.

Należy również uwzględnić, że wartości null nie mogą być stosowane (np. null jako GUID). Przy przekazywaniu danych z Comarch ERP Eneterprise do klienta parametry o wartości null są usuwane, w wyniku czego nie są dostępne po stronie klienta (wyjątek stanowią parametry zwracane przez wywołania aplikacji, patrz dalej).

Znaczniki czasu

Znaczniki czasu (prymitywny typ danych TimeStamp) mogą być po stronie CORBA reprezentowane jako typ IDL long long. Po stronie serwera nie istnieje jednak automatyczne mapowanie na typ Java java.util.Date, który jest używany w systemie jako reprezentacja znacznika czasu. Mapowanie zgodne z metodą Java currentTimeMillis() musi zostać zaimplementowane indywidualnie w aplikacji wsadowej.

Stałe odpowiadające wartościom +∞, -∞ oraz nieprawidłowemu znacznikowi czasu są zdefiniowane w interfejsie IDL CorbaDatatypeConstants.

CisObjects i Parts

CisObjectRepresentation oraz CisObjectRepresentationList służą do wywoływania aplikacji wsadowych wykorzystujących transjentne obiekty CisObject oraz Parts jako parametry. CisObjectRepresentation służy do przekazywania pojedynczego obiektu CisObject lub Part, natomiast CisObjectRepresentationList umożliwia przekazywanie uporządkowanej kolekcji takich obiektów.

W wyniku przesyłania obiektów CisObject i Parts przez CORBA tworzona jest ich kopia, zawierająca wartości atrybutów z momentu transmisji.

Instancja CisObjectRepresentation składa się z nazwy odpowiedniego obiektu deweloperskiego oraz atrybutów instancji:

• className: pełna nazwa obiektu deweloperskiego (Business Object lub Part)

• values: nazwy i wartości atrybutów w postaci CorbaParameterList

W przypadku obiektów CisObject zawierających Parts, odpowiednia wartość atrybutu w CorbaParameterList values jest również instancją CisObjectRepresentation, reprezentującą dany Part.

Podczas transmisji z klienta do Comarch ERP Enterprise przekazywane są tylko wskazane atrybuty. Atrybuty nieprzekazane są w Comarch ERP Enterprise uzupełniane wartościami domyślnymi (technicznymi) i w takiej postaci przekazywane do aplikacji wsadowej. Przy transmisji do klienta zakres przekazywanych atrybutów zależy wyłącznie od aplikacji wsadowej.

Typy danych nieobsługiwane przez interfejs CORBA nie mogą być przekazywane również jako wartości atrybutów obiektów CisObject lub Parts.

Należy także uwzględnić, że identyfikatory GUID zawarte w obiektach CisObject i Parts nie są automatycznie konwertowane do czytelnej postaci podczas transmisji jako CisObjectRepresentation.

Interfejs nowo tworzonej aplikacji wsadowej może zostać uproszczony poprzez wykorzystanie wyspecjalizowanych Parts zamiast pełnych instancji obiektów biznesowych, zawierających wyłącznie wymagane atrybuty.

Sposób działania klienta CORBA

Przy implementacji klienta CORBA można wykorzystać przykładowe klienty dostarczane wraz z systemem jako materiał referencyjny. Poniżej opisano kroki niezbędne do ustanowienia połączenia CORBA oraz wywoływania aplikacji wsadowych.

Nawiązanie połączenia

Przed nawiązaniem połączenia z serwerem CORBA Comarch ERP Enterprise należy najpierw zainicjalizować ORB. Następnie połączenie jest ustanawiane poprzez uzyskanie referencji do obiektu CorbaSessionManager. W tym celu należy użyć adresu „corbaloc:”, będącego ciągiem znaków w następującym formacie:

Elementy host oraz port oznaczają nazwę hosta i port serwera CORBA systemu, z którym ma zostać nawiązane połączenie. Trzeci parametr odpowiada wartości stałej:

CorbaConstants.SEMIRAMIS_CORBA_SESSION_MANAGER

Wywoływanie aplikacji

Z obiektu CorbaSession można uzyskać obiekt CorbaApplicationManager, za pomocą którego możliwe jest wywoływanie aplikacji wsadowych w systemie Comarch ERP Enterprise.

Parametry są przekazywane przy użyciu obiektów CorbaParameterList. Aby przekazać parametry wywołania, należy najpierw utworzyć nowy obiekt:

a następnie ustawić w nim odpowiednie parametry.

W przypadku bezstanowego wywołania aplikacji wsadowej wystarczy pojedyncze wywołanie metody:

Metoda zwraca listę parametrów zawierającą wartości zwracane oraz komunikaty. Jeśli lista parametrów ma wartość null, zgodnie z konwencją oznacza to, że wywołanie zakończyło się niepowodzeniem. Przyczyny można ustalić na podstawie komunikatów. Jeśli lista parametrów nie jest null, jej znaczenie zależy od wywołanej aplikacji wsadowej — może to również oznaczać brak powodzenia, np. gdy aplikacja zwraca szczegółowe informacje o błędzie.

W przypadku wywołań stanowych należy najpierw utworzyć instancję aplikacji:

a następnie można ją wielokrotnie wywoływać z różnymi parametrami:

Po zakończeniu pracy z aplikacją stanową należy ją zwolnić za pomocą metody:

Dokładne sygnatury oraz sposób użycia metod są opisane w IDL oraz w przykładowych klientach.

To, czy dana aplikacja wsadowa powinna być wywoływana w trybie bezstanowym czy stanowym, zależy od jej implementacji. W prostych przypadkach, wymagających niewielkiej liczby parametrów i zasobów (np. sprawdzenie klucza obcego lub zapis prostego obiektu), wystarczające są wywołania bezstanowe.

W przypadku przesyłania dużych ilości danych można wykorzystać aplikacje stanowe, które umożliwiają podział operacji na wiele wywołań (np. przetwarzanie danych w blokach). Podejście to jest stosowane m.in. w aplikacjach eksportu i importu.

Zwalnianie obiektów CORBA po stronie serwera

W CORBA czas życia obiektów dostępnych przez CORBA nie jest zarządzany przez implementację CORBA, lecz w sposób zależny od aplikacji w danym serwerze CORBA.

W interfejsie CORBA systemu Comarch ERP Enterprise przewidziano w tym celu jawne zwalnianie niepotrzebnych już obiektów CORBA, które musi zostać wykonane po stronie klienta. W tym celu dostępne są następujące metody:

• CorbaParameterList::release()
  Zwalnia obiekt CorbaParameterList oraz wszystkie zawarte w nim obiekty CorbaParameterList.
  Zwolnienie jest wymagane dla wszystkich obiektów CorbaParameterList utworzonych przez klienta oraz zwróconych przez interfejs CORBA, o ile nie są one zawarte w innych obiektach CorbaParameterList.
  Po wywołaniu metody dostęp do całej CorbaParameterList nie jest już możliwy.
• CorbaMessageQueue::release()
  Zwalnia obiekt CorbaMessageQueue.
  Zwolnienie jest wymagane dla wszystkich obiektów CorbaMessageQueue zwróconych przez interfejs CORBA.
  Po wywołaniu metody dostęp do CorbaMessageQueue oraz wszystkich zawartych w niej komunikatów nie jest już możliwy.
• CorbaApplicationManager::releaseApplication()
  Zwalnia wskazaną aplikację.

Zdalny interfejs BIS przez CORBA

Zdalny interfejs BIS składa się z trzech aplikacji wsadowych, które mogą być wywoływane za pośrednictwem interfejsu CORBA. Do ich wywoływania należy używać interfejsu CORBA.

Przypadki użycia

Aplikacje wsadowe zdalnego BIS są zoptymalizowane do scenariuszy, w których zarówno wyzwolenie operacji, jak i transmisja danych odbywają się wyłącznie przez CORBA. Jest to konieczne w sytuacjach, gdy dane użytkownika nie mogą być przekazywane między klientem CORBA a serwerem CORBA w inny sposób.

Aplikacje wsadowe zostały opisane w kolejnych rozdziałach.

Jeżeli jednak klient CORBA i serwer CORBA mają dostęp np. do wspólnego systemu plików lub Knowledge Store, korzystne może być bezpośrednie zapisywanie i odczytywanie danych właśnie tam. Zalety takiego podejścia:

• odciążenie połączenia CORBA poprzez ograniczenie ilości przesyłanych danych
• możliwość asynchronicznego przesyłania danych użytkownika względem samej operacji
• możliwość importu powiązanych plików (np. plików dla atrybutów typu BLOB)

Aby zastosować ten sposób wywołania, można korzystać z aplikacji wsadowych opisanych w dokumentacji Programowe interfejsy wymiany danych i wywoływać je bezstanowo przez CORBA, bezpośrednio za pomocą metody callApplication obiektu CorbaApplicationManager.

Aplikacje w tle

Poniżej opisano akcje, parametry oraz parametry zwracane dla aplikacji wsadowych zdalnego BIS.

Operacja w zdalnym BIS — niezależnie od tego, czy dotyczy importu, eksportu czy wyszukiwania — składa się z wielu wywołań aplikacji kierowanych do tej samej instancji aplikacji (wywołania stanowe). W przypadku przesyłania danych w blokach, przy pierwszym wywołaniu określane są parametry wejściowe oraz zwracany jest pierwszy blok wyników. Każde kolejne wywołanie zwraca następny blok danych.

Instancja aplikacji musi zostać wcześniej utworzona. W IDL CORBA dostępne są w tym celu stałe:

• APPLICATION_NAME
• APPLICATION_NAME
• APPLICATION_NAME

które należy podać jako nazwę aplikacji przy tworzeniu jej instancji.

Akcje, nazwy parametrów oraz stałe typu Valueset są również zdefiniowane w IDL CORBA jako stałe. Znajdują się one w interfejsach IDL:

• CorbaRemoteImport
• CorbaRemoteExport

Przy tworzeniu klientów CORBA zaleca się korzystanie z tych stałych.

W poniższym opisie interfejsów typy parametrów podano jako typy Java lub Comarch ERP Enterprise. W przypadku klienta CORBA należy stosować odpowiednie typy po stronie klienta. Oznacza to, że dla klienta CORBA napisanego w Java zamiast typu CisParameterList należy używać typu CorbaParameterList.

Po zakończeniu lub przerwaniu operacji możliwe jest rozpoczęcie kolejnych operacji przy użyciu tej samej instancji aplikacji. Wywołania dotyczące różnych operacji nie mogą jednak być wykonywane równolegle.

Zdalny import przez CORBA

W procesie importu dane są przekazywane do systemu w postaci dokumentu XML, przesyłanego blokami. Wielkość bloków danych importowych jest określana przez klienta CORBA. Zalecane wartości mieszczą się w zakresie od 250 kB do 1000 kB. Rozmiar bloku nie powinien być zbyt duży, aby nie obciążać nadmiernie pamięci operacyjnej serwera aplikacji Comarch ERP Enterprise. Z kolei zbyt mały rozmiar bloków powoduje dużą liczbę wywołań (roundtripów), co ze względu na opóźnienia (latencję) znacząco wydłuża czas transmisji.

W przypadku wystąpienia błędów importu można określić, czy korekta danych ma zostać przeprowadzona w systemie, czy też plik błędów ma zostać odesłany do klienta. W przypadku korekty w Comarch ERP Enterprise wykorzystywane są powiadomienia w ramach zarządzania workflow, opisane w dokumentacji Wprowadzenie: wymiana danych.

Jeżeli korekta odbywa się w plik błędów jest zapisywany w Knowledge Store w katalogu:
kstore://<obszar roboczy>/Import/RemoteErrorFiles
Jako obszar roboczy wykorzystywany jest domyślny obszar roboczy bazy danych, do której importowano dane. Katalog ten nie powinien być używany do innych celów.

Filtr używany w procesie importu musi zostać wcześniej utworzony i zapisany w aplikacji Import danych. Należy podać nazwę filtra. Szczegółowe informacje znajdują się w artykule Import danych.

Akcje i parametry

Aplikacja w tle do importu może być wywoływana z użyciem następujących akcji:

Przebieg importu z zwrotem pliku błędów wygląda następująco:

• Proces importu rozpoczyna się od wywołania akcji PROCESS.
• Dla kolejnych bloków należy wielokrotnie wywoływać PROCESS_NEXT_BLOCK, zgodnie z potrzebą.
• Zakończenie importu następuje poprzez wywołanie PROCESS_LAST_BLOCK. Jeśli podczas importu nie wystąpiły błędy, proces zostaje zakończony.
• Jeśli podczas importu wystąpiły błędy i dostępny jest plik błędów, jest on zwracany blokami za pomocą akcji GET_ERROR_FILE_NEXT_BLOCK. Jeżeli plik błędów nie ma być pobierany, należy zamiast tego jednorazowo wywołać akcję CLOSE.

Poniżej opisano parametry poszczególnych akcji.

Akcja PROCESS

Dostępne są następujące parametry:

Zwracana wartość: pusta lista parametrów

Wystąpienie błędu sygnalizowane jest wtedy, gdy zwrócona lista parametrów ma wartość null lub gdy metoda requiresAttention() obiektu CorbaMessageQueue zwraca wartość true. W takim przypadku proces importu nie może być dalej kontynuowany.

Akcja PROCESS_NEXT_BLOCK

Dostępny jest następujący parametr:

Zwracana wartość: pusta lista parametrów

Wystąpienie błędu sygnalizowane jest wtedy, gdy zwrócona lista parametrów ma wartość null lub gdy metoda requiresAttention() obiektu CorbaMessageQueue zwraca wartość true. W takim przypadku proces importu nie może być dalej kontynuowany.

Akcja PROCESS_LAST_BLOCK

Dostępny jest następujący parametr:

Zwracane wartości:

Powodzenie procesu importu można ustalić poprzez wywołanie metody requiresAttention() na obiekcie CorbaMessageQueue. Obiekt CorbaMessageQueue zawiera komunikaty będące częścią wyniku wywołania aplikacji.

• Jeśli metoda requiresAttention() zwraca wartość false, oznacza to, że import zakończył się pomyślnie. Proces importu jest zakończony.
• Jeśli metoda requiresAttention() zwraca wartość true, oznacza to, że podczas importu wystąpił błąd. Należy przeanalizować zwrócone komunikaty.

Na podstawie zwróconych liczników można rozróżnić różne przypadki błędów (szczegóły w artykule Wprowadzenie: wymiana danych).

Na podstawie parametrów zwracanych można również określić, czy dostępny jest plik błędów do przekazania klientowi. Plik ten może zostać pobrany w kolejnych wywołaniach z użyciem akcji GET_ERROR_FILE_NEXT_BLOCK.

Należy uwzględnić, że zwracane wartości liczników mogą w pewnych sytuacjach nie być dokładne, co opisano w artykule Wprowadzenie: wymiana danych.

Akcja GET_ERROR_FILE_NEXT_BLOCK

Wywołanie odbywa się z pustą listą parametrów.

Zwracana wartość:

Jeżeli plik błędów nie jest dostępny, zamiast listy parametrów zwracana jest wartość null.

Może się zdarzyć, że ostatni blok pliku błędów nie zawiera danych. Dlatego parametr Content jest opcjonalny i klient musi sprawdzić, czy występuje on w zwróconej liście parametrów.

Akcja CLOSE

Wywołanie oraz zwracana wartość: pusta lista parametrów.

Zdalny eksport przez CORBA

W procesie eksportu należy określić nazwę eksportowanego obiektu biznesowego (Business Entity), bazę danych, z której mają zostać pobrane dane, opcjonalnie filtr oraz parametry zawężające zakres danych. Wybór danych określa liczbę eksportowanych instancji obiektów biznesowych i może być zdefiniowany poprzez zapytanie OQL z parametrami selekcji i sortowania lub za pomocą dynamicznego ciągu OQL, który spełnia tę samą funkcję.

Filtr wykorzystywany w procesie eksportu musi zostać wcześniej utworzony i zapisany w aplikacji Eksport danych (lub Import danych). 

Dokument XML zawierający eksportowane instancje obiektów biznesowych jest przekazywany do klienta blokami. Rozmiar bloku wynosi około 500 kB.

Akcje i parametry

Aplikacja wsadowa do eksportu może być wywoływana z użyciem następujących akcji:

Przebieg eksportu wygląda następująco:

• Za pomocą akcji EXPORT przekazywane są parametry eksportu. Wynikiem jest pierwszy blok danych.
• Dopóki dostępne są kolejne bloki, są one pobierane poprzez wywołania akcji EXPORT_NEXT_BLOCK. Jeśli nie ma więcej bloków, proces eksportu zostaje zakończony.
• Aby pobrać schemat XML, wystarczy jednokrotne wywołanie akcji GET_SCHEMA.

Akcja EXPORT

Dostępne są następujące parametry:

Wystąpienie błędu sygnalizowane jest wtedy, gdy zwrócona lista parametrów ma wartość null lub gdy metoda requiresAttention() obiektu CorbaMessageQueue zwraca wartość true. W takim przypadku proces eksportu nie może być dalej kontynuowany.

Jeżeli nie udało się wyeksportować żadnej instancji obiektu biznesowego, np. ponieważ żadna instancja nie odpowiadała zadanym parametrom wyszukiwania, parametry zwracane Content oraz ContentLength nie występują.

Akcja EXPORT_NEXT_BLOCK

Wywołanie: pusta lista parametrów

Zwracana wartość:

Może się zdarzyć, że ostatni blok nie zawiera danych. Dlatego parametr Content jest opcjonalny i klient musi sprawdzić, czy występuje on w zwróconej liście parametrów.

Wszystkie możliwe przypadki błędów należy obsługiwać analogicznie jak w przypadku akcji EXPORT.

Akcja GET_SCHEMA

Dostępne są następujące parametry:

Zwracana wartość:

Wystąpienie błędu sygnalizowane jest wtedy, gdy zwrócona lista parametrów ma wartość null lub gdy metoda requiresAttention() obiektu CorbaMessageQueue zwraca wartość true. W takim przypadku operacja nie może być dalej kontynuowana.

Akcja CLOSE

Wywołanie oraz zwracana wartość: pusta lista parametrów.

Zdalne wyszukiwanie przez CORBA

Funkcja wyszukiwania opiera się na zapytaniu OQL. W celu zawężenia wyników można wykorzystać pola selekcyjne zdefiniowane w zapytaniu OQL. Możliwe jest również określenie sortowania wyników. Wynik wyszukiwania dla każdego wiersza zawiera pola zwracane przez zapytanie OQL.

Wyniki wyszukiwania są przekazywane stronicowo, przy czym każda strona jest zwracana w ramach osobnego wywołania aplikacji.

W odróżnieniu od importu i eksportu, wyszukiwanie oferuje zarówno format użytkownika, jak i format techniczny dla parametrów selekcji oraz wyników wyszukiwania.

Akcje i parametry

Dostępne są następujące akcje:

Przebieg wyszukiwania z pobraniem wszystkich stron wyników:

• Wywołanie akcji SEARCH z podaniem parametrów wyszukiwania. Zwracana jest pierwsza strona wyników.
• Kolejne strony wyników pobierane są poprzez wywołania akcji SEARCH_NEXT_PAGE.

Akcja SEARCH

Dostępne są następujące parametry:

Dla parametrów formatowania dostępne są następujące stałe:

• FORMAT_USER_DEPENDENT – format zależny od użytkownika
• FORMAT_TECHNICAL – format techniczny

Zwracana wartość:

Wystąpienie błędu sygnalizowane jest wtedy, gdy zwrócona lista parametrów ma wartość null lub gdy metoda requiresAttention() obiektu CorbaMessageQueue zwraca wartość true. W takim przypadku proces wyszukiwania nie może być dalej kontynuowany.

Akcja SEARCH_NEXT_PAGE

Wywołanie: pusta lista parametrów

Zwracana wartość:

Wystąpienie błędu sygnalizowane jest wtedy, gdy zwrócona lista parametrów ma wartość null lub gdy metoda requiresAttention() obiektu CorbaMessageQueue zwraca wartość true. W takim przypadku proces wyszukiwania nie może być dalej kontynuowany.

Akcja EXISTS

Dostępne są następujące parametry:

Zwracana wartość:

Jeżeli nie znaleziono żadnego obiektu, parametr ten nie jest zwracany (metoda containsParameter() zwraca wartość false).

Wystąpienie błędu sygnalizowane jest wtedy, gdy zwrócona lista parametrów ma wartość null lub gdy metoda requiresAttention() obiektu CorbaMessageQueue zwraca wartość true. W takim przypadku proces wyszukiwania nie może być dalej kontynuowany.

Akcja CLOSE

Wywołanie oraz zwracana wartość: pusta lista CisParameterList.

Przykłady 

Wraz z systemem Comarch ERP Enterprise dostarczane są klienty testowe, które demonstrują wykorzystanie zdalnych interfejsów BIS. Klienci testowi stanowią część kodu aplikacji systemu. Kod źródłowy jest również dostępny, jeśli licencjonowany jest Software Development Kit (SDK).

Klienci testowi mogą być uruchamiani zarówno z poziomu Toolshell, jak i niezależnie od serwera aplikacji systemu. W tym celu należy postępować zgodnie z instrukcjami zawartymi w rozdziale dotyczącym uruchamiania klienta testowego, zastępując nazwę narzędzia lub klasy odpowiednimi nazwami podanymi poniżej.

Niektórzy klienci testowi posiadają dodatkowe parametry wykraczające poza te opisane w dokumentacji Interfejs CORBA. Parametry te są udokumentowane w kodzie źródłowym oraz w JavaDoc.

Dostępni są następujący klienci testowi:

• Eksport
  Toolname: CorbaRemoteExportTestClient
  Klasa Java: com.cisag.app.system.corba.log.CorbaRemoteExportTestClient
• Eksport schematu
  Toolname: CorbaRemoteSchemaExportTestClient
  Klasa Java: com.cisag.app.system.corba.log.CorbaRemoteSchemaExportTestClient
• Import
  Toolname: CorbaRemoteImportTestClient
  Klasa Java: com.cisag.app.system.corba.log.CorbaRemoteImportTestClient

• Wyszukiwanie
  Toolname: CorbaRemoteSearchTestClient
  Klasa Java: com.cisag.app.system.corba.log.CorbaRemoteSearchTestClient

Kod źródłowy klienta testowego CORBA napisanego w języku Java jest dostępny w aplikacji Obiekty deweloperskie.

Klasy są szczegółowo udokumentowane w kodzie źródłowym. Należy zwrócić uwagę, że przykładowe implementacje wykorzystują klasy wygenerowane w System Engine oraz niektóre klasy interfejsu PGM, aby umożliwić ich łatwe uruchamianie zarówno z poziomu Toolshell, jak i bez jego użycia. Przy tworzeniu niezależnego klienta CORBA komponenty te nie są wymagane.

Postępowanie

Aby uruchomić klienta testowego, należy postępować zgodnie z poniższą instrukcją.

Uruchomienie serwera

W Toolshell:

strscs –host:localhost –port:2000

Uruchomienie klienta testowego

Klient testowy jest dostarczany jako zestaw obiektów deweloperskich w standardowej instalacji. Oprócz klas Java zdefiniowana jest dla niego aplikacja typu Tool. Uruchomienie klienta testowego w Toolshell odbywa się za pomocą polecenia:

CorbaTestClient -host:localhost -port:2000 -userName:<użytkownik> -password:<hasło> -oltpDatabaseName:<baza OLTP>

 

Aplikacja wsadowa wywoływana zdalnie przez klienta testowego przekazuje otrzymane parametry wejściowe jako wartości zwracane w wyniku wywołania. Dodatkowo generowany jest komunikat typu błąd. Wartości zwracane oraz komunikaty są wyświetlane w konsoli.

Klienta testowego można również uruchomić poza Toolshell. W tym celu należy dodać do ścieżki klas biblioteki JacORB (jacorb.jar, avalon-framework.jar, logkit.jar), System Engine oraz kod aplikacji. Uruchomienie odbywa się wtedy w następujący sposób:

java com.cisag.app.system.corba.log.CorbaTestClient

-Dorg.omg.CORBA.ORBClass=org.jacorb.orb.ORB
-Dorg.omg.CORBA.ORBSingletonClass=org.jacorb.orb.ORBSingleton
-cp <ścieżka klas>
-host:<host>
-port:<port>-userName:<użytkownik>
-password:<hasło>
-oltpDatabaseName:<baza OLTP>

Komunikaty błędów

W przypadku wystąpienia komunikatu błędu w formie
org.omg.CORBA.COMM_FAILURE: vmcid: SUN minor code: 201 completed: No
należy sprawdzić parametry serwera CORBA i klienta CORBA oraz komunikację między nimi.

Błędy występujące podczas logowania klienta CORBA lub podczas wykonywania aplikacji wsadowych na serwerze aplikacji systemu są — w zależności od ich wagi — zapisywane w logach i mogą zostać tam przeanalizowane.

Uwaga

Microsoft Word podczas operacji kopiowania i wklejania (Ctrl+C / Ctrl+V) może zamieniać znak „-” (minus) na „–” (myślnik). Ponieważ niektóre programy nie walidują parametrów wejściowych, może to prowadzić do nieprawidłowego działania (np. braku komunikacji z ORB). W takim przypadku należy zweryfikować parametry wprowadzone w wierszu poleceń.

CORBA i zapory sieciowe (firewalle)

CORBA realizuje architekturę obiektową, a tym samym stanową. Jedną z jej podstawowych cech jest niezależność obiektu od miejsca, w którym jest on udostępniany. Z tego wynikają dwa kluczowe wymagania dotyczące komunikacji między serwerem CORBA a klientem CORBA:

• Ponieważ klient i serwer wymieniają referencje do obiektów, klient musi mieć możliwość aktywnego wywoływania operacji na serwerze, a serwer — na kliencie. W praktyce role „klienta” i „serwera” po nawiązaniu połączenia tracą swoje znaczenie.
• Referencje do obiektów oraz same obiekty reprezentują stan, co wymaga stosowania protokołu komunikacyjnego obsługującego stan.

Problemy w komunikacji między klientami i serwerami CORBA często wynikają z działania zapór sieciowych znajdujących się pomiędzy nimi. Firewalle często przepuszczają tylko wybrane protokoły sieciowe, co może skutkować sytuacją, w której logowanie do systemu przez „https://” działa poprawnie, natomiast klient CORBA nie może uzyskać dostępu przez „iiop://”.

Przechodzenie przez zapory sieciowe jest w przypadku CORBA bardziej problematyczne niż w wielu innych protokołach, co wynika z następujących przyczyn:

• Implementacje CORBA dynamicznie przydzielają numery portów w czasie działania. Ponieważ nie są one przewidywalne, nie można ich wcześniej skonfigurować w zaporach opartych na regułach portów.
• Referencje do obiektów zawierają adres IP i numer portu, aby implementacja ORB po stronie odbiorcy mogła bezpośrednio odwołać się do obiektu. Zastosowanie NAT (Network Address Translation) powoduje jednak, że host może być dostępny pod różnymi adresami w różnych segmentach sieci, co sprawia, że adres IP przekazany w protokole może być nieprawidłowy po stronie odbiorcy.
• CORBA często wykorzystuje mechanizm wywołań zwrotnych (callbacków) z serwera do klienta. Wymaga to, aby klient był dostępny dla serwera, co bywa blokowane przez zapory sieciowe.

Ze względów bezpieczeństwa nie należy rezygnować z użycia zapór sieciowych. Aby rozwiązać powyższe problemy, producenci oferują tzw. Application Security Gateways — rozwiązania dostosowane do CORBA, które zamiast na poziomie adresów IP działają na poziomie referencji obiektów CORBA, zapewniając mechanizmy uwierzytelniania, bezpieczeństwa i routingu.

Ochrona przed niedoborem zasobów

Każda sesja otwierana przez klienta poprzez CORBA w systemie zużywa zasoby serwera aplikacji, takie jak pamięć, czas procesora oraz połączenia z bazą danych. W scenariuszach, w których bardzo duża liczba klientów utrzymuje stałe połączenie z serwerem CORBA, może dojść do niedoborów zasobów. Szczególnie krytyczne są w tym przypadku sesje CORBA (oraz połączenia z bazą danych). Każda sesja CORBA od momentu utworzenia zajmuje jeden wątek, a tym samym pamięć sterty dla stosu wątku oraz zasoby natywne zależne od systemu operacyjnego. Podczas przetwarzania żądania CORBA ORB wykorzystuje wątek ze swojej puli do jego obsługi, a następnie przekazuje je do wątku. Jeżeli przetwarzanie wymaga dostępu do danych, dodatkowo wykorzystywane są połączenia z bazą danych.

Pamięć, wątki oraz połączenia z bazą danych są zasobami ograniczonymi na serwerze aplikacyjnym. Niedobór zasobów prowadzi do wydłużenia czasu przetwarzania wywołań CORBA, a w skrajnych przypadkach może zagrozić stabilności całego serwera aplikacji.

Aby zapobiec niedoborom zasobów, dostępnych jest kilka rozwiązań. Ich wspólną ideą jest koordynacja dostępu do zasobów krytycznych w celu ograniczenia liczby równoczesnych operacji.

W pierwszym rozwiązaniu (rysunek 1) wykorzystywanych jest wiele serwerów CORBA (tj. serwerów aplikacji systemu), na które rozdzielany jest ruch klientów. Pozwala to zmniejszyć zużycie pamięci na pojedynczym serwerze aplikacyjnym. Należy jednak uwzględnić, że takie podejście może prowadzić do zwiększonego obciążenia bazy danych, jeśli wiele żądań trafia jednocześnie do serwerów aplikacji.

W drugim rozwiązaniu (rysunek 2) wykorzystywany jest niezależny proces, działający poza systemem (CORBA Proxy Queue). Żądania klientów trafiają najpierw do tego procesu, gdzie są umieszczane w kolejce, a następnie w ograniczonej liczbie przekazywane do systemu. W ten sposób ograniczana jest liczba sesji CORBA oraz liczba połączeń z bazą danych w systemie.

CORBA Proxy Queue działa jednocześnie jako serwer i klient CORBA. Implementacja takiej kolejki może zostać wykonana w dowolnym języku programowania, dostosowanym do danego przypadku użycia.

W obu przedstawionych rozwiązaniach zakłada się, że każdy proces działa na osobnym serwerze i ma do dyspozycji jego zasoby w sposób wyłączny. Również CORBA Proxy Queue powinna być uruchamiana na dedykowanym serwerze.

Już na etapie tworzenia integracji z systemu przez CORBA należy przeprowadzić testy z uwzględnieniem przewidywanej liczby klientów. Pozwala to ocenić, czy w danym przypadku konieczne jest zastosowanie mechanizmów ochrony zasobów.