Creating a Web service

The VA Smalltalk support for Web services provides the infrastructure necessary to invoke application behavior in loosely-coupled, heterogeneous computing environments. Creating the application logic for a Web service is no different than creating application logic for any standard server application. In fact, it should be easy to expose the functionality of existing server applications as Web services. The VA Smalltalk Web Services support provides a communications layer to manage the interchange of data between clients and servers using the SOAP message format. The key to the successful deployment of an application as a Web service is creating the service definition files required to describe the service. Below is a list of the files used by the VA Smalltalk Web services support.

Table 1. VA Smalltalk Web Service deployment files

File type	File description
Deployment descriptor	The deployment descriptor is an XML file that provides meta information about the service, such as the implementation class and the location of the service WSDL. The XML document describes all program resources required during the lifecycle of a service: • The location of the WSDL file that describes the service • List of image components to be loaded during deployment • List of the mapping specification files • List of service handlers • The implementor of the service (the name of a class) • Method mappings • List of service descriptions containing the following information: • name and namespace for the service • service class (usually SstWSService) • provider information. The provider defines the following: • Class that implements the service and the creation method for the class • List of operations supported by the service along with the mechanism for handling the operation. Operations can be handled by a invoking a method in the provider class or by specifying a custom service handler. Service handlers are described in the "Web services Handlers" section.
WSDL files	An XML document that describes the public interface for a service. Supported operations, parameter descriptions, and network endpoint information are some of the items that are described by the WSDL document.
Mapping file	An XML document used to specify rules for mapping XML document elements into Smalltalk classes.

The Web Services feature provides a simple file generation tool which constructs the necessary web service deployment files using information retrieved from a Smalltalk class. This tool is called SstWSXmlGeneration. To use the tool, determine which methods are to be exposed as operations in the service interface, and add those methods to the method category '@WS-API'. Launch the tool using an expression like the one below to create generalized deployment files for the service.

SstWSXmlGeneration forClass: <class name>

For instance, to generate deployment files for the insurance policy example, found in SstWebServicesInsuranceExample in the Web Services feature, evaluate the expression

SstWSXmlGeneration forClass: SstWSInsurancePolicyInterface

Or, to control where the deployment files are placed, use the expression

SstWSXmlGeneration forClass: SstWSInsurancePolicyInterface

saveTo: CfsDirectoryDescriptor startUpDirectoryPath.

Which places the files in the startup path.

For most cases, the deployment files will require modification prior to usage to reflect the proper settings for a specific installation. The files are named as shown below.

1.	<class name>'.wsdl' (WSDL implementation document)

2.	<class name>'-interface.wsdl' (WSDL interface document)

3.	<class name>'.xml' (VA Smalltalk web service deployment descriptor)

These files will be placed in the directory specified by the key DefaultResourceQualifier located in the XML stanza of the abt.ini file. Here is a sample entry:

[Xml]

DefaultResourceQualifier=D:\vast70\xml\

If this key is not found, then they will be placed in the image startup directory

CfsDirectoryDescriptor startUpDirectoryPath.

It is important to remember that these files will be OVERWRITTEN if they exist! An error will occur if the DefaultResourceQualifier points to a read only directory.

Note:

The default location of the DefaultResourceQualifier is a readonly directory. In order to run the Web Services examples, you can

1.	Generate the deployment descriptors into a directory you can write into and then use administrator priveleges to copy the files into the DefaultResourceQualifier

2.

Or copy the directory indicated by the DefaultResourceQualifier and its sister directory, samples\sstws into a direcory to which you have write priviledges, Once you have done this change the DefaultResourceQualifier to point to the xml directory. In this case, you can generate the deployment descriptors directly into the new DefaultResourceQualifier.

For the insurance policy example, the deployment description found in SstWSInsurancePolicyInterface.xml defines the services in the insurance policy web service and refers to SstWSInsurancePolicyInterface.wsdl as the source of information about the interface including the location of the service. The WSDL interface document SstWSInsurancePolicyInterface.wsdl in turn refers to the WSDL implementation document, SstWSInsurancePolicyInterface-interface.wsdl, for information on how the services are implemented including mapping operations to SOAP messages.

The next section will describe how to go about deploying a web service.