Obsah

Vo verzii 10.1.39-build4 pribudla do knižnice JAPI možnosť aplikačne definovať objekty, ktoré výrazným spôsobom prispievajú k typovo bezpečnej komunikácii pri RPC volaniach. Balíček sk.ipesoft.d2000.d2japi.annotations obsahuje triedy a anotácie pre definovanie mapovania.

Obidve časti využívajú princípy mapovania D2000 Unival-u popísané v nasledujúcej časti.

Kotva
_Toc490141250
_Toc490141250
4.1. Mapovanie typu D2000 Unival

Transformácie hodnôt typu unival na základné Java typy a späť je jedným zo základných kameňov pokročilého mapovania.

Unival hodnota je kompozitná, skladá sa z hodnoty a viacerých atribútov. V mnohých prípadoch je však zaujímavá len hodnota samotná, prípadne indikátor jej platnosti, ale len málokedy ďalšie atribúty. Hodnota a jednotlivé atribúty sa preto mapujú na objekty základných Java typov každý zvlášť.

Kotva
_Ref441562165
_Ref441562165
Kotva
_Toc490141251
_Toc490141251
4.1.1 Mapovanie hodnoty a platnosti hodnoty unival-u

Atribút platnosť hodnoty a hodnota samotná sú vzájomne veľmi silne previazané. Unival buď obsahuje platnú hodnotu, alebo má hodnotu neplatnú a vtedy sa správa, ako keby hodnotu vôbec nemal. Z toho dôvodu sú hodnota a atribút platnosť hodnoty mapované spoločne na objektové typy. Napríklad celočíselná hodnota je mapovaná typom Integer. Ak je hodnota unival-u platná, mapuje sa na hodnotu, ak je neplatná, mapuje sa ako null.

...

D2000 typ	Java typ
Logický (`BOOL`)	VBool, Boolean^{4 Anotácie JAPI pre pokročilé mapovanie na objekty D2000}¹
Celočíselný (`INT`)	Integer
Reálny (`REAL`)	Double
Absolútny čas (`TIME`)	Date, Long^{4 Anotácie JAPI pre pokročilé mapovanie na objekty D2000}²
Relatívny čas (`REAL`)	Double
Text (`TEXT`)	String
Štruktúrovaný (`RECORD`)	List<T>^{4 Anotácie JAPI pre pokročilé mapovanie na objekty D2000}³

Kotva
_Toc490141252
_Toc490141252
4.1.2. Mapovanie unival atribútu

Pre mapovanie unival atribútov slúžia anotácie ParameterAttribute, ReturnAttribute, ColumnAttribute. Ich spoločným znakom je, že sú parametrizované typom unival atribútu, na ktorý definujú väzbu. Rovnako ako hodnota unival-u, aj atribúty sú mapované výlučne na objektové typy. Avšak pokus o transformáciu prázdneho odkazu (null) na hodnotu unival atribútu je vyhodnotený ako chyba. Nasledujúca tabuľka obsahuje zoznam podporovaných transformácií:

...

Zoznam podporovaných atribútov je krátky, obsahuje len mapovania, ktoré boli doteraz potrebné. V budúcnosti bude tento zoznam rozšírený na požiadanie.

Kotva
_Ref442078508
_Ref442078508
Kotva
_Toc490141253
_Toc490141253
4.2. Mapovanie štruktúrovaných Unival hodnôt

Štruktúrované Unival hodnoty sú štandardným spôsobom reprezentované typom UnivalRecord, ktorého hodnotová časť obsahuje objekt typu sk.ipesoft.d2000.datatable.Table. Pre mnohé aplikácie je však výhodnejšie pracovať s jednoduchšou reprezentáciou, v ktorej je štruktúrovaná hodnota reprezentovaná objektom typu java.util.List, ktorého prvky reprezentujú jednotlivé riadky. V jednom zozname sú všetky prvky objektmi tej istej aplikačne definovanej triedy, ktorá je anotáciami mapovaná na bunky štruktúrovanej hodnoty.

