Webservice notes

WebServices

Web service is any piece of software that makes itself available over the Internet and uses a standardized XML messaging system.

Web service can have a public interface, defined in a common XML grammar. The interface describes all the methods available to clients and specifies the signature for each method. Currently, interface definition is accomplished via the Web Service Description Language (WSDL).

if you create a Web service, there should be some relatively simple mechanism for you to publish this fact. Likewise, there should be some simple mechanism for interested parties to locate the service and locate its public interface. The most prominent directory of Web services is currently available via UDDI, or Universal Description, Discovery, and Integration.

What is new about Web services from traditional RPC? XML

XML lies at the core of Web services, and provides a common language for describing Remote Procedure Calls, Web services, and Web service directories.

The Web service protocol stack is an evolving set of protocols used to define, discover, and implement Web services. The core protocol stack consists of four layers:

Service Transport: This layer is responsible for transporting messages between applications. Currently, this includes HTTP, SMTP, FTP, and newer protocols, such as Blocks Extensible Exchange Protocol (BEEP). 

XML Messaging: This layer is responsible for encoding messages in a common XML format so that messages can be understood at either end. Currently, this includes XML-RPC and SOAP.

Service Description: This layer is responsible for describing the public interface to a specific Web service. Currently, service description is handled via the WSDL.

Service Discovery: This layer is responsible for centralizing services into a common registry, and providing easy publish/find functionality. Currently, service discovery is handled via the UDDI. 

SOAP is an XML-based protocol for exchanging information between computers

WSDL is an XML grammar for specifying a public interface for a Web service. This public interface can include the following: 

UDDI (Universal Description, Discovery, and Integration) currently represents the discovery layer within the Web services protocol stack. 

Creating Web Services

Building an XML-RPC style web service using the J2EE 1.4 platform involves five steps:

1.                  Design and code the web service endpoint interface.

2.                  Implement the interface.

3.                  Write a configuration file.

4.                  Generate the necessary files.

5.                  Use the deploytool to package the service in a WAR file and deploy it.

Design and Code the Service Endpoint Interface

in which you declare the methods that a web service remote client may invoke on the service.

Code Sample 1: MathFace.java

package math;

import java.rmi.Remote;

import java.rmi.RemoteException;

public interface MathFace extends Remote {

  public int add(int a, int b) throws RemoteException;

}

Implement the Service Endpoint Interface

Code Sample 2: MathImpl.java

package math;

import java.rmi.RemoteException;

public class MathImpl implements MathFace {

  public int add(int a, int b) throws RemoteException {

    return a + b;

  }

}

 Write a Configuration File - be passed to the wscompile tool.

Code Sample 3: config.xml

<?xml version="1.0" encoding="UTF-8"?>

<configuration

  xmlns="http://java.sun.com/xml/ns/jax-rpc/ri/config">

  <service

      name="MyFirstService"

      targetNamespace="urn:Foo"

      typeNamespace="urn:Foo"

      packageName="math">

      <interface name="math.MathFace"/>

  </service>

</configuration

This file tells wscompile to create a WSDL file with the following information:

·                    The service name is MyFirstService.

·                    The WSDL namespace is urn:Foo.

·                    The classes for the service are in the math package under the build directory.

·                    The service endpoint interface is math.MathFace.

 Generate the Necessary Mapping Files

Now, use the wscompile tool to generate the necessary files

prompt> wscompile -define -mapping build/mapping.xml -d build -nd build -classpath build config.xml

This command, which reads the config.xml file created earlier, creates the MyFirstService.wsdl file and mapping.xml in the build directory. The command line options or flags are:

·                    -define: instructs the tool to read the service endpoint interface and create a WSDL file.

·                    -mapping: specifies the mapping file and where it should be written.

·                    -d and -nd: specifies where to place generated output files and non-class output files, respectively.

Code Sample 4: MyFirstService.wsdl

<?xml version="1.0" encoding="UTF-8"?>

<definitions name="MyFirstService" targetNamespace="urn:Foo" xmlns:tns="urn:Foo"

    xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"

    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/">

  <types/>

  <message name="MathFace_add">

    <part name="int_1" type="xsd:int"/>

    <part name="int_2" type="xsd:int"/></message>

  <message name="MathFace_addResponse">

    <part name="result" type="xsd:int"/></message>

  <portType name="MathFace">

    <operation name="add" parameterOrder="int_1 int_2">

      <input message="tns:MathFace_add"/>

      <output message="tns:MathFace_addResponse"/></operation></portType>

  <binding name="MathFaceBinding" type="tns:MathFace">

    <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="rpc"/>

    <operation name="add">

      <soap:operation soapAction=""/>

      <input>

        <soap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" 

                     use="encoded" namespace="urn:Foo"/>

      </input>

      <output>

        <soap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" 

                     use="encoded" namespace="urn:Foo"/>

      </output>

    </operation></binding>

  <service name="MyFirstService">

    <port name="MathFacePort" binding="tns:MathFaceBinding">

      <soap:address location="REPLACE_WITH_ACTUAL_URL"/>

    </port>

  </service>

