WebserviceTool (für Android) ist ein generischer XML Webservice Klient für SOAP und REST Webservices. Es gibt viele Webservices mit Informationen über Wetter, Aktienkurse, Sportergebnisse, Länder, etc. Mit WebserviceTool können Sie diese Informationen einfach und schnell auf Ihr Smartphone holen.

WebserviceTool

Was ist WebserviceTool?
Webservice definieren
Anfrage bearbeiten
HTML Ansicht
Anfrage ausführen
Verknüpfung erstellen
Rechtliches

1. Was ist WebserviceTool ?

WebserviceTool (im Folgenden die "APP" genannt) ist ein generischer XML Webservice Klient für SOAP und REST Webservices. Es gibt viele Webservices mit Informationen über Wetter, Aktienkurse, Sportergebnisse, Länder, etc. Mit WebserviceTool können Sie diese Informationen einfach und schnell auf Ihr Smartphone holen.

Das Programm hat folgende Leistungsmerkmale:

• Läuft auf Android 2.2 oder höher (Smartphone / Tablet)
• Unterstützt SOAP (1.1 and 1.2) und REST Webservices.
• Die SOAP Anfragen (und vor allem deren Anfragedaten) können automatisch aus der WSDL generiert werden (nur bei 1.1 WSDLs mit document/literal style)
• Unterstützt Webservices mit Basic Authorization
• Unterstützt WSHttpBinding (SOAP 1.2)
• Unterstützt WS-Addressing
• Unterstützt HTTPS Server mit und ohne beglaubigte Zertifikate. Unbeglaubigte Zertifikate können anhand ihres Fingerabdrucks geprüft werden.
• Die Webservice Definitionsdateien (*.wst2) können verschlüsselt gespeichert werden.
• Die XML Antwort des Webservices wird als Baum, Tabelle und in XML Form angezeigt. Die Daten können in die Zwischenablage kopiert werden.
• Die XML Antwort kann in einer HTML Ansicht angezeigt werden, welche mittels XSLT Vorlagen vollständig durch den Benutzer definierbar ist.
• Wenn die Antwort im JSON Format ist, wird sie automatisch in XML konvertiert.
• Anfragen können verknüpft und von der Android Startseite aus gestartet werden.
• Zur Fehlersuche und -behebung kann der Benutzer in den Einstellungen die Log Stufe auf DEBUG setzen, worauf die APP viele Informationen im catlog ausgibt, welche helfen können das Problem zu beseitigen (zur Anzeige wird eine separate catlog App benötigt).
• Batterie-schonendes dunkles Farbschema

zum Anfang

2. Webservice definieren

2.1 Automatisches Erstellen der SOAP Webservice Definition

Wenn Sie die WSDL eines SOAP Webservices haben, kann die APP die Anfragen automatisch aus der WSDL generieren:

1. Wählen Sie die Menüoption "Webservice | Neuer Webservice" um die Webservice Activity zu öffnen.
2. Webservice Verzeichnis: Wählen Sie das Verzeichnis, in welchem Sie die Webservice Definitionsdatei (*.wst2) speichern wollen
3. Name: Geben Sie den Namen des Webservice ein. Der Name wird als Dateiname für die .wst2 Datei verwendet.
4. Beschreibung: Geben Sie eine Beschreibung für diesen Webservice ein (optional).
5. URL: Geben Sie URL des Webservice Endpunktes ein (optional). Wenn Sie die URL hier nicht eingeben, werden Sie später danach gefragt. Also ist es am besten, die URL gleich hier einzugeben.
6. Benutzer: Geben Sie den Benutzernamen ein, falls der Webservice HTTP-BasicAuthorization verwendet.
7. Passwort: Geben Sie das Passwort ein, falls der Webservice HTTP-BasicAuthorization verwendet.
8. Klicken Sie auf die Schaltfläche "Webservice erstellen von WSDL".
9. In der WSDL Activity können Sie die WSDL vom Internet herunterladen. Wenn Sie die WSDL bereits heruntergeladen haben, werden gleich die verfügbaren Operationen angezeigt.
10. Wählen Sie die Operationen, für welche die APP Anfragen generieren soll und wählen Sie die Menüoption "Hinzufügen/aktualisieren von WSDL". Wählen Sie nur Operationen aus dem gleichen Binding (SOAP 1.1 oder SOAP 1.2 Binding). Operationen aus unterschiedlichen Bindings können nicht gemischt werden.
11. Zurück in der Hauptactivity können Sie (optional) die Anfragedaten durch Langdrücken anpassen (siehe manuelles Vorgehen unten).

