The Web Service class

Summary:

Syntax
Methods
Examples

Syntax

The Web Service class provides an interface to create and manage Genero Web Services.

Note that status is set to zero after a successful method call.

Syntax

com.WebService

Methods

Class Methods
Name	Description
`com.WebService.createWebService( name` `STRING, namespaceSTRING` `)` `RETURNING` `com.WebService`	Creates a WebService object by providing the mandatory name and namespace, which must be unique in the entire application. Throws an exception in case of errors, and updates status with an error code.

Object Methods
Name	Description
`setComment( commentSTRING` `)`	Adds a comment to a WebService; the comment will be visible in the generated WSDL file. Throws an exception in case of errors, and updates status with an error code.
`publishOperation( op com.WebOperation, roleSTRING` `)`	Publishes a WebOperation named op. The role identifies the operation if several operations have the same name. Throws an exception in case of errors, and updates status with an error code.
`saveWSDL( location STRING )` `RETURNING` `status`	Saves the WSDL of the WebService to the file system; location is the URL where the service will be deployed. Status is 0 if the file was saved, -1 if there was an error.
`generateWSDL( location STRING )` `RETURNING` `xml.DomDocument`	Returns a xml.DomDocument representing the WSDL of the WebService; location is the URL where the service will be deployed. Throws an exception in case of errors, and updates status with an error code.
`createHeader( header Variable, encodedINTEGER` `)`	Creates a global Header of the WebService; header is any Variable defining the header, encoded specifies the encoding mechanism, where `TRUE` indicates the SOAP Section 5 encoding mechanism and `FALSE` the XML Schema mechanism. Since Headers are always in Document Style, set the encoded parameter to FALSE. Throws an exception in case of errors, and updates status with an error code.
`registerWsdlHandler( functionSTRING` `)`	Registers a 4GL function executed when a WSDL is beeing generated. The 4GL function must have one input and one output parameter of type xml.DomDocument; the system provides the generated WSDL as input parameter, and you must return it (after modification) to fulfill the WSDL generation process. See example 1 Throws an exception in case of errors, and updates status with an error code.
`registerInputRequestHandler( functionSTRING` `)`	Registers a 4GL function executed when an incoming SOAP request is received and before the SOAP engine has processed it. The 4GL function must have one input and one output parameter of type xml.DomDocument; the XML SOAP request is provided as input parameter, and you must return it (after modification) to fulfill the SOAP request processing. See example 2 Throws an exception in case of errors, and updates status with an error code.
`registerOutputRequestHandler( functionSTRING` `)`	Registers a 4GL function executed just after the SOAP engine has processed it and before the SOAP response is forwarded to the client. The 4GL function must have one input and one output parameter of type xml.DomDocument; the XML SOAP response is provided as input parameter, and you must return it (after modification) to fulfill the SOAP response processing. See example 3 Throws an exception in case of errors, and updates status with an error code.

Back to the top

Examples

Example 1 : Modify the generation of a WSDL

FUNCTION WSDLHandler(wsdl)
  DEFINE wsdl Xml.DomDocument
  DEFINE node Xml.DomNode
  DEFINE list Xml.DomNodeList
  DEFINE ind  INTEGER
  DEFINE name STRING
  # Add a comment
  LET node = wsdl.createComment("First modified WSDL via a 4GL callback function")
  CALL wsdl.prependDocumentNode(node)
  # Rename input and output parameter in UPPERCASE
  LET list = wsdl.selectByXPath("//wsdl:definitions/wsdl:types/xsd:schema/xsd:complexType/xsd:sequence/xsd:element/xsd:complexType/xsd:sequence/xsd:element",NULL)
  FOR ind=1 TO list.getCount()
    LET node = list.getItem(ind)
    LET name = node.getAttribute("name")
    LET name = name.toUpperCase()
    CALL node.setAttribute("name",name)
  END FOR
  RETURN wsdl
END FUNCTION

Note : if NULL is returned from the callback function, an HTTP error will be sent and the processServices() returns error code -20.

Example 2 : Change the SOAP incoming request

FUNCTION InputRequestHandler(in)
  DEFINE in Xml.DomDocument
  DEFINE ind  INTEGER
  DEFINE node Xml.DomNode
  DEFINE copy Xml.DomNode
  DEFINE tmp  Xml.DomNode
  DEFINE parent Xml.DomNode
  DEFINE name STRING
  DEFINE list Xml.DomNodeList
  # Change input parameter below myrecord in lower case to follow high-level web service
  LET list = in.SelectByXPath("//SOAP:Envelope/SOAP:Body/fjs:EchoDOCRecordRequest/fjs:myrecord/*","SOAP","http://schemas.xmlsoap.org/soap/envelope/","fjs","http://www.mycompany.com/webservices")
  FOR ind = 1 TO list.getCount()
    LET node = list.getItem(ind)
    LET parent = node.getParentNode()
    LET name = node.getLocalName()
    LET copy = in.createElementNS(node.getPrefix(),name.toLowerCase(),node.getNamespaceURI())
    LET tmp = node.getFirstChild()
    LET tmp = tmp.clone(true)
    CALL copy.appendChild(tmp)
    CALL parent.replaceChild(copy,node)
  END FOR
  RETURN in
END FUNCTION

Note : if NULL is return from the callback function, a SOAP fault will be sent and the processServices() returns error code -18.

Example 3 : Modify the SOAP outgoing request

FUNCTION OutputRequestHandler(out)
  DEFINE out Xml.DomDocument
  DEFINE ind  INTEGER
  DEFINE node Xml.DomNode
  DEFINE copy Xml.DomNode
  DEFINE tmp  Xml.DomNode
  DEFINE parent Xml.DomNode
  DEFINE name STRING
  DEFINE list Xml.DomNodeList
  # Change output parameter below myrecord in uppercase before sending back to the client
  LET list = out.SelectByXPath("//SOAP:Envelope/SOAP:Body/fjs:EchoDOCRecordResponse/fjs:myrecord/*","SOAP","http://schemas.xmlsoap.org/soap/envelope/","fjs","http://www.mycompany.com/webservices")
  FOR ind = 1 TO list.getCount()
    LET node = list.getItem(ind)
    LET parent = node.getParentNode()
    LET name = node.getLocalName()
    LET copy = out.createElementNS(node.getPrefix(),name.toUpperCase(),node.getNamespaceURI())
    LET tmp = node.getFirstChild()
    LET tmp = tmp.clone(true)
    CALL copy.appendChild(tmp)
    CALL parent.replaceChild(copy,node)
  END FOR
  RETURN out
END FUNCTION

Note : if NULL is return from the callback function, a SOAP fault will be sent and the processServices() returns error code -19.

Back to the top