Confusion in writing web service client + jax-ws

[Jigar Naik]

Hi,

I've created a web service using jax-ws (StockQuoteService) as shown in the link bellow.

http://today.java.net/pub/a/today/2006/06/13/web-services-with-jax-ws-2.0.html

I've also deployed the service and service is running fine.

but while writing client code The article says

The astute reader will have noticed two new classes: StockQuote and StockQuoteService.

but i'm not able to find any of the classes, I have got two more classes as bellow

getQuote & getQuoteResponse

I'm not able to understand, it is becoming bit confusing. can anybody explain me in little detail.

Thanks !

My Service Implementation class

StockQuoteImpl.java

 package india;
 
import javax.jws.WebMethod;
import javax.jws.WebService;
 
/**
 * web service implementation class
 * @author Administrator
 *
 */
@WebService(serviceName="StockQuoteService", name="StockQuote")
public class StockQuoteImpl {
@WebMethod
    public double getQuote(String code) {
       double result = 0.0;
       if (code.equals("SUN")) {
          result = 20.0;
       } else if (code.equals("IBM")){
          result = 83.0;
       } else if (code.equals("BEA")) {
          result = 12;
       }
       return result;
    }
}
   

two files generated after wsgen command

GetQuote.java

  
package india.jaxws;
 
import javax.xml.bind.annotation.AccessType;
import javax.xml.bind.annotation.XmlAccessorType;
import javax.xml.bind.annotation.XmlElement;
import javax.xml.bind.annotation.XmlRootElement;
import javax.xml.bind.annotation.XmlType;
import india.jaxws.GetQuote;
 
@XmlRootElement(name = "getQuote", namespace = "http://india/")
@XmlAccessorType(AccessType.FIELD)
@XmlType(name = "getQuote", namespace = "http://india/")
public class GetQuote {
 
    @XmlElement(name = "arg0", namespace = "")
    private String arg0;
 
    /**
     * 
     * @return
     *     returns String
     */
    public String getArg0() {
        return this.arg0;
    }
 
    /**
     * 
     * @param arg0
     *     the value for the arg0 property
     */
    public void setArg0(String arg0) {
        this.arg0 = arg0;
    }
 
}
  

and GetQuoteResponse.java

   
package india.jaxws;
 
import javax.xml.bind.annotation.AccessType;
import javax.xml.bind.annotation.XmlAccessorType;
import javax.xml.bind.annotation.XmlElement;
import javax.xml.bind.annotation.XmlRootElement;
import javax.xml.bind.annotation.XmlType;
import india.jaxws.GetQuoteResponse;
 
@XmlRootElement(name = "getQuoteResponse", namespace = "http://india/")
@XmlAccessorType(AccessType.FIELD)
@XmlType(name = "getQuoteResponse", namespace = "http://india/")
public class GetQuoteResponse {
 
    @XmlElement(name = "return", namespace = "")
    private double _return;
 
    /**
     * 
     * @return
     *     returns double
     */
    public double get_return() {
        return this._return;
    }
 
    /**
     * 
     * @param _return
     *     the value for the _return property
     */
    public void set_return(double _return) {
        this._return = _return;
    }
 
}
 

WSDL file

 <definitions targetNamespace="http://india/" name="StockQuoteService">
−
<types>
−
<xsd:schema>
<xsd:import namespace="http://india/" schemaLocation="http://localhost:8080/StockQuoteService/stock_quote?xsd=1"/>
</xsd:schema>
</types>
−
<message name="getQuote">
<part element="tns:getQuote" name="parameters"/>
</message>
−
<message name="getQuoteResponse">
<part element="tns:getQuoteResponse" name="parameters"/>
</message>
−
<portType name="StockQuote">
−
<operation name="getQuote">
<input message="tns:getQuote"/>
<output message="tns:getQuoteResponse"/>
</operation>
</portType>
−
<binding type="tns:StockQuote" name="StockQuotePortBinding">
<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
−
<operation name="getQuote">
<soap :-o	 peration soapAction=""/>
−
<input>
<soap:body use="literal"/>
</input>
−
<output>
<soap:body use="literal"/>
</output>
</operation>
</binding>
−
<service name="StockQuoteService">
−
<port binding="tns:StockQuotePortBinding" name="StockQuotePort">
<soap:address location="http://localhost:8080/StockQuoteService/stock_quote"/>
</port>
</service>
</definitions>   

