What Are Web Services?

Chapter 22 - XML Web Services
Mastering Crystal Reports 9
by Cate McCoy and Gord Maric
Sybex 2003

Web services are an evolution of object-oriented technologies that we are already using. In the previous object-oriented chapter, Chapter 18, “The Object-Oriented Primer,” we took a look at the evolution of programming to object-oriented programming (OOP). We saw how common computer routines (computer code) evolved into objects and how those objects then became reusable components in different applications. In the previous three chapters, we used the Crystal Reports objects to add reports to our custom applications.

If we step back from the details of the Crystal objects and examine the architecture, we can see that the Crystal objects are installed on the same computer as our application. If we wanted to write another application on a different computer, we would have to install the objects on that computer before we could use them. This leads to the same objects being installed in multiple places. A drawback to this type of design is that each application must have the same set of objects installed on each computer for the application to work. If we needed to upgrade an object to fix a bug, we would have to upgrade it in multiple places. Wouldn’t it be nice if we did not have to install these objects on each computer and could instead install them on a central object server? We could then use those objects from that server in many applications. If we needed to upgrade our objects, we could ensure that all our clients received the update by upgrading those objects on the server.

There are a number of technologies that allow objects to reside on a server and clients to call and use those objects. The technologies are Microsoft’s Distributed Component Object Model (DCOM), Java’s Remote Method Invocation (RMI), and Common Object Request Broker Architecture (CORBA). Essentially these technologies do similar things. They allow a client to communicate with a remote server and use the objects on the remote server. The downside to these technologies is they are not compatible with one another. A DCOM component can’t be used with a client that expects a CORBA object. You have the benefit of distributing objects and centralized object management. However, you are tied to a particular technology or vendor because the different technologies are not compatible.

The Internet has necessitated the creation of standards that allow computers with different operating systems and web servers to communicate. When you surf to a computer and get a web page, you don’t know, or care, if the computer is running Microsoft’s IIS (Internet Information Server) web server or Apache’s web server on Linux. You simply receive a web page with the information you requested. For different browsers and web servers to communicate, the various vendors have agreed on standards such as TCP/IP (Transport Control Protocol/Internet Protocol) and HTML (Hypertext Markup Language) so everybody can share information no matter what operating system or language they are using.

A set of Internet standards has been created so objects can be placed on a web server and then used by any application. Web services are those objects. Web services allow any application to call them across the Internet and use the methods in those web services.

Note 

Internet standards are governed by the World Wide Web Consortium at www.w3c.org.

Web Service Example

Before we look at the Crystal Reports web services, let’s examine a simple web service so we can see how they work. Web services can be written in any language as long as they follow the standards; we will examine those standards later in the chapter. First we will create a very simple web service that accepts two numbers, adds the numbers, and then sends back the result. We will build our web service using Microsoft’s Visual Studio .NET and call it AddMe.

Building a Simple Web Service

Designing and building a web service is not much different from building an object. You decide what methods and properties need to be created for the object and then build the code. The pseudocode for our AddMe web service would look like this:

Public Function AddMe(x As Integer, y As Integer) As Long    Return x + y End Function

To write this web service in Visual Studio .NET, start Visual Studio .NET and create a new Visual Basic Project, ASP.NET web service project by clicking File > New Project as shown in Figure 22.1. In the Location text box, type the name of the web server and virtual directory that will contain the web service. Visual Studio .NET will create the virtual directory specified and a set of projects files for your web server.

Figure 22.1. Creating a web service project in Visual Studio .NET

From the Solution Explorer in Visual Studio, right-click Service1.asmx and choose View Code. Service1.asmx contains the code for our web service. In the Service1 class, write the following code, as shown in Figure 22.2:

<WebMethod()> Public Function AddMe(ByVal x As Integer, ByVal y As Integer) As Long     Return x + y End Function

Figure 22.2. Creating the AddMe web method

If you have written object-oriented code before, this will look very familiar. If not, we are creating a method called AddMe that accepts two integers. It then adds the two integers and returns the result. Notice the <WebMethod> in front of the function declaration. In Visual Studio .NET, this is called an attribute. The <WebMethod> attribute tells Visual Studio .NET to make any methods prefixed with <WebMethod> accessible via the web server as a web service. The file Service1.asmx can contain multiple methods; we are adding only one.

To make the web service available, all we need to do now is save and build the project. To build the project, click Build > Build Solution.

Using the Web Service

We are going to use our AddMe web service in Microsoft’s Visual Studio .NET Windows application using VB.NET code. We could have also used the web service in ASP.NET, ASP, VB6, C++, Java, or any language that understands how to call a web service.

