.. _ref-httpengine:

###############################################################################
HTTPEngine
###############################################################################
``maongo.core.toolkit.HTTPEngine extends Engine``


Die HTTPEngine dient dazu, aus der Presentation heraus per HTTP-Request Daten anzufordern oder auszutauschen. 
Dazu kann eine entsprechende Server-``URL`` definiert werden.

Die HTTPEngine nutzt die vom Browser bekannte Methode GET.

Bei der HTTPEngine einlaufende Daten aus Serverprozessen können folgende Formate haben:

- XML-Transmissions (Transmission ist eine Sammlung von Data-Objekten; Routing und spezielle Trigger werden unterstützt)
- Data (einzelnes Data-Objekt; Routing und spezielle Trigger werden unterstützt)
- JSON (Objekt oder Liste von Objekten: JSON wird in ein Data umgewandelt, Routing und spezielle Trigger werden unterstützt)
- beliebiges valides XML (kein Routing, generischer Trigger)
- beliebiger Text (kein Routing, generischer Trigger)

Wird ein Data an die HTTPEngine geroutet, so wird es an den Server übertragen. Der 
Server kann darauf mit einer Transmission antworten, die dann wiederum von der HTTPEngine
anhand der in ihr konfigurierten Routen in der Presentation 
verteilt wird. Eintreffende Transmissions lösen ``transmission``- und ``data``-Signale aus. Ausgehende
Data lösen ``request``-Signale aus. Siehe dazu auch :ref:`ref-httpengine-signal-example` 


Properties
------------

**URL** (URL)
	Setzt die Serveradresse für die Kommunikation::

		http://www.maongo.com/path/to/cgi
	
	Default: ``null``


**User** (String)
	Loginname für die Kommunikation mit ``URL``.
	
	Default: ``null``

**Password** (String) 
	Passwort für die Kommunikation mit ``URL``.
	
	Default: ``null``
	
**Encoding** (Symbol)
	Setzt das Text-Encoding für ausgehende Daten.
	
	Default: ``"utf-8"``
	
	Werte: ``"utf-8"``, ``"latin-1"``

	
**Timeout** (Time) 
	als Zeitangabe ("30", "30s", "0.5m"). Wird ein HTTP-Request nicht innerhalb der angegebenen Zeit abgeschlossen, 
	so wird er als ``communication-failure`` behandelt (siehe Signals) und abgebrochen/verworfen. 
		
	Default: ``30`` (30 Sekunden) 

**Interval** (Time)
	als Zeitangabe. In diesem Zeitabstand wird der Request wiederholt ausgelöst (Polling).
	
	Default: ``null`` (kein Polling)

**ProxyURL** (URL):  
   Derzeit ist eine Nutzung dieser Property noch nicht möglich.
   
   Default: ``null``

**ProxyUser** (String): 
   Derzeit ist eine Nutzung dieser Property noch nicht möglich.
    
   Default: ``null``

**ProxyPassword** (String):  
   Derzeit ist eine Nutzung dieser Property noch nicht möglich.
    
   Default: ``null``


Signale
----------------------------

Die Signale beziehen sich teilweise auf die Abwicklung der Kommunikation und teilweise auf die geladenen Daten.  
Je nach geladenem Inhalt können sich die Signale unterscheiden.


**communication-request** (URL)
	Die Engine startet einen request
	
**communication-success** (Download-Objekt)
   Die Kommunikation war erfolgreich. Als Argument wird der Action das "rohe" Ergebnis des Requests übertragen. 
   Dabei handelt es sich um ein Download-Objekt. Der Inhalt des Download-Objektes kann im Falle von XML mittels 
   ``getSource()`` ausgelesen werden. 

   Beispiel::
  
       <action trigger="communication-success" arguments="rawdata">
          trace("rawdata:" + rawdata.getSource());
       </action>
     
   Mittels ``getText()`` können die geladenen Daten als Text ausgelesen werden.
 
   Beispiel::
    
    <action trigger="communication-success" arguments="rawdata">
       trace("rawdata:" + rawdata.getText());
    </action>

   Bei Erfolg werden außerdem im Falle einer Transmision die spezifischen Signale ``transmission-start``, ``transmission-end`` 
   und ``transmission-data`` gesendet.
   Sofern es sich bei den geladenen Daten um XML, aber keine Transmission handelt, wird das Signal ``download-xml`` gesendet.
   In allen anderen Fällen wird das Signal ``download-text`` gesendet.

**communication-failure** (Exception)
	Bei der Kommunikation ist ein Fehler aufgetreten.