</definitions>

Code Sample 5: mapping.xml

This file follows the JSR 109 standard for Java <-> WSDL mappings. As you can see, the structure of the JAX-RPC mapping file matches closely with the structure of a WSDL file -- note the relationship between Java packages and XML namespaces. Each service offered is represented as a service-interface-mapping element. This element contains the mapping for the fully qualified class name of the service interface, WSDL service names, and WSDL port names. In addition, the JAX-RPC mapping file provides mappings for WSDL bindings, WSDL port types, WSDL messages, and so forth. And once again, the good news is that you needn't worry about the WSDL file (Code Sample 4) of the JAX-RPC mapping file (Code Sample 5) in order to develop, deploy, and use web services.

<?xml version="1.0" encoding="UTF-8"?>

<java-wsdl-mapping version="1.1" xmlns="http://java.sun.com/xml/ns/j2ee"

    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

    xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee

    http://www.ibm.com/webservices/xsd/j2ee_jaxrpc_mapping_1_1.xsd">

  <package-mapping>

    <package-type>math</package-type>

    <namespaceURI>urn:Foo</namespaceURI>

  </package-mapping>

  <package-mapping>

    <package-type>math</package-type>

    <namespaceURI>urn:Foo</namespaceURI>

  </package-mapping>

  <service-interface-mapping>

    <service-interface>math.MyFirstService</service-interface>

    <wsdl-service-name 

             xmlns:serviceNS="urn:Foo">serviceNS:MyFirstService</wsdl-service-name>

    <port-mapping>

      <port-name>MathFacePort</port-name>

      <java-port-name>MathFacePort</java-port-name>

    </port-mapping>

  </service-interface-mapping>

  <service-endpoint-interface-mapping>

    <service-endpoint-interface>math.MathFace</service-endpoint-interface>

    <wsdl-port-type xmlns:portTypeNS="urn:Foo">portTypeNS:MathFace</wsdl-port-type>

    <wsdl-binding xmlns:bindingNS="urn:Foo">bindingNS:MathFaceBinding</wsdl-binding>

    <service-endpoint-method-mapping>

      <java-method-name>add</java-method-name>

      <wsdl-operation>add</wsdl-operation>

      <method-param-parts-mapping>

        <param-position>0</param-position>

        <param-type>int</param-type>

        <wsdl-message-mapping>

          <wsdl-message 

                       xmlns:wsdlMsgNS="urn:Foo">wsdlMsgNS:MathFace_add</wsdl-message>

          <wsdl-message-part-name>int_1</wsdl-message-part-name>

          <parameter-mode>IN</parameter-mode>

        </wsdl-message-mapping>

      </method-param-parts-mapping>

      <method-param-parts-mapping>

        <param-position>1</param-position>

        <param-type>int</param-type>

        <wsdl-message-mapping>

          <wsdl-message 

                       xmlns:wsdlMsgNS="urn:Foo">wsdlMsgNS:MathFace_add</wsdl-message>

          <wsdl-message-part-name>int_2</wsdl-message-part-name>

          <parameter-mode>IN</parameter-mode>

        </wsdl-message-mapping>

      </method-param-parts-mapping>

      <wsdl-return-value-mapping>

        <method-return-value>int</method-return-value>

        <wsdl-message 

                     xmlns:wsdlMsgNS="urn:Foo">wsdlMsgNS:MathFace_addResponse</wsdl-message>

        <wsdl-message-part-name>result</wsdl-message-part-name>

      </wsdl-return-value-mapping>

    </service-endpoint-method-mapping>

  </service-endpoint-interface-mapping>

</java-wsdl-mapping>

 Packaging and Deploying the Service

A JAX-RPC web service is really a servlet (or a web component, in J2EE terminology), and hence you can use deploytool to package and generate all the necessary configuration files, and deploy the service. If you haven't yet used the deploytool to package and deploy applications, start the J2EE application server (or default domain) and then follow these instructions to package and deploy the math service. For the rest of the article, I will assume that the service can be accessed using the URL http://localhost:8080/math-service/math.

Creating Web Service Clients

Now, let's create a client that accesses the math service you have just deployed. A client invokes a web service in the same way it invokes a method locally. There are three types of web service clients:

1.       Static Stub

2.       Dynamic Proxy

3.       Dynamic Invocation Interface (DII)

1. Static Stub Client