To build a client, start a new Visual Studio .NET project and create a new Windows application by clicking File > New Project and choosing Visual

Basic Projects > Windows Applications. Name this project WinWebServiceClient From the toolbox, drag a command button and three textboxes onto the Windows form. Then set the following properties:

1. Set the Text property of TextBox1 to 5.

2. Set the Text property of TextBox2 to 6.

3. Set the Text property of TextBox3 to blank.

You application should look similar to Figure 22.3.

Figure 22.3. Web service client interface

From the Solution Explorer in Visual Studio .NET, right-click References and choose Add Web Reference. In the Address box of the Add Web Reference dialog box, enter the URL to the web service, http://localhost/AddMe/service1.asmx, and press the Enter key or click the green arrow beside the URL address. Service1.asmx is the class where we built the AddMe web service. Localhost is the name of the web server that contains the web service. In our case it’s on the same computer, but it could be anywhere on the Internet. The Add Web Reference dialog box will query the web service and display the methods that are available; our AddMe method is displayed, as shown in Figure 22.4. Click the Add Reference button at the bottom to add the reference to Visual Studio.

Figure 22.4. Adding a web reference

Once you have set up a reference to a web service, using it is just like using any other object, as we have done in the previous chapters; you dimension a variable that will hold a reference to an object and then use the object’s methods and properties. We are going to call the web service when the user clicks the command button and pass the web service the numbers entered into textbox1 and textbox2. The web service will add the numbers, and we will put the result in textbox3. Here is the code for the Click event of the button.

Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button1.Click Dim ws As New localhost.Service1() 'change cursor to hourglass Me.Cursor.Current = Cursors.WaitCursor 'call the addme web method. TextBox3.Text = ws.AddMe(TextBox1.Text, TextBox2.Text) 'change cursor back to arrow Me.Cursor.Current = Cursors.Default   End Sub  

Run the application by clicking the Start toolbar button in Visual Studio. The top two textboxes contain the values 5 and 6. Click the button on the form and those values are passed to the AddMe web service. The web service then adds the numbers and places the result in the last textbox. Try entering different values in the top two textboxes, and click the button again on the form.

Any client who understands how to call a web service can use the AddMe web service. It seems too easy? Visual Studio .NET does a great job of hiding the complexity behind calling web services. Let’s take a look at what is happening behind the scenes.

Behind the Scenes of Web Services

To understand how and why web services work, it is necessary to understand some Internet standards that have evolved to make web services possible.

XML Primer

XML is standard way of representing data. Period. Nothing more. XML documents contain data and information about the data. Let’s look at an example of how XML can be used and why it is so important.

If we were designing a system that accepts purchase orders, the first thing we would have to figure out is the format for our purchase order; that is, should it be comma-separated values, fixed-length columns, or an Excel file? The problem with any of those choices is that there are no standards for creating the file, and we would have to advise our customers how we want to receive the file. If we choose an XML format, it allows us to represent the data in an industry-standard way. Using XML, our purchase order would look something like this:

<PO number="123">    <Customer>       <FirstName>Gizmo</FirstName>       <LastName>Capper</LastName>       <Address>21 Harcourt Park Dr.</Address>       <City>Toronto</City>    </Customer>    <OrderLine Product="23423" Qty="6"/>    <OrderLine Product="342" Qty="1"/>    <OrderLine Product="7886t" Qty="3"/> </PO>

XML represents data in text format. Text is the lowest common denominator across all systems. It is easy to work with, it cannot carry viruses, and it is very easy to send across the Internet and to and from web servers.

An XML file contains the data and information about the data. Every piece of data, like the customer’s first name or quantity ordered, is identi

fied. This makes reading and using XML data very easy, either visually by humans or through program code.

XML allows you to represent data in two ways: as elements or attributes. Element data is always enclosed in element tags. An example of element data in our purchase order document is <FirstName> Gizmo</FirstName>. The <FirstName> and </FirstName> are the opening and closing tags. Attribute data is part of an element tag; in our example Product and Qty are attribute data.

XML follows a strict syntax to represent data:

• One root element—PO in our case.

• No spaces in the element or attribute names.

• All elements must be correctly nested.

• XML is case-sensitive.

• All attributes are enclosed in quotes.

So what’s the big deal—all we have is a way to represent data? Why all the hype about XML? The big deal is that since everybody in the computer industry has agreed to represent data in a standard way (an agreement that represents a huge feat), we can build tools to read and write data in common ways. This solves the problem of having to tell your customers in what format you would like the data. With XML, you simply say that you are sending them an XML document. You don’t care what tools they are using to read the document or what operating system they are using, because all XML tools follow the same syntax standards.