Spezifische Signale für Transmission und Data
==========================================================================================================

**transmission-start**
    Eine Transmission läuft in die Engine ein.
    
**transmission-end** (Transmission-Objekt)
    Eine Transmission ist angekommen; sie wird als Argument übertragen und kann hier direkt genutzt werden::
	
		<action trigger="transmission-end" arguments="tr">
			trace(tr.getSerial()); //getSerial() ist eine Methode der Transmission-Klasse.
		</action>

**transmission-data** (Data)
	Ein Data ist angekommen und wird als Argument übertragen::

		<action trigger="transmission-data" arguments="data">
			trace(data.get("Title"));
		</action>

Signale für XML und Text
==========================================================================================================

**download-xml** (RootNode)
	Ein XML-Dokument ist angekommen. Als Argument wird der RootNode des Dokuments als ``SimpleNode`` übergeben. Siehe dazu :ref:`ref-types`
	
**download-text** (String)
    Es ist eine undefinierte Art von Daten angekommen. Als Argument werden die empfangenen Daten als String übergeben.


.. _ref-httpengine-signal-example:

Beispiel: Signale der HTTPEngine 
========================================================================================================

::
 
    <widget name="Box1"  x="10" y="10">
      <property name="BackgroundColor" value="red"/>
      <property name="Interactive" value="true"/>
      <action trigger="pointer-down">
        var commEngine = $(this,"comm");
        commEngine.communicate();
      </action>
    </widget>
    
    
    <engine name="comm" type="Http">
        <property name="URL" value="http://www.maongo.com/examples/bom/resources/example.xml"/>
        
        <action trigger="communication-request">
            trace("communication-request");
        </action>
        
        <action trigger="communication-success" arguments="rawdata">
            trace("communication-success: " + rawdata);
        </action>
        
        <action trigger="communication-failure" arguments="excp">
            trace("communication-failure: " + excp);
        </action>
        
        <action trigger="transmission-start" arguments="excp">
            trace("transmission-start: " + excp);
        </action>
        
        <action trigger="transmission-end" arguments="trans">
            trace("transmission-end: " + trans);
        </action>
        
        <action trigger="transmission-data" arguments="data">
            trace("transmission-data: " + data);
        </action>
        
        <action trigger="download-xml" arguments="xmlroot">
            trace("download-xml: " + xmlroot);
        </action>
        
        <action trigger="download-text" arguments="text">
            trace("download-text: " + text);
        </action>
        
    </engine> 

Methoden
-------------

**communicate**
	Die Methode ``communicate()`` dient dazu, den konfigurierten Request manuell aufzurufen.

Beispiel::

	$(this, "commEngine").communicate()

Routing
-------------
Der automatische Routing-Mechanismus für Data weist für Kommunikations-Engines wie die HTTP-Engine eine Besonderheit auf:

Wird ein Data von anderer Stelle in der Presentation auf die Engine geroutet, so wird dieses Data zum Server übertragen. 

.. note:: Das Versenden von Data, welche auf die HTTPEngine geroutet werden ist derzeit nicht implementiert.

Die in der Engine eingetragene Route wird genutzt, um einen vom Server erhaltenen Inhalt zu routen, falls dieser Inhalt
geroutet werden kann, also falls er als Data vorliegt.

Aus eingehenden Transmissions werden die einzelnen Data-Objekte so geroutet.
Eingehendes JSON wird in ein Data-Objekt verwandelt und ebenfalls geroutet.
Jeweils vorausgesetzt, dass entsprechende Routen in der Engine eingetragen sind.




MAD
----------------
**Beispiel 1**::

  <presentation>

  <widget name="Button1" type="Button" x="20" y="20" shape="R 50 50">
    <property name="BackgroundColor" value="olive"/>
    <action trigger="pointer-down">
      $(this, "comm").communicate();
      $(this, "comm").URL = "http://www.maongo.com/notfound";
    </action>
  </widget>

  <widget name="Widget2" y="20" x="100" shape="O 50">
    <property name="BackgroundColor" value="gray"/>
  </widget>

  <engine name="comm" type="Http">
    <property name="URL" value="http://www.maongo.com/examples/bom/resources/example.xml" />
    <route property="*" match="*" target="widget2" />
    <action trigger="transmission-data">
      $(this, "startButton").BackgroundColor = "orange";
    </action>
    <action trigger="communication-success">
      $(this, "Widget2").BackgroundColor = "green";
    </action>
    <action trigger="communication-failure">
      $(this, "Widget2").BackgroundColor = "red";
    </action>
  </engine>

  </presentation>
    
