Click here to view and discuss this page in DocCommentXchange. In the future, you will be sent there automatically.

SAP Sybase SQL Anywhere 16.0 » SQL Anywhere Server - Programming » HTTP web services » HTTP web service examples » Tutorial: Using SQL Anywhere to access a SOAP/DISH service

 

Lesson 1: Setting up a web server to receive SOAP requests and send SOAP responses

In this lesson, you set up a new database server and create a SOAP service to handle incoming SOAP requests. The server anticipates SOAP requests that provide a Fahrenheit temperature value that is converted to the equivalent Celsius degrees.

Prerequisites

This lesson assumes that you have the roles and privileges listed in the Privileges section at the start of this tutorial: Tutorial: Using SQL Anywhere to access a SOAP/DISH service.

 Task
  1. Create a SQL Anywhere database that will be used to contain web service definitions.

    dbinit -dba DBA,sql ftc
  2. Start a database server using this database. This server will act as a web server.

    dbsrv16 -xs http(port=8082) -n ftc ftc.db

    The HTTP web server is set to listen on port 8082 for requests. Use a different port number if 8082 is disallowed on your network.

  3. Connect to the database server with Interactive SQL.

    dbisql -c "UID=DBA;PWD=sql;SERVER=ftc"
  4. Create a new DISH service to accept incoming requests.

    CREATE SERVICE soap_endpoint 
        TYPE 'DISH'
        AUTHORIZATION OFF
        SECURE OFF
        USER DBA;

    This statement creates a new DISH service named soap_endpoint that handles incoming SOAP service requests. If you logged in with a different user ID, then the USER DBA clause must be changed to reflect your user ID.

  5. Create a new SOAP service to handle Fahrenheit to Celsius conversions.

    CREATE SERVICE FtoCService
        TYPE 'SOAP'
        FORMAT 'XML'
        AUTHORIZATION OFF
        USER DBA
        AS CALL FToCConverter( :fahrenheit );

    This statement creates a new SOAP service named FtoCService that generates XML-formatted strings as output. It calls a stored procedure named FToCConverter when a web client sends a SOAP request to the service. If you logged in with a different user ID, then the USER DBA clause must be changed to reflect your user ID.

  6. Create the FToCConverter procedure to handle incoming SOAP requests. This procedure performs the necessary calculations to convert a client-supplied Fahrenheit temperature value to the equivalent Celsius temperature value.



    CREATE OR REPLACE PROCEDURE FToCConverter( temperature FLOAT )
    BEGIN
        DECLARE hd_key LONG VARCHAR;
        DECLARE hd_entry LONG VARCHAR;
        DECLARE alias LONG VARCHAR;
        DECLARE first_name LONG VARCHAR;
        DECLARE last_name LONG VARCHAR;
        DECLARE xpath LONG VARCHAR;
        DECLARE authinfo LONG VARCHAR;
        DECLARE namespace LONG VARCHAR;
        DECLARE mustUnderstand LONG VARCHAR; 
    header_loop:
        LOOP
            SET hd_key = NEXT_SOAP_HEADER( hd_key );
            IF hd_key IS NULL THEN
                -- no more header entries
                LEAVE header_loop;
            END IF;
            IF hd_key = 'Authentication' THEN
                SET hd_entry = SOAP_HEADER( hd_key );
                SET xpath = '/*:' || hd_key || '/*:userName';
                SET namespace = SOAP_HEADER( hd_key, 1, '@namespace' );
                SET mustUnderstand = SOAP_HEADER( hd_key, 1, 'mustUnderstand' );
                BEGIN
                    -- parse the XML returned in the SOAP header 
                    DECLARE crsr CURSOR FOR 
                        SELECT * FROM OPENXML( hd_entry, xpath )
                            WITH ( alias LONG VARCHAR '@*:alias',
                                first_name LONG VARCHAR '*:first/text()',
                                last_name LONG VARCHAR '*:last/text()' );
                    OPEN crsr;
                    FETCH crsr INTO alias, first_name, last_name;
                    CLOSE crsr;
                END;
    
                -- build a response header
                -- based on the pieces from the request header
                SET authinfo = 
                    XMLELEMENT( 'Authentication',
                        XMLATTRIBUTES(
                            namespace as xmlns,
                            alias,
                            mustUnderstand ),
                            XMLELEMENT( 'first', first_name ),
                            XMLELEMENT( 'last', last_name ) );
                CALL SA_SET_SOAP_HEADER( 'authinfo', authinfo );
            END IF;
        END LOOP header_loop;
        SELECT ROUND((temperature - 32.0) * 5.0 / 9.0, 5) AS answer;
    END;

    The NEXT_SOAP_HEADER function is used in a LOOP structure to iterate through all the header names in a SOAP request, and exits the loop when the NEXT_SOAP_HEADER function returns NULL.

    Note

    This function does not necessarily iterate through the headers in the order that they appear in the SOAP request.

    The SOAP_HEADER function returns the header value or NULL when the header name does not exist. The FToCConverter procedure searches for a header named Authentication and extracts the header structure, including the @namespace and mustUnderstand attributes. The @namespace header attribute is a special SQL Anywhere attribute used to access the namespace (xmlns) of the given header entry.

    The following is an XML string representation of a possible Authentication header structure, where the @namespace attribute has a value of "SecretAgent", and mustUnderstand has a value of 1:

    <Authentication xmlns="SecretAgent" mustUnderstand="1">
        <userName alias="99">
            <first>Susan</first>
            <last>Hilton</last>
        </userName>
    </Authentication>

    The OPENXML system procedure in the SELECT statement parses the XML header using the XPath string "/*:Authentication/*:userName" to extract the alias attribute value and the contents of the first and last tags. The result set is processed using a cursor to fetch the three column values.

    At this point, you have all the information of interest that was passed to the web service. You have the temperature in Fahrenheit degrees and you have some additional attributes that were passed to the web service in a SOAP header. You could look up the name and alias that were provided to see if the person is authorized to use the web service. However, this exercise is not shown in the example.

    The SET statement is used to build a SOAP response in XML format to send to the client. The following is an XML string representation of a possible SOAP response. It is based on the above Authentication header structure example.

    <Authentication xmlns="SecretAgent" alias="99" mustUnderstand="1">
      <first>Susan</first>
      <last>Hilton</last>
    </Authentication>

    The SA_SET_SOAP_HEADER system procedure is used to set the SOAP response header that will be sent to the client.

    The final SELECT statement is used to convert the supplied Fahrenheit value to a Celsius value. This information is relayed back to the client.

Results

At this point, you now have a running SQL Anywhere web server that provides a service for converting temperatures from degrees Fahrenheit to degrees Celsius. This service processes a SOAP header from the client and sends a SOAP response back to the client.

Next

In the next lesson, you develop an example of a client that can send SOAP requests to the web server and receive SOAP responses from the web server. Proceed to Lesson 2: Setting up a web client to send SOAP requests and receive SOAP responses.

 See also