Wenn Sie die WSDL nicht herunterladen können, Sie aber die WSDL als Datei haben, gehen Sie wie folgt vor: Kopieren Sie die WSDL Datei in das Webservice Verzeichnis und benennen Sie die Datei gleich wie die Webservice Definitionsdatei, aber mit der Extension .wsdl. Beispiel: Wenn die Webservice Definitionsdatei /sdcard/ws/service1.wst2 heisst, dann speichern Sie die WSDL Datei als /sdcard/ws/service1.wsdl. Dann drücken Sie in der Hauptactivity lange auf eine Anfrage und wählen "Verwalten | Hinzufügen/aktualisieren von WSDL".

zum Anfang

2.2 SOAP Webservice Definition manuell erstellen

Wenn Sie keine WSDL haben oder der WSDL Typ von der APP nicht unterstützt ist, können Sie den Webservice trotzdem verwenden, indem Sie die Definitionen manuell erstellen.

1. Folgen Sie den Schritten 1 bis 7 des automatischen Vorgehens von oben.
2. Kodierung: Wählen Sie die korrekte Kodierung (normalerweise UTF-8)
3. Webservice Typ: Wählen Sie "SOAP"
4. Binding: Wählen Sie "BasicHttp" für SOAP 1.1 oder "WsHttp" für SOAP 1.2
5. Zertifikat Fingerabdruck (SHA1): Lassen Sie dieses Feld normalerweise LEER! Wenn der Webservice HTTPS verwendet, aber der Zertifizierungspfad nicht verifiziert werden kann, geben Sie hier den Fingerabdruck des Zertifikates ein (zum Beispiel 86:19:d4:94:7c:f1:f9:71:9a:f4:aa:43:33:e1:d5:47:a1:db:b9:12). Wenn der Fingerabdruck nicht mit dem Fingerabdruck übereinstimmt, den die APP vom Webservice empfängt, wird die Anfrage aus Sicherheitsgründen abgebrochen (Sie kommunizieren dann wahrscheinlich mit einem falschen Webservice!)
6. Zeige Attribute im Baum: Wenn Sie diese Option markieren, werden alle XML Attribute der Antwort im Baum als eigene XML Elemente angezeigt. Dies ist für gewisse REST Webservices nützlich.
7. Drücken Sie "Speichern" (oder "Abbrechen" um nicht zu speichern).
8. Zurück in der Hauptactivity drücken Sie lange auf die Anfrage "Neue Anfrage" und bearbeiten die Anfrage.

zum Anfang

2.3 REST Webservice Definition erstellen

Folgen Sie den gleichen Schritten wie beim manuellen Vorgehen für SOAP Webservices, aber mit folgenden Änderungen:

1. URL: Geben Sie die Basis URL für diesen REST Webservice ein. Die Basis URL ist derjenige Teil der URL, welcher für alle Anfragen gleich ist.
2. Webservice Typ: Wählen Sie "REST"
3. Binding: Wählen Sie das korrekte Binding, wahrscheinlich "BasicHttp"

zum Anfang

3. Anfrage bearbeiten

3.1 SOAP Anfrage bearbeiten

Um SOAP Anfragen zu bearbeiten, gehen Sie wie folgt vor:

1. In der Hauptactivity drücken Sie lange auf die Anfrage und wählen "Verwalten | Bearbeiten". Dies öffnet die Anfrageactivity.
2. Name: Geben Sie den Namen der Anfrage ein. Sie können einen beliebigen Namen verwenden.
3. Beschreibung: Geben Sie eine Beschreibung für die Anfrage ein (optional).
4. Benutzer: Geben Sie den Benutzernamen ein, falls der Webservice HTTP-BasicAuthorization verwendet. Wenn das Feld leer bleibt, wird der Benutzer verwendet, welcher beim Webservice definiert wurde.
5. Passwort: Geben Sie das Passwort ein, falls der Webservice HTTP-BasicAuthorization verwendet. Wenn das Feld leer bleibt, wird das Passwort verwendet, welches beim Webservice definiert wurde.
6. HTTP Befehl: Wählen Sie "POST"
7. SOAP Aktion: Geben Sie die korrekte SOAP Aktion ein
8. HTTP Custom Header Felder: Hier können Sie zusätzliche HTTP Header Felder eingeben in der Form Name:Inhalt
9. Anfragedaten: Drücken Sie diese Schaltfläche, um die POST Daten einzugeben, welche zum Webservice geschickt werden sollen. Das GUI für die Eingabe der Anfrage Parameter wird automatisch anhand der Anfragedaten aufgebaut: Alle XML Elemente mit dem Attribut wst_title werden dem Benutzer zur Eingabe angezeigt, bevor die Anfrage an den Webservice geschickt wird. Der Wert des Attributes wird als Titel für das Eingabefeld verwendet. Das Attribut wird nach der Dateneingabe aus den POST Daten entfernt, bevor diese an den Webservice geschickt werden. Wenn Sie ein Eingabefeld im GUI unterdrücken wollen, entfernen Sie das Attribut wst_title aus den Anfragedaten. Das Feld wird dann zwar an den Webservice geschickt, im GUI aber nicht angezeigt.
10. XSLT Daten für HTML Ansicht: Drücken Sie diese Schaltfläche, um die XSLT Daten einzugeben, welche das Aussehen der HTML Ansicht definieren. Sind die XSLT Daten noch nicht definiert, verwendet die APP die Standartvorlage XSLT-default.xsl aus dem Arbeitsverzeichnis (siehe Menüpunkt 'Infos')
11. Standard Ansicht: Dies definiert die Standard Ansicht, in welcher die XML Antwort angezeigt wird.
12. Tabellenansicht auf Element: Für die Standard Ansicht 'Tabelle' definiert dies den XPath des Elements, welches zusammen mit all seinen Geschwister-Elementen in Tabellenform dargestellt werden soll. Sie erhalten den XPath im Kontextmenü des Antwortbaumes.
13. Auto Speichern der Anfrage Daten: Aktivieren diese Option, wenn die APP sich die im dynamischen GUI eingegebenen Daten merken soll.