[ February 20, 2008: Message edited by: Jigar Naik ]

[Peer Reynders]

Read a bit further:

The astute reader will have noticed two new classes: StockQuote and StockQuoteService. ... You generate these classes, and all of the other classes that the client needs, using the wsimport tool

It's wsimport that generates these classes, not wsgen.

GetQuote.java and GetQuoteResponse.java are the Java object versions of the XML elements {http://india/}getQuote and {http://india/}getQuoteResponse respectively, found in the schema at

http://localhost:8080/StockQuoteService/stock_quote?xsd=1

[Jigar Naik]

yes, i missed one step of wsimport.

now that i will be able to write client code but there are 2 questions in my mind.

1) is my sequence correct ? (through service endpoint implementation class, wsgen generate required classes, and than wsgen will generate wsdl file linked to the wsgen generated classes.) What are these classes called(I'm talking about classes generated through wsgen, not wsimport) ?

2) and what wsimport does ? i guess it generate stub which are again few more classes. What are they used for ?

Thanks in anticipation,

[ February 20, 2008: Message edited by: Jigar Naik ]

[Peer Reynders]

You'll have a much easier time understanding the "basics" if you simply use Java SE 6.

/*  --- StockQuoteImpl.java
 */
package com.wakaleo.tutorials.webservices.server;
 
import javax.jws.WebMethod;
import javax.jws.WebService;
 
/**
 * A sample web service implementation class.
 * @author John
 *
 */
@WebService(name="StockQuote", serviceName="StockQuoteService")
 
public class StockQuoteImpl {
 
    /**
     * A web service method designed to return a stock value.
     * For the purposes of this tutorial, it returns one of 3 fixed values.
     * @param code a stock code: SUN, IBM or BEA
     * @return the cost of that stock
     */
@WebMethod()
public double getQuote(String code) {
double result = 0.0;
if (code.equals("SUN")) {
result = 20.0;
} else if (code.equals("IBM")){
result = 83.0;
} else if (code.equals("BEA")) {
result = 12;
}
return result;
}
}
 
 
/*  --- Main.java
 */
package com.wakaleo.tutorials.webservices.server;
 
import javax.xml.ws.Endpoint;
 
class Main {
    public static void main(String[] args) {
 
        Endpoint.publish(
            "http://localhost:8080/wsdemo/stock_quote",
             new StockQuoteImpl());
 
    }
}

To build:

javac -d . StockQuoteImpl.java
javac -d . Main.java
wsgen -cp . com.wakaleo.tutorials.webservices.server.StockQuoteImpl

To run:

java com.wakaleo.tutorials.webservices.server.Main

Now with the web browser check http://localhost:8080/wsdemo/stock_quote?wsdl and http://localhost:8080/wsdemo/stock_quote?xsd=1

Control-C exits the com.sun.net.httpserver.HttpServer

