# XML - Managing Data Exchange/Web Services

+----------------------------------+----------------------------------+
| `<font size=4>`{=html}**Learning | sponsored by:                    |
| objectives**`</font>`{=html}\    |                                  |
|                                  | ```{=html}                       |
| -   `<font size=3>`{=html} To    | <center>                         |
|     understand web services, and | ```                              |
|     what they can                | `<font size=3>`{=html}**The      |
|     do.`</font>`{=html}          | University of                    |
| -   `<font size=3>`{=html} To    | Georgia**`</font>`{=html}        |
|     know what SOAP is, and what  |                                  |
|     web services use it for.     | `<font size                      |
|     `</font>`{=html}             | =5 color=#990000>`{=html}**Terry |
| -   `<font size=3>`{=html} To    | College of                       |
|     know what Web Services       | Business**`</font>`{=html}       |
|     Description Language is, and |                                  |
|     how to read a WSDL           | `<                               |
|     file.`</font>`{=html}        | font size=3>`{=html}**Department |
| -   `<font size=3>`{=html} To    | of Management Information        |
|     know what the Universal      | Systems**`</font>`{=html}        |
|     Description, Discovery, and  |                                  |
|     Integration (UDDI) standard  | ```{=html}                       |
|     is.`</font>`{=html}          | </center>                        |
| -   `<font size=3>`{=html} To    | ```                              |
|     understand how to use Java   |                                  |
|     to connect to a web          |                                  |
|     service.`</font>`{=html}     |                                  |
+----------------------------------+----------------------------------+

## Web Services Overview

**Web Services** are a new breed of Web application. They are
self-contained, self-describing, modular applications that can be
published, located, and invoked across the Web. Web services perform
functions, which can be anything from simple requests to complicated
business processes. Once a Web service is deployed, other applications
(and other Web services) can discover and invoke the deployed service.
Web services make use of XML to describe the request and response, and
HTTP as its network transport.

The primary difference between a Web Service and a **web application**
relates to collaboration. Web applications are simply business
applications which are located or invoked using web protocols.
Similarly, Web Services also perform computing functions remotely over a
network. However, Web Services use internet protocols with the specific
intent of enabling inter operable machine to machine coordination.

Web Services have emerged as a solution to problems associated with
distributed computing. **Distributed computing** is the use of multiple
systems to perform a function rather than having a single system perform
it. The previous technologies used in distributed computing, primarily
Common Object Request Broker Architecture (CORBA) and Distributed
Component Object Model (DCOM), had some limitations. For example,
neither has achieved complete platform independence or easy transport
over firewalls. Additionally, DCOM is not vendor independent, being a
Microsoft product.

Some of the primary needs for a distributed computing standard were:

-   Cross-platform support for Business to Business, as well as
    internal, communication.
-   Concordance with existing Internet infrastructure as much as
    possible.
-   Scalability, both in number and complexity of nodes.
-   Internalization.
-   Tolerance of failure.
-   Vendor independence.
-   Suitability for trivial and non-trivial requests.

Over time, business information systems became highly configured and
differentiated. This inevitably made system interaction extremely costly
and time consuming. Developers began realizing the benefits of
standardizing Web Service development. Using web standards seemed to be
an intuitive and logical step toward attaining these goals. Web
standards already provided a platform independent means for system
communication and were readily accepted by information system users.

The end result was the development of Web Services. A Web Service forms
a distributed environment, in which objects can be accessed remotely via
standardized interfaces. It uses a three-tiered model, defining a
service provider, a service consumer, and a service broker. This allows
the Web Service to be a loose relationship, so that if a service
provider goes down, the broker can always direct consumers to another
one. Similarly, there are many brokers, so consumers can always find an
available one. For communication, Web Services use open Web standards:
TCP/IP, HTTP, and XML based SOAP.

At higher levels technologies such as XAML, XLANG, (transactional
support for complex web transactions involving multiple web services)
and XKMS (ongoing work by Microsoft and Verisign to support
authentication and registration) might be added.

## SOAP

!SOAP structure{width="220"}