zum Anfang

3.2 REST Anfrage bearbeiten

REST Webservices können neben dem POST Befehl weitere HTTP Befehle verwenden. Sie verwenden normalerweise GET, um Daten abzurufen und PUT oder POST, um Daten zu senden. Daten können als URL Parameter oder als PUT/POST Daten gesendet werden. Die Anfragen werden gleich definiert wie bei SOAP Anfragen, aber mit folgenden Abweichungen:

1. HTTP Befehl: Wählen Sie den richtigen Befehl
2. Anfragedaten: Die Anfragedaten werden als XML Daten mit folgender Struktur definiert: Das Wurzelelement kann beliebig benannt werden und kann folgende 3 Subelemente enthalten:
   • relativeURL: Dieses Element wird normalerweise immer benötigt. Die Subelemente dieses Elementes können beliebig benannt werden. Die URL wird später anhand der Werte der Subelemente aufgebaut.
   • parameters: Fügen Sie dieses Element hinzu, wenn Sie URL Parameter übergeben wollen. Die Namen der Subelemente müssen dem Parameternamen entsprechen. Der Wert des Subelements wird dann als Wert des entsprechenden Parameters geschickt.
   • POSTdata: Fügen Sie dieses Element hinzu, wenn Sie Daten mit dem PUT oder POST Befehl schicken wollen. Die Subelemente müssen der Spezifikation des REST Webservices entsprechen.