XML syntax solves the problem of representing data; however, we still have to solve the problem of telling our customers what tags we would like to see in a purchase order document. For example, the document needs to start with a <PO> tag, and the <PO> tag must contain an attribute called Number that represents the purchase order number. If we could take our simple purchase order and get everybody in the world to agree on the elements and attributes for a purchase order system, then it would be very easy to exchange purchase orders with anybody. When you establish a set of tags and rules for what tags you are allowing in a particular XML document, you have created a vocabulary for that type of XML document. As long as everybody agrees to use XML and follow the established vocabulary, then it becomes very easy for any system to exchange data with any other system.

That is the hype and the big deal of XML. XML allows you to build standard ways of representing data and the allowable elements and attributes for a particular vocabulary. If we can agree on vocabularies to represent data for purchase orders—or any document—then sending information between computer systems becomes easier.

Note 

Organizations like www.rosettanet.org are working to create XML standard vocabularies for XML documents.

Note 

The XML world has two standards that describe the allowable elements and attributes in an XML document; Document Type Definitions (DTD), and XML Schemas. DTDs are text documents that are not written in XML syntax; DTDs are limited and are being replaced by XML Schemas. XML Schemas are written in XML syntax and contain a vocabulary for describing the allowable elements and attributes in an XML file.

HTML is a vocabulary of XML! Let’s examine a simple HTML document:

<html> <head>    <title>Simple HTML file</title> </head> <body>    <h1>Hello World</h1> </body> </html>

An HTML file looks very much like an XML file, except the elements and attributes are predefined (HTML has its own vocabulary). For example, the browser knows when it sees a piece of data wrapped in an <h1> tag to display it in a large bold font. That is the reason why, when we surf the web, it does not matter if we get our HTML documents from a Unix server or a Windows server; they both give us HTML, which is a common format, and the browser can interpret it.

Note 

HTML does not have to strictly follow the XML rules mentioned above. Browsers are written to deal with inconsistencies. If an HTML author creates an HTML document that follows the stricter XML rules, the HTML document is called XHTML.

SOAP

SOAP, the Simple Object Access Protocol, is an XML vocabulary. It allows you to specify, in an XML document, what objects or program you would like to access on a remote computer, what data you are passing to the object or program, and what is returned.

WSDL

Web Services Description Language (WSDL) is an XML vocabulary that describes the services that are available, the methods that are available, and the expected input and output parameters. If you are a programmer, you can think of WSDL as an XML-based type library.

Tip 

For complete details on SOAP, WSDL, XML, DTD, XML Schemas, and other Internet standards, visit www.w3c.org.

Putting It All Together

In our example, we used Visual Studio to build the web service and the client that uses the web service; however, we did not see WSDL, SOAP, or XML. Visual Studio .NET does a great job of hiding the complexity of SOAP, WSDL, and XML. Figure 22.5 shows what is happening behind the scenes.

Figure 22.5. Web service architecture

When we created our Windows client and made a web reference to http://localhost/AddMe/service1.asmx, we received from the web service a WSDL document describing the web services that are available. Open your Windows client and make a web reference to our web service again. Refer back to "Using the Web Service" and Figure 22.4. From the Add Web Reference dialog box, you can see that the AddMe method is identified as an available service. Visual Studio received this information from the WSDL document. If you click the Service Description link above the AddMe method, you can see the WSDL document describing the web service, shown in Figure 22.6.

Figure 22.6. WSDL document

To use a web service, a client must build a SOAP request document, identifying what method it would like to call and the data it will pass to those methods, and then send the SOAP document to the web server running the web service. The web server reads the SOAP XML document to determine what services the client would like run. It then calls and runs the requested program. When the program has completed, the web server builds a SOAP response document and sends it back to the client that made the request. Click the AddMe web method and Visual Studio will show you a sample of the SOAP request and the response that will be sent back to the client from the server, as shown in Figure 22.7.

Figure 22.7. SOAP request and response using Visual Studio’s test client

When you make a web reference, Visual Studio allows you to test the web service. Above the SOAP request and response, you can see a sample client that Visual Studio built for AddMe. Specify the values for the x and y parameters, click the Invoke button, and Visual Studio will build a SOAP request to call the web service and display the SOAP response returned. Figure 22.8 displays the SOAP response.

Figure 22.8. SOAP response from the AddMe web

Use of content on this site is expressly subject to the restrictions set forth in the Membership Agreement

Conello © 2000-2003     Feedback