Besteht eine Verbindung zum Server, muß man sich zuerst anmelden, um weitere Serverkommandos benutzen zu können. Das geschieht mit der Methode login(). Diese Methode benötigt einige Parameter, von denen nur der user Pflicht ist.
Nach erfolgreicher Anmeldung gibt die Methode die vom Server vergebene eindeutige SessionId als String zurück.
Mit der Anmeldung wird zwischen Client und Server auch die zu verwendende API Version ausgehandelt, siehe API Version weiter unten.
| Typ Parameter | Pflicht | Beschreibung |
|---|---|---|
| String user | J | Benutzername |
| String configuration | N | Pfad zur DLE Session Konfigurationsdatei. Keine Angabe verwendet die DLESessionConfig.xml. Ein ~ am Anfang des Dateinamens dient als Platzhalter für das DLE Installationsverzeichnis. Relative Pfade sind nicht erlaubt. Alle anderen Angaben sind relativ zum client/ Verzeichnis der DLE. |
| Locale locale | N | Sprach/Ländereinstellung, die verwendet werden soll. Keine Angabe verwendet die aktuelle Einstellung. |
| Sring businessClientId | N | Die Mandantenkennung, keine Angabe verwendet die 1. |
| String previousSessionId | N | Wurde vorher ein logout() mit keepSession = true gemacht, kann hier die vorher benutzte SessionId übergeben werden. Der Server benutzt dann die zuvor erstellte Session weiter. |
| Map parameters | N | Eine optionale weitere Liste von Parametern. Wird für die Anmeldung selbst nicht verwendet. Der Client ergänzt die Liste automatisch um den Parameter ApiVersionRequested, dieser darf nicht überschrieben werden. |
Mögliche Exceptions:
- IOException – Kommunikationsfehler
- DLEUnknownMessageTypeException – Server hat eine unbekannte Nachricht erhalten
- DLEServerException – Interner Server Fehler
- DLELoginFailedException – Login ist fehlgeschlagen
- DLEUnexpectedAnswerException – Der Client hat eine unbekannte Antwort erhalten
API Version
Verfügbar ab DLE-Version 2.3.0.005 ff.
Die API Version bestimmt, wie die Werte innerhalb einer Nachricht maskiert werden. Sie wird bei der Anmeldung ausgehandelt: Der Client fordert mit dem Parameter ApiVersionRequested im Login Request eine Version an, der Server bestätigt die tatsächlich verwendete Version mit dem Parameter API_VERSION in der Login Antwort. Beide Parameter werden vom Client automatisch gesetzt bzw. ausgewertet, es ist dafür kein eigener Aufrufparameter nötig.
| Parameter | Nachricht | Beschreibung |
|---|---|---|
| ApiVersionRequested | Login Request | Die vom Client gewünschte API Version. Die erste Version hat keine Kennung, die zweite Version wird mit "A" angefordert. Kennt der Server die angeforderte Version nicht, bleibt die Verbindung auf der ersten Version. |
| API_VERSION | Login Ack | Die vom Server bestätigte API Version. Wird der Parameter nicht zurückgegeben, verwendet die Verbindung die erste Version. |
Die Versionen unterscheiden sich in der Maskierung der Werte. Nachrichten sind in Tokens der Form Name=Wert aufgebaut, die durch einen Pipe (|) getrennt werden. Enthält ein Wert selbst einen Pipe, muß dieser maskiert werden.
| Version | Maskierung | Beschreibung |
|---|---|---|
| Erste Version (ohne Kennung) | | wird zu \| | Nur der Pipe wird maskiert, der Backslash selbst nicht. Ein Wert, der mit einem Backslash endet, maskiert daher das Trennzeichen und zerstört die Nachricht. Werte mit Backslashes können nicht zuverlässig übertragen werden. |
| Zweite Version ("A") | | wird zu \| und \ wird zu \\ | Auch der Backslash wird mit einem zusätzlichen Backslash maskiert. Innerhalb eines Tokens steht damit nur noch \| für einen Pipe. Alle Werte werden unverändert übertragen, unabhängig von Pipes und Backslashes. |
Beispiel für den Wert C:\temp\datei.txt|D:\daten in der zweiten Version:
PARAM=C:\\temp\\datei.txt\|D:\\daten|
Hinweise:
- Die Aushandlung ist in beide Richtungen kompatibel: Ein alter Client sendet den Parameter ApiVersionRequested nicht und bleibt auf der ersten Version. Ein neuer Client an einem alten Server erhält keinen Parameter API_VERSION zurück und bleibt ebenfalls auf der ersten Version.
- Der Login Request und die Login Antwort selbst werden immer noch mit der Maskierung der ersten Version übertragen, da die Version zu diesem Zeitpunkt noch nicht feststeht. Erst alle darauf folgenden Nachrichten verwenden die ausgehandelte Version. Werte der Anmeldeparameter sollten daher keine Backslashes am Ende enthalten.
- Wurde die zweite Version ausgehandelt, ist das erste Zeichen der zurückgegebenen SessionId die Versionskennung "A" anstelle einer Ziffer. Die SessionId ist unverändert als undurchsichtige Zeichenkette zu behandeln.
- Ein eigener Client, der nicht die mitgelieferte Client-Bibliothek verwendet, muß die Maskierung der zweiten Version selbst umsetzen, bevor er sie anfordert: beim Senden Backslash und Pipe maskieren, beim Lesen ein Trennzeichen nur dann als solches werten, wenn ihm eine gerade Anzahl Backslashes vorausgeht.
- Ein Wert der ausschließlich aus dem Trennzeichen besteht, also nur ein Pipe, ist ebenfalls zulässig.