Kotva
_Ref441569011
_Ref441569011
Kotva
_Toc490141254
_Toc490141254
4.2.1. Príklad s vysvetlivkami

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;
	}
}

Trieda Person je anotáciou @StructureDefinition označená pre mapovanie štruktúrovanej hodnoty. Hodnota atribútu anotácie name indikuje väzbu na objekt SD.Person.

Anotácia @ColumnValue na metóde getName indikuje, že metóda slúži ako getter hodnoty v bunke stĺpca Name (podľa atribútu anotácie name = "Name") a že sú hodnoty v tomto stĺpci textového typu (podľa atribútu anotácie columnType = ColumnType.text). JAPI bude pri spracovaní tejto anotácie vyžadovať prítomnosť setter metódy Trieda Person je anotáciou @StructureDefinition označená pre mapovanie štruktúrovanej hodnoty. Hodnota atribútu anotácie name indikuje väzbu na objekt SD.Person.
Anotácia @ColumnValue na metóde getName indikuje, že metóda slúži ako getter hodnoty v bunke stĺpca Name (podľa atribútu anotácie name = "Name") a že sú hodnoty v tomto stĺpci textového typu (podľa atribútu anotácie columnType = ColumnType.text). JAPI bude pri spracovaní tejto anotácie vyžadovať prítomnosť setter metódy setName a tiež bude očakávať, že property Name Podľa konvencie JavaBeans tvoria metódy getName a setName spolu property Name. je ⁴ je typu String. Obdobným spôsobom funguje anotácia @ColumnValue na metóde getId.

Anotácia @ColumnAttribute na metóde getNameTime indikuje, že metóda slúži ako getter časovej značky hodnoty (podľa atribútu anotácie attribute = UnivalAttributeType.valueTime) v bunke stĺpca Name (podľa atribútu anotácie name = "Name"). JAPI bude pri spracovaní tejto anotácie vyžadovať prítomnosť setter metódy setNameTime a tiež bude očakávať, že property NameTime Podľa konvencie JavaBeans tvoria metódy getName a setName spolu property Name. je ⁴ je typu Date alebo Long. Pri konverzii na unival by bolo považované za chybu, ak by bola hodnota NameTime rovná null, preto metóda setNameTime takúto hodnotu odmietne nastaviť.

Anotácia @ConvertedColumnValue na metóde setConvertedName indikuje, že metóda slúži ako setter formátovanej hodnoty v bunke stĺpca Name. Ide o formátovanie hodnoty pre zobrazenie na používateľskom rozhraní.

