Modifications to XML files
Modification of the web service deployment descriptor
The generated deployment descriptor is ‘SstWSInsurancePolicyInterface.xml’. Notice the following line which associates the concrete definition of the service with the deployment descriptor.
<wsdlUrls>
<wsdlUrl>SstWSInsurancePolicyInterface.wsdl</wsdlUrl>
</wsdlUrls>
The deployment descriptor has a tag for specifying the path to mapping specificatioin files.
<mappingSpecUrls>
<mappingSpecUrl>VASTInsuranceExample.map</mappingSpecUrl>
</mappingSpecUrls>
In the snippet above the file VASTInsuranceExample.map (found in <vas>\samples\sstws\common) defines the mapping of schema types to VA Smalltalk classes. The file must be copied to the <vas>/xml directory.
This concludes changes needed to the deployment descriptor common to the client and server. Write the changes to SstWSInsurancePolicyServerInterface.xml.
Modifying the Web Service Location
The high level definition of the web service implementation is found in ‘SstWSInsurancePolicyInterface.wsdl’. It is interesting to note the following line which associates the concrete definition of the interface to the lower level interface definition.
<import
namespace="http://www.SstWSInsurancePolicyInterface.com/SstWSInsurancePolicyInterface-interface"
location="SstWSInsurancePolicyInterface-interface.wsdl"/>
The line in ‘SstWSInsurancePolicyInterface.wsdl’ which locates the web servlet is .
<soap:address location="http://vasthost:7374/SstWSServlet"/>
If you are not able to change your hosts file, it is sufficient to change ‘vasthost’ ‘localhost’ or the IP address of the server machine. Notice the port number, 7374. When the web service is deployed, a servet is automatically started to handle the web service requests (a POST). This web servlet runs on port 7374 and is separate from the web service. Clients will be sending their HTTP requests to the SstWSServlet.
Refining Web Service Type Definitions
The automatically generated types for the parameters and responses of the web service are always strings. They do not reflect the parameters and return values in
SstWSInsurancePolicyInterface. In order to bring the public interface of the web service expressed in ‘SstWSInsurancePolicyInterface-interface.wsdl’ in sync with the Smalltalk implementation, the types need to be edited.
The automatically generated interface definition ‘SstWSInsurancePolicyInterface-interface.wsdl’ is the WSDL specification minus the port definition tag, which is kept separate in the spirit of separating implementation from interface. It contains the following sections:
•Definition – defines the name of the web service and declares namespaces for the WSDL.
•Types - section includes schema(s) for the interface and data type definitions.
•Messages - whose internal structure is dictated by the SOAP style of the web service;
•Port definition defines input and output messages for each web service operation;
•Binding defines soap actions for each web service operation.
In general the manual changes to the web service interface file will involve the types section or the messages, depending on the SOAP style specified for the web service. Namespaces may also need to be declared in the types and/or defnitions section for imported schemas. .
Definition
Notice the < definitions> tag at the beginning of the file.
<definitions name="SstWSInsurancePolicyInterface-interface"
targetNamespace="http://www.SstWSInsurancePolicyInterface.com/SstWSInsurancePolicyInterface-interface"
xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:tns="http://www.SstWSInsurancePolicyInterface.com/SstWSInsurancePolicyInterface-interface"
xmlns:swsipi="urn:SstWSInsurancePolicyInterface"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:tin="urn:SstWSInsurancePolicyInterface"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
The line in bold must be added to the tag because at least some of the complex types in this example are not included in the standard XML schema. The namespace is named tin, short for types input, and will be used in specifying the complex types to be passed to and from the sample web service.
Types
Notice the <types> section; it contains a schema which defines XMLSchema and elements corresponding to the various operations exposed in the
sample service. The bold text adds a namespace with a schema defining the new complex types to the automatically generated schema:
<types>
<xsd:schema targetNamespace="urn:SstWSInsurancePolicyInterface"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:import namespace="urn:SstWSInsurancePolicyInterface"
schemaLocation="SstWSInsurancePolicyInterface.xsd" />
… … …
</xsd:schema>
</types>
SstWSInsurancePolicyInterface.xsd is a specialized insurance policy schema and is found in <vas>\samples\sstws\common\ . It defines SstWSAddress, SstWSPerson, SstWSPersonCollection, SstWSInsurancePolicy, and SstWSInsurancePolicyCollection. The file must be copied to the <vas>/xml directory.
Once the application-specific types have been introduced via the schema, the problem boils down to the simple case: replace xsd:string with tin:xxx or ins:xxx, where tin and ins are namespace prefixes referring to namespaces containing the domain-specific types and xxx is one of the types, e.g. SstInsurancePolicyCollection, or SstWSInsurancePolicy. Tin refers to the namespace of the web service ins to the namespace which contains the schema element.
The following specifies what parameter types are passed for what operation. The parameter types are found in the schema, SstWSInsurancePolicyInterface.xsd:
•about takes no parameter and answers an xsd:string
•ratePolicy takes an xsd:string (representing the policy number) and answers an xsd:float
•getAllPolicies takes no parameter and answers a collection of policies tin:SstInsurancePolicyCollection or ins:SstInsurancePolicyCollection.
•getInfoForPolicy takes an xsd:string (representing the policy number) and answers a tin:SstWSInsurancePolicy (or ins:SstWSInsurancePolicy.)
•updatePolicy takes a policy tin:SstWSInsurancePolicy (or ins:SstWSInsurancePolicy )and answers an xsd:boolean indicating whether the update was successful.
The specific changes depend on whether the WSDL was generated as a document literal or an rpc style. If it is a document literal style, the schema in the types section is modified.
Document literal types before and after
For the document literal style, the parameters passed in the message are actually specified in the <types> section of the web service interface definition. For each web service message, a schema element defines the element contained the message body. The schema elements are automatically generated so that the parameters are either strings or complex types containing strings. No schema element is generated for parameter-less requests.
Consider two methods for the ratePolicy operation: ratePolicy and ratePolicyResponse. The latter passes a float, which is one of the types defined in the http://www.w3.org/2001/XMLSchema. In this case the change to the schema in the <types> section is simple:
<xsd:element name="ratePolicyResponse" type="xsd:string"/>
becomes
<xsd:element name="ratePolicyResponse" type="xsd:float"/>
The xsd:float replaces the automatically generated as xsd:string.
The latter method, ratePolicy, takes a complex type, SstWSInsurancePolicy, as a parameter. The automatically generated XML is
<xsd:element name="ratePolicy" >
<xsd:complexType>
<xsd:sequence>
<xsd:element name="ratePolicy" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
Notice it has a complex type as a place holder. The changed form is
<xsd:element name="ratePolicy" type="ins:SstWSInsurancePolicy">
</xsd:element>
which draws on the definition of SstWSInsurancePolicy found in the imported schema SstWSInsurancePolicyInterface.xsd.
Most of the rest of the operations will follow one of these two patterns. Refer to the
list of operations enumerated in the discussion of types for the specific types used.
The exceptions are about and getAllPolicies which pass no parameters. The schema elements for these are changed to the following:
<xsd:element name="about" type="xsd:string" nillable="true"/>
<xsd:element name="getAllPolicies" type="xsd:string" nillable="true"/>
The messages generated for a RPC style web service have a type in them and so the message is the thing changed.
Messages
As already mentioned, the message is constructed a bit differently for document or rpc styles. For the document literal style, the parameters passed in the message are actually determined in the types section of the web service interface definition. The description of the changes needed to introduce complex types is covered in the Types section above. For the rpc literal style, each message contains a type for the parameter passed.
RPC messages before and after
Since the complex types used in this example have already been defined and associated with the web service definition, all types are treated in a similar manner: change the automatically generated xsd:string to xsd:xxx or tin:xxx, where xxx is the type e.g.
<message name="about">
</message>
<message name="aboutResponse">
<part name="outMsg" type="xsd:string"/>
</message>
<message name="ratePolicy">
<part name="ratePolicy" type="xsd:string"/>
</message>
<message name="ratePolicyResponse">
<part name="outMsg" type="xsd:float"/>
</message>
<message name="updatePolicy">
<part name="updatePolicy" type="tin:SstWSInsurancePolicy"/>
</message>
<message name="updatePolicyResponse">
<part name="outMsgBoolean" type="xsd:boolean"/>
</message>
Notice about has no part since it has no parameter. This is also true for getAllPolicies. The other messages have one parameter, which is automatically generated as a string. The float and boolean parameters are defined in XMLSchema
; tin:SstWSInsurancePolicy is found in the schema file, SstWSInsurancePolicyInterface.xsd, imported into the web service definition. Refer to the
list of operations enumerated in the discussion of types for the specific types used.
This concludes the changes to the interface definition.
Binding
The <binding> section needs no changes. However it is interesting to note its construction:
Rpc literal
<binding name="SstWSInsurancePolicyInterfaceBinding" type="tns:SstWSInsurancePolicyInterfacePortType">
<soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
<operation name="about">
<soap:operation soapAction="http://www.SstWSInsurancePolicyInterface.com/SstWSInsurancePolicyInterface-interface/about"/>
<input>
<soap:body use="literal"/>
</input>
<output>
<soap:body use="literal"/>
</output>
</operation>
This section defines the encoding style as rpc literal. A RPC encoded soap body would look like
<soap:body use="encoded"... encodingStyle="encoded"/>
A document literal soap body would look like the auto-generated version
<soap:body use="literal"/>