Case jako dowolny obiekt

Info

Poniżej opis budowania obiektu sprawy jako dowolna definicja XML lub JSON. Postać ta jest wykorzystywana w usługach SOAP (metody z sufiksem XML w nazwie) oraz usługach REST (usługi z sufiksem ExtRest w nazwie).

ANY XML


Warstwy, w których użyty	Business
Rodzaj	Obiekt biznesowy
Interfejs Java	`org.w3c.dom.Document`
Interfejs DTO	`org.w3c.dom.Element`

ANY XML reprezentuje dowolną sprawę - wykorzystywany jest w usługach SOAP. Zadaniem systemu Mercury DB (HgDB) jest między innymi automatyczne identyfikowanie typu sprawy. Usługa biznesowa pozwala na zapis sprawy dowolnego typu przedstawionej za pomocą XML’a. Niezbędnym elementem reprezentacji obiektu sprawy jest istnienie pola mrcCaseHeader, którego typ został opisany w artykule poświęconemu nagłówkowi sprawy CaseHeader.

XML

Istnieją ograniczenia związane z stosowanym nazewnictwem pól obiektu np. pole w reprezentowanym przez sprawę obiekcie (prostym lub złożonym) nie może nazywać się mrcCaseHeader. W obiekcie (prostym lub złożonym) reprezentowanym przez sprawę może być maksymalnie 128 pól (tagów).

Poniżej prosty przykład argumentu do zapisu dowolnego typu sprawy za pomocą prostego XML’a:

Przykład sprawy w postaci XML
<caseXML>
 <testObjectWithoutAttrs>
  <mrcCaseHeader xmlns="http://business.dto.ws.hgdb.io/mrcObject" 
	  xsi:schemaLocation="http://business.dto.ws.hgdb.io/mrcObject http://hgdb.io/xsd/dto/hgdb-mrc-object-3.0.xsd" 
	  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <typeCode><![CDATA[TestObjectWithoutAttrs]]></typeCode>
    <status><![CDATA[A]]></status>
    <storeId><![CDATA[2003]]></storeId>
    <className><![CDATA[TestObjectWithoutAttrs]]></className>
    <dirty><![CDATA[true]]></dirty>
    <pkPropertyName><![CDATA[name]]></pkPropertyName>
  </mrcCaseHeader>
  <status><![CDATA[Aktywny]]></status>
  <name><![CDATA[Mistrz]]></name>
 </testObjectWithoutAttrs>
</caseXML>

W pokazanym przykładzie przesyłamy sprawę o następujących właściwościach:

Kod typu sprawy to: TestObjectWithoutAttrs
Nazwa typu sprawy to: TestObjectWithoutAttrs
Sprawa zostanie przypisana do magazynu o identyfikatorze 2003
Sprawa ma zdefiniowane pole unikalne o nazwie name
Sprawa reprezentuje obiekt prosty typu nazwanego jako TestObjectWithoutAttrs ma dwa pola o nazwach:
- status (wartość pola Aktywny)
- name (wartość pola Mistrz)

W wyniku wywołania usługi zapisującej otrzymamy przykładową reprezentację XML sprawy:

Przykład odpowiedzi w postaci XML
<variable type="TestObjectWithoutAttrs">
   <mrcCaseHeader type="MrcCaseHeader" version="1" xmlns="http://business.dto.ws.hgdb.io/mrcObject" 
	    xsi:schemaLocation="http://business.dto.ws.hgdb.io/mrcObject http://hgdb.io/xsd/dto/hgdb-mrc-object-3.0.xsd" 
	    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <caseId type="Integer">5012</caseId>
      <groupId type="Integer">2507</groupId>
      <typeId type="Integer">3008</typeId>
      <typeCode type="String">TestObjectWithoutAttrs</typeCode>
      <status type="String">A</status>
      <previousVersionId type="Integer">4511</previousVersionId>
      <priceValue type="Decimal">1000.0</priceValue>
      <storeCount type="Integer">1</storeCount>
      <storeId type="Integer">2003</storeId>
      <createDate isEncoded="false" type="Date">2017/06/26 17:34:09.150 CEST</createDate>
      <createdBy type="String">mateusz</createdBy>
      <lastModifyDate isEncoded="false" type="Date">2017/06/26 17:34:09.150 CEST</lastModifyDate>
      <lastModifiedBy type="String">mateusz</lastModifiedBy>
      <modifyComment type="String">SOAP request</modifyComment>
      <createdByRoleName type="String">CKBPM-Team</createdByRoleName>
      <lastModifiedByRoleName type="String">CKBPM-Team</lastModifiedByRoleName>
      <className type="String">TestObjectWithoutAttrs</className>
      <version type="String">3</version>
      <dirty type="Boolean">false</dirty>
      <pkPropertyName type="String">name</pkPropertyName>
   </mrcCaseHeader>
   <status id="1" isEncoded="false" position="1" type="String" version="1">Aktywny</status>
   <name id="2" isEncoded="false" position="2" type="String" version="1">Mistrz</name>