Anotácia @MulticonvertedColumnValue na metóde setMultiConvertedName indikuje, že metóda slúži ako setter formátovanej hodnoty v bunke stĺpca Name pre všetky dostupné jazykové mutácie.

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:

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(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 5 4.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 5v kapitole 4.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.

4.3.2.2. Mapovanie vstupno-výstupného parametra

Blok kódu

language	java
theme	Eclipse

@RPC(name = "Square",

...


	parameters =

...


	{
		@Parameter(name = "v", type = ParameterType.real)

...

})

...


@ReturnValue(name = "v")

...


public Double sqare_1(

...


	@ParameterValue(name = "v") Double value);

...




@RPC(name = "Square",

...


	parameters =

...


	{
		@Parameter(name = "v", type = ParameterType.real)

...

})

...


public void sqare_2(

...


	@ParameterValue(name = "v") InOut<Double> value);

Metódy square_1 a square a square_2 mapujú obidve tú istú RPC (je to dovolené). V porovnaní s predošlým príkladom je však niekoľko odlišností v použití anotácie @RPC a @Parameter:

parameter RPC.asynchronous nie je uvedený, lebo je nepovinný a v takom prípade nadobúda automaticky hodnotu false.
parameter Parameter.inOut nie je uvedený, lebo je nepovinný a v takom prípade nadobúda automaticky hodnotu true.

Metódy square_1 a square a square_2 sa vzájomne odlišujú spôsobom, akým mapujú parameter volania:

square_1 rozdeľuje vstupnú a výstupnú časť parametra RPC procedúry na vstupný parameter a návratovú hodnotu metódy.
square_2 ponecháva vstupnú aj výstupnú časť parametra RPC procedúry v parametri metódy. Pretože Java ako jazyk nemá vstupno-výstupné parametre, parameter metódy value je deklarovaný s typom InOut<Double>.

Knižnica JAPI použije parameter metódy ako vstupno-výstupný (pri volaní prečíta jeho vstupnú hodnotu a po skončení nastaví jeho výstupnú hodnotu) vtedy, ak sú splnené nasledovné podmienky.

formálny parameter RPC procedúry je definovaný ako vstupno-výstupný
parameter metódy je deklarovaný s typom InOut<>. Generický parameter typu musí zodpovedať typu formálneho parametra.
nepovinný parameter anotácie @ParameterValue.direction nebol uvedený, čiže automaticky nadobudol hodnotu ParameterDirectionType.derived. (Rovnaké správanie by bolo dosiahnuté, keby bol explicitne nastavený na hodnotu derived alebo inout.)

4.3.2.3. Mapovanie synchrónnej procedúry s odloženým vyhodnotením výsledku

...

Blok kódu

language	java
theme	Eclipse

RPC(name = "Square",

...


	parameters =

...


	{
		@Parameter(name = "v", type = ParameterType.real)

...

})

...


@ReturnValue(name = "v")

...


public Future<Double> sqare_3(

...


	@ParameterValue(name = "v") Double value);

Metóda square_3 sa od metódy square_1 odlišuje typom návratovej hodnoty. Keď je typ návratovej hodnoty deklarovaný ako Future, volanie metódy nie je blokujúce, tak ako pri bežnej synchrónnej RPC, ale skončí hneď. Výsledok je uložený vo Future objekte, ktorého .get() metóda zabezpečí synchrónnosť volania.zabezpečí synchrónnosť volania.

4.3.2.4. Mapovanie parametra so štruktúrovaným typom

Blok kódu

language	java
theme	Eclipse

@RPC(name = "Redim",

...


	parameters =

...


	{
		@Parameter(name = "n", type = ParameterType.integer, inOut = false),

...


		@Parameter(name = "r", type = ParameterType.record, recordType = Person.class)

...

})

...


@ReturnValue(name = "r")

...


public List<Person> redim(

...


	@ParameterValue(name = "n") Integer length,

...


	@ParameterValue(name = "r") List<Person> data);

Metóda redim mapuje RPC, ktorej druhým formálnym parametrom je štruktúrovaná hodnota. Pre správne mapovanie je typ parametra v anotácii nastavený na @Parameter.type = ParameterType.record a nepovinný parameter anotácie @Parameter.recordType = Person.class. Použitá definícia štruktúry SD.Person a jej mapovanie triedou Person pochádza z kapitoly 5.2.1.

Pri použití metódy redim bude pre účely návratovej hodnoty vytvorená nová inštancia typu List<Person> a jej prvky budú nové inštancie typu Person napriek tomu, že majú rovnaký obsah ako inštancie, ktoré boli použité ako parametre.parametre.

4.3.2.5. Mapovanie asynchrónneho volania a časovej značky hodnoty

...

Blok kódu

language	java
theme	Eclipse

@RPC(name = "SetValue",

...


	asynchronous = true,

...


	parameters =

...


	{
		@Parameter(name = "v", type = ParameterType.time, inOut = false)

...

})

...


public void setValue(

...


	@ParameterValue(name = "v") Date value,

...


	@ParameterAttribute(name = "v", attributeType = UnivalAttributeType.valueTime)

...


	Long valueTime);

Metóda setValue sa od predošlých príkladov odlišuje tým, že mapuje asynchrónne volanie (RPC.asynchronous = true). To znamená, že z pohľadu používateľa skončí jej volanie okamžite (po odoslaní správy) a nečaká sa na doručenie odpovede o výsledku. Preto tiež asynchrónna metóda nemôže pristupovať ku výstupnej časti parametrov volania a teda nemôže použiť anotáciu @ReturnValue alebo @ReturnAttribute a takisto nemôže nastaviť parametre anotácií ParameterValue.direction a ParameterAttribute a ParameterAttribute.direction na hodnoty inout alebo out.

Nová anotácia @ParameterAttribute mapuje vybraný unival atribút – v tomto prípade časovú značku hodnoty (attributeType = UnivalAttributeType.valueTime) . Pozor, nie je dovolené zavolať metódu s null hodnotou null hodnotou tohto parametra – mapovanie null na atribút univalu nie je možné.

V príklade je zámerne použitý iný typ parametra value (java.util.Date) a parametra valueTime (java.lang.Long). Obidva typy je možné rovnako dobre použiť na mapovanie hodnoty vyjadrujúcej „D2000 absolútny čas", ich výber je na tvorcovi mapovania.mapovania.

4.3.2.6. Mapovanie procedúry s dvomi výstupnými štruktúrovanými parametrami

Blok kódu

language	java
theme	Eclipse

@RPC(name = "GetDataAndMetadata",

...


	asynchronous = false,

...


	parameters =

...

 
		{
			@Parameter(
				name = "data",

...


				inOut = true,

...


				type = ParameterType.record,

...


				recordType = Person.class),

...


			@Parameter(

...


				name = "meta"

...

,
				inOut = true,
				type = ParameterType.record,

...


				recordType = Metadata.class)})

...


public void getDataAndMetadata(

...


	@ParameterValue(name = "data") InOut<List<Person>> data,

...


	@ParameterValue(name = "meta") InOut<List<Metadata>> meta);

Metóda getDataAndMetadata mapuje procedúru s dvomi vstupno-výstupnými parametrami (2 parametre s inOut = true). V porovnaní s predošlými metódami stojí za povšimnutie:

Typ parametra data je InOut<List<Person>>  Generickým ➔ Generickým parametrom kontajnera InOut je generický List, ktorého parametrom je trieda Person, ktorej mapovanie na SD.Person je popísané v kapitole 5 4.2.1.
Trieda Metadata mapuje definíciu štruktúry SD.Metadata. Jej definíciu v príkladoch neuvádzame.
Inštancia objektu typu List, ako aj inštancie predstavujúce jeho prvky, ktoré sa nachádzajú v kontajneri typu InOut po skončení synchrónneho volania sú vždy iné, ako inštancie, ktoré sa v kontajneri nachádzali na začiatku volania. Toto správanie je vlastnosť knižnice JAPI.

Kotva
_Ref441670798
_Ref441670798
Kotva
_Toc490141259
_Toc490141259
4.3.3. Volanie z ESL do JAPI – príklad s komentármi

V nasledujúcej ukážke bude uvedený zdrojový kód triedy ExampleHandler. Je to aplikačne definovaná trieda, ktorej metódy môžu byť volané ako RPC z prostredia ESL Môžu byť volané aj z prostredia internej Javy a tiež z prostredia JAPI..
import .

Blok kódu

language	java
theme	Eclipse

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

...


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

...


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

...


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

...


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

...



public class ExampleHandler

...


	@RPC(name = "Parse",

...


		parameters =

...


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

...


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

...

})

