Visual Objects Talks SOAP – Part 1
Extract
In the past, we’ve been talking a lot about SQL, XML, and how these technologies will influence upcoming projects. While it is very simple to build client-server applications for the local area network, client-server applications across the internet are far more complicated. Especially, given that security issues will make it impossible to talk directly to a database.
In this ‘serie’ of 2 articles, we will demonstrate how to design and program a client-server application for use across the internet without the need for n-tier architecture. We will show how Visual Objects works with SOAP. A web service will be built using VO & Sybase SQL version 9 as the basis. This project will also show how this interface is used with various programming environments including Visual Objects and C#.
During these sessions, we will demonstrate a sample VO application which uses Microsoft's SOAP SDK to call a web service, retrieve an XML-document, and display the results. Beyond that, we will also show how to use a web service to manipulate an SQL database by sending information via SOAP. In an intranet environment, this kind of architecture can be helpful, so you definitely should not miss these sessions.
In the 1st article – which you are reading now – we will focus more on the ‘theoretical’ background, while in de 2nd article the practical side will get the focus.
Web services are being constructed, for consumption by applications, not by users
Overview
Before adventuring into web services, we have to walk through the theory. What is a web service, what are the secrets of using one, and why may it be a good idea to use, or offer, a web service? After touching on the theory, we’ll take two different approaches to build a web service. The first one will be a VO application, to be more precise a VO class, which delivers some service information to the calling client. The second will be a web service, based on the latest Sybase SQL Anywhere, Version 9. After building the services, we can get on the highway with them. Of course, the subject of building a web service is far more complicated than using one, but before we can use one, we have to build one. The second part of our presentation will be easier than the first part. We’ll show how to use our web services from both a Visual Objects client and, to maintain the challenge, a C# client out of the .Net world.
What is a Web Service ?
Would you like to reach new markets with your software solution, by exposing components for third party consumption? Or would you like to integrate existing services from the internet into your application? You may already have a clue about the nature of web services, but you want to learn more about the technology and get into this fascinating ‘new’ world? Then, you’re definitely in the right ‘session’. One session, or one paper, cannot contain the full details. Therefore, I will only present the core components before attempting to program a service or a client consuming a service.
A Little Piece of History
Before approaching a new technology, it is always a good idea to try to understand it’s history, and how it has evolved. In the last few years, applications have been increasingly encapsulated through component technologies. Various reasons are responsible for this change. People want to reuse existing code in a different environment, and applications have been distributed across various machines to optimize resource consumption and improve performance. In the past, while we were still in the mainframe age, we only had dumb terminals and the available re-sources where concentrated in one location. As PC technology has evolved, a process also evolved, which has distributed resources wildly across the world. Parallel to this evolution, the internet evolved and built a “perfect” infrastructure for distributing resources, while maintaining access to them. While there have been some attempts in the past to achieve such distribution in an intranet environment (COM/DCOM), these technologies failed to include the internet in their calculations. For reasons of platform independence and security, the distribution technologies have not appeared in the internet. Other technologies, such as client/server computing, are however in place, and playing a major role in modern software development.
These technologies (COM/DCOM) failed to include the internet in their calculations
Web Services
A web service is a tool, exposed via a well-defined interface to the potential users (inter-net/intranet). Standardized protocols, such as FTP & HTTP, define the accessibility of such tools. Client applications are performing a kind of remote procedure call (RPC) to provide needed information and get results. Although HTTP provides the transportation, another protocol is needed to make processes understand each other. This protocol is called SOAP (Simple Object Access Protocol), and is based on XML. SOAP has one big advantage, when compared against other approaches such as DCOM: It “tunnels” through HTTP and becomes available in nearly all environments via this transport protocol. Most networks allow access the HTTP/HTTPS ports (such as 80, 8008, 8080, or 443). It is “The Port” used to surf the ‘net.
Theoretically, web services are being constructed for consumption by applications, not by users. They allow third party providers to offer services, which can be integrated into other applications. Because standardized protocols are being used, they are highly platform independent. A good example for a web service could be a piece of software, which is able to deliver the correct rate of exchange for a given date and currency. With such a service available, there’s no need to integrate and maintain your table for exchange rates.
Advantages of Web Services
Web services offer a couple of undeniable advantages for the client, as well as for the provider:
- Platform Independence: a web service can be used from any platform which is able to connect to the network (e.g. the internet), and send, or receive, SOAP messages
- Simple Transport Channel: there is no need for complicated installations or protocols. TCP, IP, and HTTP are available to almost every machine/operating system.
- Interoperation Between Companies: web services offer a very simple and stable integration of diverse business environments
- Reusability: software development can reuse existing services quite simply and therefore increase development speed, reduce costs, and deliver more stability.
- Secure Communication: due to the fact, that the communication uses the simple transportation protocol like “normal” web applications, web services can use the same variety of security mechanisms
Standards for Web Services
There were other technologies before the modern definition of web services (DCOM and CORBA, for example), which tried to offer distributed functionality. The “revolution” (or rather, “evolution”) dictates that web services should only be exposed via standardized interfaces. Here’s a overview:
- The HTTP protocol for communication
- XML as a description language:
- SOAP
- WSDL (Web Service Description Language)
- DISCO (Discovery Protocol)
- UDDI (Universal Description, Discovery and Integration)
SOAP and WSDL will be of particular interest to us. The others are included for completeness.
Architecture of Web Services
There two different techniques for working with web services. A service can be exposed via the internet (which technically includes the intranet) to offer a public service, which allows the rest of the world to use your internal functionality. Alternatively, one can access a web service via a customized client, to use external functionality.
A service can be exposed via the internet to offer a public service, which allows the rest of the world to use your internal functionality
Publishing a Web Service
Web services offer a bunch of new ideas to open your business to the rest of the world. The potential to easily communication with clients (in a standardized way), will push this technology and evolve to a completely new application architecture. Keep in mind: these services are exclusively meant for consumption by other applications. The ability to send messages and data through such a web service offer fascinating new ways to add new functionality to your business application
In the past (and in the present, of course), we saw many vendors of COM components, which allow us to reuse code and easily add new functionality to our applications, without the need to re-invent the wheel. In the future, we will see companies publishing services, attempting to reach the same goal. While COM components are usually bound by a licensing model, web services offer different business model. Pay per use, subscription models…hmm…I bet we’ll see many new ideas in that area.
Consuming a Web Service
Being a normal application developer, you probably want to consume web services. The level of the application architecture, with which you normally work, is unimportant; web services will be an integral part of future solutions. As consumption of the supply chain increase, your software is likely to need improved dovetailing with “partner” solutions. I personally expect web services to be very successful as an interface to other software systems. “Stop the confusion! Information here and now” is the motto. Stop the data redundancy and the need to validate data (safe-guards against out-dated or erroneous information). Concentration on the fundamentals: Your business! Use the external knowledge of the experts: web services!
Protocols
We already mentioned the fundamental parts of web services, now let’s take a closer look to the important definitions.
SOAP
The ‘Simple Object Access Protocol’ (SOAP) is the kernel protocol for web services. It is an XML-based standard for describing parameters and methods, which can be called as a web service. In addition to the description of the methods and parameters, it also manages the communication between the participating components. It says nothing about the implementation of the web service; it’s only a interface description.
HTTP is not the only possible transport protocol
Most documents about SOAP explicitly say that HTTP is not the only possible transport protocol. It is possible to transport SOAP messages through other protocols. SOAP describes the formal format of such a message; not the means of transportation. However, we’ll also apply the KISS (Keep It Simple, Stupid) theory, and only apply HTTP. The SOAP standard allows every application (including devices) to expose web services, as long as it can deliver and receive valid SOAP messages. It is completely unimportant which language is being used to implement the service, or which platform provides the service. Most SOAP implementations do not require in-depth knowledge of SOAP. Often, (for example in Visual Studio.Net) the complete handling is automated by generated proxy classes, which makes the process of consuming, or offering, a web service extremely simple.
SOAP Format
Although we theoretically must not do this, it is a good idea to take a closer look into the format of a SOAP message. It’s always a good idea to know what’s going on behind the scenes.
SOAP is being specified by using XML. If you already have some experience with XML-documents (if you were at DevFest last year, you should have), it should be very easy for you to read and interpret the meaning of a SAOP message.
SOAP messages are divided into 3 parts:
- Method call
- Result message
- Error Message
The method call is a request to call a method, probably with parameters, of a web service. The result of the call will generally will be a result message, including an error message (an error message is nothing less than a special result message). An error message naturally can only be received as long as there is an existing connection, and the method was called. It is a reaction to the method call. If there is a problem in transportation, you’ll get error messages appropriate to the transport protocol, in our case HTTP.
All SOAP messages use the following schema:
HTTP://SCHEMAS.XMLSOAP.ORG/SOAP/ENVELOPE/” >
à
à
All information in a SOAP message is inside an envelope node. A envelope node always has a body element. The header element is optional. If there is a header element, it must be the first element inside the envelope. All elements are bound to a specific namespace, which is named in the corresponding W3C document.
All information in a SOAP message is inside an envelope node
The header element contains so-called “meta-data”, which do not necessarily belong to the method call, for example the identification of the caller. The SOAP specification describes an attribute ‚mustUnderstand’ which, when set to true (1=true, 0=false), indicates that the service needs to understand this information. Otherwise, it must refuse the call. Here’s a little sample how to use this attribute :
HTTP://SCHEMAS.XMLSOAP.ORG/SOAP/ENVELOPE/” >
xmlns:AF5NS=www.appfact.de
SOAP-ENV:mustUnderstand=”1”>
KIELEXTERN/msm
à
By setting this attribute, the service is required to process the provided information or to refuse the call, if it can’t understand the node, CallerID. Pay attention to the fact, that we are using our own namespace here, to separate custom elements from the SOAP specification.
The body element is always present in a SOAP message, and “the heart” of the message. The message type determines the content of the body element. A method call, for example, consists of the name of the method and descriptive information about the parameters. Again, lets look at a simple sample. A web service is provided, which publishes the following method (C#):
int AddNumbers ( int nP1 , int nP2 );
The SOAP message to call this method would look like :
HTTP://SCHEMAS.XMLSOAP.ORG/SOAP/ENVELOPE/” >
xmlns:AF5NS=“www.appfact.de”
SOAP-ENV:mustUnderstand=”1”>
FUCKIEL/msm
11
13
This message asks the service to call the method AddNumbers with the two parameters 11 and 13. Normally, this call leads to a result, which will is sent in a SOAP message. Let’s take a look to this result message:
HTTP://SCHEMAS.XMLSOAP.ORG/SOAP/ENVELOPE/” >
24
As you see, the web service answers with a SOAP message, which delivers the result of the method call in a standardized way. The tag names are constructed by extending the method name with the string “Response”.
In case of an error, the SOAP message holds the following information:
The body element holds exactly one fault node, which probably contains the following sub-nodes:
- Faultcode: error identification
- Faultstring: error description
- Faultactor: indicates which server generated the error. This might be helpful when SOAP messages are being passed from component to component in a distributed environment.
- Detail: additional, application-specific, details for the error. Commonly, this tag will have sub-nodes, which provide us with additional information.
Again a sample, let’s assume the service receives parameters, which are out of scope. Here a possible reaction to this situation:
HTTP://SCHEMAS.XMLSOAP.ORG/SOAP/ENVELOPE/” >
SOAP-ENV:Server
error in application http://addnumservice.softfact.de
Parameterueberlauf
5333
Do we need to waste a single word on this? I find this one of the more comfortable properties of XML, although it is sometimes a little bit chatty. The error mechanisms guarantee a uniform treatment of errors and a way to transport application-specific information.
Do we need to waste a single word on this?
How is SOAP serializing the data in a message? Parameters and results do have data types and it has to be secured, so that these are interpreted in a unique way. Therefore, systems must commit themselves to interpretation standards for data types. The SOAP specification explicitly determines how to serialize data inside a SOAP message.
A sample again: the signature
float GetCurrency ( string name );
requires the following message
xmlns:SOAP-ENV=
HTTP://SCHEMAS.XMLSOAP.ORG/SOAP/ENVELOPE/
xmlns:xsi=“http://www.w3.org/2001/XMLSchema-instance“>
USD
Be aware of the used name space: http://www.w3.org/2001/XMLSchema-instance. This name space is being used to describe data types inside of XML schema’s.
Here are some of the most common data types:
- String
- Boolean
- Float
- Int
- Datetime
- Binary
For a complete list, please refer to: http://www.w3.org/TR/xmlschema-2/.
OK, we know how elementary data types are being transported, but what about the more complex types? Is it possible to transport objects (if we can do that, we can do everything)?
It is! Let’s take a look at how
Public struct ExchangeRate
{
public string Name;
public float Rate;
public datetime ValidAfter;
}
This would be serialized as
USD
0.921
20031021 00:00:00
It should be clear, how this is embedded in a real SOAP message, and the potential this offers to us.
SOAP over HTTP
As mentioned earlier, HTTP has some invaluable advantages. Foremost, it’s availability in the internet environment: it’s very easy to send a SOAP messages via HTTP. Without going into details, here’s a short overview of what has to be done:
- Declare the content-type as text/xml
- Deliver a special HTTP header named as SOAPAction
The SOAPAction header is meant to give firewalls the opportunity to process SOAP messages very quickly, without examining the XML code. Let’s have a look to the corresponding HTTP message:
POST /SendError.aspx HTTP/1.1.
Host: www.softfact.de
Content-Type: text/xml; charset=“utf-8“
Content-Length: nnn
SOAPAction: “uri:softfact#SendError”
……
At the URL www.softfact.de is a web service, found at SendError.aspx, which can be used by our application to automatically retrieve error messages, and store them in our central CRM database.
WSDL
SOAP is a standard, which describes how to format messages and what they should contain, so that a web service can understand the message. How do we get information about the structure of the web service? Which methods are being exposed? Which parameters do they expect?
How do we get information about the structure of the web service?
Naturally does the provider of the web service know what’s there and what’s where. One option is an external document about the services provided, and their parameters. We all know that this kind of information is difficult to create properly, and expensive to maintain. However, the greatest disadvantage comes out of a totally different corner. It would be nearly impossible to force all vendors to use a standardized format. It’s very difficult to analyze proprietary information.
The solution to this problem is so-called WSDL (Web Service Description Language). WSDL uses XML standards, and can be understand by a variety of systems.
A WSDL document holds all of the information about a web service, which is needed to consume the published methods. A lot of programming environments are using this information to generate proxy classes for a web services, which make the access of the web service even easier, because one doesn’t have to deal with the whole SOAP issue. In fact, these proxy classes generate valid SOAP messages for us. We will introduce some of these tools later.
An analogue to SOAP, WSDL is a standard described in XML. A complete analysis of the WSDL format would require too much time, so we will concentrate on the most important parts. A WSDL document is a XML document with the following five elements:
- Types – holds the definitions for the used data types inside the documents
- Message – abstract definition about the messages, which the service can accept
- PortType – a list of abstract operations, which, roughly speaking, correspond to the method signatures of the web service
- Binding – defines the message format and the used protocol for every port type
- Service – the physical address of the web service
Just for illustration, let’s have a look at a WSDL document. In this case, a web service found on the web for getting exchange rates:
xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:s=http://www.w3.org/2001/XMLSchema
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:tns="http://www.webserviceX.NET/"
xmlns:tm="http://microsoft.com/wsdl/mime/textMatching/"
xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"
targetNamespace="http://www.webserviceX.NET/"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
targetNamespace="http://www.webserviceX.NET/">
name="FromCurrency"
type="tns:Currency" />
name="ToCurrency"
type="tns:Currency" />
(NB: Het volledige XML document is te vinden op de SDN website )
Conclusion of part 1
We have been looking mostly at the theoretical parts behind XML, SOAP and WSDL so far. in the next magazine we will put an end to the theory here and approach the stuff more practically.