4D v14.3

SOAP DECLARATION

Home

 
4D v14.3
SOAP DECLARATION

SOAP DECLARATION 


 

SOAP DECLARATION ( Variablenname ; Typ ; Input_Output {; Alias} )  
Parameter Typ   Beschreibung
Variablenname  Variable in Variable für ein bzw. ausgehendes SOAP Argument
Typ  Lange Ganzzahl in 4D Typ, auf den das Argument zeigt
Input_Output  Lange Ganzzahl in 1 = SOAP Input, 2 = SOAP Output
Alias  String in Name, der während SOAP Austausch für dieses Argument veröffentlicht wird

Der Befehl SOAP DECLARATION deklariert explizit den SOAP Typ der Parameter in einer 4D Methode, die als Web Service veröffentlicht wird.

Wird eine Methode als ein Web Service veröffentlicht, werden die Standardparameter $0, $1... $n verwendet, um die Parameter des Web Service für die Außenwelt zu beschreiben, insbesondere in der WSDL Datei. Für das SOAP Protokoll müssen Parameter explizit benannt werden; 4D verwendet standardmäßig die Namen “FourD_arg0, FourD_arg1 ... FourD_argn”.

Diese Standardoperation kann jedoch aus folgenden Gründen problematisch sein:

  • Es ist nicht möglich, $0 oder $1, $2, etc. als Array zu deklarieren. Dafür sind Zeiger erforderlich; in diesem Fall muss jedoch zum Erzeugen der WSDL Datei die Art der Werte bekannt sein.
  • Es kann hilfreich oder notwendig sein, die Parameternamen anzupassen (eingehend und ausgehend).
  • Sie wollen Parameter wie XML Strukturen und DOM Referenzen verwenden.
  • Es kann auch notwendig sein, Werte größer als 32 000 Zeichen zurückzugeben (Limit für Textargumente in Datenbanken, die im Nicht-Unicode Modus laufen).
  • Schließlich macht es diese Operation unmöglich, in $0 mehr als einen Wert pro RPC Aufruf zurückzugeben.

Mit dem Befehl SOAP DECLARATION unterliegen Sie nicht diesen Einschränkungen. Sie können diesen Befehl für jeden ein- und ausgehenden Parameter ausführen und ihm einen Namen und einen Typ zuweisen.

Hinweis: Auch bei Verwendung dieses Befehls müssen Sie 4D Variablen und Arrays in der Methode "Compiler_Web" immer mit Befehlen aus dem Kapitel Compiler deklarieren.

In Variablenname übergeben Sie die 4D Variable, auf die im RPC Aufruf verwiesen wird.

Achtung: Sie können auf Prozessvariablen oder Parameter in 4D Methoden ($0 to $n) verweisen. Lokale und Interprozessvariablen können Sie nicht verwenden.

Da SOAP nur Texte vom Typ Argument verwenden kann, sind Antworten vom SOAP Server in Datenbanken, die im Nicht-Unicode Modus laufen, auf 32 KB begrenzt. Über BLOBs können Sie jedoch SOAP Argumente größer als 32 KB zurückgeben. Dazu müssen Sie lediglich vor Aufrufen von SOAP DECLARATION die Argumente als BLOBs deklarieren (siehe Beispiel 4).

Hinweis: Abonnieren Sie auf Client-Seite diese Art von Web Service mit 4D, generiert der Web Services Assistent eine Variable vom Typ Text. Um sie zu verwenden, müssen Sie lediglich die zurückgegebene Variable in der Proxy-Methode als BLOB typisieren.

In Typ übergeben Sie den entsprechenden 4D Typ. Sie können die meisten Arten von 4D Variablen und Arrays verwenden. Sie können die vordefinierten Konstanten unter dem Thema Feld und Variablentypen einsetzen:

Konstante Typ Wert
Boolean array Lange Ganzzahl 22
Date array Lange Ganzzahl 17
Integer array Lange Ganzzahl 15
Is BLOB Lange Ganzzahl 30
Is Boolean Lange Ganzzahl 6
Is date Lange Ganzzahl 4
Is integer Lange Ganzzahl 8
Is LongInt Lange Ganzzahl 9
Is real Lange Ganzzahl 1
Is string var Lange Ganzzahl 24
Is text Lange Ganzzahl 2
Is time Lange Ganzzahl 11
LongInt array Lange Ganzzahl 16
Real array Lange Ganzzahl 14
String array Lange Ganzzahl 21
Text array Lange Ganzzahl 18

