Komunikacja między obiektami biznesowymi - API biznesowe

Tworząc nowe rozwiązanie biznesowe jako developerzy powinniśmy pomyśleć o reużywalności naszego kodu. Warto w taki sposób pisać kod biznesowy, aby najważniejsze operacje logiki biznesowej udostępniać na zewnątrz obiektu. Np. tworząc kartotekę klientów warto udostępnić metodę do dodawania nowego klienta lub weryfikacji czy klient o konkretnym ID jest aktywny w naszej kartotece. Innym przykładem może być projekt WORKFLOW gdzie w swoim "zewnętrznym API" udostępnia możliwość dodawania nowego zadania praktycznie z każdego miejsca w systemie. Takie podejście znacznie ułatwia nam integrację między projektami Neosowymi, jak również wystawianie interfejsu webowego WebApi.

W technologii NEOS do utworzenia API obiektu biznesowego wykorzystujemy statyczne publiczne metody logiki biznesowej. Metody te mogą przyjmować dowolną ilość parametrów i wykonywać zaawansowane algorytmy biznesowe. Dzięki temu, że metody są statyczne mamy do nich dostęp z innych obiektów bez konieczności tworzenia instancji takiego obiektu. Ponadto wystarczy dodać projekt do listy referencji w innym projekcie NEOSowym aby uzyskać dostęp do API wszystkich obiektów biznesowych. Takie podejście znacznie ułatwia i przyspiesza tworzenie projektów biznesowych.

Przykład wywołania metody API w tym samym projekcie

Projekt SZKOLENIE zawiera obiekt towary, który posiada statyczną metodę logiki biznesowej do zmiany aktywności towaru o wskazanym kodzie towarowo magazynowym. Programista przygotowując taką funkcjonalność pamiętał o wystawianiu API biznesowego dla obiektów i uznał, że taka funkcjonalność będzie wykorzystywana w innych projektach.

Tworząc metody statyczne logiki biznesowej, które będą możliwe do wykorzystania jako API biznesowe warto pamiętać o walidacji parametrów wejściowych. Unikamy niepotrzebnych wywołań kodu np. dla pustych wartości parametrów wejściowych. Ponadto pamiętajmy, że wszystkie odwołania do bazy danych w ramach jednej metody logiki biznesowej będą realizowane w tej samej transakcji.

Tak przygotowaną metodę możemy wywoływać praktycznie z dowolnego miejsca w ramach tego samego projektu. Poniżej przykład wywołania.

Namespace LOGIC zawiera wszystkie obiekty biznesowe z tego samego projektu które mają co najmniej jedną metodę logiki biznesowej (i bez tego obiekt będzie dostępny z standardowymi metodami). Dzięki takiemu rozwiązaniu inny developer w łatwy sposób może zidentyfikować, że wywołujemy metodę API obiektu biznesowego TOWARY.

Przykład wywołania metody API w innym projekcie

Metody biznesowego API możemy wywoływać w innym projekcie, który posiada na liście referencji projekt z którego chcemy wywołać metodę. Posiadamy projekt SZKOLENIE w którym znajduje się obiekt TOWARY a on posiada znaną nam metodę biznesowego API ChangeStateKTM. Projekt SZKOLENIE2 posiada referencję na projekt SZKOLENIE. Dzięki takiemu rozwiązaniu w projekcie SZKOLENIE2 uzyskujemy dostęp do metody API logiki biznesowej w obiekcie TOWARY.

Przykład wywołania metody biznesowego API z projektu SZKOLENIE w projekcie SZKOLENIE2. Wywołanie to różni się od poprzedniego dodaniem nazwy projektu z którego chcemy wywołać metodę. Należy pamiętać, że dostęp do obiektów z innych projektów w poniższy sposób jest możliwy tylko po dodaniu referencji na inny projekt.

Przykład wywołania metody API w projekcie bez dodawania referencji

Czasem możemy potrzebować wywołać metodę API biznesowego z innego projektu, jednak nie możemy dodać tego projektu do listy referencji. Brak możliwości dodania do listy referencji projektu pojawia się przy bardziej rozbudowanych projektach, gdzie po dodaniu projektu mamy efekt "zapętlenia zależności". Najprostszym sposobem na uzyskanie takiego stanu jest dwukierunkowe wskazanie referencji. Czyli projekt B ma na liście referencji projekt A a następnie do projektu A dodamy na listę referencji projekt B. Takie rozwiązanie jest niedopuszczalne gdyż prowadzi do zapętlenia serwera. Jednak i z tym przypadkiem możemy sobie poradzić w następujący sposób.

Za pomocą API.InvokeStaticMethod możemy podać nazwę projektu wraz z nazwą obiektu z którego chcemy wywołać metodę API biznesowego. Następnie podajemy nazwę metody do wywołania. Aby przekazać parametry wejściowe do metody mamy 2 sposoby. Jeden z nich to przekazanie parametrów w stringu w następujący sposób: "parametr1=wartość;parametr2=wartość". Drugi sposób to przekazanie tablicy obiektów. Metoda ta jest dobrze udokumentowana w intellisense.

Warto pamiętać, że sposób z wykorzystaniem API.InvokeStaticMetod daje możliwości wykonywania metod statycznych z dowolnego obiektu, bez konieczności dodawania referencji do projektu, jednak posiada kilka wad:

• Nie pilnuje spójności projektów, tzn. po zmianie nazwy metody lub ilości parametrów wejściowych projekt skompiluje się prawidłowo jednak przy próbie wywołania takiej metody otrzymamy błąd w runtime-ie.

• Wywołanie metod jest minimalnie wolniejsze od klasycznego wywołania metody.

Zwracanie wielu zmiennych z metod logiki biznesowych

Czasem zachodzi potrzeba zwrócenia więcej niż jednej zmiennej z metod logiki biznesowej. Jeśli potrzebujemy zwrócić wartość logiczną (true, false) lub jakiś ciąg tekstu to wystarczy zadeklarować odpowiedni typ prosty w sygnaturze metody. Natomiast gdy musimy zwrócić wiele wartości lub np. listę elementów to należy utworzyć nową strukturę danych.

Aby dodać własną klasę modelu należy w edytorze kodu NEOSa wybrać przycisk Funkcje -> Dodaj strukturę danych. Następnie wybieramy pola, które potrzebujemy zwrócić z naszej metody logiki biznesowej. Po wygenerowaniu nowej struktury zobaczymy kod klasy z wybranymi polami. Może to wyglądać np. tak:

Gdy struktura danych jest odpowiednio wygenerowana możemy przejść do tworzenia metody logiki biznesowej. Chcemy napisać metodę logiki biznesowej, która zwróci nam podstawowe informacje tylko o aktywnych towarach. Przykład takiej implementacji można zobaczyć poniżej:

Spoglądając na powyższą metodę widzimy, że jest ona publiczna i zwraca listę obiektów modelu klasy Towar. Następnie wykonujemy zapytanie i iterujemy po wynikach tego zapytania. W pętli tworzymy nowy obiekt klasy Towar i odpowiednio ustawiamy pola naszego obiektu. Następnie dodajemy taki obiekt do wcześniej utworzonej listy. Po zakończeniu pętli foreach zwracamy utworzoną listę.

Analogicznie możemy w taki sposób przekazywać obiekt do metody zamiast np. 30 parametrów, które są wymagane. Ponadto praca na obiektach modelu umożliwia w łatwy sposób wystawienie web serwisów, które przyjmują i zwracają model serializowany do XML'a czy JSON'a.