SOAP was created to describe and/or implement the rules for program to program communication over HTTP using XML. SOAP is often perceived as complicated because of its obscurity, and that is quite possibly why most implementations use a very small portion of the specification. SOAP tools weren’t available immediately and the details of SOAP were never meant for human eyes to decipher. Instead SOAP was meant to be an “under-the-covers” type technology. The way most SOAP implementations work is a SOAP envelope and body are simply added to the beginning and end of the XML document. Remember, SOAP is nothing more than text (say XML). Take a look at Figure 8 which shows a non-SOAP example of a simple price calculating XML request.
Figure 9 shows what the equivalent in SOAP would be. Note that this particular example is using a style named RPC (Remote Procedure Call) Encoded – a common SOAP implementation. This approach to SOAP is undesirable because it causes the data type to be sent along with the data (what Encoded means), adding more to the already bloated document. The preferable SOAP style would be what’s called Document Literal as shown in Figure 10. When using Document Literal you specify the data types for the XML in an XSD within what’s called a WSDL. After working with RPC and Document approaches you will most likely ask yourself “Why were RPC and Document Literal created as separate styles instead of just having a single style coupled with a Boolean flag specifying whether or not the data type should be sent along with the request?”. This is where flexibility to withstand change introduced obscurity, giving us what we now have.
WSDL
Web Service Description Language (WSDL)
WSDL’s are used at development time to describe a web service program including the names of procedures, input/output parameters, URL of the web service, and what enveloping mechanisms and transport will be used (i.e. SOAP over HTTP). If you are the one creating a web service then you create a WSDL file that other programmers will use when they develop code on their end to consume your web service. WSDL files are not used at runtime but are simply a method for most programming languages to “stub out” their code, or rather produce a code template that can be filled in with their business logic.
In concept WSDL files are a beautiful thing. After all, they save from having to verbally describe the web service to a trading partner. Your trading partner can simply point their browser to a WSDL on your server and know every technical aspect about how to make use of your web service. The WSDL states the exact URL of the web service it is defining (e.g. http://myiSeries.com/cgi-bin/ws1) and describes what data is required for input and output – all in one singular document. I liken a WSDL to an RPG service program. Figure 11 shows an example of how an RPG prototype can be transposed into WSDL’s equivalent portType tag. Note that both the prototype and portType are making references to the actual message to be used for input/output structures using LIKEDS and message respectively. We have to look elseware in the WSDL document to find how the data types defined in the message attribute are defined - just like how we need to look elseware in our program to see how the structure specified in LIKEDS is defined.
Figure 11
Figure 12 shows how the message tags of a WSDL relate to RPG data structures. They both define the name and data type of information passed in/out of the interfaces.
Figure 12
Now that names of the subprocedures (read portTypes) are defined we need to state where they are located. Concerning an RPG Service Program, one simply needs to know the library where the object resides to call it. With a WSDL you use the service element to define the URL location of the web service as shown in Figure 13.
Figure 13
You will also notice the port element and associated binding attribute. When creating a WSDL to define a web service you have what’s called the binding portion of the document. WSDL’s binding tag isn’t as easily related to the RPG environment. Its purpose is to connect the <service> to the <portType> and define the enveloping mechanism and transport to be used (i.e. SOAP envelopes over HTTP) as shown in Figure 14. The information contained in the binding tag could have easily been placed in either the service tag or the portType, but the creators of the specification separated it out for modularity sake. You will note the type attribute in the binding tag contains the name of the previously defined portType – ORDSV. You will also note that there are two operation tags named the same as the operations defined in the portType tag. This is where the defining of the envelope (i.e. SOAP) takes place.
Figure 14
A raw WSDL is even more painful than looking at a raw XSD, which is why we can again be thankful for visual drag ’n’ drop WSDL tooling also available in WDSC. Figure 15 gives a visual example of the four portions of a WSDL. From this screen in WDSC you can completely compose a WSDL without having to look at the raw text.
Figure 15
Note that even though the WSDL specification allows many different approaches to be taken concerning plumbing there are only a couple approaches commonly used. For instance, the enveloping will be SOAP and transport will be HTTP/HTTPS 99% of the time.
Once you have a complete WSDL document in hand you can fully test it using WDSC by right clicking on the WSDL document and select Web Services -> Test with Web Services Explorer. This will open a view allowing you to select one of the procedures to call along with specifying necessary input parameters. Hitting the Submit button will send the request on it’s way to the web service specified in the <service> portion of the WSDL. When the process completes you have access to the request and response XML documents which is very helpful when debugging or trying to determine what exactly is being sent across the wire.XML(use the chapter 2.1 of the RXS user manual for this definition and XSD)
back to top
XML
The Extensible Markup Language (XML) is a W3C-recommended general-purpose markup language that supports a wide variety of applications. XML languages or 'dialects' are easy to design and to process. XML is also designed to be reasonably human-legible, and to this end, terseness was not considered essential in its structure. XML is a simplified subset of Standard Generalized Markup Language (SGML). Its primary purpose is to facilitate the sharing of data across different information systems, particularly systems connected via the Internet. Formally defined languages based on XML (such as RSS, MathML, XHTML, Scalable Vector Graphics, MusicXML and thousands of other examples) allow diverse software reliably to understand information formatted and passed in these languages.
back to top
XSD
An XSD defines the structure of a document and what type of data can appear in each of the elements. Take the following XML Schema Definition which defines the <PostAdr> element.
Oddly, this might look like an XML file to you. You are not confused. XSDs use XML to define themselves. The first tag is the <schema> tag. It merely declares what type of document we are in. Next is <element name="PostAdr">. That essentially declares the name of the element being described. Within the <element… tag there is a <complexType> tag which states PostAdr either has attributes or children elements, or both. The <name> element needs to be defined within the <PostAdr> tag. The <sequence> tag specifies that realtionship. The contents of the <sequence> tag should contain only a sequence of child element definitions. The innermost children will be simple datatypes defined by the type="string" attribute (or other primitive data type). The value of the data type attribute could specify a variety of types ranging from numerical to dates, timestamps, Booleans, and so forth.
Next note the definition of the phone element. It states that it can contain a string and must have at least one occurrence of the <phone> element included in the XML document at transaction time. It also states that there can be a total of two <phone> elements sent (i.e. maxOccurs=”2”)
Finally note the definition of an element's attribute (i.e. the residential attribute of element PostAdr) located within the PostAdr's <complexType> tag. Using the <attribute> tag defines the name and type - residential and boolean respectively.
The nested aspect of an XML Schema Definition is similar to the relationships between commonly used iSeries Physical Files. Consider an order application that maintains data taken over the phone. That application would likely rely on a header (or parent) type file describing when the order was taken, the customer number, when the order will ship, and so forth. It could also use a detail (or child) file holding multiple line items in a single order. Its records could specify things like item ordered, quantity, unit price, extended price, discounts, and the like.
Additional XSD resources
back to top
HTTP
(provided by wikipedia.org)
Hypertext Transfer Protocol (HTTP) is a method used to transfer or convey information on the World Wide Web. Its original purpose was to provide a way to publish and retrieve HTML pages.
HTTP is a request/response protocol between clients and servers. The originating client, such as a web browser, spider, or other end-user tool, is referred to as the user agent. The destination server, which stores or creates resources such as HTML files and images, is called the origin server. In between the user agent and origin server may be several intermediaries, such as proxies, gateways, and tunnels.
An HTTP client initiates a request by establishing a Transmission Control Protocol (TCP) connection to a particular port on a remote host (port 80 by default; see List of TCP and UDP port numbers). An HTTP server listening on that port waits for the client to send a request message.
Upon receiving the request, the server sends back a status line, such as "HTTP/1.1 200 OK", and a message of its own, the body of which is perhaps the requested file, an error message, or some other information.
back to top