.. _ref-httpengine:

###############################################################################
PekingEngine
###############################################################################
``maongo.core.toolkit.PekingEngine extends CommEngine``

.. sectionauthor:: mao


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

**URL** (URL)
	Setzt die Adresse der state.xml::

		http://localhost:8080/path/to/state.xml
	
	Default: ``null``

**Timeout** (Time) 
	als Zeitangabe ("30", "30s", "0.5m"). Wird ein HTTP-Request nicht innerhalb der angegebenen Zeit abgeschlossen, so wird er als Fehler behandelt. 
	
	Default: ``120`` (120 Sekunden)

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

**Lifetime** (Time)
	als Zeitangabe. In diesem Zeitabstand bekommen die Peking-Requests einen neuen Timestamp.
	Der Wert muss eine Zweierpotenz sein (4,8,16,32,64,128), falls nicht wird die nächsthöhere
	Zweierpotenz benutzt.
	
	Default: ``32`` (32 Sekunden)
	
**ProtocolVersion** (Integer)
	Variante des initialen Abrufs der state.xml. Hieraus resultiert auch die Art der Synchronisierung mit der Serverzeit. 
	Wirkt sich derzeit hauptsächlich auf Flash aus
	
	* 1: Default-Zustand: Die Zeitinformation für die Synchronisierung wird aus den Response-Headern ausgelesen und an den Maongo-Client weitergereicht.
	     Der erste Abruf der state.xml wird in Flash mittels eines AJAX-Aufrufs aus der einbindenden HTML-Seite gestartet.
	     Updates bzw. die Channel-Dateien liegen in einem Verzeichnis http://meinserver.de/states/channel-123.xml
	* 2: Die Zeitinformation für die Synchronisierung wird aus den Response-Headern ausgelesen und an den Maongo-Client weitergereicht.
	     Der erste Abruf der state.xml wird in Flash mittels eines AJAX-Aufrufs aus der einbindenden HTML-Seite gestartet.
	     Updates bzw. die Channel-Dateien liegen in einem Verzeichnis http://meinserver.de/channel-123.xml
	* 3: Die Zeitinformation für die Synchronisierung wird aus der geladenen ersten state.xml ausgelesen.
	     Der erste Abruf der state.xml wird direkt aus Flash gestartet. In der initial abgerufenen state.xml muss ein Attribut `time="123"`enthalten sein.
	     Updates bzw. die Channel-Dateien liegen in einem Verzeichnis http://meinserver.de/channel-123.xml
	
	Default: ``1`` 
	
**UseFirstXML** (Boolean)
	Sofern diese Property auf ``true`` gesetzt wird, erfolgt der erste Abruf der ``state.xml`` nicht auf die Datei ``state.xml`` sondern auf eine Datei ``first.xml``, welche
	unter dem gleichen Pfad wie ``state.xml`` erreichbar sein muss. Dieser Aufruf kann für Trackingzwecke genutzt werden, da dieser Aufruf pro aktivem Client nur einmal erfolgt.
	
	
	Default: ``false`` 
	
Signals
------------

**transmission-start** (Transmission)


**transmission-data** (Data)


**transmission-end** (Transmission)
	


Das Peking-Protokoll
--------------------------

Das Peking-Protokoll dient dazu, eine grosse Anzahl von Clients mit einem Datensatz zu versorgen und diese Clientdaten synchron mit dem Originaldatensatz zu halten.

Wichtig sind:
Geschwindigkeit: Die Synchronisierung muss schnell passieren.
Skalierbarkeit: Das Protokoll kann durch übliche Lastverteilungen hindurch (Akamai) viele zehntausend Clients versorgen.
Zuverlässigkeit: Alle Clients bleiben synchron mit dem Originaldatensatz


Ein Datensatz heisst Channel. Er beinhaltet ein oder mehrere Data-Elemente, die im Rahmen des PP versioniert werden. 

Nach einer ersten Versorgung eines Clients mit einem Basisdatensatz (“channel-123.xml”) lädt dieser weitere Daten noch inkrementell als Updates nach (“update-124.xml”, “update-125.xml”, ...)

Der aktuelle Zustand eines Channels heisst “state” und wird in einer Datei “state.xml” verwaltet.


Ablauf einer Client-Channel Kommunikation

1) Kontaktaufnahme
Der Client lädt die state.xml so, dass jeder Cache umgangen wird, üblicherweise mit einem Zufalls-Parameter. http://my.server.com/mychannel/state.xml?8376452836487246282364
Der Client wertet das von Server zurückgegebene “Date” Field im http-header aus um einen Offset zwischen der eigenen Zeit und der Serverzeit zu errechnen.

2) Basisdaten
In der state.xml findet der Client die aktuelle serial-number des Channels (z.B.42). Er kann den entsprechenden Basisdatensatz jetzt aus der datei “channel-42.xml” laden.

3) Polling
In regelmässigen Abständen pollt der Client die state.xml. Er verwendet dabei eine modifizierte Serverzeit als parameter. Diese errechnet sich wie folgt:

Die Serverzeit in sekunden (seit 1970) wird errechnet aus eigener Zeit und Serveroffset.
Die letzten 6 (5/7) bits werden auf 0 gesetzt, so dass sich der Parameter alle 32 (16/64) sekunden ändert.

Wird eine neue serial-number im state.xml gefunden, so muss der Client jedes Update zwischen seiner aktuellen lokalen version und der im state.xml angegebenen serial laden.
 

Peking II

Neu: Pro Channel ein Verzeichnis, alle Dateien liegen darin.

state.xml - wie bisher, aber jetzt im Verzeichnis
channel.xml - eine kopie der aktuellsten channel.xml

channel-123.xml
update-123.xml

Inhalt der state.xml

Minimal:
<state serial=”123” protocol=”2”/>

Angabe der lifetime als zweierpotenz:
<state serial=”123” protocol=”2” lt=”5”/>

Angabe des Poll-Interval in sekunden
<state serial=”123” protocol=”2” pi=”30”/>