W przypadku prostych jednostek biznesowych wymiana danych jest możliwa bez dodatkowego nakładu pracy programistycznej, ponieważ usługa integracji biznesowej (BIS) obsługuje generyczny import i eksport. W przypadku bardziej złożonych zastosowań należy użyć klasycznej wymiany danych. Zapewnia ona największą możliwą elastyczność.
Uproszczona wymiana danych kładzie większy nacisk na szybkość wymiany danych. Typowym przykładem użycia uproszczonej wymiany danych byłoby np. okresowe przesyłanie zawsze tych samych 10 atrybutów obiektu biznesowego Partner. Wysoka prędkość przesyłania wynika z zawsze takiej samej struktury danych.
Niniejszy artykuł wyjaśnia podstawowe procedury implementacji kontrolera dla uproszczonej wymiany danych i zawiera wskazówki dotyczące korzystania z odpowiedniego interfejsu programistycznego.
Grupa docelowa
- Programiści aplikacji
Definicje terminów
- Kontroler — kontroler to klasa Javy, która realizuje import lub eksport jednostki biznesowej. W przypadku uproszczonej wymiany danych konkretny kontroler musi dziedziczyć z abstrakcyjnej klasy com.cisag.pgm.bi.lite.LiteController. Kontroler dostarcza model danych, który ma być używany do importu lub eksportu, a tym samym określa zestaw obiektów, atrybutów i relacji dostępnych dla jednostki biznesowej.
- Obiekt zewnętrzny — obiekt zewnętrzy to obiekt deweloperski, który zawiera wybrane i ewentualnie już rozwiązane atrybuty. W kontrolerze uproszczonej wymiany danych służy on jako filtr, podobnie jak w klasycznym Business Integration Service (BIS). Ponieważ jest to obiekt deweloperski, aby zmienić filtr, należy utworzyć nową wersję tego obiektu.
- ExternalValueNode — te zewnętrzne węzły odwzorowują strukturę zewnętrzną. Obiekt jest opakowaniem dla obiektu zewnętrznego i dodatkowo zna strukturę, tj. nadrzędne i podrzędne inne obiekty zewnętrzne. Ta struktura jest tworzona poprzez rejestracje.
- InternalValueNode — te wewnętrzne węzły odwzorowują strukturę wewnętrzną. Obiekt jest opakowaniem dla danego CisObject. Dodatkowo zna nadrzędne i podrzędne obiekty biznesowe. Ta struktura jest tworzona przez ObjectInfo.
Rozwój
Struktura określona przez obiekt deweloperski typu Obiekt zewnętrzny pozwala na blokowe odczytywanie i zapisywanie danych. Może to prowadzić do znacznego wzrostu wydajności w porównaniu z klasycznym Business Integration Service (BIS). Jeśli podczas tworzenia kontrolera dodatkowo będą wykonywane pojedyncze dostępy do bazy danych, zysk ten zostanie zniweczony. Dlatego należy pamiętać: jeśli konieczne są pojedyncze dostępy do bazy danych, jest to wskazówka, że wymagana jest elastyczność klasycznego BIS. Uproszczona wymiana danych nie nadaje się do tego.
Obiekty aplikacji
Warunkiem uproszczonego eksportu lub importu danych są obiekty deweloperskie typu Aplikacja, dla których określono typ aplikacji Uproszczona wymiana danych oraz szczególne zastosowanie Eksport lub Import. Mogą one zostać wybrane w aplikacjach Eksport uproszczony lub Import uproszczony. Jako klasę Java należy podać kontroler.
Kontroler
Kontroler to klasa Javy, która realizuje import i eksport dla określonej jednostki biznesowej. Należy pamiętać o następujących kwestiach:
- Kontroler dla uproszczonej wymiany danych musi dziedziczyć z abstrakcyjnej klasy com.cisag.pgm.bi.lite.LiteController
- Jeśli dla jednostki biznesowej mają być możliwe eksport i import, ale import ma obejmować tylko wycinek modelu danych eksportu, należy zaimplementować kontroler importu i eksportu w dwóch różnych klasach, aby móc zdefiniować odmienne modele danych
ObjectInfo
Każdy kontroler definiuje model danych BIS, który jest używany podczas importu lub eksportu. W przypadku uproszczonej wymiany danych ObjectInfo ma dwa zadania:
- Jeśli za pomocą importu ma zostać utworzony nowy obiekt, określa się całkowitą liczbę obiektów biznesowych do utworzenia. W tym celu konieczna jest dodatkowa rejestracja obiektu szablonu.
- Jeśli chce się zbudować bardziej złożoną strukturę i połączyć kilka obiektów zewnętrznych, połączenie odbywa się za pomocą relacji zdefiniowanej w ObjectInfo
Model danych BIS określa strukturę importowanych lub eksportowanych danych.
Rejestracja
Struktura zewnętrzna
W klasycznym BIS dostępne są filtry, z których można wybrać używane atrybuty. Uproszczona wymiana danych wymaga ustalonej struktury danych. To ustalenie odbywa się za pomocą obiektu zewnętrznego.
W konkretnej implementacji kontrolera dla uproszczonej wymiany danych należy zmienić abstrakcyjną metodę registerExternalInformation. W niej trzeba zdefiniować określone informacje dla uproszczonej wymiany danych.
Przykład dla prostego przypadku tej metody:
@Override
protected boolean registerExternalInformation() {
return registerExternalObjectByBusinessKey(ExternalItem.class);
}
W tym przykładzie obiekt zewnętrzny ExternalItem jest rejestrowany jako obiekt główny. Ten obiekt zewnętrzny odnosi się do obiektu biznesowego Item. Jednocześnie ustalono, że ma być używany Business Key.
Do rejestracji obiektu głównego dostępne są następujące metody:
- registerExternalObjectByPrimaryKey
- registerExternalObjectByBusinessKey
- registerExternalObjectBySecondaryKey
Zalecana jest rejestracja za pomocą Business Key. W ramach jednego kontrolera można zarejestrować tylko jeden obiekt zewnętrzny jako obiekt główny, co oznacza, że dokładnie jedna z tych metod musi zostać wywołana dokładnie raz.
Można również budować bardziej złożone struktury zewnętrzne. To, co jest możliwe, jest z góry określone przez już zdefiniowane ObjectInfo.
Aby zarejestrować dodatkowe obiekty, można wykorzystać następującą składnię:
@Override
protected boolean registerExternalInformation(){
boolean result = registerExternalObjectByBusinessKey(ExternalItem.class);
AssociationDescriptor purchaseItemsAssociation = getObjectInfo().getAssociation(„PurchaseItems”);
result &= registerExternalChildByPrimaryKey(ExternalItem.class,purchaseItemsAssociation , ExternalPurchaseItem.class);
return result;
}
W tym przykładzie najpierw, jak powyżej, rejestrowany jest obiekt zewnętrzny ExternalItem za pomocą Business Key. Między obiektami biznesowymi Item i PurchaseItem zdefiniowana jest relacja za pomocą ObjectInfo. Można jej użyć do zarejestrowania obiektu zewnętrznego ExternalPurchaseItem jako obiektu podrzędnego obiektu zewnętrznego ExternalItem.
Obiekt zewnętrzny ExternalPurchaseItem odnosi się do obiektu biznesowego PurchaseItem. W tym przypadku rejestracja odbywa się za pomocą PrimaryKey. Relacja jest skierowana na PrimaryKey obiektu biznesowego PurchaseItem.
Jako pierwszy parametr podawany jest obiekt zewnętrzny nadrzędny, następnie relacja między obiektami, a na końcu obiekt zewnętrzny podrzędny. Obiekt nadrzędny musi być już zarejestrowany, aby móc rejestrować dla niego obiekty podrzędne..
Do rejestrowania obiektów podrzędnych dostępne są następujące metody:
- registerExternalChildByPrimaryKey
- registerExternalChildByBusinessKey
- registerExternalChildBySecondaryKey
Za pomocą tej metody można również rejestrować obiekty podrzędne dla zarejestrowanych już obiektów podrzędnych.
Obiekt szablonu
Można dokonać kilku innych rejestracji. Najważniejsza z nich to ta metoda registerTemplateKey(byte[] key).
Za jej pomocą można wyróżnić obiekt biznesowy, który ma być używany jako szablon podczas importu. Struktura zewnętrzna jest zazwyczaj tylko małym wycinkiem maksymalnej liczby obiektów i zawartych w nich atrybutów, które są zdefiniowane za pomocą ObjectInfo. Importowane są tylko te dane, które zostały określone za pomocą struktury zewnętrznej i użytych do tego obiektów zewnętrznych. Zazwyczaj jest to jednak niewystarczające.
Aby móc użyć artykułu, potrzebne są jednak jeszcze dane księgowe. Służy do tego obiekt szablonu. Ponieważ w tym przykładzie Item jest obiektem głównym, użytkownik rejestruje artykuł jako obiekt szablonu. Jeśli podczas importu zostanie stwierdzone, że nie istnieje instancja dla tego artykułu, tworzona jest kopia obiektu szablonu, a dane zewnętrzne są przenoszone do tej kopii. Oczywiście wszystkie unikalne klucze wszystkich tak skopiowanych obiektów muszą zostać zmienione. Jeśli te atrybuty klucza są typu danych Guid, dzieje się to automatycznie. Wszystkie unikalne klucze wszystkich zaangażowanych obiektów biznesowych muszą zostać zmienione w kopii obiektu szablonu, albo automatycznie, albo za pomocą struktury zewnętrznej. W przeciwnym razie nieuchronnie wystąpiłby błąd DuplicateKeyViolation.
@Override
protected boolean registerExternalInformation(){
…
registerTemplateKey(Item.buildByNumberKey(„ABCDE”));
…
}
Jeśli podczas importu zostanie stwierdzone, że brakuje artykułu, który ma zostać zaimportowany, artykuł ABCDE zostanie użyty jako szablon. Należy organizacyjnie upewnić się, że artykuł ABCDE faktycznie istnieje. Technicznie tworzona jest kopia artykułu szablonowego. Obejmuje to wszystkie obiekty biznesowe podane w ObjectInfo.
Można również zarejestrować kilka obiektów szablonowych, a następnie samodzielnie zdecydować, którego z nich użyć w konkretnym przypadku. W tym celu należy zmienić następującą metodę protected InternalValueNode getTemplate(ExternalValueNode vn.
Jeśli zarejestrowano tylko jeden obiekt szablonu, nie jest to konieczne. W takim przypadku zawsze zostanie zwrócony ten jeden obiekt.
Jeśli nie zarejestruje się żadnego obiektu szablonu, system nie będzie mógł tworzyć nowych obiektów za pomocą importu. W takim przypadku w aplikacji Import uproszczony pojawi się odpowiedni komunikat ostrzegawczy.
FormatLookUp
Podobnie jak w klasycznym Business Integration Service (BIS), można zarejestrować FormatLookup dla atrybutu. Jest to przydatne, na przykład, gdy wyświetlanie wartości atrybutu zależy od używanego formatu pliku.
Standardowe rozwiązania
W obiekcie deweloperskim typu Obiekt zewnętrzny można zdefiniować rozwiązania. Obiekt zewnętrzny zawiera atrybut, który w rzeczywistości jest kluczem obcym. W obiekcie zewnętrznym, za pomocą relacji do obiektu biznesowego, można określić, skąd pochodzi klucz obcy oraz czy i jak ma zostać rozwiązany. Zazwyczaj klucz obcy to PrimaryKey obiektu docelowego. Jednak bardziej czytelny jest BusinessKey.
Jeśli zatem klucz nie może zostać rozwiązany, automatycznie sprawdzane jest następujące:
- Czy atrybut sam jest częścią klucza głównego?
- Czy atrybut jest typu danych guid?
- Czy w przypadku eksportu wartość jest równa ZEROGUID?
- Czy w przypadku importu wartością dla atrybutu BusinessKey jest pusty ciąg znaków lub null w pliku importu?
Zarówno w przypadku eksportu, jak i importu, konkretna instancja obiektu biznesowego Country nie ma znaczenia. Wymagane jest tylko rozwiązanie PrimaryKey na BusinessKey. Jeśli więc powyższe warunki są spełnione, rozwiązanie jest wykonywane wewnętrznie w pamięci, bez konkretnej instancji.
Jeśli występują przypadki odbiegające od tego wzorca, a mimo to ma nastąpić rozwiązanie klucza, można interweniować za pomocą rejestracji registerDefaultResolving.
Jako parametry należy podać obiekt zewnętrzny, zdefiniowaną w nim nazwę narzędzia do rozwiązywania kluczy obcych, wartość atrybutu klucza obcego oraz wartość rozwiązującą. Jeśli rekord danych odpowiada tym warunkom, do rozwiązania używana jest ta rejestracja.
W ten sposób można również zmienić opisane powyżej standardowe zachowanie.
@Override
protected boolean registerExternalInformation(){
…
registerDefaultResolving(ExternalItemCountryData.class, „country”,
Guid.ZEROGUID, „ZEROGUIDSTRING”);
…
}
W tym przypadku w obiekcie zewnętrznym ExternalItemCountryData zostanie obsłużone narzędzie do rozwiązywania kluczy obcych country. Jeśli konkretna wartość jest równa ZEROGUID, do eksportowanego pliku dla atrybutu rozwiązującego zostanie wpisana wartość ZEROGUIDSTRING.
W przypadku importu proces jest odwrotny: jeśli w importowanym pliku dla atrybutu rozwiązującego zostanie znaleziona wartość ZEROGUIDSTRING, zostanie przyjęta wartość ZEROGUID dla konkretnego atrybutu klucza obcego. W ten sposób zmienia się opisane powyżej standardowe zachowanie.
Dla bardziej złożonych kluczy istnieje druga sygnatura. W niej wartości są przekazywane jako dwie listy.
Ładowanie dodatkowych obiektów
Zaletą wydajnościową uproszczonej wymiany danych jest blokowe odczytywanie i zapisywanie danych. Jeśli konieczne jest przeprowadzenie kontroli spójności importowanych danych i w tym celu potrzebne są dane, które nie znajdują się w plikach importu, można w ten sposób zadbać o to, aby te dane również były odczytywane blokowo.
@Override
protected boolean registerExternalInformation(){
…
registerAdditionalObjectToBeLoaded(ItemAccountingData.class);
…
}
W tym przykładzie dane dotyczące zaopatrzenia są weryfikowane z danymi księgowymi. Jednocześnie dane księgowe nie są częścią importu. Warunkiem jest, aby żądany obiekt biznesowy był częścią ObjectInfo.
Technicznie ten rodzaj rejestracji nie jest konieczny, ale w pewnych okolicznościach można w ten sposób poprawić wydajność.
Kontrole
Implementując kontroler, użytkownik przejmuje odpowiedzialność za spójność importowanych danych. Niektóre czysto techniczne kontrole są przeprowadzane automatycznie. Jeśli zmieniane są istniejące dane poprzez import, unikalne klucze nie mogą być zmieniane.
Jeśli poprzez import zlecane jest systemowi utworzenie nowych danych, ma miejsce dokładnie odwrotna sytuacja. System automatycznie sprawdza, czy każdy unikalny klucz został zmieniony w stosunku do obiektu szablonu.
Dzięki zaimplementowaniu metod validateImport można przeprowadzić dodatkowe kontrole. Jeśli użytkownik wykryje błąd, może oznaczyć dane jako invalid.
Anulowanie lub kontynuacja
Dane są przetwarzane blokowo. Jeśli wśród importowanych danych zostaną znalezione błędne rekordy, są one zazwyczaj pomijane, a zapisywane są tylko poprawne dane.
Można jednak, zmieniając metodę handleImportErrors zdecydować, czy proces ma zostać przerwany, czy błędne rekordy mają zostać osobno zalogowane.