...


	@ReturnValue(name = "result")

...


	public Integer parseInt(

...


		@ParameterValue(name = "text") String text)

...


	{
		try
		{
			return Integer.parseInt(text);

...


		}
		catch (NumberFormatException ex)

...


		{
			return null;
		}
	}
}

Metóda parseInt má rovnaké formálne rozhranie a ja tiež funkčne zhodná s RPC s RPC PROCEDURE E.Service.Parse uvedenou v kapitole 5 4.3.2. Pri jej mapovaní boli použité rovnaké anotácie s rovnakým významom ako na metódu Service.parse.

Rozdiel medzi RPC Parse napísanej v ESL a metódou ExampleHandler.parseInt je v tom, že metódu parseInt nie je možné zavolať asynchrónne. Pre takéto volanie by sa JAPI pokúsilo nájsť druhú metódu s rovnakým formálnym rozhraním, ktoré by malo parameter RPC.asynchronous = true.

Kotva
_Toc490141260
_Toc490141260
4.3.4. Použitie anotácie CallerInformation

Blok kódu

language	java
theme	Eclipse

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

...


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

...


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

...


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

...


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

...



public class HelloHandler

...


	@RPC(name = "Hello")

...


	public void hello(

...


	    @CallerInformation(type = CallerInformationType.processHobj) Integer processHobj,

...


	    @CallerInformation(type = CallerInformationType.eventHobj) Integer eventHobj,

...


	    @CallerInformation(type = CallerInformationType.internalJava) Boolean java)