wsgen creates:
com/wakaleo/tutorials/webservices/server/jaxws/GetQuote.class JVM server object version of {http://server.webservices.tutorials.wakaleo.com}getQuote
com/wakaleo/tutorials/webservices/server/jaxws/GetQuoteResponse.class JVM server object version of {http://server.webservices.tutorials.wakaleo.com}getQuoteResponse


The client code

package com.wakaleo.tutorials.webservices.client;
 
import com.wakaleo.tutorials.webservices.client.StockQuote;
import com.wakaleo.tutorials.webservices.client.StockQuoteService;
   
public class StockQuoteClient {
      
public static double getQuote(String quote) {
    StockQuoteService service = new StockQuoteService();
    StockQuote port = service.getStockQuotePort();
    return port.getQuote(quote);
}
   
public static void main(String[] args) {
    String code = "SUN";
    
    if (args.length > 0) {
        code = args[0];
    }
    double result = getQuote(code);
    System.out.println(code + ": " + result);
    }      
}

To build (while com.wakaleo.tutorials.webservices.server.Main is running in another console window to present the WSDL):

wsimport -p com.wakaleo.tutorials.webservices.client <a href="http://localhost:8080/wsdemo/stock_quote?wsdl" target="_blank" rel="nofollow">http://localhost:8080/wsdemo/stock_quote?wsdl</a>
javac -d . StockQuoteClient.java

To run (while com.wakaleo.tutorials.webservices.server.Main is running in another console window):

java com.wakaleo.tutorials.webservices.client.StockQuoteClient

Output:

SUN: 20.0

wsimport creates:
com/wakaleo/tutorials/webservices/client/GetQuote.class JVM client object version of {http://server.webservices.tutorials.wakaleo.com}getQuote
com/wakaleo/tutorials/webservices/client/GetQuoteResponse.class JVM client object version of {http://server.webservices.tutorials.wakaleo.com}getQuoteResponse
com/wakaleo/tutorials/webservices/client/ObjectFactory.class most likely the code responsible for Object/XML marshalling unmarshalling
com/wakaleo/tutorials/webservices/client/package-info.class metadata?
com/wakaleo/tutorials/webservices/client/StockQuote.class Class implementing the service port
com/wakaleo/tutorials/webservices/client/StockQuoteService.class Class implementing the service


This is an example of "Contract Last Development" - i.e. the Java server code is written first and the service contract (WSDL) is generated from that.
I personally prefer Contract First Development - i.e. design the artifact that the client actually sees (the WSDL) first and then use the contract to generate some server stubs.
[ February 21, 2008: Message edited by: Peer Reynders ]

[Peer Reynders]

Once you get the above working it's time to see what is going on.

Download java.net tcpmon and start it up in a third console window while the web service is running:

java -jar tcpmon.jar

Configure TCP Monitor:
Local Port: 8090
Server Name: 127.0.0.1
ServerPort: 8080
click Add monitor.

To be able to see the request/response parts the client needs to go to port 8090 instead of 8080. To accomplish that we need a modified WSDL for the client:

<?xml version="1.0" encoding="UTF-8" ?>
<definitions 
    xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:tns="http://server.webservices.tutorials.wakaleo.com/"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    targetNamespace="http://server.webservices.tutorials.wakaleo.com/" 
    name="StockQuoteService"
  >
  <types>
    <xs:schema 
      version="1.0"
      xmlns:xs="http://www.w3.org/2001/XMLSchema"
      xmlns:tns="http://server.webservices.tutorials.wakaleo.com/"
      targetNamespace="http://server.webservices.tutorials.wakaleo.com/" 
    >
      <xs:element name="getQuote" type="tns:getQuote"/>
      <xs:element name="getQuoteResponse" type="tns:getQuoteResponse"/>
      
      <xs:complexType name="getQuote">
        <xs:sequence>
          <!-- should have been named tickerSymbol -->
          <xs:element name="arg0" type="xs:string" minOccurs="0"/>
        </xs:sequence>
      </xs:complexType>
 
      <xs:complexType name="getQuoteResponse">
        <xs:sequence>
          <!-- should have been named unitValue -->
          <xs:element name="return" type="xs:double"/>
        </xs:sequence>
      </xs:complexType>
      
    </xs:schema>
  </types>
 
  <message name="getQuote">
    <part name="parameters" element="tns:getQuote"/>
  </message>
 
  <message name="getQuoteResponse">
    <part name="parameters" element="tns:getQuoteResponse"/>
  </message>
 
  <portType name="StockQuote">
    <operation name="getQuote">
      <input message="tns:getQuote"/>
      <output message="tns:getQuoteResponse"/>
    </operation>
  </portType>
 
  <binding name="StockQuotePortBinding" type="tns:StockQuote">
    <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/>
 
    <operation name="getQuote">
      <soap:operation soapAction=""/>
    <input>
        <soap:body use="literal"/>
      </input>
      <output>
        <soap:body use="literal"/>
      </output>
    </operation>
  </binding>
 
  <service name="StockQuoteService">
    <port name="StockQuotePort" binding="tns:StockQuotePortBinding">
      <!-- Redirect location to tcpmon listening on port 8090 -->
      <soap:address location="http://localhost:8090/wsdemo/stock_quote"/>
    </port>
  </service>
</definitions>

Now modify the client code to use the modified WSDL:

package com.wakaleo.tutorials.webservices.client;
 
import com.wakaleo.tutorials.webservices.client.StockQuote;
import com.wakaleo.tutorials.webservices.client.StockQuoteService;
 
import java.net.URL;
import java.net.MalformedURLException;
import javax.xml.namespace.QName;
   
public class StockQuoteClient {
      
    public static double getQuote(String quote) throws MalformedURLException {
        /*  Point to WSDL with modified address location at 8090
            Configure Tcp Monitor:
                Local Port:  8090
                Server Name: 127.0.0.1
                ServerPort:  8080
            click Add monitor
         */
        URL wsdlLocation  = new URL("file:///C:/dev/java/StockQuote/StockQuote.wsdl");
        QName serviceName = new QName(
            "http://server.webservices.tutorials.wakaleo.com/",
            "StockQuoteService"
        );
  
        StockQuoteService service = new StockQuoteService(
            wsdlLocation,
            serviceName
        );
  
        StockQuote port = service.getStockQuotePort();
        return port.getQuote(quote);
    }
   
    public static void main(String[] args) {
        String code = "SUN";
    
        if (args.length > 0) {
            code = args[0];
        }
 
        try {
            double result = getQuote(code);
            System.out.println(code + ": " + result);
      
        } catch (MalformedURLException e) {
            e.printStackTrace();
        }
    }
}

Rebuild the client and start it up while the web service and tcpmon are running. In tcpmon you should see the request and response.

HTTP/SOAP Request:

POST /wsdemo/stock_quote HTTP/1.1
SOAPAction: ""
Accept: text/xml, multipart/related, text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Content-Type: text/xml; charset=utf-8
User-Agent: Java/1.6.0_04
Host: localhost:8090
Connection: keep-alive
Content-Length: 222
 
<?xml version="1.0" ?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Body>
    <ns2:getQuote xmlns:ns2="http://server.webservices.tutorials.wakaleo.com/">
      <arg0>SUN</arg0>
    </ns2:getQuote>
  </S:Body>
</S:Envelope>

Basically a com.wakaleo.tutorials.webservices.client.GetQuote instance is marshalled on the client side to

<ns2:getQuote xmlns:ns2="http://server.webservices.tutorials.wakaleo.com/">
  <arg0>SUN</arg0>
</ns2:getQuote>

That XML is unmarshalled on the service side to a com.wakaleo.tutorials.webservices.server.jaxws.GetQuote instance. The service processes the request and creates a com.wakaleo.tutorials.webservices.server.jaxws.GetQuoteResponse instance which is marshalled to

<ns2:getQuoteResponse xmlns:ns2="http://server.webservices.tutorials.wakaleo.com/">
  <return>20.0</return>
</ns2:getQuoteResponse>

which is included as the SOAP payload in the HTTP/SOAP Response:

HTTP/1.1 200 OK
Transfer-encoding: chunked
Content-type: text/xml; charset=utf-8
 
<?xml version="1.0" ?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Body>
    <ns2:getQuoteResponse xmlns:ns2="http://server.webservices.tutorials.wakaleo.com/">
      <return>20.0</return>
    </ns2:getQuoteResponse>
  </S:Body>
</S:Envelope>

On the client side the SOAP payload is unmarshalled to com.wakaleo.tutorials.webservices.client.GetQuoteResponse. The StockQuote instance extracts the return value from the GetQuoteResponse instance and uses it as the return value for your port.getQuote() call. It was StockQuote that created the GetQuote instance in the first place to send the stock ticker symbol to the service.
[ February 21, 2008: Message edited by: Peer Reynders ]