Untenstehend ist ein Beispiel für das Pivotal Tracker API (http://www.pivotaltracker.com/help/api).

<PivotalTracker>
  <relativeURL>
    <part1>projects</part1>
    <part2 wst_title="Project number:">1234</part2>
    <part3>stories</part3>
  </relativeURL>
  <parameters>
    <token wst_title="Security token:">010203040506070809A0</token>
  </parameters>
  <POSTdata>
    <story>
      <story_type wst_title="Story type:">feature</story_type>
      <name wst_title="Story name:">User Story 123</name>
      <requested_by wst_title="Requestor:">Tom Arn</name>
      <description wst_title="Story description:">This is the user story number 123</description>
    </story>
  </POSTdata> 
</PivotalTracker>

Wenn Sie die (Basis) URL für diesen Webservice als https://www.pivotaltracker.com/services/v3 definieren, wird mit den obigen Anfragedaten ein dynamisches GUI erzeugt, wo Sie die relativen Teile der URL, die URL Parameter und die POST Daten eingeben können. Wenn die Anfrage an den Webservice geschickt wird, wird folgender HTTP Rohcode gesendet:

POST /services/v3/projects/1234/stories?token=010203040506070809A0 HTTP/1.1
Host: www.pivotaltracker.com
Content-Type: text/xml; charset=utf-8
Content-Length: 181

<story>
  <story_type>feature</story_type>
  <name>User Story 123</name>
  <requested_by>Tom Arn</name>
  <description>This is the user story number 123</description>
</story>

zum Anfang

4. HTML Ansicht

Die HTML Ansicht ist für fortgeschrittene Benutzer, welche die Darstellung der XML Antwort individuell gestalten wollen. Sie können die Extensible Stylesheet Language Transformation (XSLT) verwenden, um zu definieren, welche Daten in der HTML Ansicht angezeigt werden sollen und wie diese Daten dargestellt werden sollen. In den mitgelieferten Webservices (samples) finden Sie einige XSLT Beispiele.

4.1 Andere Anfragen starten

Die HTML Ansicht unterstützt JavaScript und das Android JavaScript Interface. Mit dem JavaScript Interface können Sie aus der HTML Ansicht andere Anfragen starten und Daten in deren dynamische GUI Activity übergeben. Definieren Sie Ihr JavaScript wie folgt:

<script type="text/javascript">
function launchRequestXYZ(data)
{
  WebserviceTool.invokeRequest("1353517041646",data);
}
</script>

Der erste Parameter der Methode invokeRequest ist die eindeutige ID der aufzurufenden Anfrage. Sie sehen diese ID, wenn Sie die Anfrage bearbeiten. Der zweite Parameter ist ein String, welcher die Daten enthält. Wenn Sie mehr als einen String übergeben wollen, können Sie Strings mit ~ abtrennen, z.B. "data1~data2~data3".

Der Link zum Aufrufen des Skripts könnte wie folgt aussehen:

<a href="#" onClick="javascript:launchRequestXYZ('{elementABC/@attrX}')">
<xsl:value-of select="elementABC/@attrX"/></a>

Dieser Link verwendet XSL, um den Wert des Attributs attrX des Elements elementABC zu holen, ruft das Skript launchRequestXYZ auf und übergibt ihm die Daten.

Andere Apps starten

Aus der HTML Ansicht können Sie auch andere Apps starten, indem Sie URLs verwenden, welche implizite Intents aufrufen. Um eine Geo Lokalisierungsapp wie Google Maps zu starten, können Sie folgenden Link verwenden:

<a href="geo: {position/@lat},{position/@lng}?z=18">
<xsl:value-of select="position/@lat"/>, <xsl:value-of select="position/@lng"/></a>

Dieser Link verwendet XSL, um den geografischen Standort aus den Attributen lat und lng des Elements position zu holen und startet mit diesen Daten eine Geo Lokalisierungsapp.

zum Anfang

5. Anfrage ausführen

Um eine Anfrage auszuführen, gehen Sie wie folgt vor:

1. Öffnen Sie einen bestehenden Webservice oder erstellen Sie einen neuen.
2. Drücken Sie lange auf eine Anfrage im Reiter "Anfragen"
3. Wählen Sie "Ausführen". Dies öffnet das dynamische GUI.
4. Geben Sie die Eingabedaten ein und drücken Sie "OK" (zum Abbrechen drücken Sie "ESC")
5. Die Antwort des Webservice wird im Reiter "Antwort (Baum)" und "Antwort (XML)" angezeigt.
6. Wiederholte Elemente können als Tabelle dargestellt werden. Drücken Sie hierzu lange auf ein beliebiges dieser Elemente und wählen Sie "Tabellen Ansicht"

zum Anfang

6. Verknüpfung erstellen

Um eine Anfrage direkt von der Startseite zu starten gehen Sie wie folgt vor:

1. Auf der Startseite wählen Sie "Verknüpfung erstellen" und wählen Sie "WebserviceTool". Dies öffnet die Shortcut Activity der APP.
2. Wählen Sie eine Webservice Definitionsdatei (*.wst2). Die verfügbaren Anfragen werden nun in das Anfragen Dropdown geladen.
3. Im Dropdown wählen Sie eine Anfrage oder den leeren Eintrag, wenn die Verknüpfung nur die .wst2 Datei öffnen soll (ohne eine Anfrage auszuführen)
4. Geben Sie den Namen ein, welcher bei der Verknüpfung angezeigt werden soll und drücken Sie OK.

Beim Erstellen einer Verknüpfung wird eine eindeutige VerknüpfungsID erstellt, welche sicherstellt, dass die Verknüpfung die definierte Anfrage immer findet, auch wenn die Anfrage umbenannt oder in der Liste an eine andere Position verschoben wird.

zum Anfang

7. Rechtliches

Vielen Dank, dass Sie sich für diese SOFTWARE entschieden haben! Sie dürfen die SOFTWARE nur nutzen, wenn Sie mit den nachfolgenden Bestimmungen einverstanden sind:

URHEBERRECHT
Diese SOFTWARE wurde durch Tanapro GmbH (Tom Arn), www.tanapro.ch, (im folgenden AUTOR genannt) entwickelt. Alle Rechte vorbehalten.

KEINE GEWÄHRLEISTUNG
Die SOFTWARE wird im Ist-Zustand ausgeliefert. Der AUTOR lehnt jede Haftung ab, ob ausdrücklich oder gesetzlich, einschliesslich der Garantien der Handelbarkeit und der Eignung für einen bestimmten Zweck. Der AUTOR übernimmt keine Garantie dafür, dass die Software ausfallsicher oder fehlerfrei ist. Der Benutzer muss bei der Verwendung der SOFTWARE sämtliches Risiko übernehmen.

KEINE SCHADENHAFTUNG
Der AUTOR übernimmt keine Haftung für Schäden oder Folgeschäden, direkt oder indirekt, die aufgrund der Verwendung (oder der Unmöglichkeit der Verwendung) der SOFTWARE entstehen könnten, auch wenn der AUTOR über die Möglichkeit solcher Schäden in Kenntnis gesetzt worden ist.

zum Anfang