An Introduction to Web Services

Jackson Muoki

A web service is a network accessible interface to the application functionality, which is built using the standard Internet technologies.A web service has some special characteristics as follows.

XML-based: Web services use the XML as the data transport protocols. XML eliminates the platform dependencies that other protocols may have.

Loosely coupled: A web service and the consumer of the web service are not tied closely to one another; the web service interface can change without affecting the client's interaction with the service.

Ability to be synchronous or asynchronous: In synchronous scenario, the client blocks and waits for the service to complete. In the asynchronous invocations, the client invokes a services and then executes other operations, and the result could be received at a later point.

Web Service Technologies Stack

The web services architecture is based on a few core technologies.

Simple Object Access Protocol (SOAP)

SOAP is a standardized packaging protocol for the messages shared by applications. The specification defines the simple XML-based envelope for the information being transferred. And it defines a set of rules for translating application and platform-specific data types into XML representations. SOAP relies heavily on XML standards like XML Schema and XML Namespaces for its definition and function.

Web Service Description Language (WSDL)

The SOAP specification does not address description. The standard specification used to describe the interface of a web service is the WSDL. Using WSDL a web service can describe everything about what it does and how consumers of that web service can go about using it.

Universal Description, Discovery, and Integration (UDDI)

The UDDI is an industry effort to define a searchable registry of services and their descriptions so that consumers can discover the services they need.

JEE Web Service APIs

In early 2002, Sun Microsystems released the first version of the Java Web Services Developer Pack (JWSDP). The Java web service is one of the major new features in the J2EE platform. The APIs defined in this pack include:

JAX-RPC: The Java API for XML-based RPC (JAX-RPC)

It is designed to provide a simple way to create remote procedure call based web services. JAX-RPC allows a client written in the Java to access a service implemented on the Microsoft .NET. Whereas RMI clients and servers must both are written in Java.

SAAJ: The SOAP with Attachments API for Java (SAAJ)

It is a convenient API that allows applications to exchange SOAP messages containing information encoded in XML.

JAXM: The Java API for XML Messaging (JAXM)

Builds on SAAJ and provides a common set of Java APIs for creating, consuming and exchanging SOAP envelopes over various transport mechanisms.

JAXR: The Java API for XML-based Registries (JAXR)

Provides an interface to UDDI and ebXML registries. JAXR allows both the publication of information to registries and information retrieval.

SOAP Message

We do not cover too many details of the underlying technologies of the web services. The SOAP message is explained a little bit here; so that you have some ideas of in what format the data are transferred. A SOAP message consists of an envelope which contains an optional header and a required body. The header contains blocks of information which is relevant to how the message is to be processed. The body contains the actual message to be delivered and processed. Anything that can be expressed in the XML syntax can go into the body of the message.

A typical SOAP message could be as follows.

<soap-env:Envelope xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/">
                <soap-env:Header>
                    <...>
                    </...>
                    <...>
                    </...>
                </soap-env:Header>
                <soap-env:Body>
                <...>
                </...>
                <...>
                </...>
                <...>
                </...>
            </soap-env:Body>
        </soap-env:Envelope>

Axis SOAP Engine

Apache Axis is an implementation of the SOAP. It is a framework for constructing SOAP processors such as clients and servers. It comes with tools to help you build web services easily, e.g. WSDL2Java and Java2WSDL.

Installing Axis

The first step is to go to the apache website and download a war release of Axis (e.g. axis2-1.7.5-war.zip).

You need to have installed tomcat and its running.

Copy the downloaded file to:

$Tomcat_Home /webapps

The application server will automatically deploy the axis.

Testing The Axis Installation

After the Axis is installed and deployed to Tomcat, you could test the installation by the following steps. 1. Start Tomcat. 2. Open a browser to the URL http://localhost:8080/axis/ and you should see a page with heading "apache axis"

Axis AdminServlet

Axis comes with a AdminServlet, through which you can view the list of deployed webservices. The servlet is disabled by default. To enable the servlet, open the web.xml file under $Tomcat_Home\webapps\axis\WEB-INF, and uncomment the following lines of code and restart Tomcat.

<!-- uncomment this if you want the admin servlet -->
     <!--
      <servlet-mapping>
        <servlet-name>AdminServlet</servlet-name>
        <url-pattern>/servlet/AdminServlet</url-pattern>
      </servlet-mapping>
     -->

Open a web browser to the URL http://localhost:8080/axis/servlet/AxisServlet

Creating First Web Service

We will go through creating a simple web service called HelloWorldWebService and deploy this web service to the Axis Server we just deployed. The HelloWorldWebService interface has a method ``say'' which is used to print out a string "Hello World From Webservice".