A Java class that is statically bound to a service endpoint interface. A stub, or a client proxy object, defines all the methods that the service endpoint interface defines. Therefore, the client can invoke methods of a web service directly via the stub. The advantage of this is that it is simple and easy to code.The disadvantage is that the slightest change of web service definition lead to the stub being useless... and this means the stub must be regenerated.

Use the static stub technique if you know that the web service is stable and is not going to change its definition. Static stub is tied to the implementation. In other words, it is implementation-specific.

Code Sample 6: config-wsdl.xml

<?xml version="1.0" encoding="UTF-8"?>

<configuration

         xmlns="http://java.sun.com/xml/ns/jax-rpc/ri/config">

  <wsdl location="http://localhost:8080/math-service/math?WSDL"

       packageName="sstub"/>

</configuration>

As you can see, the URL http://localhost:8080/math-service/math?WSDL identifies the location of the WSDL file for MyFirstService.

Once you have written the configuration file, you're ready to generate client stubs, using the following command:

prompt> wscompile -gen:client -d build -classpath build config-wsdl.xml

The -gen:client instructs wscompile to generate the stubs, as well as other needed runtime files such as serializers and value types.

This commands reads the MyFirstService.wsdl (the location of which is specified in the config-wsdl.xml), then generates files based on the information in the WSDL file and on the command-line flags. 

Code Sample 7: MathClient.java

package sstub;

import javax.xml.rpc.Stub;

public class MathClient {

   private String endpointAddress;

   public static void main(String argv[]) {

      try {

         // Invoke createProxy() to create a stub object

         Stub stub = createProxy();

         // Set the endpoint address the stub uses to access the service

         stub._setProperty(javax.xml.rpc.Stub.ENDPOINT_ADDRESS_PROPERTY, 

                      "http://localhost:8080/math-service/math");

         // Cast the stub to the service endpoint interface (MathFace)

         MathFace math = (MathFace) stub;

         // Invoke the add method

         System.out.println(math.add(12, 24));

      } catch (Exception ex) {

         ex.printStackTrace();

      }

   }

   private static Stub createProxy() {

      // Create a stub object

      // Note that MyFirstService_Impl, generated by wscompile, is implementation-specific

      return (Stub) (new MyFirstService_Impl().getMathFacePort());

   }

}

Compile and run the Client.

2. Dynamic Proxy

Supports a service endpoint interface dynamically at runtime. Here, no stub code generation is required. A proxy is obtained at runtime and requires a service endpoint interface to be instantiated. As for invocation, it is invoked in the same way as a stub. This is useful for testing web services that may change their definitions. The dynamic proxy needs to be re-instantiated but not re-generated as is the case with stub.

The client in this case calls a remote procedure through a dynamic proxy or a class that is created at runtime. Note that in the case of the static stub, the code relied on an implementation-specific class, but here (dynamic proxy) the code doesn't have this limitation.

The first step is to create a configuration file same as for Stub client

<?xml version="1.0" encoding="UTF-8"?>

<configuration

         xmlns="http://java.sun.com/xml/ns/jax-rpc/ri/config">

  <wsdl location="http://localhost:8080/math-service/math?WSDL"

       packageName="sstub"/>

</configuration>

ð       Now, use the wscompile to generate the needed interfaces:

C:\Sun\APPSER~1\apps\dynamic-proxy> wscompile -import -d build -nd build -f:norpc structures -classpath build config-wsdl.xml

MathClient.java

package dynamicproxy;

import java.net.URL;

import javax.xml.rpc.Service;

import javax.xml.rpc.JAXRPCException;

import javax.xml.namespace.QName;

import javax.xml.rpc.ServiceFactory;

import dynamicproxy.FirstIF;

public class MathClient {

   public static void main(String[] args) {

      try {

         String nameSpaceUri = "urn:Foo";

         String serviceName = "MyFirstService";

         String portName = "MathFacePort";

         // Specify the location of the WSDL file

         URL url = new URL("http://localhost:8080/math-service/math?WSDL");

         // Create an instance of service factory

         ServiceFactory serviceFactory = ServiceFactory.newInstance();

         // Create a service object to act as a factory for proxies.

         Service mathService = serviceFactory.createService(url,

                    new QName(nameSpaceUri, serviceName));

         // Create a proxy

         dynamicproxy.MathFace myProxy = (dynamicproxy.MathFace) mathService.getPort

                       (new QName(nameSpaceUri, portName), dynamicproxy.MathFace.class);

         // Invoke the add method

         System.out.println(myProxy.add(23, 12));

      } catch (Exception ex) {

         ex.printStackTrace();

      }

   }

}

Here, an instance of the service factory is created. The service factory is used to create a service object that acts as a factory for proxies. As you can see, the createService method takes two parameters: a URL of the WSDL files and a QName object, which is a tuple that represents an XML qualified name -- the namespace URI and the local part of the qualified name (the service name). A proxy object is then created, and finally the add method is invoked on that object.