**Simple Object Access Protocol (SOAP)** is a method for sending
information to and from Web Services in an extensible format. SOAP can
be used to send information or remote procedure calls encoded as XML.
Essentially, SOAP serves as a universally accepted method of
communication with web services. Businesses adhere to the SOAP
conventions in order to simplify the process of interacting with Web
Services.

``` XML
<SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
 <SOAP:Header>

  <!-- SOAP header -->

 </SOAP:Header>
 <SOAP:Body SOAP:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">

  <!-- SOAP body -->

 </SOAP:Body>
</SOAP:Envelope>
```

A SOAP message contains either a request method for invoking a Web
Service, or contains response information to a Web Service request.

Adhering to this layout when developing independent Web Services
provides notable benefits to the businesses. Due to the fact that Web
Applications are designed to be utilized by a myriad of actors,
developers want them to be easily adoptable. Using established and
familiar standards of communication ultimately reduces the amount of
effort it takes users to effectively interact with a Web Service.

The SOAP Envelope is used for defining and organizing the content
contained in Web Service messages. Primarily, the SOAP envelope serves
to indicate that the specified document will be used for service
interaction. It contains an optional SOAP Header and a SOAP Body.
Messages are sent in the SOAP body, and the SOAP head is used for
sending other information that wouldn\'t be expected in the body. For
example, if the SOAP:actor attribute is present in the SOAP header, it
indicates who the recipient of the message should be.

A web service transaction involves a SOAP request and a SOAP response.
The example we will be using is a Web Service provided by Weather.gov.
The input is latitude, longitude, a start date, how many days of
forecast information desired, and the format of the data. The SOAP
request will look like this:

``` XML
  <?xml version="1.0" encoding="UTF-8" standalone="no"?/>
  <SOAP-ENV:Envelope
      SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" 
      xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
     
     <SOAP-ENV:Body>
        <m:NDFDgenByDayRequest xmlns:SOAPSDK1="http://www.weather.gov/forecasts/xml/DWMLgen/wsdl/ndfdXML.wsdl">
           <latitude xsi:type="xsd:decimal">33.955464</latitude>
           <longitude xsi:type="xsd:decimal">-83.383245</longitude>
           <startDate xsi:type="xsd:date"></startDate>
           <numDays xsi:type="xsd:integer">1</numDays>
           <format>24 Hourly</format>
        </m:NDFDgenByDayRequest>
     </SOAP-ENV:Body>
     
  </SOAP-ENV:Envelope>
```

The startDate was left empty because this will automatically get the
most recent data. The format data type is not defined because it is
defined in the WSDL document.

The response SOAP looks like this.

``` XML
  <?xml version="1.0" encoding="UTF-8" standalone="no"?/>
  <SOAP-ENV:Envelope
      SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" 
      xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
     
     <SOAP-ENV:Body>
        <NDFDgenByDayResponse xmlns:SOAPSDK1="http://www.weather.gov/forecasts/xml/DWMLgen/wsdl/ndfdXML.wsdl">
           <dwmlByDayOut xsi:type="xsd:string">.....</dwmlByDayOut>
        </NDFDgenByDayResponse>
     </SOAP-ENV:Body>
     
  </SOAP-ENV:Envelope>
```

SOAP handles data by encoding it on the sender side and decoding it on
the receiver side. The data types handled by SOAP are based on the W3C
XML Schema specification. Simple types include strings, integers,
floats, and doubles, while compound types are made up of primitive
types.

``` XML
  <element name="name" type="xsd:string" />
  <SOAP:Array SOAP:arrayType="xsd:string[2]">
     <string>Web</string>
     <string>Services</string>
  </SOAP:Array>
```

Because they are text based, SOAP messages generally have no problem
getting through firewalls or other barriers. They are the ideal way to
pass information to and from web services.

## Service Description - WSDL

**Web Service Description Language (WSDL)** was created to provide
information about how to connect to and query a specific Web Service.
This document also adheres to strict formatting and organizational
guidelines. However, the methods, parameters, and service information
are application specific. Web Services perform different functionality
and contain independent information, however they are all organized the
same way. By creating a standard organizational architecture for these
services, developers can effectively invoke and utilize them with little
to no familiarization. To use a web service, a developer can follow the
design standards of the WSDL to easily determine all the information and
procedures associated with its usage.