sowie für XML Typen Konstanten unter dem Thema Web Services (Server):

Konstante Typ Wert
Is DOM reference Lange Ganzzahl 37
Is XML Lange Ganzzahl 36

In Input_Output übergeben Sie einen Wert, der anzeigt, ob der bearbeitete Parameter “eingehend” (z.B. Wert, den eine Methode empfängt) oder “ausgehend” (z.B. Wert, den eine Methode zurückgibt) ist. Sie können die vordefinierten Konstanten für SOAP unter dem Thema Web Services (Server) einsetzen:

Konstante Typ Wert
SOAP input Lange Ganzzahl 1
SOAP output Lange Ganzzahl 2

Über die Konstanten Is XML und Is DOM reference können Sie Variablen vom Typ "XML Struktur" und "DOM Referenz" deklarieren, sowohl eingehend wie ausgehend. Bei Parametern dieses Typs erfolgt keine Bearbeitung oder Codierung. Die Daten werden unverändert gesendet (siehe Beispiel 5).

  • Ausgehende Parameter:
    • Is XML gibt an, dass der Parameter eine XML Struktur enthält,
    • Is DOM reference gibt an, dass der Parameter die DOM Referenz einer XML Struktur enthält. In diesem Fall ist das Einfügen der XML Struktur in die SOAP Meldung dasselbe wie Ausführen des Befehls DOM EXPORT TO VAR.
Hinweis: Werden DOM Referenzen als ausgehende Parameter verwendet, sollten Sie globale Referenzen einsetzen, die z.B. beim Startup erstellt werden und sich schließen, wenn das Programm geschlossen wird. Denn eine DOM Referenz, die im Web Service selbst angelegt wird, lässt sich nicht mit DOM CLOSE XML schließen, da sonst der Web Service nichts mehr zurückgeben würde. Das mehrfache Aufrufen eines Web Dienstes führt deshalb auch dazu, dass mehrere nicht-geschlossene DOM Referenzen erstellt werden, was zu einer Speicherüberlastung führen kann.
  • Eingehende Parameter:
    • Is XML gibt an, dass der Parameter ein vom SOAP Client gesendetes XML Argument empfangen soll.
    • Is DOM reference gibt an, dass der Parameter die DOM Referenz einer XML Struktur empfangen soll, die dem vom SOAP Client gesendeten XML Argument entspricht.
  • Veränderung der WSDL Datei: 4D deklariert diese XML Strukturen in der WSDL als "jeder Typ" (unbestimmt). Wollen Sie eine XML Struktur genauer deklarieren, müssen Sie die WSDL Datei sichern und das gewünschte Datenschema im Abschnitt <types> der WSDL manuell hinzufügen.

Eingehende SOAP Argumente, die über 4D Variablen, also nicht über Argumente von 4D Methoden aufgerufen werden, müssen Sie zuerst über die Projektmethode "Compiler_Web" deklarieren. Setzen Sie in Methoden für Web Services Prozessvariablen ein, müssen diese deklariert sein, bevor die Methode aufgerufen wird. Die Projektmethode "Compiler_Web" wird – sofern vorhanden – für jede akzeptierte SOAP Anfrage aufgerufen. Die Methode "Compiler_Web" ist standardmäßig nicht vorhanden. Sie müssen diese explizit anlegen.

Der 4D Web Server ruft "Compiler_Web" auch auf, wenn er “konventionelle” Web Anfragen vom Typ POST erhält. Weitere Informationen dazu finden Sie im Abschnitt SPELL GET DICTIONARY LIST.

In Alias übergeben Sie den Argumentnamen, wie er in WSDL und SOAP Austauschaktionen erscheinen muss.

Achtung: Dieser Name muss im RPC Aufruf einmalig sein (Eingabe- und Ausgabeparameter zusammengenommen), ansonsten berücksichtigt 4D nur die letzte Deklaration.

Hinweis: Die Namen dürfen in Anlehnung an die XML Standards für Marker-Namen WEDER Leerzeichen NOCH Zeichen aus dem erweiterten ASCII-Satz enthalten. Nur Zeichen des Latin-Satzes sind zulässig ([A-Za-z0-9._] | '-')*.

