Websydian v6.1 online documentationOnline documentation - WebsydianExpress v3.5

XMLServiceHandler Example

Introduction

This document describes the example XML and SOAP services that are delivered as part of the demosite.

The examples show the implementation of a simple XML based web service and how the same service can be published as a SOAP and a non-SOAP service.

The service reads an XML document formatted like this:

And creates the response document that is formatted like this:

This document is aimed at showing where the relevant definitions and programs can be found in the Plex model and which definitions in the administration interface that controls how the service is published.

XML-based services are not available in the iSeries variant.

This means that this example is only relevant for the Java, WinC, WinC/iSeries variants.

Modeling the documents

The definitions of the request and response documents are found in the WSYAPIWS model. The modeling is done using the abstract TransacXML objects.

The request document is:

_Examples.Greet.Request

The response document is:

_Examples.Greet.Response

Service handler

The service handler that implements the service is:

WSYAPIWS/_Examples.Greet.GreetHandler

Publishing the service

The generated objects are delivered as part of the runtime. In a normal situation; you would naturally have to start by moving the generated program objects to the correct application folder.

In the administration interface of the demosite open the service structure.

The three URLs each use a different service processor.

The service is deployed on the soap and the xml URLs.

XML

The xml URL element scopes one criterion: "Top element name".

This means that the runtime will use the name of the top element will be used to identify a service handler for all requests that targets the URL:

...express30/service/site/demosite/xml

The service handler for the greet service is scoped by the criteria - and the value for the criteria is specified as "Request".

The XMLServiceProcessor loads the request data to the XML parser and make the TransacXML references available for the service handler.

After the service handler has been called, the processor returns the generated response document to the client.

SOAP

The exact same service handler is also published as a SOAP 1.1 based web service.

The criteria used by the service is "SOAPAction", which means that the SOAPAction http-header will be used to determine which service handler that will be called for requests that targets the URL:

.../express30/site/demosite/service/soap

The service handler for the greet service is scoped by the criteria - and the value for the criteria is specified as "GreetService".

(Normally the soap action will be either a URL or a URN that use the domain of your website to make the soap action universally unique - but to make the deployment of the service as part of the runtime easier, the simple name has been used).

The SoapServiceProcessor loads the request data to the XML parser, extracts the request document from the SOAP-Body and makes it available for the service handler.

After the service handler has been called, the processor wraps the generated response document in a SOAP-Envelope and returns it to the client.

Testing the service

XML

The services can't be called from a browser - as there is no way for the handler to provide the request data.

To help make it possible for you to test your services, we have made the (very basic) test tool we use ourselves available on our download page.

If the URL specifying the xml service is: "http://MyServer/express30/site/demosite/service/xml" (see above)

Specify the following values:

Internet ServerName: MyServer

Port: 80 (if the URL starts with MyServer:nnnn/...) - then you specify the value nnnn.

URL: /express30/site/demosite/service/xml

HTTP version: HTTP/1.1

Method: Post

Use SSL: *No

Request filename: Specify a file containing the following request data.

<?xml version="1.0" encoding="UTF-8"?>
<ws:Request xmlns:ws="http://www.websydian.com/services/greet">
<ws:firstName>John</ws:firstName>
<ws:lastName>Doe</ws:lastName>
</ws:Request>

In the header table you must change the value for the content type to: text/xml;charset=utf-8

Press Execute, The response headers and file will be shown in the bottom of the panel.

SOAP

The soap service is tested in the same way - but you need to specify another request file - as the request has to be wrapped in a SOAP-structure.

The request file should hold the following information: 

<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"><SOAP-ENV:Body><ws:Request xmlns:ws="http://www.websydian.com/services/greet">
<ws:firstName>John</ws:firstName>
<ws:lastName>Doe</ws:lastName>
</ws:Request></SOAP-ENV:Body></SOAP-ENV:Envelope>

The specified URL must be: /express30/site/demosite/service/soap

The rest of the definitions must be the same, but you must add the following to the header table (upper right corner):

Header Name: SOAPAction

Header Value: http://www.websydian.com/soapactions/greet

Press Execute, The response headers and file will be shown in the bottom of the panel.

More information

Background: The WSYAPIWS model

Background: Handling a web service request

Background: Understanding the service structure

Background: Service handlers

Background: Service processors

Background: Selection criteria

Guide: Implementing an XML service handler

Guide: Testing services