SOAP DECLARATION

Version 11.2 (Geändert)

SOAP DECLARATION (Variable; Typ; Input_Output{; Alias})

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 Texargumente 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 des Befehls SOAP DECLARATION müssen Sie 4D Variablen und Arrays in der Methode "Compiler_Web" immer mit Befehlen aus dem Kapitel "Compiler" deklarieren.

In Variable ü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, sowie für XML und SOAP Typen, Konstanten unter dem Thema "Web Services (Server)":

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 unter dem Thema "Web Services (Server)" einsetzen (siehe oben).

XML Typen verwenden: Über die Konstanten Is XML und Is DOM reference können Sie Variablen vom Typ "XML Struktur" und "DOM Referenz" deklarieren, sowohl einge--hend wie ausgehend. Bei Parametern dieses Typs erfolgt keine Bearbei-tung 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 Refe-renzen 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 gesende-ten XML Argument entspricht.

• Veränderung der WSDL Datei:

4D deklariert diese XML Strukturen in der WSDL als "jeder Typ" (unbe-stimmt). 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.

COMPILER_WEB Methode: 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 URLs und Form Actions.

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 4th Dimension 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.

(1) 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")

(2) 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")

(3) 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)

(4) 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.

(5) Nachfolgendes Beispiel zeigt die Ergebnisse der verschiedenen Deklara-tionstypen:

   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

Get SOAP info, Is data file locked, SEND SOAP FAULT.

Themen Feld und Variablentypen und Web Services (Server)

Anwendung des Befehls

Connecting 4D Databases through SOAP, Returning Pictures Through SOAP, Subscribe to a SOAP based Web Service

---