</variable>

Atrybuty tagów XML

Aby doprecyzować identyfikację typu sprawy podczas akcjhi jej zapisu/aktualizacji, rekomenduje się dodanie odpowiednich atrybutów do tag’ów, na podstawie których system będzie mógł zidentyfikować np. jakiego typu jest dane pole, czy też pozycja, na której to pole występuje w definicji typu sprawy. Poniżej lista atrybutów jakie można wykorzystać w definicji sprawy w formacie XML:

Atrybut	Opis	Typ	Wymagany	Dozwolone wartości
name	Nazwa pola (nazwa definicji pola). Jeżeli atrybut jest pusty wartość ta pobrana zostanie z nazwy tag’a XML. Reprezentacja pola `definitionName` w kluczu złożonym `ParamDefinitionPK` encji `ParamDefinition`.	`String`	Nie
version	Wersja definicji parametru składowana w bazie Mercury DB. Reprezentacja pola `version` w kluczu złożonym `ParamDefinitionPK` encji `ParamDefinition`.	`String`	Nie	Reprezentacja pola typu Integer. Wartości liczb całkowitych większych od zera
label	Rekomendowana etykieta pola prezentowana w wygenerowanym formularzu edycji (modyfikacji) sprawy. Jeżeli atrybut będzie pusty, etykieta przyjmie nazwę pola. Reprezentacja pola `recomendedLabel` encji `ParamDefinition`.	`String`	Nie
id	Identyfikator XML pola. Pole pozwalające na identyfikację pól o tych samych nazwach (tag’ach) w przesyłanym XML – nie dotyczy elementów list (kolekcji). Jeżeli nie zostanie podane, pole przyjmie wartość pozycji pola w XML. Reprezentacja pola `xmlId` w encji `TypeParam`.	`String`	Nie
isRequired	Czy pole ma być zidentyfikowane jako pole wymagane podczas późniejszej edycji – pole na potrzeby nie tylko generacji formularzy edycji danych sprawy danego typu. Reprezentacja pola `isRequired` w encji `TypeParam`.	`String`	Nie	Reprezentacja pola `Boolean`: `true` lub `false`
updateable	Czy pole może być aktualizowane/zmieniane? Reprezentacja pola `updateable` w encji `TypeParam`.	`String`	Nie	Dozwolana jedna z wartości: `READWRITE`, `READONLY`, `ONCREATE`, `ONCREATEVISIBLE`, `OTHER`
isEncoded	Czy pole jest zakodowane do postaci przechowywanej w bazie Mercury. Jeżeli pole ma wartość ostawioną na `false` oznacza, że wartość jest wartością prezentacyjną. Prosty przykład. Wartość pola typu Date w bazie Mercury jest przechowywana jako liczba milisekund. Jeżeli `isEncoded=”true”` to zostanie przesłana liczba, jeżeli `isEncoded=”false”`, to data sformatowana zgodnie z zadanym formatem w kontekście akcji.	`String`	Tak, jeżeli chcemy przesłać wartości, które wymagają dekodowania np. dla pól typu `Date`, `Currency`, `Lob`.	Reprezentacja pola `Boolean`: `true` lub `false`
position	Atrybut w XML definiujący pozycję pola. Reprezentacja pola ‘position’ w kluczu głównym `TypeParamPK` encji `TypeParam`.	`String`	Nie	Reprezentacja pola typu `Integer`. Wartości liczb całkowitych [1..128]
type	Nazwa typu pola sprawy. Odpowiednik pola `subType` w encji `ParamDefinition`. Dla typów pól, które są listą elementów, do nazwy typu rekomenduje się doklejenie sufiksu `[]` np. `Date[]`, `TestUser[]` itp. jednoznacznie wskazującego na to, że parametr jest listą.	`String`	Rekomendowany dla typów reprezentujących obiekty złożone to nazwy ich nazwy np. `TestUser`. Dla zdefiniowania typów prostych system jednoznacznie identyfikuje typy proste o nazwach: `Boolean`, `BooleanInteger`, `Text`, `String`, `Password`, `Number`, `Decimal`, `Currency`, `Integer`, `Date`, `DateLong`, `Time`, `Image`, `Document`, `URL`, `Lob`, `NameValuePair`. W przeciwnym razie nastąpi próba przekształcenia pola do typu `String`, a dla list (nazwa z sufiksem `[]`) do pola typu `Lob`