The essential steps are as follows.

Create the HelloWorld interface.

            package com.jack.service;
            public interface HelloWorldService {
                public String say();
            }

Create the HelloWorld implementation class

            package com.jack.service.impl;
            import com.jack.service.HelloWorldService;
public class HelloWorldServiceImpl implements HelloWorldService {
                public String say() {
                return "Hello World From Webservice.";
            }
                }

Create the Web Service Deployment Descriptors (WSDDs)

A WSDD file is an XML file used to describe the properties of a particular Axis web service. There are two type of WSDD files, one is used for deployment and one is used for undeployment.

            <deployment xmlns="http://xml.apache.org/axis/wsdd/"
            xmlns:java="http://xml.apache.org/axis/wsdd/providers/java">
            <service name="HelloWorldService" provider="java:RPC">
                    <parameter name="className" 
        value="com.jack.service.impl.HelloWorldServiceImpl"/>
                    <parameter name="allowedMethods" value="*"/>
                </service>
            </deployment>

            <undeployment xmlns="http://xml.apache.org/axis/wsdd/">
                <service name="HelloWorldService"/>
            </undeployment>

Writing a Client For HelloWorld Web Service

We will write a client application called "HelloWorldWebserviceClient" that executes the HelloWorld web service's methods. Axis provides client-side APIs that makes it relatively simple to create SOAP clients.

package com.jack.service.client;
    import org.apache.axis.client.Call;
    import org.apache.axis.client.Service;
    import org.apache.axis.encoding.XMLType;
    public class HelloWorldServiceClient {
        public static void callHelloWorldService() {
            // Set the endpoint and the method to call.
            String endpoint = "http://localhost:8080/axis/services/HelloWorldService";
            String method = "say";
            try {
                Service service = new Service();
                Call call = (Call) service.createCall();
                // Set the properties.
        call.setTargetEndpointAddress(new java.net.URL(endpoint));
                call.setOperationName(method);
                call.setReturnType(XMLType.XSD_STRING);
                // Invoke the method in the HelloWorld webservice.
            System.out.println("Invoking the HelloWorld Webservice...");
                System.out.println((String) call.invoke(new Object[]{}));
                System.out.println("Done!");
            } catch (Exception e) {
                e.printStackTrace();
            }
        }
        public static void main(String[] args) throws Exception {
            callHelloWorldService();
        }
    }

Adding Axis To An Existing Web Application

In the last example, we created a Hello World web service and deployed it to the Axis Server. However in the real world, the chances are we need to add the web services to the existing web applications, e.g. expose some services of current application as web services. In this section, we will go through adding the web services to a web application HelloWorldServlet. The application is a simple servlet that prints a string Hello World Service on the screen. The method say() contains the business logic and our goal is to expose this method through web services.

Testing HelloWorldServletWithWebService

After the changes have been made, you may invoke the deploy.web.war ant target to deploy the "HelloWorldServletWithWebservice" web application to Tomcat. Then start Tomcat, and invoke the "deploy.webservice" ant target to deploy the web service. You may use the same "HelloWorldWebserviceClient" client in the first example to test this web services. The only thing you need to change is the "endpoint"of the web service. The endpoint in this example is http://localhost:8080/HelloWorldServletWithWebservice/services/HelloWorldServletWithWebservice Run the client application and if the web service is deployed successfully, you could see the messages in the console. Invoking the HelloWorld Webservice... Hello World Service. Done!

Axis and WSDL

WSDL provides a standard way to describe a web service and it tells the clients how to call and use the web service. Axis comes with tools that help you create and use WSDL. 1. Java2WSDL: This tool could be used to create the WSDL document from the service code. 2. WSDL2Java: This tool could be used to generate the client-side stub helper classes, so that the client code to find and call a web service would besimplified greatly.

Using Java 2 WSDL and WSDL 2 Java

We will go through creating an example using the Java2WSDL and WSDL2Java tools that Axis provides.

Writing A Client With Client-Side Stub

All you need is to retrieve the HelloWorld service from the service locator, and call the method on it, pretty much the same way you make a local method call. Run the test client application and if the web service is deployed successfully, you could see the following messages in the console. Invoking the HelloWorld Webservice... Hello World Service.Done!

Using TCPMON Monitor Utility

Axis provides a tool called "tcpmon" that can be used to check the SOAP messages that a web service client sends and receives. You can start it using the following command, assuming you select port 6060 for tcpmon. java -classpath axis.jar org.apache.axis.utils.tcpmon 6060 localhost 8000

Conclusion

Having gone through this tutorial, you are expected to have understood the basics of how Web Services operates, and are able to write any piece of code using Web Services.