...

Na obrázku je uvedená definícia štruktúry SD.Person, ktorá poslúži ako príklad. Nasleduje mapovanie definície štruktúry na triedu Person.

Image Modified

Blok kódu

language	java
theme	Eclipse

import sk.ipesoft.d2000.d2japi.annotations.UnivalAttributeType;
import sk.ipesoft.d2000.d2japi.annotations.UnivalConvertor;
import sk.ipesoft.d2000.d2japi.annotations.structureBinding.ColumnAttribute;
import sk.ipesoft.d2000.d2japi.annotations.structureBinding.ColumnValue;
import sk.ipesoft.d2000.d2japi.annotations.structureBinding.ConvertedColumnValue;
import sk.ipesoft.d2000.d2japi.annotations.structureBinding.MulticonvertedColumnValue;
import sk.ipesoft.d2000.d2japi.annotations.structureBinding.StructureDefinition;
import sk.ipesoft.d2000.d2japi.sharedResources.ConversionResult;
import sk.ipesoft.d2000.datatable.ColumnType;

@StructureDefinition(name = "SD.Person")
public class Person {
	private ConversionResult convertedName;
	private Integer id;
	private List<ConversionResult> multiConvertedName;
	private String name;
	private Long nameTime;

	public Person() {
		this.id = null;
		this.name = null;
		this.nameTime = 0L;
		this.convertedName = null;
		this.multiConvertedName = Collections.emptyList();
	}

	public Person(Integer id, String name, Long nameTime) {
		this.setId(id);
		this.setName(name);
		this.setNameTime(nameTime);
	}

	public ConversionResult getConvertedName() {
		return convertedName;
	}

	@ConvertedColumnValue(name = "Name")
	public void setConvertedName(ConversionResult convertedName) {
		this.convertedName = convertedName;
	}

	@ColumnValue(name = "Id", columnType = ColumnType.integer)
	public Integer getId() {
		return id;
	}

	public final void setId(Integer id) {
		this.id = id;
	}

	public List<ConversionResult> getMultiConvertedName() {
		return multiConvertedName;
	}

	@MulticonvertedColumnValue(name = "Name")
	public void setMultiConvertedName(List<ConversionResult> multiConvertedName) {
		this.multiConvertedName = multiConvertedName;
	}

	@ColumnValue(name = "Name", columnType = ColumnType.text)
	public String getName() {
		return name;
	}


    public final void setName(String name) {
		this.name = name;
	}

	@ColumnAttribute(name = "Name", attribute = UnivalAttributeType.valueTime)
	public Long getNameTime() {
		return nameTime;
	}

	public final void setNameTime(Long nameTime) {
		if (nameTime == null) {
			throw new NullPointerException("nameTime is null");
		}
		this.nameTime = nameTime;
	}
}

...

Všimnite si, že trieda Person neobsahuje mapovanie buniek stĺpca Active. Pri mapovaní štruktúrovaných unival hodnôt je mapovanie jednotlivých stĺpcov nepovinné. Pri mapovaní z unival u sú hodnoty bez mapovania ignorované. Pri mapovaní do univalu sú hodnoty bez mapovania nahradené neplatnými hodnotami. Chýbajúce časové značky sú doplnené aktuálnym časom.

Kotva
_Toc490141255
_Toc490141255
4.2.2. Priame použitie triedy UnivalConvertor pre využitie mapovania

So štruktúrovanými hodnotami sa v prostredí JAPI stretávame na dvoch miestach – parametre RPC volaní a hodnoty objektov typu štruktúrovaná premenná. Ak sú pre RPC použité pokročilé anotácie, štruktúrované hodnoty sú konvertované podľa mapovania automaticky. Inak je možné konvertovať medzi typom UnivalRecord a mapovanou triedou ručne, za pomoci objektu triedy UnivalConvertor.

Každá inštancia triedy UnivalConvertor (v nasledujúcej kapitole označovaná ako convertor) potrebuje pre svoju prácu aktuálne informácie o definíciách štruktúr, ktoré pripojený JConnector sprístupňuje objektom typu D2StructureDefinitionResolver. Na väčšinu praktických úloh je plne vyhovujúci tzv. defaultUnivalConvertor.

Blok kódu

language	java
theme	Eclipse

UnivalConvertor convertor = session.getConnector().getDefaultUnivalConvertor();

V prípade, že by bolo žiaduce pracovať s viacerými rôznymi inštanciami, pričom každá z inštancií by poznala len vybrané mapovania, je možné získať novú inštanciu nasledovným spôsobom:

Blok kódu

language	java
theme	Eclipse