Przykład sprawy typu TestRole w postaci XML
<role>
 <mrcCaseHeader type="MrcCaseHeader" version="1" xmlns="http://business.dto.ws.hgdb.io/mrcObject" 
    xsi:schemaLocation="http://business.dto.ws.hgdb.io/mrcObject http://hgdb.io/xsd/dto/hgdb-mrc-object-3.0.xsd" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <groupId type="Integer"><![CDATA[2003]]></groupId>
    <typeCode type="String"><![CDATA[TestRole]]></typeCode>
    <status type="String"><![CDATA[A]]></status>
    <priceValue type="Decimal"><![CDATA[1000.0]]></priceValue>
    <storeCount type="Integer"><![CDATA[1]]></storeCount>
    <storeId type="Integer"><![CDATA[2003]]></storeId>
    <className type="String"><![CDATA[TestRole]]></className>
    <version type="String"><![CDATA[1]]></version>
    <dirty type="Boolean"><![CDATA[true]]></dirty>
    <pkPropertyName type="String"><![CDATA[name]]></pkPropertyName>
 </mrcCaseHeader>
 <status id="1" label="Status roli" type="String"><![CDATA[Aktywny]]></status>
 <name id="1" label="Nazwa roli" type="String"><![CDATA[Mistrz]]></name>
 <priv id="2" label="Uprawnienia do panelu administracji" type="String"><![CDATA[RW]]></priv>
 <priv id="3" label="Uprawnienia do portalu" type="String"><![CDATA[RO]]></priv>
 <users id="4" label="Lista uprawnionych" type="String[]">
   <item><![CDATA[slawas]]></item>
   <item><![CDATA[ttesteusz]]></item>
 </users>
</role>

Zwróćmy uwagę na dodatkowe dane przesłane do systemu Mercury DB (HgDB):

Zdefiniowane etykiety dla poszczególnych pól (atrybut label)
Zdefiniowane identyfikatory XML (atrybut id) dla pól o tych samych nazwach (w tym przypadku pole priv)
Zdefiniowane atrybuty opisujące typy poszczególnych pól.

ANY JSON


Warstwy, w których użyty	Business
Rodzaj	Obiekt biznesowy
Interfejs Java	`org.mercury.json.JSONObject`
Abstrakcja DTO	`com.fasterxml.jackson.databind.JsonNode`

ANY JSON reprezentuje dowolną sprawę - wykorzystywany jest w usługach REST. Niezbędnym elementem reprezentacji obiektu sprawy jest istnienie pola mrcCaseHeader, którego typ został opisany w artykule poświęconym nagłówkowi sprawy CaseHeader.

JSON

Zwróćmy uwagę, że format JSON jest znacznie uboższy do formatu XML. Ma to swoją zaletę, bo przesyłamy znacznie mniej danych. Ma to też wadę że nie możemy przesłać zbyt wiele informacji na temat zdefiniowanego typu.

Przykład sprawy w postaci JSON
{
  "mrcCaseHeader": {
    "caseId": 783695,
    "groupId": 300042,
    "typeId": 3509,
    "typeCode": "SlawasTestObj",
    "status": "A",
    "rootVersionId": 783695,
    "priceValue": 0,
    "storeCount": 1,
    "storeId": 1505,
    "createDate": "12-01-2019 03:14:12 +01:00",
    "createdBy": "slawas",
    "lastModifyDate": "12-01-2019 03:14:12 +01:00",
    "lastModifiedBy": "slawas",
    "modifyComment": "SOAP request",
    "createdByRoleName": "CKBPM-Team",
    "lastModifiedByRoleName": "CKBPM-Team",
    "className": "SlawasTestObj",
    "version": "1",
    "dirty": false,
    "pkPropertyName": "name"
  },
  "status": "Aktywny",
  "name": "aatest",
  "priv": "RO",
  "users": [
    "slawa1233",
    "slawas2",
    "slawas3",
    "slawas4",
    "ttest2345"
  ]
}

ANY XML​

Atrybuty tagów XML​

ANY JSON​

ANY XML

Atrybuty tagów XML

ANY JSON