.. _ref-socketengine:

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

.. sectionauthor:: jo
.. note:: XXXXXXXXXXXXXXX Status 01.11.2010: Zur Diskussion XXXXXXXXXXXXXXXXXXXX

Die SocketEngine dient dazu, aus der Presentation heraus eine 
Serververbindung zu öffnen (TCP-Socket zu ``Server``auf ``Port``), über die beidseitig Data ausgetauscht werden können.

Bei der SocketEngine 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)

Zu übertragende Daten (Data) müssen auf die SocketEngine geroutet werden. Der 
Server kann die TCP-Connection ebenfalls nutzen, um Daten zu schicken, die dann ggf. in Data umgewandelt werden und
anhand der in der Engine konfigurierten Routen in der Presentation 
verteilt wird. Eintreffende Transmissions lösen ``transmission``- und ``data``-Signale aus. Ausgehende
Data lösen ``transmit``-Signale aus. *?*

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

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

		server.com
		172.16.0.123
		localhost
	
	Default: null

**Port** (Integer)
	Nummer des TCP-Ports, über den kommuniziert werden soll.

	Default: null

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

	als Zeitangabe.
	
	Default: 30 (30 Sekunden)


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

*communication-start* (Data)
	Ein Data ist auf die SocketEngine geroutet worden und wird zum Server weitergeleitet.
	
**communication-success** *kann es das geben?*
	Bei der Kommunikation ist ein Fehler aufgetreten.

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

**communication-connect**
	Eine dauerhafte Serververbindung wurde gestartet

**communication-disconnect**
	Eine dauerhafte Serververbindung wurde unterbrochen

**communication-ping**
	Der Server hat das gesendete Ping bestätigt.
	
	
*send-start*
	Start der Datenübertragung ZUM Server. (Socket und HTTP)

*send-end*
	Ende der Datenübertragung ZUM Server. (Socket und HTTP)

*receive-start*
	Start der Datenübertragung VOM Server. (Socket und HTTP)

*receive-end*
	Ende der Datenübertragung VOM Server. (Socket und HTTP)


Transmission und Data:

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

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

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





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

**communicate**
	Führt die in der Engine definierte Kommunikation aus.

Beispiel::

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


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

Wird ein Data von anderer Stelle in der Presentation auf die Engine geroutet, so wird dieses Data zum Server übertragen. 
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.