Essentially, a WSDL document serves as an instruction for interacting
with a Web Service. It contains no application logic, giving the service
a level of autonomy. This enables users to effectively interact with the
service without having to understand its inner workings.

The following is an example of a WSDL file for a web service that
provides a temperature, given a U.S. zip code.

``` XML
<?xml version="1.0"?>
<definitions 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" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" 
xmlns:si="http://soapinterop.org/xsd" xmlns:tns="http://www.weather.gov/forecasts/xml/DWMLgen/wsdl/ndfdXML.wsdl" 
xmlns:typens="http://www.weather.gov/forecasts/xml/DWMLgen/schema/DWML.xsd" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" 
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns="http://schemas.xmlsoap.org/wsdl/" 
targetNamespace="http://www.weather.gov/forecasts/xml/DWMLgen/wsdl/ndfdXML.wsdl>
 
 <types>
    <xsd:schema targetNamespace="http://www.weather.gov/forecasts/xml/DWMLgen/schema/DWML.xsd">
       <xsd:import namespace="http://schemas.xmlsoap.org/soap/encoding/" />
       <xsd:import namespace="http://schemas.xmlsoap.org/wsdl/" />
       <xsd:simpleType name="formatType">
          <xsd:restriction base="xsd:string">
             <xsd:enumeration value="24 hourly" />
             <xsd:enumeration value="12 hourly" />
          </xsd:restriction>
       </xsd:simpleType>
       <xsd:simpleType name="productType">
          <xsd:restriction base="xsd:string">
             <xsd:enumeration value="time-series" />
             <xsd:enumeration value="glance" />
          </xsd:restriction>
       </xsd:simpleType>
       <xsd:complexType name="weatherParametersType">
          <xsd:all>
             <xsd:element name="maxt" type="xsd:boolean" />
             <xsd:element name="mint" type="xsd:boolean" />
             <xsd:element name="temp" type="xsd:boolean" />
             <xsd:element name="dew" type="xsd:boolean" />
             <xsd:element name="pop12" type="xsd:boolean" />
             <xsd:element name="qpf" type="xsd:boolean" />
             <xsd:element name="sky" type="xsd:boolean" />
             <xsd:element name="snow" type="xsd:boolean" />
             <xsd:element name="wspd" type="xsd:boolean" />
             <xsd:element name="wdir" type="xsd:boolean" />
             <xsd:element name="wx" type="xsd:boolean" />
             <xsd:element name="waveh" type="xsd:boolean" />
             <xsd:element name="icons" type="xsd:boolean" />
             <xsd:element name="rh" type="xsd:boolean" />
             <xsd:element name="appt" type="xsd:boolean" />
          </xsd:all>
       </xsd:complexType>
    </xsd:schema>
</types>

<message name="NDFDgenRequest">  
   <part name="latitude" type="xsd:decimal"/>
   <part name="longitude" type="xsd:decimal" />
   <part name="product" type="typens:productType" />
   <part name="startTime" type="xsd:dateTime" />
   <part name="endTime" type="xsd:dateTime" />
   <part name="weatherParameters" type="typens:weatherParametersType" />
</message>

<message name="NDFDgenResponse">
   <part name="dwmlOut" type="xsd:string" />
</message>

<message name="NDFDgenByDayRequest">  
   <part name="latitude" type="xsd:decimal" />
   <part name="longitude" type="xsd:decimal" />
   <part name="startDate" type="xsd:date" />
   <part name="numDays" type="xsd:integer" />
   <part name="format" type="typens:formatType" />
</message>

<message name="NDFDgenByDayResponse">
   <part name="dwmlByDayOut" type="xsd:string" />
</message>

<portType name="ndfdXMLPortType">
   <operation name="NDFDgen">
      <documentation> Returns National Weather Service digital weather forecast data </documentation>
      <input message="tns:NDFDgenRequest" />
      <output message="tns:NDFDgenResponse" />
   </operation>
   <operation name="NDFDgenByDay">
      <documentation> Returns National Weather Service digital weather forecast data summarized over either 24- or 12-hourly periods </documentation>
      <input message="tns:NDFDgenByDayRequest" />
      <output message="tns:NDFDgenByDayResponse" />
   </operation>
</portType>

<binding name="ndfdXMLBinding" type="tns:ndfdXMLPortType">
   <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http" />
   <operation name="NDFDgen">
      <soap:operation soapAction="http://www.weather.gov/forecasts/xml/DWMLgen/wsdl/ndfdXML.wsdl#NDFDgen" style="rpc" />
      <input>
         <soap:body use="encoded" namespace="http://www.weather.gov/forecasts/xml/DWMLgen/wsdl/ndfdXML.wsdl" 
             encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
      </input>
      <output>
         <soap:body use="encoded" namespace="http://www.weather.gov/forecasts/xml/DWMLgen/wsdl/ndfdXML.wsdl" 
             encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
      </output>
   </operation>
   <operation name="NDFDgenByDay">
      <soap:operation soapAction="http://www.weather.gov/forecasts/xml/DWMLgen/wsdl/ndfdXML.wsdl#NDFDgenByDay" style="rpc" />
      <input>
         <soap:body use="encoded" namespace="http://www.weather.gov/forecasts/xml/DWMLgen/wsdl/ndfdXML.wsdl" 
             encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
      </input>
      <output>
         <soap:body use="encoded" namespace="http://www.weather.gov/forecasts/xml/DWMLgen/wsdl/ndfdXML.wsdl" 
             encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
      </output>
   </operation>
</binding>

<service name="ndfdXML">
   <documentation>The service has two exposed functions, NDFDgen and NDFDgenByDay. 
                        For the NDFDgen function, the client needs to provide a latitude and 
                        longitude pair and the product type. The client also needs to provide 
                        the start and end time of the period that it wants data for. For the 
                        time-series product, the client needs to provide an array of boolean values 
                        corresponding to which weather values should appear in the time series product. 
                        For the NDFDgenByDay function, the client needs to provide a latitude and longitude 
                        pair, the date it wants to start retrieving data for and the number of days worth 
                        of data. The client also needs to provide the format that is desired.</documentation>
   <port name="ndfdXMLPort" binding="tns:ndfdXMLBinding">
      <soap:address location="http://www.weather.gov/forecasts/xml/SOAP_server/ndfdXMLserver.php" />
   </port>
  </service>
</definitions>
```