:download:`Dieses Beispiel laden <../../reference/toolkit/httpengine.mad>`.
	
Button 1 startet bei Klick die HTTPEngine. Diese färbt bei eingetroffenem Data den Button orange,
und je nach Erfolg der Kommunikation mit dem Server das Widget2 grün oder rot.
Gleichzeitig wird die URL der Engine auf eine nicht erreichbare Adresse umgeschrieben, sodaß ein zweiter Klick einen communication-failure auslöst.


**Beispiel 2**::

  <presentation width="600" height="600">
   <widget type="Button" x="10" y="10">
     <property name="Shape" value="R 150 20"/>
     <property name="Text" value="Transmission laden"/>
     <action trigger="button-clicked">
        $(this, "CommResult").BackgroundColor = "white";
        $(this,"comm").URL = "http://www.maongo.com/examples/bom/resources/basictransmission.xml";
        $(this,"comm").communicate();
     </action>
    </widget>
    
    <widget type="Button" x="10" y="40">
     <property name="Shape" value="R 150 20"/>
     <property name="Text" value="JSON laden"/>
     <action trigger="button-clicked">
        $(this, "CommResult").BackgroundColor = "white";
        $(this,"comm").URL = "http://www.maongo.com/examples/bom/resources/basicjson.json";
        $(this,"comm").communicate();
     </action>
    </widget>
    
    <widget type="Button" x="10" y="70">
     <property name="Shape" value="R 150 20"/>
     <property name="Text" value="XML laden"/>
     <action trigger="button-clicked">
        $(this, "CommResult").BackgroundColor = "white";
        $(this,"comm").URL = "http://www.maongo.com/examples/bom/resources/basicxml.xml";
        $(this,"comm").communicate();
     </action>
    </widget>
    
    <widget type="Button" x="10" y="100">
     <property name="Shape" value="R 150 20"/>
     <property name="Text" value="Text laden"/>
     <action trigger="button-clicked">
        $(this, "CommResult").BackgroundColor = "white";
        $(this,"comm").URL = "http://www.maongo.com/examples/bom/resources/basictext.txt";
        $(this,"comm").communicate();
     </action>
    </widget>
    
    <widget type="Button" x="10" y="130">
     <property name="Shape" value="R 150 20"/>
     <property name="Text" value="Ladefehler auslösen"/>
     <action trigger="button-clicked">
        $(this, "CommResult").BackgroundColor = "white";
        $(this,"comm").URL = "http://www.maongo.com/examples/bom/resources/nonexisting.xml";
        $(this,"comm").communicate();
     </action>
    </widget>
    
    <widget name="CommResult" type="Text" x="300" y="10">
     <property name="Shape" value="R 250 20"/>
     <property name="Text" value="Kommunikation erfolgreich?"/>
     <property name="BackgroundColor" value="white"/>
     <property name="BorderColor" value="black"/>
     <property name="BorderWidth" value="1"/>
    </widget>
    
    <engine name="comm" type="Http">
      <property name="URL" value="http://www.maongo.com/examples/bom/resources/example.xml"/>
    
     <action trigger="communication-request">
        trace("communication-request");
      </action>
        
     <action trigger="communication-success" arguments="rawdata">
        trace("communication-success: " + rawdata);
        $(this, "CommResult").BackgroundColor = "green";
      </action>
        
      <action trigger="communication-failure" arguments="excp">
         trace("communication-failure: " + excp);
         $(this, "CommResult").BackgroundColor = "red";
      </action>
        
      <action trigger="transmission-start" arguments="excp">
        trace("transmission-start: " + excp);
      </action>
        
      <action trigger="transmission-end" arguments="trans">
        trace("transmission-end: " + trans);
      </action>
        
      <action trigger="transmission-data" arguments="data">
        trace("transmission-data: " + data);
      </action>
        
      <action trigger="download-xml" arguments="xmlroot">
        trace("download-xml: " + xmlroot);
      </action>
        
      <action trigger="download-text" arguments="text">
        trace("download-text: " + text);
      </action>
        
    </engine>   
  
  </presentation> 
  
:download:`Dieses Beispiel laden <../../reference/toolkit/httpengine2.mad>`.
  
In diesem Beispiel können über die verschiedenen Buttons unterschiedliche Datentypen geladen werden. Über die jeweiligen Actions werden die dabei 
auftretenden Signale ausgegeben. Je nach Erfolg oder Mißerfolg der Kommunikation wird das Widget "CommResult" grün oder rot eingefärbt.