UnivalConvertor convertor = session.getConnector().createUnivalConvertor();

Z optimalizačných dôvodov je možné vykonať registráciu mapovacích tried ručne, v inicializačnej časti aplikácie, pred prvým skutočným konvertovaním štruktúrovaných hodnôt. V tomto kroku dochádza k analýze a vyhodnoteniu správnosti použitia mapovacích anotácií. Mapovanie však nie je kontrolované voči aktuálnej definícii štruktúry v systéme D2000.

Blok kódu

language	java
theme	Eclipse

convertor.registerStructure(Person.class);

Explicitná registrácia je však nepovinná, convertor ju v prípade potreby vykoná automaticky, pred prvou konverziou štruktúrovanej hodnoty.

Blok kódu

language	java
theme	Eclipse

List<Vector> list = convertor.decodeStructure(record, Vector.class);

...


UnivalRecord<?, ?, ?> data = convertor.encodeStructure(list, Vector.class);

Formátovanie hodnôt jednotlivých buniek pre zobrazenie na používateľskom rozhraní v konkrétnom jazku je možné vykonať po dekódovaní hodnôt následným volaním:

Blok kódu

language	java
theme	Eclipse

Convertor dictionaryConvertor = session.createDictionaryConvertor();

...


convertor.fillConvertedValues(list, Person.class, dictionaryConvertor);

Alebo pre konverziu do všetkých jazykov:
List<Convertor> dictionaryConvertors = new

Blok kódu

language	java
theme	Eclipse

List<Convertor> dictionaryConvertors = new ArrayList<>();

...


for (DictionaryLanguage language : session.getConnector()

...


                                  .getSharedResourcesCache().getDictionaryLanguages())

...


    dictionaryConvertors.add(

...


        session.getConnector().createDictionaryConvertor(language.getIndex()));

...


convertor.fillMulticonvertedValues(list, Person.class, dictionaryConvertors);

Kotva
_Ref442078467
_Ref442078467
Kotva
_Toc490141256
_Toc490141256
4.3. Definícia mapovania RPC volaní

Podľa rôznych kategórií je možné RPC volania deliť nasledovne.

Podľa toho, kto je volajúci a kto volaný:

...

S využitím JAPI knižnice je možné vytvárať odchádzajúce RPC aj prijímať prichádzajúce RPC. Spôsob realizácie je však pomerne odlišný, preto je každej kategórii venovaná samostatná kapitola.

Podľa toho, či sa čaká na výsledok volania:

...

V prostredí ESL a v prostredí internej Javy je synchrónne aj asynchrónne RPC nasmerované do tej istej procedúry (metódy). Spôsob volania vyberá volajúci na základe dohody, lebo volaný kód toto nevie ovplyvniť ani zistiť. V prostredí JAPI je vo volanom kóde RPC vidieť, či bol zavolaný synchrónne alebo asynchrónne. Pokročilými anotáciami sa dokonca dVolajúci okonca volaný kód označí tak, aby spracúval iba jeden konkrétny z dvoch typov volania.

Kotva
_Toc490141257
_Toc490141257
4.3.1. Zoznam parametrov pre volanie RPC

Volanie RPC je systémom D2000 prenášané ako správa zložená z viacerých častí:

adresa volajúceho
- HOBJ procesu (proces typu Event Handler, HI, Session),
- dynamické HOBJ vykonávaného objektu (objekt typu Event, Schéma alebo 0 ak je volajúci Session),
- príznak, či RPC volanie pochádza z prostredia interného Java run-time,
adresa volaného
- HOBJ procesu (proces typu Event Handler, HI, Session),
- HOBJ vykonávaného objektu (objekt typu Event, Schéma alebo 0 ak je volajúci Session),
- príznak, či RPC volanie smeruje do prostredia interného Java run-time,
- číslo inštancie vykonávaného objektu (ak ide o „inštančne" vytvorený Event alebo Schému a HOBJ objektu bolo bázové, inak 0),
identifikátor volanej RPC
- meno
- HOBJ objektu ESL Interface, ak ide o implementáciu RPC definovanej v ESL Interface, inak 0,
hodnoty parametrov volania,
príznak, či ide o synchrónne Volajúci čaká na dokončenie vykonávania RPC a môže tak získať návratové hodnoty parametrov. alebo asynchrónne Volajúci pokračuje vo vykonávaní hneď po odoslaní správy a nemá žiadnu spätnú väzbu o vykonaní. volanie⁵ alebo asynchrónne⁶ volanie.

Klasický spôsob volania RPC prostredníctvom JAPI vyžadoval, aby volajúci pri každom volaní uviedol všetky položky okrem adresy volajúceho (ktorú doplnil D2Connector). Nevýhodou tohto prístupu je predovšetkým chýbajúca typová kontrola hodnôt parametrov volania ako aj ich prácne vytváranie. Nepohodlná je tiež nutnosť ručne získať a ukladať HOBJ objektov a procesov.

Kotva
_Ref441663211
_Ref441663211
Kotva
_Toc490141258
_Toc490141258
4.3.2. Volanie z JAPI do ESL – príklad s komentármi

...

unmigrated-wiki-markup

Blok kódu

language	esl
theme	RDark

RPC PROCEDURE Parse(IN TEXT _text, INT _result)
  _result := %StrToI(_text)
END Parse
\\
\\
RPC PROCEDURE Square(REAL _value)
  _value := _value * _value
END Square
\\
\\
RPC PROCEDURE Redim(IN INT _n, RECORD NOALIAS(SD.Person) _data)
  REDIM _data\[_n\]
END Redim
\\
\\
RPC PROCEDURE SetValue(IN TIME _value)
  U.Value := _value TIME _value\TIM
END SetValue
\\
\\
RPC PROCEDURE GetDataAndMetadata(RECORD NOALIAS(SD.Person) _data,RECORD NOALIAS(
                                 RECORD NOALIAS(SD.Metadata) _metadata)
  ...
END Redim
\\
\\
BEGIN
END

Uvedený

...

ESL

...

kód

...

predstavuje

...

zdrojový

...

kód

...

server

...

event-u

...

E.Service,

...

ktorého

...

rodič

...

je

...

proces

...

SELF.EVH.

...

Väčšina

...

procedúr

...

má

...

pre

...

ilustratívnosť

...

implementované

...

jednoduché

...

telo.

...

RPC

...

GetDataAndMetadata

...

telo

...

nemá,

...

pretože

...

by

...

bolo

...

príliš

...

zložité.

...

Ilustruje

...

však

...

príklad

...

procedúry,

...

ktorá

...

má

...

viac

...

ako

...

jeden

...

výstupný

...

parameter⁷ .

V nasledujúcich podkapitolách bude postupne po častiach uvedený zdrojový kód, ktorý by za normálnych okolností tvoril jeden súbor.

4.3.2.1 Jednoduché mapovanie vstupného a výstupného parametra

Blok kódu

language	java
theme	Eclipse

import java.util.Date;

...


import java.util.List;

...


import sk.ipesoft.d2000.d2japi.annotations.InOut;

...


import sk.ipesoft.d2000.d2japi.annotations.ParameterDirectionType;

...


import sk.ipesoft.d2000.d2japi.annotations.ParameterType;

...


import sk.ipesoft.d2000.d2japi.annotations.UnivalAttributeType;

...


import sk.ipesoft.d2000.d2japi.annotations.eventBinding.Event;

...


import sk.ipesoft.d2000.d2japi.annotations.eventBinding.Parameter;

...


import sk.ipesoft.d2000.d2japi.annotations.eventBinding.ParameterAttribute;

...


import sk.ipesoft.d2000.d2japi.annotations.eventBinding.ParameterValue;

...


import sk.ipesoft.d2000.d2japi.annotations.eventBinding.RPC;

...


import sk.ipesoft.d2000.d2japi.annotations.eventBinding.ReturnValue;

...




@Event(name = "E.Service")

...


public interface Service

...


	@RPC(name = "Parse",

...


		asynchronous = false,

...


		parameters =

...


		{
			@Parameter(name = "value", type = ParameterType.text, inOut = false),

...


			@Parameter(name = "result", type = ParameterType.integer, inOut = true)

...

})

...


	@ReturnValue(name = "result")

...


	public Integer parse(

...


		@ParameterValue(name = "value") String value);

...

Anotácia @Event indikuje, že rozhranie Service slúži na mapovanie RPC volaní z JAPI. Nepovinný parameter name v tomto prípade indikuje, že je mapovaný objekt E.Service.

Rozhranie má jednu metódu – parse. Anotácia @RPC na tejto metóde indikuje, že volanie tejto metódy má byť premenené na odchádzajúce RPC volanie. Parametre anotácie majú nasledovný význam:

name = "Parse"  ➔ definuje identifikátor volanej RPC, ktorý musí byť zhodný s identifikátorom v ESL.
asynchronous = false  definuje ➔ definuje, že volanie má prebehnúť synchrónne a teda, že sa po zavolaní má počkať na výsledok.
parameters = {...  definuje ➔ definuje zoznam „formálnych" parametrov RPC. Tento zoznam musí v presnom poradí uvádzať, aké parametre sú v ESL deklarované.
- name  lokálna name ➔ lokálna identifikácia parametra. Tento identifikátor sa môže líšiť s názvom parametra v ESL, lebo rozsah platnosti tohto identifikátora je len v rámci mapovania tejto RPC. (Odkazujú sa naň ďalšie anotácie, ale inde sa nepoužíva.)
- type  deklarovaný type ➔ deklarovaný typ hodnoty parametra.
- inOut inOut = false, resp. inOut = true  indikuje ➔ indikuje, či je parameter deklarovaný ako vstupný (v ESL je pred typom kľúčové slovo IN) alebo vstupno-výstupný a teda jeho výsledná hodnota bude prenesená naspäť.

Anotácia @ReturnValue slúži na previazanie návratovej hodnoty metódy s návratovou hodnotou niektorého z parametrov. Parameter anotácie name = "result" indikuje, že to má byť návratová hodnota 2. parametra zo zoznamu formálnych parametrov kvôli zhode v identifikátoroch. Typ návratovej hodnoty Integer zodpovedá typu formálneho parametra podľa tabuľky v kapitole 54.1.1. Dôležitou podmienkou je, aby bol formálny parameter označený ako vstupno-výstupný.

Anotácia 1. parametra metódy @ParameterValue indikuje, že hodnota tohto parametra má byť premenená na vstupnú hodnotu 1. formálneho parametra (podľa parametra anotácie name = "value"). Typ hodnoty String zodpovedá typu formálneho parametra podľa tabuľky v kapitole 5.1.1.
Zaujímavý je tiež fakt, že pre 2. formálny parameter (result) nie je definované mapovanie vstupnej hodnoty. V takomto prípade je pri volaní RPC procedúry nastavený 2. parameter na neplatnú (invalidnú) hodnotu.

...

Kotva

	4
	4

⁴Podľa konvencie JavaBeans tvoria metódy getName a setName spolu property Name.

Kotva

	5
	5

⁵Volajúci čaká na dokončenie vykonávania RPC a môže tak získať návratové hodnoty parametrov.

Kotva

	6
	6

⁶ Volajúci pokračuje vo vykonávaní hneď po odoslaní správy a nemá žiadnu spätnú väzbu o vykonaní.

Kotva

	7
	7

⁷ Rovnako v dokumente neuvádzame definíciu a mapovanie pre SD.Metadata, lebo nie je potrebné.

Strom stránky

Porovnávané verzie

Stará verzia 4

Nová verzia 5

Kľúč

Kotva
_Toc490141255
_Toc490141255
4.2.2. Priame použitie triedy UnivalConvertor pre využitie mapovania

Kotva
_Ref442078467
_Ref442078467
Kotva
_Toc490141256
_Toc490141256
4.3. Definícia mapovania RPC volaní

Kotva
_Toc490141257
_Toc490141257
4.3.1. Zoznam parametrov pre volanie RPC

Kotva
_Ref441663211
_Ref441663211
Kotva
_Toc490141258
_Toc490141258
4.3.2. Volanie z JAPI do ESL – príklad s komentármi

4.3.2.1 Jednoduché mapovanie vstupného a výstupného parametra

Strom stránky

História stránky

Porovnávané verzie

Stará verzia 4

Nová verzia 5

Kľúč

Kotva_Toc490141255_Toc4901412554.2.2. Priame použitie triedy UnivalConvertor pre využitie mapovania

Kotva_Ref442078467_Ref442078467 Kotva_Toc490141256_Toc4901412564.3. Definícia mapovania RPC volaní

Kotva_Toc490141257_Toc4901412574.3.1. Zoznam parametrov pre volanie RPC

Kotva_Ref441663211_Ref441663211 Kotva_Toc490141258_Toc4901412584.3.2. Volanie z JAPI do ESL – príklad s komentármi

4.3.2.1 Jednoduché mapovanie vstupného a výstupného parametra

Kotva
_Toc490141255
_Toc490141255
4.2.2. Priame použitie triedy UnivalConvertor pre využitie mapovania

Kotva
_Ref442078467
_Ref442078467
Kotva
_Toc490141256
_Toc490141256
4.3. Definícia mapovania RPC volaní

Kotva
_Toc490141257
_Toc490141257
4.3.1. Zoznam parametrov pre volanie RPC

Kotva
_Ref441663211
_Ref441663211
Kotva
_Toc490141258
_Toc490141258
4.3.2. Volanie z JAPI do ESL – príklad s komentármi