The WSDL file defines a service, made up of different endpoints, called
ports. The port is made up of a network address

`       and a binding.`

``` XML
<service name="ndfdXML">
   <documentation>The service has two exposed functions, NDFDgen and NDFDgenByDay. 
                        For the NDFDgen function, the client needs to provide a latitude and 
                        longitude pair and the product type. The client also needs to provide 
                        the start and end time of the period that it wants data for. For the 
                        time-series product, the client needs to provide an array of boolean values 
                        corresponding to which weather values should appear in the time series product. 
                        For the NDFDgenByDay function, the client needs to provide a latitude and longitude 
                        pair, the date it wants to start retrieving data for and the number of days worth 
                        of data. The client also needs to provide the format that is desired.</documentation>
   <port name="ndfdXMLPort" binding="tns:ndfdXMLBinding">
      <soap:address location="http://www.weather.gov/forecasts/xml/SOAP_server/ndfdXMLserver.php" />
   </port>
</service>
```

The binding identifies the binding style and protocol for each
operation. In this case, it uses Remote Procedure Call style binding,
using SOAP.

``` XML
   <binding name="ndfdXMLBinding" type="tns:ndfdXMLPortType">
   <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http" />
   <operation name="NDFDgen">
      <soap:operation soapAction="http://www.weather.gov/forecasts/xml/DWMLgen/wsdl/ndfdXML.wsdl#NDFDgen" style="rpc" />
      <input>
         <soap:body use="encoded" namespace="http://www.weather.gov/forecasts/xml/DWMLgen/wsdl/ndfdXML.wsdl" 
             encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
      </input>
      <output>
         <soap:body use="encoded" namespace="http://www.weather.gov/forecasts/xml/DWMLgen/wsdl/ndfdXML.wsdl" 
             encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
      </output>
   </operation>
   <operation name="NDFDgenByDay">
      <soap:operation soapAction="http://www.weather.gov/forecasts/xml/DWMLgen/wsdl/ndfdXML.wsdl#NDFDgenByDay" style="rpc" />
      <input>
         <soap:body use="encoded" namespace="http://www.weather.gov/forecasts/xml/DWMLgen/wsdl/ndfdXML.wsdl" 
             encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
      </input>
      <output>
         <soap:body use="encoded" namespace="http://www.weather.gov/forecasts/xml/DWMLgen/wsdl/ndfdXML.wsdl" 
             encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
      </output>
   </operation>
</binding>
```