...


	{
	    ...

...

Anotácia parametra metódy @CallerInformation indikuje, že za hodnotu parametra má byť dosadená informácia o volajúcom. Hodnota parametra type určuje, aká informácia bude dosadená:

processHobj – HOBJ procesu (EVH, HIP, DCC), z ktorého bola RPC zavolaná
eventHobj – HOBJ objektu typu Event, z ktorého bola RPC zavolaná.
internalJava – nadobúda hodnotu true, ak bola RPC zavolaná z prostredia internej Javy.

Kotva
_Toc490141261
_Toc490141261
4.4. Použitie anotovaných objektov

V kapitolách 5 4.2. a 5 4.3. a ich podkapitolách boli vytvorené definície mapovania štruktúrovaných hodnôt (SD.Person  Person ⟺ Person) a definície mapovania volania RPC (Service  E➔ E.Service) a späť (trieda ExampleHandler). Ich použitie zjednodušuje mechanickú prácu vytvárania a konverzie unival hodnôt ako aj potrebu manažovať a opakovane používať množstvo HOBJ pre volanie RPC.

Pri používaní anotácií v jazyku Java je dôležité si uvedomiť, že označenie nejakého objektu anotáciou nemá žiadne priame funkčné dôsledky. Napríklad, ak vytvoríme inštanciu triedy ExampleHandler a následne zavoláme jeho metódu parseInt, jej vykonanie prebehne vždy rovnako, bez ohľadu na prítomnosť alebo neprítomnosť anotácie @RPC. Anotácie slúžia iba na to, aby sa kód, ktorý skúma iné časti kódu, vedel lepšie orientovať.

Nasledujúce príklady sa budú odkazovať na triedy vytvorené v príkladoch v kapitolách 5 4.2.1, 5 4.3.2. a 5 4.3.3. Okrem toho budú použité nasledovné objekty::

Blok kódu

language	java
theme	Eclipse

D2Connector connector = ... // aktivne spojenie

...


D2Session session = connector.createSession(... // aktivna session

Na konverzie štruktúrovaných hodnôt bude použitý objekt typu UnivalConvertor prístupný cez connector.getDefaultUnivalConvertor().

Kotva
_Toc490141262
_Toc490141262
4.4.1. Príklad volania z JAPI do ESL

V uvedenom príklade je ukážka volania RPC z prostredia JAPI. Príklad sa skladá z inicializačnej časti (kroky 1 a 2), ktorú je potrebné spraviť raz, pri štarte aplikácie, po pripojení sa ku kernelu. Ďalšie kroky (odrážky), sú príklady samotného volania, je možné použiť v ľubovoľnom poradí a opakovať podľa potreby.

Vytvorenie tzv. Event Proxy Factory objektu. V tomto kroku je trieda Service analyzovaná. Nový objekt (factory) v sebe implementuje mapovanie RPC volaní podľa nájdených anotácií. Parametre volania majú nasledujúci význam:
- Service.class  referencia ➔ referencia na triedu, ktorá definuje mapovanie
- session
   získanie
  ➔ získanie HOBJ a parent HOBJ objektu E.Service
  Blok kódu
  language java
  theme Eclipse
  EventProxyFactory<Service> factory =EventProxyFactory.createFactory(Service.class, session);
Vytvorenie tzv. Event Proxy objektu s využitím factory z predošlého kroku. V tomto kroku vznikne inštancia anonymnej triedy (odvodenej od java.lang.reflect.Proxy), ktorá implementuje rozhranie Service, aby bolo možné volať anotované metódy. Implementáciu tejto triedy generuje JAPI. Parameter volania má nasledovný význam:
- session
   asociuje
  ➔ asociuje vytvorený objekt proxy s touto inštanciou Session – v jej mene budú RPC volané. Môže to byť iná inštancia, ako v kroku 1.
  Blok kódu
  language java
  theme Eclipse
  Service proxy = factory.createDefault(session);

Nasledujú príklady samotného volania:

Jednoduché volanie RPC Parse:
Blok kódu
language java
theme Eclipse
Integer result;

...


result = proxy.parse("12"); // Integer.valueOf(12)

...

result = proxy.parse("ab"); // null

Použitie kontajnera InOut<> vo volaní RPC Square:
Blok kódu
language java
theme Eclipse
Double value = 5.0;

...


InOut<Double> valueContainer = new InOut<>(value);

...

proxy.sqare_2(valueContainer);

...


Double result = valueContainer.getValue();

V aplikáciách, kde dochádza k viacnásobnému pripájaniu a odpájaniu počas životného cyklu aplikácie:

Krok 1 stačí spraviť raz, po vytvorení 1. session. Vzniknutú factory môžete považovať za platnú, pokým je aktívny connector. Pre nový connector je potrebné vytvoriť novú factory.
Krok 2 je potrebné raz zopakovať pre každú novú session, z ktorej majú byť volané RPC.

Kotva
_Toc490141263
_Toc490141263
4.4.2. Príklad volania z ESL do JAPI

V uvedenom príklade je ukážka volania RPC z prostredia ESL do prostredia JAPI a najmä spôsob spracovania a odpovedania na toto volanie. Príklad sa skladá z inicializačnej časti (kroky 1 a 2), po ktorej bude možné adresovať RPC volania do zvolenej session. Krok 3 je inicializáciou v ESL. Krok 4 je samotné volanie, ktorý možno podľa potreby opakovať s ľubovoľnými parametrami.

Vytvorenie tzv. Event Wrapper Factory objektu. V tomto kroku je trieda ExampleHandler analyzovaná. Nový objekt factory v sebe implementuje spracovanie prichádzajúcich RPC volaní a ich mapovanie na volania metód triedy ExampleHandler. Význam použitých parametrov je nasledovný:
- ExampleHandler.class  referencia ➔ referencia na triedu, ktorá definuje mapovanie
- session
   preklad
  ➔ preklad mien
  Blok kódu
  language java
  theme Eclipse
  EventWrapperFactory<ExampleHandler> factory = EventWrapperFactory.createFactory(ExampleHandler.class, session);
Registrácia inštancie triedy ExampleHandler pre prijímanie RPC volaní do konkrétnej session. Po tomto kroku bude možné adresovať volanie RPC Parse aj do použitej session.
Blok kódu
language java
theme Eclipse
ExampleHandler handler = new ExampleHandler();

...


factory.registerNewHandler(session, handler);

Uloženie HOBJ dynamického objektu session, aby bolo možné neskôr volať späť. V tele ľubovoľnej RPC v ESL je možné zistiť adresu (HOBJ procesu a objektu) volajúceho nasledovným spôsobom:
Blok kódu
language esl
theme RDark
INT _sessionHobj

...

RPC PROCEDURE Register

...

_sessionHobj := %GetRPCCallerProcess()

...

END Register

...

unmigrated-wiki-markup

Volanie

RPC z prostredia ESL. Namiesto mena objektu je použité [(0)] pretože v JAPI neexistuje ekvivalent objektu typ Event. Namiesto mena procesu je použité (_sessionHobj) pretože session je v D2000 DODM dynamický objekt typu proces a na jeho meno sa nedá použiť ako identifikátor v zdrojovom kóde.

Blok kódu

language	esl
theme	RDark

INT _r
CALL  z prostredia ESL. Namiesto mena objektu je použité \[(0)\] pretože vParse("12", _JAPI_r) neexistuje ekvivalent objektu typ Event. Namiesto mena procesu je použité (_sessionHobj) pretože session je v D2000 DODM dynamický objekt typu proces a na jeho meno sa nedá použiť ako identifikátor v zdrojovom kóde.

Značky Wiki
INT _r CALL \[(0)\] Parse("12", _r) ON (_sessionHobj) \\

ON (_sessionHobj)

...

Kotva

	1
	1

¹ D2000 logická hodnota je štandardne mapovaná vymenovaným typom sk.ipesoft.d2000.base.VBool. Pre zjednodušenie použitia je umožnené mapovať typom java.lang.Boolean, pričom je hodnota vOscillate mapovaná ako false.

Kotva

	2
	2

²Počet milisekúnd od UNIX epochy (1. 1. 1970 00:00:00 GMT). Pozor, systém D2000 používa inú epochu, jej hodnota je uložená v objekte sk.ipesoft.d2000.utils.D2Time.d2TimeEpoch.

Kotva

	3
	3

³Generický parameter T musí zodpovedať použitej definícii štruktúry.

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é.

Kotva

	8
	8

⁸ Môžu byť volané aj z prostredia internej Javy a tiež z prostredia JAPI Kotva11¹ D2000 logická hodnota je štandardne mapovaná vymenovaným typom sk.ipesoft.d2000.base.VBool. Pre zjednodušenie použitia je umožnené mapovať typom java.lang.Boolean, pričom je hodnota vOscillate mapovaná ako false. Kotva22²Počet milisekúnd od UNIX epochy (1. 1. 1970 00:00:00 GMT). Pozor, systém D2000 používa inú epochu, jej hodnota je uložená v objekte sk.ipesoft.d2000.utils.D2Time.d2TimeEpoch. Kotva33³Generický parameter T musí zodpovedať použitej definícii štruktúry.

Strom stránky

Porovnávané verzie

Stará verzia 2

Nová verzia Aktuálny

Kľúč

Kotva
_Toc490141250
_Toc490141250
4.1. Mapovanie typu D2000 Unival

Kotva
_Ref441562165
_Ref441562165
Kotva
_Toc490141251
_Toc490141251
4.1.1 Mapovanie hodnoty a platnosti hodnoty unival-u

Kotva
_Toc490141252
_Toc490141252
4.1.2. Mapovanie unival atribútu

Kotva
_Ref442078508
_Ref442078508
Kotva
_Toc490141253
_Toc490141253
4.2. Mapovanie štruktúrovaných Unival hodnôt

Kotva
_Ref441569011
_Ref441569011
Kotva
_Toc490141254
_Toc490141254
4.2.1. Príklad s vysvetlivkami

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

4.3.2.2. Mapovanie vstupno-výstupného parametra

4.3.2.3. Mapovanie synchrónnej procedúry s odloženým vyhodnotením výsledku

4.3.2.4. Mapovanie parametra so štruktúrovaným typom

4.3.2.5. Mapovanie asynchrónneho volania a časovej značky hodnoty

4.3.2.6. Mapovanie procedúry s dvomi výstupnými štruktúrovanými parametrami

Kotva
_Ref441670798
_Ref441670798
Kotva
_Toc490141259
_Toc490141259
4.3.3. Volanie z ESL do JAPI – príklad s komentármi

Kotva
_Toc490141260
_Toc490141260
4.3.4. Použitie anotácie CallerInformation

Kotva
_Toc490141261
_Toc490141261
4.4. Použitie anotovaných objektov

Kotva
_Toc490141262
_Toc490141262
4.4.1. Príklad volania z JAPI do ESL

Kotva
_Toc490141263
_Toc490141263
4.4.2. Príklad volania z ESL do JAPI

Strom stránky

História stránky

Porovnávané verzie

Stará verzia 2

Nová verzia Aktuálny

Kľúč

Kotva_Toc490141250_Toc4901412504.1. Mapovanie typu D2000 Unival

Kotva_Ref441562165_Ref441562165 Kotva_Toc490141251_Toc4901412514.1.1 Mapovanie hodnoty a platnosti hodnoty unival-u

Kotva_Toc490141252_Toc4901412524.1.2. Mapovanie unival atribútu

Kotva_Ref442078508_Ref442078508 Kotva_Toc490141253_Toc4901412534.2. Mapovanie štruktúrovaných Unival hodnôt

Kotva_Ref441569011_Ref441569011 Kotva_Toc490141254_Toc4901412544.2.1. Príklad s vysvetlivkami

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_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

4.3.2.2. Mapovanie vstupno-výstupného parametra

4.3.2.3. Mapovanie synchrónnej procedúry s odloženým vyhodnotením výsledku

4.3.2.4. Mapovanie parametra so štruktúrovaným typom

4.3.2.5. Mapovanie asynchrónneho volania a časovej značky hodnoty

4.3.2.6. Mapovanie procedúry s dvomi výstupnými štruktúrovanými parametrami

Kotva_Ref441670798_Ref441670798 Kotva_Toc490141259_Toc4901412594.3.3. Volanie z ESL do JAPI – príklad s komentármi

Kotva_Toc490141260_Toc4901412604.3.4. Použitie anotácie CallerInformation

Kotva_Toc490141261_Toc4901412614.4. Použitie anotovaných objektov

Kotva_Toc490141262_Toc4901412624.4.1. Príklad volania z JAPI do ESL

Kotva_Toc490141263_Toc4901412634.4.2. Príklad volania z ESL do JAPI

Kotva
_Toc490141250
_Toc490141250
4.1. Mapovanie typu D2000 Unival

Kotva
_Ref441562165
_Ref441562165
Kotva
_Toc490141251
_Toc490141251
4.1.1 Mapovanie hodnoty a platnosti hodnoty unival-u

Kotva
_Toc490141252
_Toc490141252
4.1.2. Mapovanie unival atribútu

Kotva
_Ref442078508
_Ref442078508
Kotva
_Toc490141253
_Toc490141253
4.2. Mapovanie štruktúrovaných Unival hodnôt

Kotva
_Ref441569011
_Ref441569011
Kotva
_Toc490141254
_Toc490141254
4.2.1. Príklad s vysvetlivkami

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

Kotva
_Ref441670798
_Ref441670798
Kotva
_Toc490141259
_Toc490141259
4.3.3. Volanie z ESL do JAPI – príklad s komentármi

Kotva
_Toc490141260
_Toc490141260
4.3.4. Použitie anotácie CallerInformation

Kotva
_Toc490141261
_Toc490141261
4.4. Použitie anotovaných objektov

Kotva
_Toc490141262
_Toc490141262
4.4.1. Príklad volania z JAPI do ESL

Kotva
_Toc490141263
_Toc490141263
4.4.2. Príklad volania z ESL do JAPI