Compiling and Testing your Web Service
After you have created your web service, you need to compile and test it. You can do this by selecting Debug -> Run from the menu in the Studio.
Note
All DataFlex web services can be accessed using a browser. The browser will display a test page that provides information about your service and all of its operations. It lets you look at the service description (the WSDL file) and allows you to test the service.
The test page is generated by pointing a browser’s URL to a location consisting of your virtual directory, your web service name (defined by the WSO’s psServiceName property), and the extension .wso. For example, if the name of your service is HelloService and your virtual directory is http://localhost/MyApplication, the service test page can be accessed at http://localhost/MyApplication/HelloService.wso.
The test page is used for more than debugging. Other client applications will use this page to provide information about your service. One of the options on the test page is the ability to view the service description, which displays the service’s WSDL file. This is an important function as it provides access to the service’s definition, which clients will use to figure out how to interact with the service. For example, within DataFlex, the client web service class generator will use this WSDL to build the client web service class.
The WSDL page can be explicitly loaded by appending ?WSDL to your web service’s URL (e.g., http://localhost/MyApplication/HelloService.wso?WSDL).
The test pages and the WSDL definition are generated dynamically while the web application is running. This means that your service definition is always up to date. It also means that you do not need to concern yourself with creating and maintaining your service definitions, as the web application server does this for you automatically.
Using the Web Service Test Page
You can test the web service directly in the browser in two modes: plain XML output or JSON output. By default, the response will be returned to the browser in plain XML mode. The XML will appear in the same way as to a SOAP client, but without the SOAP envelope and body wrapper, allowing you to concentrate on the specific data returned from your service.
To request that the response is returned in JSON format, simply follow the corresponding link: "To view the output in JSON format, click here" instead of clicking the Invoke button. The web service is invoked in the same way, but returns the data in JSON format instead of XML. Note that when debugging the web service method, you will see no difference in the DataFlex code. The return value from the web service method is automatically transformed either to XML or JSON (or SOAP if invoked from a SOAP client) before it's returned to the browser or client.
The test page also displays example data approximating what an exchange with the service could look like in both JSON and SOAP. You can take advantage of the example data exchange, as well as the actual response displayed in the browser, to assist in using the web service and understanding the structure and format of the data returned. If your intent is to use JSON output or plain XML output (as opposed to SOAP), note the format of the URL and how the parameters are specified, as both the example and the actual URL displayed in the browser can assist in understanding how to use the web service.
How a Web Service is Located
As mentioned above, a web service is located by pointing to a URL address on your server (e.g., http://localhost/MyApplication/HelloService.wso). Normally, a browser-based web application will be accessed by pointing to a file name with an .asp, .htm, .html, or .wml extension. You will notice that the web service file name contains a .wso file extension. The .wso file extension is registered within IIS to have a special meaning. When a .wso file is requested, the server redirects this request to the DataFlex web service server, bypassing all normal ASP and HTML processing.
If you look within your virtual directory (your appHtml directory within your workspace), you will see that the .wso file actually exists (e.g., look for ..\appHtml\HelloService.wso). This is a small file that contains all of the information needed to direct a web service request to the proper WSO object and to generate your test and WSDL pages. This file, when accessed over the web, connects a SOAP request to the web service object in your web application.
The name of this .wso file is important. Its name is determined by the value you set in your WSO’s psServiceName property. Each WSO within a single web application should have a unique psServiceName. (Note that the WSO’s object name is purposefully not used for this purpose. The service name is defined in your WSDL description and is used by clients to build client web service classes. You want to be able to control the name of a service.)
You normally do not need to concern yourself with the .wso file, as the Studio maintains it automatically. After a successful compile, all .wso files are generated as needed. It is important to note that the automatic maintenance of this .wso file only occurs if you compile your web application within the Studio. If you compile your web application outside of the Studio, which is not recommended, you will need to maintain the .wso file yourself.
To summarize, a web application may contain multiple web services. Each web service is handled by a single WSO object. For each WSO in your application’s appSrc area, there must be a corresponding .wso file in your appHtml area. Each of these .wso files must have a unique name. The name is maintained in the WSO’s psServiceName property. As long as you set a proper psServiceName, everything else will be taken care of for you.