Port Types are abstract collections of operations. In this case, the
operation is getTemp.

``` XML
   <portType name="ndfdXMLPortType">
      <operation name="NDFDgen">
         <documentation> Returns National Weather Service digital weather forecast data     </documentation>
         <input message="tns:NDFDgenRequest" />
         <output message="tns:NDFDgenResponse" />
      </operation>
      <operation name="NDFDgenByDay">
         <documentation> Returns National Weather Service digital weather forecast data summarized over either 24- or 12-hourly periods </documentation>
         <input message="tns:NDFDgenByDayRequest" />
         <output message="tns:NDFDgenByDayResponse" />
      </operation>
   </portType>
```

Finally, messages are used by the operations to communicate - in other
words, to pass parameters and return values.

``` XML
   <message name="NDFDgenByDayRequest">  
      <part name="latitude" type="xsd:decimal" />
      <part name="longitude" type="xsd:decimal" />
      <part name="startDate" type="xsd:date" />
      <part name="numDays" type="xsd:integer" />
      <part name="format" type="typens:formatType" />
   </message>

   <message name="NDFDgenByDayResponse">
      <part name="dwmlByDayOut" type="xsd:string" />
   </message>
```

From the WSDL file, a consumer should be able to access data in a web
service.

For a more detailed analysis of how this particular web service, please
visit Weather.gov

## Service Discovery - UDDI

You\'ve seen how WSDL can be used to share interface definitions for Web
Services, but how do you go about finding a Web Service in the first
place? There are countless independent Web Services that are developed
and maintained by just as many different organizations. Upon adopting
Web Service practices and methodologies, developers sought to foster the
involvement and creative reuse of their systems. It soon became apparent
that there was a need for an enumerated record of these services and
their respective locations. This information would empower developers to
leverage the best practices and processes of Web Services quickly and
easily. Additionally, having a central reference of current Web Service
capabilities enables developers avoid developing redundant applications.

UDDI defines registries in which services can be published and found.
The UDDI specification was creaed by Microsoft, Ariba, and IBM. UDDI
defines a data structure and Application Programming Interface (API).

In the three-tier model mentioned before, UDDI is the service broker.
Its function is to enable service consumers to find appropriate service
providers.

Connecting to UDDI registries using Java can be accomplished through the
Java API for XML Registries (JAXR). JAXR creates a layer of abstraction,
so that it can be used with UDDI and other types of XML Registries, such
as the ebXML Registry and Repository standard.

## Using Java With Web Services

To execute a SOAP message, an application must be used to communicate
with the service provider. Due to its flexibility, almost any
programming language can be used to execute SOAP message. For our
purposes, however, we will be focusing on using Java to interact with
Web Services.

Using Java with web services requires some external libraries.

-   Apache SOAP Toolkit
-   Java Mail Framework
-   JavaBeans Activation Framework
-   Xerces XML parser

Let\'s go through using Java to query the Temperature Web Service we
talked about earlier.

