SAWS User Guide - the Dyalog APL Tools Library
Contents
1. A Sample Web Service The Web Service3 we re going to build is a very simple database application To simplify things the database is just a matrix in the workspace though it could easily be stored in a file or in a database system like Microsoft SQL Server or MySQL The point is you ve got some data and you want to share it with others Jdisplay DataBase gt App te 15 6 99 Bau 3 14 99 cactus 0 9 99 Dai sy 19 2 49 3 This Web Service can be found in PriceCheck in the SAWS workspace 4 display is a user command to display the structure of the result of an APL expression For more information on user commands please visit http www dyalog com documentation 8 SAWS Our database consists of three columns 1 The Item Name 52 Quantity on Hand 3 Item Price We re going provide two functions The first ListItems will return the names of items in the database The second function GetItemInfo will take an item name as an argument and return the quantity on hand and price NS PriceCheck PriceCheck CS PriceCheck PriceCheck v r ListItems a result noatt 1 A Implements the ListItems method for the PriceCheck web service 2 A arg empty MLS Markup Language Structure there are no arguments to this method 3 a r 1 1 indicates r 2 is an MLS 4 a r 2 MLS containing the result 5 A 5 1 depth of nesting origin 1 6 A 52 element name 7 A 3 element2. gt lt wsdl definitions xmiIns soap http schemas xmlsoap org wsdl soap xmins tm http microsoft com wsdl mime textMatching xmins soapenc http schemas xmlsoap org soap encoding xmins mime http schemas xmlsoap org wsdl mime xmins tns http www webserviceX NET xmins s http www w3 org 2001 XMLSchema xmins soap12 http schemas xmlsoap org wsdl soap12 xmins http http schemas xmlsoap org wsdl http targetNamespace http www webserviceX NET xmins wsdl http schemas xmlsoap org wsdl gt lt wsdl types gt lt s schema elementFormDefault qualified targetNamespace http www webserviceX NET gt lt s element name GetQuote gt lt s complexType gt lt s sequence gt lt s element minOccurs 0 maxOccurs 1 name symbol type s string gt lt s sequence gt lt s complexType gt lt s element gt lt s element name GetQuoteResponse gt lt s complexType gt lt s sequence gt lt s element minOccurs 0 maxOccurs 1 name GetQuoteResult type s string gt lt s sequence gt lt s complexType gt lt s element gt lt s element name string nillable true type s string gt lt s schema gt lt wsdl types gt lt wsdl message name GetQuoteSoapin gt lt wsdl part name parameters element tns GetQuote gt lt wsdl message gt lt wsdl message name GetQuoteSoapOut gt lt wsdl part name parameters element tns GetQuoteResponse gt lt wsdl message gt lt ws
3. e 1 ItemName datatype string minimum 1 maximum 1 e ItemInfo e ItemName PEE datatype string CCT WA ANA ym M y ine 2 ItemQty datatype integer minimum 1 maximum 1 2 ItemPrice datatype double minimum 1 maximum 1 Implementing Your Methods SAWS Web Service methods are monadic functions which return a result The right argument represents the input message and the result represents the output message The input and output messages are each contained in an MLS These MLS s correspond to their descriptions contained in the API 25 26 SAWS Input Message The input message contained in the right argument is an MLS It contains elements representing the arguments for the method where columns 52 and 3 are of particular interest 51 contains the level number this can be ignored 2 contains the element name 3 contains the element value 54 is not currently used and contains the value 0 2pe The function gete lement in WebServices is a useful utility to retrieve elements It will return the element value if found or an empty vector if not found getelement a 2 1cw a 53 c Output Message The result of your function used to implement the Web Service method is a 2 element array result 1 1 indicates that result 2 contains an MLS result 2 MLS if result 1 1 otherwise it is any APL array The MLS contains 1 contains the level number
4. lt wsdl port name StockQuoteSoap binding tns lt soap address location http lt wsdl port gt lt wsdl services There may be several port tags within the service tag Locate the port tag corresponding to SOAP 1 1 in this case its named StockQuoteSOAP There are two pieces of information of interest here The first is the address tag which will indicate the location and page of the web service The second is the binding attribute which will lead us to the definition of the service 3 Working up the file find the matching StockQuoteSOAP binding tag lt wsdl binding name StockQuoteSoap type tns StockQuoteSoap gt lt soap operation soapAction http www webserviceX NET GetQuote style document gt The type attribute of the binding tag StockQuoteSoap will point us to the appropriate portType tag The soapAction attribute of the operation tag is useful for debugging Web Service calls more on this later 4 Again working up the file find the matching portType tag lt wsdl portType name StockQuoteSoap gt lt wsdl operation name gt lt wsdl input message tns GetQuoteSoapIn gt lt wsdl output message tns GetQuoteSoapOut 5 lt wsadl operations lt wsdl portType gt There may be more than one operation defined Find the operation you re interested in in this case GetQuote Within the operation tag you may find input and output tags 5 If an input tag exists find t
5. service the namespace name containing the service soapaction optional If a non standard SOAPAction is required in the HTTP header it may be specified here as a character vector SSLparms optional If calling a secure Web Service this element is used to contain the appropriate Conga parameters in the form X509 client certificate SSLValidation n where client certificate is a type DRC X509Cert certificate SSLValidation specifies any optional flags for the processing of certificates Please refer to the Conga v2 1 or later documentation for more information on X509Cert and SSLValidation Right Argument The right argument to SAWS Cal can be either e A character vector containing the entire SOAP over HTTP request OR e A3 element nested vector 30 SAWS service The name of the service In many cases this will be either the page name or the service name will be method arg The method name to be invoked Can be in one of three formats e A simple non empty character vector containing the XML SOAP message No HTTP header information should be included here e Anempty vector if the web service method takes no parameters e A nested vector containing the names and values for the parameters to the web service method in any of the following formats e Depth 2 vector of vectors for example parami valuet param2 value2 e Depth 3 vector where each element contains a
6. SOAP 1 1 over HTTP POST stockquote asmx HTTP 1 1 Host www webservicex net Content Type text xml charset utf 8 Content Length length SOAPAction http www webserviceX NET GetQuote lt xml version 1 0 encoding utf 8 gt lt soap Envelope xmlns xsi http www w3 org 2001 XMLSchema instance xmlns xsd http www w3 org 2001 XMLSchema xmlns soap http schemas xmlsoap org soap envelope gt lt soap Body gt lt GetQuote xmlns http www webserviceX NET gt lt symbol gt string lt symbol gt lt GetQuote gt lt soap Body gt lt soap Envelope gt The first part of the message is an HTTP header which describes the location of the Web Service the fact that this is a SOAP request the function that will be invoked and how the content is encoded The second part of the message is an XML message that contains the SOAP request with the function to be invoked and the parameters that are passed There are several ways to invoke Web Services SAWS uses SOAP 1 1 over HTTP SAWS 7 CHAPTER 3 Let s Build a Web Service Steps to Build and Run a Web Service Building a Web Service using SAWS consists of the following steps In a namespace e Write one or more functions that do something useful interesting or amusing e Write a function called Buil dAPI that describe your useful interesting or amusing functions their arguments and results Then start the SAWS Server That s it end of story
7. This can be used to indicate nesting of data in the output message result 5 2 contains the output message element name 5 3 contains the output message element value 54 is not currently used and contains the value O 2pc The structure below depicts an element called ItemList which contains two ItemName elements Jdis 2 gt PriceCheck ListItems 0 4p0 gt y KO 1 ItemList E 0 gt 2 ItemName Apple ft M r 2 ItemName Ball M M r NG 2 ItemName Cactus 0 M r 2 ItemName Daisy M SAWS 27 APPENDIX I Namespaces Provided with SAWS ClientSample Contains a class WWWeather which implements a sample world wide weather dialog using the SAWS Client SAWS Cal l zH new ClientSample WWWeather PIS World Wide Weather Country United Kingdom City London Heathrow Aiport v London Heathrow Airport United Kingdom EGLL 51 29N 000 27W 0M Jan 29 2010 10 20 PM EST 2010 01 30 0320 UTC from the WNW 300 degrees at 10 MPH 9 KT 0 greater than 7 mile s 0 30 F 1C Windchill 21 F 6 C 1 23 F 5C 74 29 41 in Hg 0996 hPa Success MyWebService Contains a sample Web Service which implements a simple regression analysis service PriceCheck Contains a sample Web Service which implements a simple database driven application SAWS Contains the functions to invoke and serve Web Services WebServices Contains nested namespaces
8. dialog to invoke the ListItems method PriceCheck Listitems Dyalog Ltd Oo t Xx e http localhost 8080 PriceCheck Listltems ve Favorites PriceCheck Listitems PriceCheck ListItems ListItems List the items available via this service Return to main page SAWS 13 Clicking on the Submit button will in invoke the Listltems method PriceCheck Listitems Dyalog Ltd Go e X http localhost8080 PriceCheck Listitems We Favorites PriceCheck Listitems PriceCheck ListItems ListItems List the items available via this service ItemList ItemName Apple ItemName Ball ItemName Cactus ItemName Daisy In less than 30 lines of code plus comments we have created a fully functional albeit modest Web Service 14 SAWS CHAPTER 4 Invoking Web Services Using SAWS Invoking Web Services In Chapter 3 we saw how you can invoke a Web Service using a web browser Many Web Services may be invoked in this manner Using a browser is not an optimal way to integrate the results from a Web Service into your application or business process For this you use a Web Service client Introducing SAWS Cal l SAWS Ca l is the client function used to invoke Web Services Before you use SAWS Cal l or the SAWS server SAWS Run you need to initialize SAWS with SAWS Init This needs to be done only once in a session Then to invoke the Web S
9. parameter value pair This format is similar to that used for Dyalog GUI objects param value1 param2 value2 e 2 column matrix of 4 parameter names 2 parameter values 2 2 p parami valuet param2 value2 Result r 1 is a return code of O meaning no exception was detected or non zero to indicate that some exception was detected If r 1 0 no exception was detected r 2 will be a 3 element vector containing 4 the method name 2 the method result either in the form of an MLS or arbitrary APL data 3 pvm for the attributes applied to the method Depending on the SOAP response is built by the Web Service a return code of O may not guarantee success Additional examination of the contents of r 2 may be necessary to validate the response If r 1 1 the Web Service sent a SOAP Fault response r 2 a vector of vectors containing information about the fault SAWS Init reSAWS Init SAWS 31 If r 1 71 the SOAP message could not be decoded r 2 isa 3 element vector containing 1 Client Invalid 2 error message 3 na If r 1 gt 1 Conga signalled an exception then r contains r 1 exception code r 2 exception name r 3 additional exception information if any Initialize SAWS r 1 is 0 for success otherwise a Conga exception code r 2 is a character vector status message If r 1 0 then r 2 is either Conga loaded if Conga has not been previously
10. the service locally on port 8080 the URL for the service is http localhost 8080 PriceCheck The SAWS server includes HTML code to display information about your Web Service PriceCheck Dyalog Ltd GO tay gt 4 X l http localhost 8080 PriceCheck X gt O i sg Google ir Favorites PriceCheck The following operations are supported For a formal definition please review the Service Description e Listitems e GetltemInfo 12 SAWS Clicking on the Service Description link will display the WSDL that was built by SAWS for your Web Service Ve Favorites http localhost 8080 PriceCheck WSDL lt xml version 1 0 encoding UTF 8 gt A lt definitions name PriceCheck targetNamespace http localhost 8080 PriceCheck WSDL xmins tns http localhost 8080 PriceCheck WSDL xmins mytypes http localhost 8080 PriceCheck schema xmins http schemas xmlsoap org wsdl xmins xsd http www w3 org 2001 XMLSchema xmins soap http schemas xmlsoap org wsdl soap xmins soapenc http schemas xmlsoap org soap encoding xmins http http schemas xmlsoap org wsdl http xmins mime http schemas xmlsoap org wsdl mime gt lt types gt lt xsd schema targetNamespace http localhost 8080 PriceCheck schema elementFormDefault qualified gt lt xsd element name Listitems gt lt xsd complexType gt m Clicking on the ListItems link will display a
11. value 8 A 54 2 column attribute name value pairs 9 A The result represents a 2 level nested structure of 10 A ItemList which contains O or more ItemNames 11 A equivalent to the XML 12 A lt ItemList gt 13 A lt ItemName gt First Item Name lt ItemName gt 14 A lt ItemName gt Second Item Name lt ItemName gt 15 A ait 16 a lt ItemList gt 17 noatt 0 2pc A no attributes 18 result 1 4p1 Itemlist noatt A build the ItemList Level 19 result lt 2 c ItemName DataBase 1 cnoatt A Add the ItemNames from the database 20 re result SAWS 9 v reGetItemInfo arg ind name qty price resp znoatt result 1 A Implements the GetItemInfo method for the PriceCheck web service 2 A arg 1 row Markup Language Structure MLS 3 A 1 level 1 4 A 5 2 ItemName 5 A 3 character vector of the name of the item to retrieve 6 A 34 c0 2p indicating there are no attributes 7 a r 1 1 indicates r 2 is an MLS 8 a r 2 MLS containing the result 9 A 51 depth of nesting origin 1 10 A 52 element name 11 A 53 element value 12 A 34 2 column attribute name value pairs 13 A The result represents a 2 level nested structure of 14 A ItemInfo which contains information for equivalent to the XML 15 A lt ItemInfo gt Not Found 16 A lt ItemName gt name lt ItemName gt 17 A lt ItemQty gt quantity lt ItemName gt 18 A lt ItemPrice g
12. KNANG sdengeadeveds oteecsesbeseedssdedon aden slbnudsa stolen AGNO 4 Whati a WebiSerlice naci SNANG NIKA NA BAI 4 SOAP WSDL and many other Acronym3S mmaaaaaawaaaaaaaanaaaaaaanaaaaaasanasanaaanasasasasansanaasassasaanaanasasans 5 WSDL a E EET 5 SOAP onan GAAN BINABA A A A ake gies 0d led eae Ba daa a AA Adi a 6 LET S BUILD A WEB SERVICE A RET RE RE a 7 Steps to Build and Run a Web Service ana nanaawwaaawanaanaaananananaasasanasanaaanasasasasansanasasasasannansasasans 7 A SOMple WED Service ena a iN NAAT AN NPA DANG KANA 0 AGA BABABA 7 INVOKING WEB SERVICES USING SAWS ul nna nanan 14 INVOKING WED SCPVICES o a Apan ANA KA KABIBE NGARAN 14 Introducing SAWS CB nna salen GA aad Sa an td ea ea ati a ah 14 REGGING Eo MUTET DI DE FIC EE anG NGANGA TAK castbacdbocban IG lates TE 15 Sample SOAP REGUCS T e sass shen naka nase Aida adidas GAD NAAN 18 LOE TNE User BOWIE iii ia BA NIBA NGI BA ARA AA 19 PROVIDING WEB SERVICES WITH SAWS ul nananana 20 Using SAWS RUN Naga atea 20 Dedicated Web Services ci A ae a e a adea tdaveelebated 20 Running Multiple Web Services 2 00000003ma nananana aaaanaaaaaaaanananaanasasanansanaanasasanananaanasasasensnnaanasasssossnn 20 Secure Web Services Using SAWS RUNSECUPE cc cdc nca nan wwna naan aananaawanaaaawannaaananaaansanaasannansanannaaoan 21 INTEGRATING SAWS WITHIN YOUR APPLICATION 222000000n nn 22 Steps to Integrate SAWS 103 asana GN NANANA 22 BUTLER PA ida 23 Impleme
13. The tool of thought for expert programming mr 1 7 1 Dyalog for Windows SAWS User Guide Stand Alone Web Service Framework Version 1 4 Dyalog Limited Minchens Court Minchens Lane Bramley Hampshire RG26 5BH United Kingdom National 01256 830030 International 44 1256 830030 fax 44 0 1256 830031 email support dyalog com http www dyalog com tel Dyalog is a trademark of Dyalog Limited Copyright O 1982 2011 by Dyalog Limited All rights reserved Version 1 4 Developed for Conga v2 1 First Edition March 2011 No part of this publication may be reproduced in any form by any means without the prior written permission of Dyalog Limited Dyalog Limited makes no representations or warranties with respect to the contents hereof and specifically disclaims any implied warranties of merchantability or fitness for any particular purpose Dyalog Limited reserves the right to revise this publication without notification TRADEMARKS Unix is a trademark of X Open Ltd Linux is a trademark of Linus Torvalds Windows is a trademark of Microsoft Corporation Intel and Core are trademarks of Intel Corporation All other trademarks and copyrights are acknowledged Contents WHATIS SAW a a aia iiaa 1 BOCKITOUNA Oi a EAN AA 1 Ii Maa A A A NRO 1 Testing SAWS dit 3 WED Services VIA NET id NG ING ABAD NING ABA RENA BAGA ANG NITA 3 A BRIEF WEB SERVICE PRIMER c lt ces csccs sg pasya kna nd tencia cayo
14. aded r is the thread number for the server If arg 2 is 0 run in current thread r isn t particularly interesting Description SAWS must have been initialized prior to using SAWS Run See SAWS INIT The expression SAWS Run 8 will start a SAWS server named HTTPSRV on port 8080 in the current thread To stop a SAWS server running in the current thread you need to generate a strong interrupt and the server should interrupt within 10 seconds SAWS RunSecure Start a Secure SAWS Server r lt svc SAWS RunSecure port threaded srvname address rootcertpath cert address The address domain name or IP address for the service This is used is the WSDL that SAWS generates Defaults to localhost if empty or not supplied cert The server certificate as an instance of DRC X509Cert Please refer to Conga v2 1 or later documentation for information on X509Cert port The port number for the server defaults to port 8080 SAWS 33 r If arg 2 is 1 run threaded r is the thread number for the server If arg 2 is O run in current thread r isn t particularly interesting rootcertpath The path containing the certification authority CA certificates to be used defaults to the result of SAWS Samples CertPath srvname The name to assign to the web server If not supplied Conga will assign the name HTTPSRV svc The name of the namespace containin
15. ameter to SAWS Run SAWS RunSecure Added SAWS DEBUG 1 2 Aug 2010 Added SAWS Cal LSOAP Added additional modes to SAWS DEBUG 1 3 Sep 2010 Removed SAWS Cal LSOAP and modified SAWS Call Added additional mode to SAWS TRACE Added certificate parameter to SAWS Cal l 1 4 Mar 2011 Updated areas addressing secure web services to be compatible with Conga v2 1
16. arly those outside of APL realm has often been cumbersome and sometimes problematic Conversely incorporating the results of functionality developed outside of APL has proven to be similarly challenging Enter the Stand Alone Web Service SAWS framework SAWS e Enables an APL programmer to easily make results available via Web Services without having to become an expert in all of the standards and protocols necessary to develop and deploy Web Services e Makes it easy to retrieve the results of Web Services developed by others and use them in a natural APL manner SAWS will handle most Web Service needs but is not intended to be a comprehensive offering that addresses all of the nuances of very complex Web Services In particular SAWS supports Web Services using the Simple Object Access Protocol SOAP standard and Web Service Description Language WSDL At present SAWS does 1 Please refer to the Conga User Guide for more information on Conga 2 SAWS not support REpresentational State Transfer RESTful Web Services nor Web API Web Services SAWS 3 Testing SAWS To quickly test SAWS on your system load the SAWS workspace and enter SAWS Test 1 O Conga Web server HTTPSRV started on port 8080 Handling requests using SAWS HandleRequest Running 100 tests 100 calls in 611 msec 163 7 calls sec Response 0 Regression 1 RegResult xmlns http localhost MyWebService 2 Coeff0 0 05 2 Coeffi 2 03 2 Coe
17. ase see the reference for SAWS RunSecure function SAWS Test Secure in the workspace for an example of how to use SAWS RunSecure and SAWS Ca l to provide and consume secure Web Services 22 SAWS CHAPTER 6 Integrating SAWS within Your Application Steps to Integrate SAWS 1 Have an application It could be an existing application that you desire to make available as a Web Service It could be an application in which you desire to use functionality available through third party Web Services It could be a brand new application Or any combination of the above Copy the SAWS namespace into your application workspace SAWS can be installed in the root or in any namespace For this discussion we ll copy SAWS into the root namespace cs SAWS CY SAWS If your application already uses Conga you may want to assign SAWS DRC to reference the existing DRC namespace as follows assuming that Conga is in DRC SAWS DRC DRC In your application initialization code include the line SAWS Init This will initialize SAWS when your application runs If you are a Web Service consumer you ll use SAWS Ca l to invoke and retrieve results from Web Services If you are a Web Service provider you ll need to write functions for each method in your Web Service as well as Bui Ld API to describe your Web Service and then use SAWS Run or SAWS RunSecure to provide access to your WebService SAWS 23 BuildAPI Bui
18. back to the client instead of the response built by your application code This is useful for testing the interface to new clients to your Web Service SAWS DEBUG 1 A turn debug mode 1 on SAWS DEBUG 3 A turn debug modes 1 and 2 on SAWS DEBUG lt lt 1 A turn all debugging on SAWS DEBUG 0 A turn all debugging off 36 SAWS SAWS SILENT Suppress Session Output SAWS SILENT allows you to suppress output that would normally be sent to the APL session This is useful when running SAWS in a runtime environment Tracing output displayed when setting SAWS TRACEe1 3 is not suppressed SAWS Silent 1 A suppress session output Note All output is funneled through the function SAWS Out put which could be modified to log SAWS output to a file or some similar use SAWS TIMEOUT Client Timeout Setting SAWS TIMEOUT allows you to set the number milliseconds that SAWS Call should wait for a response from a Web Service before timing out The default is 10000 10 seconds SAMWS TIMEOUT 15000 A set 15 second timeout SAWS TRACE Trace Client and Server SAWS TRACE uses additive powers of 2 to turn on different tracing features Mode Description 1 Controls the display of trace information Setting this value will cause SAWS to display more detailed information about requests and responses that 1t processes 2 Set terse or verbose mode As some messages in the trace output can be rather lengthy setting this value will truncate
19. dAPlI is the function which returns the description of your Web Service SAWS uses Bui LAAPI to build the WSDL for your Web Service The result of Bui LdAPI is a vector with one element per method in your Web Service Each element of the vector contains three Markup Language Structure MLS elements These are a description of the method itself a description of the argument s to the method and a description of the result s of the method Describing the Method The method description can be as simple as the character vector name of the method ListItems Or the method could be an ML Sas follows 1 1 2 method name 3 4 parameter value matrix pvm 3 Valid parameters are documentation character vector description of the service pattern integer 1 2 or 4 describing the type of interaction with the method 1 one way input only 2 two way request response 4 one way output only notification method 1 4p1 GetItemInfo 2 2p pattern 2 documentation Get information about an item Describing the Method s Arguments and Results The argument and result descriptions are MLS structures and describe the allowable structure of the data for each element 51 level generally 1 for argument elements but can be used to represent more complex structures 2 element name 5 3 not currently used 51 parameter value matrix pvm 7 See Common Data Structures for more information on the structur
20. dedicated to running that particular Web Service MyWebService SAWS Run 8080 1 Web server HTTPSRV started on port 8080 Handling requests using SAWS HandleRequest If you want to run multiple dedicated Web Services you will need to run each in a separate APL session Running Multiple Web Services If you don t specify a namespace SAWS will search for a namespace that matches the name in the request In this way you can offer a number of Web Services from a single server Namespaces can be nested Consider the following example we have a namespace named WebServices and it contains three namespaces PriceCheck Regression and Weather each of which implements a Web Service To run all of these services use SAWS Run 8080 1 This will start a web server on port 8080 in a new thread The page name for each Web Service coincides with the namespace name Use instead of to delimit the namespace names SAWS 21 Using a web browser you would specify http localhost 8080 W ebServices PriceCheck GetItemInfo ItemName A pple Using SAWS Cal L you would specify localhost 8080 WebServices PriceCheck SAWS Call GetItemInfo ItemName Apple WebServices PriceCheck VListItems VGetItemInfo Regression VRegression Weather VWhatShouldIWear Secure Web Services Using SAWS RunSecure SAWS RunSecure is an analogous function to SAWS Run that provides secure Web Services over HTTPS Ple
21. dl message name GetQuoteHttpGetin 5 lt wsdl part namez symbol type s string gt SAWS 39 lt wsdl message gt lt wsdl message name GetQuoteHttpGetOut gt lt wsdl part name Body element tns string gt lt wsdl message gt lt wsdl message name GetQuoteHttpPostin gt lt wsdl part name symbol type s string gt lt wsdl message gt lt wsdl message name GetQuoteHttpPostOut gt lt wsdl part name Body element tns string gt lt wsdl message gt lt wsdl portType name StockQuoteSoap gt lt wsdl operation name GetQuote gt lt wsdl documentation xmins wsdl http schemas xmlsoap org wsdl gt Get Stock quote for a company Symbol lt wsdl documentation gt lt wsdl input message tns GetQuoteSoapin gt lt wsdl output message tns GetQuoteSoapOut gt lt wsdl operation gt lt wsdl portType gt lt wsdl portType name StockQuoteHttpGet gt lt wsdl operation name GetQuote gt lt wsdl documentation xmins wsdl http schemas xmlsoap org wsdl gt Get Stock quote for a company Symbol lt wsdl documentation gt lt wsdl input message tns GetQuoteHttpGetin gt lt wsdl output message tns GetQuoteHttpGetOut gt lt wsdl operation gt lt wsdl portType gt lt wsdl portType name StockQuoteHttpPost gt lt wsdl operation name GetQuote gt lt wsdl documentation xmins wsdl http schemas xmlsoap org wsdl gt Get Stock quote for a company Symbol lt wsdl documentation gt l
22. e of an MLS 8 See Common Data Structures for more information on the structure of a pvm 24 SAWS Valid parameters are documentation character vector description of the argument or result datatype generally one of string boolean integer or double It can also be a data type described by http www w3 org TR xmlschema 2 If you use one of these data types use the prefix xsd asin xsd dateTime minimum integer indicating the minimum number of times this element can occur within its parent element maximum integer indicating the maximum number of times this element can occur within its parent element 3 2p datatype integer minimum 1 maximum 1 Describes a single required integer element 1 2p minimum O Describes an optional array of any length The following code fully describes the GetltemInfo method of the PriceCheck Web Service method 1 4p1 GetItemInfo 2 2p pattern 2 documentation Get information about an item resultearg 0 4p0 arg3 1 ItemName 3 2p datatype string minimum 1 maximum 1 result lt 1 ItemInfo 1 2p minimum 0 result 2 ItemName 1 2p datatype string result lt 2 ItemQty 3 2p datatype integer minimum 1 maximum 1 result 2 ItemPrice 3 2p datatype double minimum 1 maximum 1 api cmethod arg result SAWS display z1 gt api gt e 1 Get1temInfo pattern documentation Get information about an item
23. e provider receives the request message and parameters and if valid processes the request and formats the response according to the service description and transmits it back using HTTP or HTTPS Finally the requestor receives the response parses it and uses the information contained therein WSDL uses XML to describe a Web Service When you want to use a Web Service provided by someone else you will need to examine its WSDL to understand how to invoke the service what arguments will be passed and what the results will look like There are six primary elements ina WSDL document 2 SOAP once stood for Simple Object Access Protocol but the acronym was dropped with Version 1 2 of the SOAP standard 5 6 SAWS SOAP Element Description kaagi This is the root element of the document and contains all the lt definition gt other elements Describes the data elements and types in the input and output lt types gt messages lt message gt Describes the messages that will be transmitted lt portType gt Describes the operations that are supported lt binding gt Describes how the messages will be transmitted lt service gt Describes the location of the service We ll take a closer look at how to interpret a WSDL document in order to invoke a Web Service from APL in Chapter 4 The request that is sent to a Web Service and the response it sends back use SOAP Below is sample request using
24. each of which implements a Web Service This is a sample to demonstrate one way to organize the delivery of multiple WebServices using a single SAWS server 28 SAWS APPENDIX II SAWS REFERENCE Common Data Structures There are two data structures that are used frequently in SAWS These are MLS Markup Language Structure 1 Level 52 Element Tag name 53 Element Tag value 54 pvm MLS s are used in the result of the SAWS Web Service Bui dAPI function and as the result of any functions which return the results of methods within the Web Service pvm parameter value matrix 1 Parameter name 2 Parameter value If no parameters exist the pvmis O 2p pvm s are used within an MLS and elsewhere in SAWS Functions SAWS Call SAWS 29 Invoke a Web Service rehost port page soapaction SSLparms SAWS Call soaprequest service method arg Left Argument host A character vector containing the host IP address or URI for the service optionally prefixed by http or https Examples localhost Www webservice net https www securews com port optional The port for the service If port is not specified the default HTTP port 80 will be used or 443 if HTTPS is specified in the host parameter Ports 80 and 443 are the typical ports for HTTP and HTTPS services respectively page optional The webpage for the service or in the case of SAWS hosted
25. eading a WSDL File Building a successful SAWS Cal request can involve a bit of research investigation and experimentation The primary source of information used to divine how to invoke a Web Service is its WSDL Some Web Services also publish sample SOAP over HTTP messages We ll start by looking at the WSDL for a public Web Service that retrieves stock quotes 1 At the top of the file find targetNamespace attribute in the definitions tag lt wsdl definitions xmins soap http schemas xmlsoap org wsdl soap xmins tm http microsoft com wsdl mime textMatching xmins soapenc http schemas xmlsoap org soap encoding xmins mime http schemas xmlsoap org wsdl mime xmins tns http www webserviceX NET xmins s http www w3 org 2001 XMLSchema 5 SAWS Cal L is fully documented in Appendix Il 6 See Appendix IV for the complete WSDL file listing 16 SAWS xmins soap12 http schemas xmlsoap org wsdl soap12 xmins htto http schemas xmlsoap org wsdl http targetNamespace http www webserviceX NET xmins wsdl http schemas xmlsoap org wsdl gt The targetNamespace will be the server that is used as the first argument to SAWS Call The capitalization and punctuation are significant Some targetNamespace tags may have a trailing as this one does 2 Find the service tag near the bottom of the file lt wsdl service name StockQuote gt
26. eb Services are XML Web services with a SOAP API that allows you to add location based functionality to your application that calls on the high quality maps as well as the location finding and routing capabilities of MapPoint Web Services http river sdsc edu wateroneflow N WIS Daily Values asmx WSDL The USGS National Water Information System NWIS provides access to millions of sites measuring streamflow groundwater levels and water quality This Web Service provides methods for retrieving daily values data such as discharge and water levels from NWIS http ws cdyne com WeatherWS Weather asmx wsdl Get Weather information by zipcode ws cdyne com 80 WeatherWs Weather asmx SAWS Call MeatherWS GetCityWeatherByZIP ZIP 20001 http www nws noaa gov xml This is the National Oceanic and Atmospheric Administration s National Weather Service National Digital Forecast Database Web Service http www usgovxml com USGovXML is an index to publically available web services and XML data sources that are provided by the US government USGovXML indexes data sources from all 3 branches of government as well as its boards commissions corporations and independent agencies 38 SAWS APPENDIX IV Sample WSDL This Appendix lists the entire WSDL for the StockQuote Web Service At the time of this writing this file was located at http www webservicex net stockquote asmx WSDL lt xml version 1 0 encoding utf 8
27. ervice we built in the previous chapter you would use data localhost 8080 PriceCheck SAWS Call GetItemInfo ItemName Cactus display data KN gt gt 0 gt ma m GetItemInfo y nm re ma gt gt ItemInfo re re xmlns http localhost c m gt gt ItemName Cactus N gt gt p ItemQty o rey re N T 9 99 re re gt ItemPrice N E SAWS 15 The syntax for SAWS CaLL is rehost port page SAWS Call service method pvm Optional host The host name for the service in this case localhost For other Web Services located on the Internet the host would be of the form www domainname com port The port for the service Defaults to port 80 the HTTP port page Optional The webpage for the service or in the case of SAWS hosted service the namespace name containing the service service The name of the service In many cases either the page name or the service name will be method The method name to be invoked pvm The parameter value matrix that contains the arguments to the method r r 17 is a return code of 0 for success non zero for failure The remaining part of the result can vary based on the particular Web Service or where the failure occurred See Appendix II for details on SAWS Call R
28. es the targetnamespace Port Unless otherwise specified port 80 HTTP or 445 HTTPS Page Name stockquote asmx Service Name None in this case Method Name GetQuote 18 SAWS Input Parameters Name symbol Value string containing stock symbol of interest Output Parameters Name GetQuoteResult Value string Sample SOAP Request A Web Service provider may publish a sample SOAP request and response The request is useful to compare to the request that SAWS Cal l builds POST stockquote asmx HTTP 1 1 Host www webservicex net Content Type text xml charset utf 8 Content Length length SOAPAction http www webserviceX NET GetQuote lt xml version 1 0 encoding utf 8 gt lt soap Envelope xmlns xsi http www w3 org 2001 XMLSchema instance xmlns xsd http www w3 org 2001 XMLSchema xmlns soap http schemas xmlsoap org soap envelope gt lt soap Body gt lt GetQuote xmlns http www webserviceX NET gt lt symbol gt string lt symbol gt lt GetQuote gt lt soap Body gt lt soap Envelope gt You can display intermediate results for both the SAWS client and server by setting SAWS TRACE to 1 The HTTP header hdr and SOAP request req are displayed You can examine SOAPAction in hdr to ensure that it matches the soapAction attribute in the WSDL see step 3 above or in the sample SOAP request SAWS TRACE lt 1 z www webserviceX NET 80 stockq
29. ff2 0 2 Residual 0 00075 0 Object HTTPSRV has been closed Web Server shutting down Web Services Via NET In addition to SAWS Dyalog APL provides a means to build and call Web Services using NET Please refer to the NET Interface Guide for more information 4 SAWS CHAPTER 2 A Brief Web Service Primer Note This chapter presents some background information about Web Services For those of you who are eager to roll up your sleeves and get to building and using Web Services skip to Chapter 3 What is a Web Service A quick search on the Internet for the definition of a Web Service will turn up a rather large number of results The W3C defines a web service as a software system designed to support interoperable machine to machine interaction over a network It has an interface described in a machine processable format specifically Web Services Description Language WSDL Other systems interact with the web service in a manner prescribed by its description using SOAP messages typically conveyed using HTTP with an XML serialization in conjunction with other web related standards Web Services are modular a Web Service is self contained and self describing Everything necessary to invoke a Web Service and interpret its results is a part of the Web Service itself Web Services are accessed via standard protocols Web Services can be accessed over the Internet or an intranet using a web browser or other client Web Serv
30. g the Web Service If svc is supplied the server runs in dedicated mode and will service only requests for the Web Service defined in the namespace If svc is not supplied the server will search for a namespace matching the Web Service name threaded Is 1 to run the service in a separate thread O the default to run in the current thread Discussion SAWS RunSecure is almost identical to SAWS Run except that it uses SSL TLS to provide secure communications SAWS must have been initialized prior to using SAWS RunSecure See SAWS INIT cert DRC X509Cert ReadCertFromFile c mycert cer rootcertpath c Imycertpath SAWS RunSecure 445 1 HTTPSRV rootcertpath cert Will start a secure SAWS server named HTTPSRV on port 445 in a separate thread and look in the directory c mycertpath for root certificates to use SAWS Stop Stop a SAWS Server r SAWS Stop srvname Svrname The SAWS server name to stop If empty 8 or all SAWS servers will be stopped 34 SAWS SAWS Test addre addre SAWS TestSecure Test SAWS ss SAWS Test close ss SAWS TestSecure close Address The address of the web server to use Defaults to localhost Close Flag to indicate how to run the test close 0 just start the SAWS server do not run tests close 1 start the SAWS server and run tests close 1 SAWS server already running just run tests Discussion SAWS Test isan easy
31. he matching message tag lt wsdl message name GetQuoteSoapIn gt lt wsdl part name parameters element tns GetQuote gt lt wsdl message gt SAWS 17 Each part tag names the element that describes the input parameters in this case GetQuote 6 Find the matching element tag lt s element name GetQuote gt lt s complexType gt lt s sequence gt lt s element minOccurs 0 maxOccurs 1 name symbol type s string 5 lt s sequence gt lt s complexType gt lt s element gt Here we find that there is one parameter symbol and that it is a string The minOccurs and maxOccurs attributes indicate the minimum and maximum number of occurrences of this parameter 7 Similar to the input tag if there is an output tag from Step 4 above find the matching message tag lt wsdl message name GetQuoteSoapOut gt lt wsdl part name parameters element tns GetQuoteResponse gt lt wsdl message gt 8 Find the matching element tag lt s element name GetQuoteResponse gt lt s complexType gt lt s sequence gt lt s element minOccurs 0 maxOccurs 1 name GetQuoteResult type s string gt lt s sequence gt lt s complexType gt lt s element gt We see that the result is named GetQuoteResult and is a string Based on the WSDL file here is what we know about this Web Service Server address www webserviceX NET notice the capitalization match
32. ices are platform independent Web Service providers and requestors can communicate effectively without any knowledge of the platform that either is using Web Services share data business logic or processes Web Services can deliver a wide range of function from very simple a query response service to very complicated business processes SAWS SOAP WSDL and many other Acronyms WSDL SOAP XML Request Based on WSDL Service Provider Service Requestor SOAP XML Response Based on WSDL WSDL Service Description The diagram above depicts a typical Web Service interaction The provider has developed some sort of service that he wishes to make available The service is developed in whatever language or technology the provider chooses The service could implement several methods functions each with different parameters arguments To make the service available the provider describes the service its methods their parameters and responses using the Web Service Description Language WSDL WSDL is formatted using XML The requestor uses the WSDL Service Description to build a request message using SOAP SOAP is formatted using XML as well The SOAP message is transmitted from the requestor to the provider typically using HTTP HTTPS can also be used when secure interaction is required The request will indicate what method is being requested along with any parameters necessary for the request Th
33. loaded Conga reset if Conga has been previously loaded Discussion SAWS Init is used to initialize SAWS You must call SAWS Init prior to running the SAWS client or server but you need only call it once during your session Note If Conga is in use elsewhere in your application you should use that instance of Conga instead of running SAWS INIT This is done by assigning SAWS DRC to the path of the DRC namespace For example if Conga the DRC namespace is in the root you would assign SAWS DRC as follows SAWS DRC lt DRC SAWS Run Start a SAWS Server r lt svc SAWS Run port threaded srvname address address The address domain name or IP address for the service This is used is the WSDL that SAWS generates Defaults to localhost if empty or not supplied 32 SAWS port The port number for the server defaults to port 8080 threaded 1 indicates run the server in a separate thread 0 the default indicates run the server in the current thread srvname The name to assign to the web server If not supplied Conga will assign the name HTTPSRV SVC A reference to the namespace containing the Web Service If svc is supplied the server runs in dedicated mode and will service only requests for the Web Service defined in the namespace If svc is not supplied the server will search for a namespace matching the Web Service name r If arg 2 is 1 run thre
34. nting YOUR Methods iii said 25 NAMESPACES PROVIDED WITH SAWS ccccsssssscccccccecececeseeeaeeeaeaeseeeeceeeeeseseseseseeeseeeeeseseeeeeseeeeeeeeeeeeeseeeeeeeeees 27 SAWS REFERENCE naima Gan NAGA DINA ANNA E EE I EE 28 COMMON Data Str CtUFeS 2a sana DAN NANG GA ABANGAN 28 FUNCION PAE A AA AA AA 29 VOTADOS ici BANGAG A NAG ANNA DATA NALANG NG NATAL ATLANTA 34 A SAMPLING OF PUBLIC WEB SERVICES cccccceccecececececececececececececeeeceeeeeeeeseeeeeeeee cece se ceseseseseseseseseseseseserenenens 37 SAMPLEWSD Lies nara A dad 38 DOCUMENT CHANGELOG a saaan NA maa NEN an NA MAD aaa At Ga DA NAG E Eaa ie rar Er aaia NG DUMIRAID 42 CHAPTER 1 What is SAWS Background SAWS is a workspace with tools to help you easily share the functionality you develop in Dyalog APL with others via Web Services SAWS hides most of the underlying complexities of building Web Services allowing you to focus on solving the problem at hand and make your results available to others SAWS uses Conga to communicate via TCP IP The Web Service protocol is one of the most widely used mechanisms for making functionality over the internet and is supported by a very wide variety of programming languages and development tools Introduction APL programmers have long built highly functional applications and utilities to perform various types of analysis query databases and a myriad of other tasks Sharing the results of these efforts with others particul
35. on gt lt wsdl binding gt lt wsdl binding name StockQuoteHttpPost type tns StockQuoteHttpPost gt lt http binding verb POST gt lt wsdl operation name GetQuote gt lt http operation location GetQuote gt lt wsdl input gt lt mime content type application x www form urlencoded gt lt wsdl input gt lt wsdl output gt lt mime mimeXml part Body gt lt wsdl output gt lt wsdl operation gt lt wsdl binding gt lt wsdl service name StockQuote gt lt wsdl port name StockQuoteSoap binding tns StockQuoteSoap gt lt soap address location http www webservicex net stockquote asmx gt lt wsdl port gt lt wsdl port name StockQuoteSoap12 binding tns StockQuoteSoap12 gt lt soap12 address location http www webservicex net stockquote asmx gt SAWS 41 lt wsdl port gt lt wsdl port name StockQuoteHttpGet binding tns StockQuoteHttpGet gt lt http address location http www webservicex net stockquote asmx gt lt wsdl port gt lt wsdl port name StockQuoteHttpPost binding tns StockQuoteHttpPost gt lt http address location http www webservicex net stockquote asmx gt lt wsdl port gt lt wsdl service gt lt wsdl definitions gt 42 SAWS Document Change Log This section describes the major changes made with each version of this document Version Date Description 1 0 Dec 2009 Original version 1 1 Jul 2010 Added address par
36. t price lt ItemPrice gt 19 A lt ItemInfo gt 20 name arg 2 1c ItemName gt arg 3 c A get the ItemName element 21 ind DataBase 1 icname A look the name up 22 resp ItemName ItemQty ItemPrice 1 5 DataBasezname 8 ind A look up item information 23 noatt 0 2pc A no attributes 24 result 1 4p1 ItemInfo Not Found 4 4xinds ppDataBase noatt A ItemInfo level 25 result 2 resp cnoatt A item details 26 rei result 10 SAWS Finally we ll define our API Application Programming Interface for the Web Service 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 y api BuildAPI method arg result IML A Construct the API for the PriceCheck Web Service A api vector of method definitions one element per method in the Web Service 1 method description 2 argument s description 3 result s description This Web Service has 2 methods ListItems and GetItemInfo ListItems has no arguments and returns a list of the items in the database A GetItemInfo takes the name of an item and returns information about the item DD D D D D OML 1 api 0pe A ListItems method definition method 1 4p1 ListItems 1 2p documentation List the items available via this service result arg 0 4p0 A initialize the ListItems method s argument and result descriptions A as there is no argumen
37. t to this method arg remains a O row matrix results lt 1 Itemlist minimum 1 maximum 1 A there is exactly 1 ItemList result result 2 ItemName datatype string minimum 0 A which contains O or more ItemNames api cmethod arg result A append the ListItems method definition A GetItemInfo method definition method 1 491 GetItemInfo 1 2p documentation Get information about an item result arg 0 4p0 A initialize the GetItemInfo method s argument and result descriptions arg 1 ItemName t datatype string minimum 1 maximum 1 A the argument is an ItemName result lt 1 ItemInfo minimum 1 maximum 1 A the result an ItemInfo which contains result 2 ItemName datatype string minimum 1 maximum 1 A 1 ItemName result 2 ItemQty t datatype integer minimum 1 maximum 1 A 1 ItemQty result 2 ItemPrice datatype double minimum 1 maximum 1 A and 1 ItemPrice api cmethod arg result A append the GetItemInfo method definition SAWS 11 The programming for our Web Service is done Now all that s left to do is start up the SAWS server SAWS Init A Initialize SAWS O Conga loaded from C Program Files Dyalog Dyalog SAWS Run 8080 1 A Start service on port 8080 in a new thread Web server HTTPSRV started on port 8080 Handling requests using SAWS HandleRequest We re ready to try the service out Since we started
38. t wsdl input message tns GetQuoteHttpPostin gt lt wsdl output message tns GetQuoteHttpPostOut gt lt wsdl operation gt lt wsdl portType gt lt wsdl binding name StockQuoteSoap type tns StockQuoteSoap gt lt soap binding transport http schemas xmlsoap org soap http gt lt wsdl operation name GetQuote gt lt soap operation soapAction http www webserviceX NET GetQuote style document gt lt wsdl input gt lt soap body use literal gt lt wsdl input gt lt wsdl output gt 40 SAWS lt soap body use literal gt lt wsdl output gt lt wsdl operation gt lt wsdl binding gt lt wsdl binding name StockQuoteSoap12 type tns StockQuoteSoap gt lt soap12 binding transport http schemas xmlsoap org soap http gt lt wsdl operation name GetQuote gt lt soap12 operation soapAction http www webserviceX NET GetQuote style document gt lt wsdl input gt lt soap12 body use literal gt lt wsdl input gt lt wsdl output gt lt soap12 body use literal gt lt wsdl output gt lt wsdl operation gt lt wsdl binding gt lt wsdl binding name StockQuoteHttpGet type tns StockQuoteHttpGet gt lt http binding verb GET gt lt wsdl operation name GetQuote gt lt http operation location GetQuote gt lt wsdl input gt lt http urlEncoded gt lt wsdl input gt lt wsdl output gt lt mime mimeXml part Body gt lt wsdl output gt lt wsdl operati
39. the output to the first 65 characters of a message This is useful for monitoring the flow of requests and responses within SAWS rather than their detailed content SAWS TRACE lt 1 A turn verbose tracing on SAWS TRACE 3 A turn terse tracing on SAWS TRACE lt 0 A turn all debugging off SAWS STYLE Cascading Style Sheet for Web Pages The HTML web pages that SAWS Run produces are built in the function SAWS ServiceHTML While you could modify this function to change the content look and feel of the web pages most changes can be accomplished by modifying the variable SAWS STYLE which is a Cascading Style Sheet CSS SAWS 37 APPENDIX III A Sampling of Public Web Services This appendix lists some free public Web Services the author happened upon while doing research for this manual www webserviceX NET www wsdll com There are a large number of free web services offered from www webserviceX NET ranging from stock quotations to weather services to Bible quotations to unit conversions including if you ever wondered how many miles are in a parsec well here it is 3 gt 2 2 gt www webserviceX NET 80 Astronomical asmx SAWS Call ChangeAstronomicalUnit AstronomicalValue 1 fromAstronomicalUnit parsec toAstronomicalUnit miles 19173514177205 121 This is a website that catalogs both free and fee Web Services including http staging mappoint net standard 30 Microsoft MapPoint W
40. uote asmx SAWS Call GetQuote symbol k hdr POST stockquote asmx HTTP 1 1 Host www webserviceX NET SOAPAction http www webserviceX NET GetQuote Content Type text xml charset utf 8 Content Length 50 req lt xml version 1 0 gt lt SOAP ENV Envelope SOAP ENV encodingStyle http schemas xmlsoap org soap encoding xmlns SOAP ENC http schemas xmlsoap org soap encoding xmlns SOAP ENV http schemas xmlsoap org soap envelope xmlns xsd http www w3 org 2001 XMLSchema xmlns xsi http www w3 org 2001 XMLSchema instance gt lt SOAP ENV Body gt lt GetQuote SAWS 19 xmlns http www webserviceX NET gt lt symbol gt k lt symbol gt lt GetQuote gt lt SOAP ENV Body gt lt SOAP ENV Envelope gt Chapter NET Interface Guide Let the User Beware There are free Web Services and there are Web Services that can be subscribed to for a fee Be mindful that when you use a free service the provider is under no obligation to maintain the service inform you of changes or even keep the service running 20 SAWS CHAPTER 5 Providing Web Services With SAWS Using SAWS Run SAWS Run is used to run Web Service s It starts a Conga based web server and processes SOAP requests Dedicated Web Services When you supply namespace name as the left argument to SAWS Run only methods defined in that namespace are available via the Web Service In effect the port you specify 8080 in this case is
41. way to verify that SAWS will function in your environment SAWS TestSecure will perform the same tests securely using HTTPS Variables SAWS DEBUG Debug Mode Settings SAWS DEBUG uses additive powers of 2 to turn on different debugging features Mode Description 1 Controls the server error trapping when executing your Web Service methods Normally SAWS will trap any unhandled error in your Web Service method and return an error code Setting SAWS DEBUG to 1 will disable SAWS built in error handling This is useful for debugging your Web Service methods but should not be left on in general Captures the last request and response pair When using SAWS Ca Ll L the last request and response pair are stored in SAWS LastCal lRequest and SAWS LastCal lResponse When using SAWS Run the last request and response pair are stored in SAWS LastRunRequest and SAWS LastRunResponse These are useful for testing and debugging Use alternate messages When using SAWS Cal L you may construct an entire SOAP over HTTP request and assign it to the variable SAWS AltRequest SAWS will send SAWS 35 this request to the Web Service rather than the one built from the arguments to SAWS Call This is useful when testing for basic connectivity to a Web Service When using SAWS Run you may construct a SOAP response and assign it to the variable SAWS Al tResponse SAWS will send this response
Download Pdf Manuals
Related Search