====== HMR language ======

The HMR language has been designed to textual human and machine redable representation of XTT2 models.
The syntax of the HMR is a subset of Prolog syntax where a number of operators have been defined.

Each HMR file consists of the following parts:
  * [requied] Types definitions (predicate //xtype//),
  * [optional] Types groups definitions (predicate //xtpgr//),
  * [requied] Attributes definitions (predicate //xattr//),
  * [optional] Attributes groups definitions (predicate //xatgr//),
  * [requied]Definicje schematów (tabel) (predicate //xschm//),
  * [requied] Rules definitions (predicate //xrule//),
  * [optional] States definitions (predicate //xstat//).
  * [optional] Callbacks definitions (predicate //xcall//)
Each of predicates (besides //xschm// and //xrule//) is a Prolog list, which defines the properities of a XTT object.

In example, the definitions of type //weekdays// and an attribute //day// is as follows:
<code>
xtype [name: weekdays,
       base: symbolic,
       desc: 'A set of days of the week',
       domain: ['Monday'/1,'Tuesday'/2,'Wednesday'/3,'Thursday'/4,'Friday'/5,'Saturday'/6,'Sunday'/7],
       ordered: yes
      ].
	  
xattr [name: day,
       abbrev: day,
       class: simple,
       type: weekdays,
       comm: in,
       callback: [ask_symbolic_GUI,[day]],
       desc: 'The current day'
      ].
	  
xcall ask_symbolic_GUI : [AttName] >>> (jpl_new('skeleton.RequestInterface',[],T),
	 alsv_domain(AttName,Domain,symbolic),
	 Params = [AttName|Domain],
	 term_to_atom(Params, AtomParams),
	 jpl_call(T,request,['callbacks.input.ComboBoxFetcher',AtomParams],Answer),
	 atom_to_term(Answer,Answer2,_),
	 alsv_new_val(AttName,Answer2)).
</code>

=== Exercise ===
Compare the HMR file with XTT model:
  * HMR file:
 {{:pl:dydaktyka:piw:2010:systemy_ekspertowe:thermostat-clb-pl.pl|}}
  * XTT file: 
{{:pl:dydaktyka:piw:2010:systemy_ekspertowe:thermostat-xtt.png|}}

====== Callbacks in HMR ======
Callbacks are the functions that are executed during the XTT tables evaluation in order to get a value or to present a value.
The example of the callbacks execution results are showed  in the picture below.
In the cashpoint system, the callbacks are used for calling a enter PIN dialog as well as for displaying messages to the user.

{{:pl:dydaktyka:piw:2010:systemy_ekspertowe:callbacks.png|}}

There are two types of callbacks:
  * //in// - are executed before (or during) inference process in order to get attributes value.
  * //out// - are executed for values of attributes presentation, when the inference process is finished. 
The type of a callback is determined by value of the attribute //comm// property.

HMR syntax provides a **callback** property of the XTT attribute that indicates which callback function should be called.
The property has a list structure, where the first element is the name of the callback function and the second is a list of parameters.
<code>
xattr [name: day,
       abbrev: day,
       class: simple,
       type: day,
       comm: in,
       callback: [ask_console,[day]]
      ].
</code>
The above example defines an attribute //day//.
The value of the property //comm// of this attribute is **in** what defines the type of the callback to be **in**.
For this attribute the **ask_console** callback function will be called, which will get the value of the attribute **day**.

==== Callbacks and attributes ====
In HMR, callbacks are related to attributes. For each attribute two properties must be defined in order to use callbacks:
  * //comm// - defines when the callback is executed (possible values: //in// or //out//)
  * //callback// - the name and the list of parameters of the required callback. 

HMR provides //xcall// predicate that allows for callback definition.
The following example shows the JPL mechnism, which is used to create a callback written in Java.
<code>
xcall ask_symbolic_GUI : [AttName] >>> (jpl_new('skeleton.RequestInterface',[],T),
	 alsv_domain(AttName,Domain,symbolic),
	 Params = [AttName|Domain],
	 term_to_atom(Params, AtomParams),
	 jpl_call(T,request,['callbacks.input.ComboBoxFetcher',AtomParams],Answer),
	 atom_to_term(Answer,Answer2,_),
	 alsv_new_val(AttName,Answer2)).
</code>

==== Programming languages ====
HeaRT supports the callbacks written in:
  * Prolog
  * XPCE
  * Java
=== Prolog ===
Prolog-based callbacks are an ordinary Prolog predicates.
<code>
xcall ask_console : [AttName] >>> (write('Type value for attribute:  '),
     write(AttName),nl,
     read(Answer),
     alsv_new_val(AttName,Answer)).
</code>

**Exercise** \\
In order to run inference process directly from HeaRT interpreter you must:
  * download the source code of HeaRT {{:hekate:heart-m3.tar.gz}},
  * run it by typing //heart//,
  * in order to complie XTT model in the form of HMR type in console: //[name-of-hmr-file]//,
  * run the //gox// command:<code>gox(current, ListOfProcessedTables, ddi)</code>
Run the inference for the following model: {{:pl:dydaktyka:piw:2010:systemy_ekspertowe:thermostat-clb-pl.pl|}}

=== XPCE ===
The XPCE-based callbacks consist of the ordinary Prolog predicates that are enriched by XPCE functions.
In order to assure the correct integration with HaeRT, the following schema must be used:
<code>
xcall xpce_ask_numeric: [AttName] >>> (
	dynamic(end),
        % The body of the callback, which prepares a dialog to appear.
	repeat,
	    % Waiting for OK button
		send(@display,dispatch),
	end,!,
	retractall(end)).
</code>


The example of the callback that reads a value from the range [Min; Max] is presented below:
<code>
xcall xpce_ask_numeric: [AttName] >>> (alsv_domain(AttName,[Min to Max],numeric),
	dynamic(end),
	new(@dialog,dialog('Select a value')),
	send_list(@dialog,append, 
		[new(I,int_item(AttName,low := Min, high := Max)),
		 new(_,button('Select',and(message(@prolog,assert,end),and(message(@prolog,alsv_new_val,AttName,I?selection),message(@dialog,destroy)))))]),
	send(@dialog,open),
	repeat,
		send(@display,dispatch),
	end,!,
	retractall(end)).
</code>

**Exercise** \\
Run the inference mechanism for the ATM example and trace the callback mechanism:
  * {{:pl:dydaktyka:piw:2010:systemy_ekspertowe:cashpoint-clb-xpce.pl|}}

=== Java ===
The Java-based callbacks are the Java programs that are executed by prolog with the help of JPL.
To exploit this mechanism, the following classes mysu be used:
  * DataFetcher.java - an abstract class that must be inherited by all the callbacks
  * RequestInterface.java - controller
  * Response.java - class that stores a data retrieved from a user.
  
The set of basic components, which can be used to the retrieval data from a user, is prepared to facilitate the callbacks implementation.
  * **ComboBoxFetcher.java** - creates a list of selectable values. It returns one (selected) value.
  * **SliderFetcher.java** - allowf for selecting a value from a given range of values. It returns one (selected) value.
  * **TwoListsFetcher.java** - creates a list of selectable values. It returns list of all selected values.
  * **ComboGUI.java** - GUI for ComboBoxFetcher
  * **SliderGUI.java** - GUI for SliderFetcher
  * **TwoListsGUI.java** - GUI for TwoListsFetcher
Download a source code {{:hekate:callbackslibrary.zip|here}}. 

== Example ==
In order to use some of the above components to create callback, you must go through the following steps:
  - Compile the source code <code>javac callbacks/input/*.java skeleton/*.java</code> and move it to the HMR file directory.
  - Modify the HMR file by adding the //callback// filed to the appropriate attributes.
  - Define the value of this filed by entering the name of the callback as well as a list of parameters i.e. <code>callback: [ask_symbolic_GUI,[day]]</code>
  - Add the //xcall// predicates to the HMR file, which execute a given callback:<code>
  xcall ask_symbolic_GUI : [AttName] >>> (
     % Creating controller
	 jpl_new('skeleton.RequestInterface',[],T),
	 % Creating a list of params
	 alsv_domain(AttName,Domain,symbolic),
	 Params = [AttName|Domain],
	 term_to_atom(Params, AtomParams),
         % Execute the callback with the params contained by AtomPArams term.
         % The result will be stored in Answer term.
	 jpl_call(T,request,['callbacks.input.ComboBoxFetcher',AtomParams],Answer),
         % Map the returned value into term and add it the the factbase
	 atom_to_term(Answer,Answer2,_),
	 alsv_new_val(AttName,Answer2)).
  </code>
  - Go to HMR file directory.
  - Run HeaRT tool.
  - Compile HMR file.
  - Run the inference mechanism.
  - The callback should be executed.

**Exercise 1** \\
Download the file {{:pl:dydaktyka:piw:2010:systemy_ekspertowe:kardio.zip|}} and run the inference for the HMR file.

**Exercise 2** \\
  - Run HeaRT and load HMR {{:pl:dydaktyka:piw:2010:systemy_ekspertowe:cashpoint-clb-xpce.pl|file}}. 
  - Then run the infenrence mechnism using predicate (//gox/3//).
  - Add a new XPCE-based callback, which would present the results of the inference.
  - Download HMR {{:pl:dydaktyka:piw:2010:systemy_ekspertowe:thermostat-clb-pl.pl|file}}.
  - Add (modify an existing Prolog-based) a new JAVA-based callbacks in the same way as in the previous section.


===== Komentarze =====

Z braku lepszego miejsca tutaj studenci wpisują komentarze natury ogólnej do tego lab. 8-)