``` java
import java.io.*;
import java.net.*;
import java.util.*;
import org.apache.soap.util.xml.*;
import org.apache.soap.*;
import org.apache.soap.rpc.*;

public class TempClient
{

 public static float getTemp (URL url, String zipcode) throws Exception 
 {

  Call call = new Call ();

  // Service uses standard SOAP encoding
  String encodingStyleURI = Constants.NS_URI_SOAP_ENC;
  call.setEncodingStyleURI(encodingStyleURI);

  // Set service locator parameters
  call.setTargetObjectURI ("urn:xmethods-Temperature");
  call.setMethodName ("getTemp");

  // Create input parameter vector
  Vector params = new Vector ();
  params.addElement (new Parameter("zipcode", String.class, zipcode, null));
  call.setParams (params);

  // Invoke the service ....
  Response resp = call.invoke (url,"");

  // ... and evaluate the response
  if (resp.generatedFault ()) 
  {
   throw new Exception();
  } 
  else 
  {
   // Call was successful. Extract response parameter and return result
   Parameter result = resp.getReturnValue ();
   Float rate=(Float) result.getValue();
   return rate.floatValue();
  }
 }

 // Driver to illustrate service invocation
 public static void main(String[] args)
 {
  try
  {
   URL url=new URL("http://services.xmethods.net:80/soap/servlet/rpcrouter");
   String zipcode= "30605";
   float temp = getTemp(url,zipcode);
   System.out.println(temp);
  }
  catch (Exception e) 
  {
   e.printStackTrace();
  }
 }
}
```

This Java code effectively hides all the SOAP from the user. It invokes
the target object by name and URL, and sets the parameter *zipcode*. But
what does the underlying SOAP Request look like?

``` XML
  <?xml version="1.0" encoding="UTF-8"?>
  <soap:Envelope xmlns:n="urn:xmethods-Temperature"
      xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
      xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
      xmlns:xs="http://www.w3.org/2001/XMLSchema" 
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

     <soap:Body soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
        <n:getTemp>
           <zipcode xsi:type="xs:string">30605</zipcode>
        </n:getTemp>
     </soap:Body>

  </soap:Envelope>
```

As you see, the SOAP request uses the parameters passed in by the Java
Call to fill out the SOAP envelope and direct the message. Similarly,
the response comes back into the Java program as \'70.0\'. The response
SOAP is also hidden by the Java program.

``` XML
  <?xml version='1.0' encoding='UTF-8'?>
  <SOAP-ENV:Envelope 
      xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
      xmlns:xsd="http://www.w3.org/2001/XMLSchema">

     <SOAP-ENV:Body>
        <ns1:getTempResponse xmlns:ns1="urn:xmethods-Temperature" 
            SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
           <return xsi:type="xsd:float">70.0</return>
        </ns1:getTempResponse>
     </SOAP-ENV:Body>

  </SOAP-ENV:Envelope>
```

Here\'s an additional example of using Java and SOAP to interact with
Web Services. This particular Web Service is called the \"US Zip
Validator\" and takes a ZipCode as a parameter, which then returns a
corresponding latitude and longitude. When developing applications to
interact with Web Services, the first step should be to review the WSDL
document.

The WSDL document for this service is located here:
<http://www.webservicemart.com/uszip.asmx?WSDL>

This document will contain all the necessary instructions for
interacting with the \"US Zip Validator\" Web Service.

**SOAPClient4XG**

Modified by - Duncan McAllister From:
<http://www.ibm.com/developerworks/xml/library/x-soapcl/>