Übergeben Sie keinen Parameter in Alias, verwendet 4D standardmäßig den Namen der Variablen oder FourD_argN für die Argumente der 4D Methode ($0 to $n).

Hinweis: Der Befehl SOAP DECLARATION muss innerhalb der Methode liegen, die als Web Service veröffentlicht wird. Er lässt sich nicht über eine andere Methode aufrufen.

Dieses Beispiel gibt den Parameternamen an:

  ` In der Methode COMPILER_WEB
 C_LONGINT($1)
 
  ` In der Methode Web Service
  ` Beim Erzeugen der WSDL Datei und SOAP Aufrufe wird das Wort
  ` PLZ anstelle von fourD_arg1verwendet.
 C_LONGINT($1)
 SOAP DECLARATION($1;Is LongInt;SOAP input;"PLZ")

Dieses Beispiel findet ein Array mit Postleitzahlen in Form von langen Ganzzahlen:

  ` Setzen Sie in die Methode "Compiler_Web"
 ARRAY LONGINT(codes;0)
 
  ` In der Service Methode
 SOAP DECLARATION(codes;LongInt array;SOAP input;"in_codes")

Dieses Beispiel verweist auf zwei zurückgegebene Werte ohne Angabe eines Argumentnamens:

 SOAP DECLARATION(ret1;Is LongInt;SOAP output)
 SOAP DECLARATION(ret2;Is LongInt;SOAP output)

Dieses Beispiel ermöglicht dem 4D SOAP Server, ein Argument größer als 32 KB in Datenbanken im Nicht-Unicode Modus zurückzugeben:

 C_BLOB($0)
 SOAP DECLARATION($0;Is text;SOAP output)

Beachten Sie, dass der Typ Is Text und nicht Is BLOB ist. So lässt sich das Argument korrekt bearbeiten.

Nachfolgendes Beispiel zeigt die Ergebnisse der verschiedenen Deklarationstypen:

 ALL RECORDS([Contact])
  `XML Struktur aus der Auswahl Contact erstellen
  `und die XML in einem BLOB speichern
 C_BLOB(ws_vx_xmlBlob)
 getContactsXML(->ws_vx_xmlBlob)
  `Die XML Struktur in einer Textvariablen wiederfinden
 C_TEXT(ws_vt_xml)
 ws_vt_xml:=BLOB to text(ws_vx_xmlBlob;UTF8 text without length)
  `Eine DOM Referenz auf die XML Struktur wiederfinden
 C_TEXT(ws_vt_xmlRef)
 ws_vt_xmlRef:=DOM Parse XML variable(ws_vt_xml)
  `Die verschiedenen Deklarationen testen
 SOAP DECLARATION(ws_vx_xmlBlob;Is BLOB;SOAP output;"contactListsX")
  `4D konvertiert XML in Base64
 SOAP DECLARATION(ws_vt_xml;Is text;SOAP output;"contactListsText")
  `Die XML wird von 4D in Text konvertiert (< > become entities)
 SOAP DECLARATION(ws_vt_xml;Is XML;SOAP output;"xmlContacts")
  `Die XML wird als XML Text übergeben
 SOAP DECLARATION(ws_vx_xmlBlob;Is XML;SOAP output;"blobContacts")
  `Die XML wird als ein XML BLOB übergeben
 SOAP DECLARATION(ws_vt_xmlRef;Is DOM reference;SOAP output;"contactByRef")
  `Die XML wird als Referenz übergeben

 
EIGENSCHAFTEN 

Produkt: 4D
Thema: Web Services (Server)
Nummer: 782

 
GESCHICHTE 

Geändert: 4D v11 SQL Release 2

 
SIEHE AUCH 

Is data file locked
SOAP Get info
SOAP SEND FAULT

 
ARTIKELVERWENDUNG

4D Programmiersprache ( 4D v14 R2)
4D Programmiersprache ( 4D v14 R3)
4D Programmiersprache ( 4D v13.5)
4D Programmiersprache ( 4D v14.3)
4D Programmiersprache ( 4D v14 R4)

Geerbt von : SOAP DECLARATION ( 4D v11 SQL Release 6)