``` java
import java.io.*;
import java.net.*;
import java.util.*;

public class SOAPClient4XG {
    
    public static void main(String[] args) throws Exception {

        args = new String[2];
        
        args[0] = "http://services.xmethods.net:80/soap/servlet/rpcrouter";
        args[1] = "SOAPrequest.xml";
        
        if (args.length  < 2) {
            System.err.println("Usage:  java SOAPClient4XG " +
                               "http://soapURL soapEnvelopefile.xml" +
                               " [SOAPAction]");
                System.err.println("SOAPAction is optional.");
            System.exit(1);
        }

        String SOAPUrl      = args[0];
        String xmlFile2Send = args[1];

          String SOAPAction = "";

                
        // Create the connection where we're going to send the file.
        URL url = new URL(SOAPUrl);
        URLConnection connection = url.openConnection();
        HttpURLConnection httpConn = (HttpURLConnection) connection;

        // Open the input file. After we copy it to a byte array, we can see
        // how big it is so that we can set the HTTP Cotent-Length
        // property. (See complete e-mail below for more on this.)

        FileInputStream fin = new FileInputStream(xmlFile2Send);

        ByteArrayOutputStream bout = new ByteArrayOutputStream();
    
        // Copy the SOAP file to the open connection.
        copy(fin,bout);
        fin.close();

        byte[] b = bout.toByteArray();

        // Set the appropriate HTTP parameters.
        httpConn.setRequestProperty( "Content-Length",
                                     String.valueOf( b.length ) );
        httpConn.setRequestProperty("Content-Type","text/xml; charset=utf-8");
          httpConn.setRequestProperty("SOAPAction",SOAPAction);
        httpConn.setRequestMethod( "POST" );
        httpConn.setDoOutput(true);
        httpConn.setDoInput(true);

        // Everything's set up; send the XML that was read in to b.
        OutputStream out = httpConn.getOutputStream();
        out.write( b );    
        out.close();

        // Read the response and write it to standard out.

        InputStreamReader isr =
            new InputStreamReader(httpConn.getInputStream());
        BufferedReader in = new BufferedReader(isr);

        String inputLine;

        while ((inputLine = in.readLine()) != null)
            System.out.println(inputLine);

        in.close();
    }

  // copy method from From E.R. Harold's book "Java I/O"
  public static void copy(InputStream in, OutputStream out) 
   throws IOException {

    // do not allow other threads to read from the
    // input or write to the output while copying is
    // taking place

    synchronized (in) {
      synchronized (out) {

        byte[] buffer = new byte[256];
        while (true) {
          int bytesRead = in.read(buffer);
          if (bytesRead == -1) break;
          out.write(buffer, 0, bytesRead);
        }
      }
    }
  } 
}
```

This Java class refers to an XML document(SOAPRequest.xml), which is
used as the SOAP message. This document should be included in the same
project folder as the Java application invoking the service.

After reviewing the \"US Zip Validator\" WSDL document, it is clear that
we would like to invoke the \"getTemp\" method. This information is
contained within the SOAP body and includes the appropriate parameters.

**SOAPRequest.xml**

``` XML
<?xml version="1.0" encoding="UTF-8"?>
  <soap:Envelope xmlns:n="urn:xmethods-Temperature"
      xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
      xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
      xmlns:xs="http://www.w3.org/2001/XMLSchema" 
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

     <soap:Body soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
        <n:getTemp>
           <zipcode xsi:type="xs:string">30605</zipcode>
        </n:getTemp>
     </soap:Body>

  </soap:Envelope>
```

Following a successful interaction, the Web Service provider will
provide a response that is similar in format to the user request. When
developing in NetBeans, run this project and examine the subsequent SOAP
message response in the Tomcat output window.

## Web Services with Netbeans

The Netbeans version used for this explanation is 5.0.

After Netbeans is open, click on the \"Runtime\" tab on the left pane,
then right-click \"Web Services\" and select \"Add Web Service.\" In the
\"URL\" field, enter the address of the web service WSDL file, in our
example above it is
\"<http://www.weather.gov/forecasts/xml/DWMLgen/wsdl/ndfdXML.wsdl>\" and
click Get Web Service Description. This will bring up the information of
the web service.

## Summary

  ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
  Web services are applications that use XML to communicate with many different systems to perform a task. To facilitate the use of web services, protocols were developed that allow them to be flexible and scalable. SOAP is used to send and define information and WSDL was created to provide information about how to connect to and query a web service. UDDI describes where these web services can be found.
  ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

## Exercises

## Answers

## Appendix

## References and Links

-   Weather.gov
-   WebServices.org
-   W3C\'s Web Services Reference
-   UDDI.org
-   XMethods.net
-   Java API for XML Registries
-   Apache SOAP Toolkit
-   JavaMail Framework
-   Java Activation
    Framework
-   Xerces Java Parser
-   Jasnowski, Mike. *Java, XML, and Web Services Bible*
-   Microsoft Web Services
-   <http://www.xml.com/>
-   <http://www.w3schools.com/soap/soap_intro.asp>
-   <http://en.wikibooks.org/wiki/XML_-_Managing_Data_Exchange/Web_services>
-   <http://www.w3.org/TR/2007/REC-soap12-part0-20070427/>
-   <http://www.eweek.com/article2/0,1895,1589730,00.asp>
-   <http://www.ibm.com/developerworks/xml/library/x-soapcl/>

