A simple tutorial about creating SOAP Web Service in netbean 6.9.1 with Metro and use user defined class as parameters for Web service call.

In Java world, as far as I know, there are at least five Web service stacks: Metro, Axis2, Glue, JBossWS and CXF. According to this WS stack comparison, it seems that Axis2 supports most features than others do. However, according to this performance comparison article, it seems that Metro has better performance than Axis2 when WS-Security is used in application. I used Axis before. And I think every thing keeps changing including the performance benchmark. I will just give Metro a try this time. There are many tutorials online. But, most of them just show a simple function (operator) to operate on primary or String type. Obviously, it is not enough for a real project as real project always requires to deliver user defined classes as parameters for SOAP Web Service call.

Below is the steps to create a simple Metro (JAX-WS) based Web service and the service consumer. It is a simple stub Web service. But, it could be a good start for a real project, where user defined classes as parameters are required.

1) Well, let's start it by creating a Web project in Netbeans. By clicking  File -> New Project... -> Java Web -> Web Application, we see screen like below. I name the project as JiaMetroWS and give it package name as jia.blog.ws. Click Finish to close this dialogue window.

2) Select the new created project jiaBlogWS in project list and right click the node. Click New -> Web Service... as shown below.

3) Right click the new created Web service jiaBlogWs and select add operator, we see below screen. We click the "add operation" button to add a operator (function) into the new created Web service jiaBlogWS.

4) After add the operator, we can see the main area of Netbean is like this. Please notice that there are two buttons there, source and Design. I suggest to click source to have a look at the source code with Web service annotation. These annotations are keys.

I added some dummy data in the class. And, I created two helper classes Invoice.java and Item.java as return parameters. Now, we have jiaMetroWS source code like below,

JiaBlogWS.java

package jia.blog.ws;

import java.util.ArrayList;
import javax.jws.WebMethod;
import javax.jws.WebParam;
import javax.jws.WebService;

/**
 *
 * @author Yiyu Jia
 */
@WebService()
public class jiaBlogWS {

    /**
     * Web service operation
     */
    @WebMethod(operationName = "callSP")
    public Invoice[] callSP(@WebParam(name = "customID")
    final String customID) {
        //creat a dummy invoice data.
        Invoice inv = new Invoice();
        inv.setInvoiceNum(2);
        inv.setName("yiyu jia");
        ArrayList list1 = new ArrayList();
        Item i1 = new Item();
        i1.setItemNum("00011");
        list1.add(i1);
        inv.setItems(list1);
        //crteate another dummy invoice data.
        Invoice inv2 = new Invoice();
        inv2.setInvoiceNum(3);
        inv2.setName("yan zhang");
        ArrayList list2 = new ArrayList();
        Item i2 = new Item();
        i2.setItemNum("00011");
        list2.add(i2);
        inv2.setItems(list2);

        //create a dummy invoice array as return data.
        Invoice[] invs = new Invoice[2];
        invs[0] = inv;
        invs[1] = inv2;
        return invs;
    }
}

Invoice.java

package jia.blog.ws;

import java.util.List;
import javax.xml.bind.annotation.XmlAccessType;
import javax.xml.bind.annotation.XmlAccessorType;
import javax.xml.bind.annotation.XmlElement;

/**
 *
 * @author Yiyu Jia
 */
@XmlAccessorType (XmlAccessType.FIELD)
public class Invoice {

    public int invoiceNum;

    public String name;

    @XmlElement(name = "items")
    List items;

    public int getInvoiceNum() {
        return invoiceNum;
    }

    public void setInvoiceNum(int invoiceNum) {
        this.invoiceNum = invoiceNum;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public List getItems() {
        return items;
    }

    public void setItems(List items) {
        this.items = items;
    }

}

Item.java

import javax.xml.bind.annotation.XmlAccessorType;
/**
 *
 * @author Yiyu Jia
 */
@XmlAccessorType (XmlAccessType.FIELD)
public class Item {
    String itemNum;

    public String getItemNum() {
        return itemNum;
    }

    public void setItemNum(String itemNum) {
        this.itemNum = itemNum;
    }
}

Also, in order to illustrate a situation closing to real world app, I created two helper classes, which are used as parameters returned by jiaMetroWS.

Invoice.java

package jia.blog.ws;

import java.util.List;
import javax.xml.bind.annotation.XmlAccessType;
import javax.xml.bind.annotation.XmlAccessorType;
import javax.xml.bind.annotation.XmlElement;

/**
 *
 * @author Yiyu Jia
 */
@XmlAccessorType (XmlAccessType.FIELD)
public class Invoice {

    public int invoiceNum;

    public String name;

    //declaring list of items as List type.
    @XmlElement(name = "items")
    List items;

    public int getInvoiceNum() {
        return invoiceNum;
    }

    public void setInvoiceNum(int invoiceNum) {
        this.invoiceNum = invoiceNum;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public List getItems() {
        return items;
    }

    public void setItems(List items) {
        this.items = items;
    }

}

Item.java

package jia.blog.ws;

import javax.xml.bind.annotation.XmlAccessType;
import javax.xml.bind.annotation.XmlAccessorType;
/**
 *
 * @author Yiyu Jia
 */
@XmlAccessorType (XmlAccessType.FIELD)
public class Item {
    String itemNum;

    public String getItemNum() {
        return itemNum;
    }

    public void setItemNum(String itemNum) {
        this.itemNum = itemNum;
    }
}

Now, we can test our Web service. Since I use Glassfish 3.0 as my Web container, I can see the test page by right click Web Service node in project explorer and select "Test Web Service". After the testing page has been shown in your Web browser, you can play around by input parameter and get return. Also, we can see the request SOAP message in XML format and the return SOAP message. And, the most useful info is that you can find WSDL in the test page. Then, you can find XSD file in WSDL document.


Once we successfully see the test page, we can move to next step to create an Web service client to test our Web service. If you can not successfully see the test page. I do not know why. But, I can suggest you to uninstall the netbeans and reinstall the latest netbeans. I am using Netbeans 6.9.1. You can try to reinstall netbeans even you think your netbeans has same version as mime.

Creating a simple Web Service client with Metro toolkit is simple too.

1) In netbeans, we create a new standalone java project.

2) right click the new created project and select New --> Web Service Client... . Then, we will see a screen as below,

3) After we input the correct WSDL URL and click Finish, the netbeans will generate lots of stuff for us, including the stub classes for calling jiaMetroWS, which is still running on our local machine now.

4) writing our own simple code to call jiaMetroWS through generated Web service stub classes. The code is as below,

MetroClientTest.java

package jia.blog.ws.client;

import java.util.Iterator;
import java.util.List;

/**
 *
 * @author Yiyu Jia
 */
public class MetroClientTest {

    public static void main(String[] args){
    jia.blog.ws.client.JiaBlogWSService service = new jia.blog.ws.client.JiaBlogWSService();
    jia.blog.ws.client.JiaBlogWS port = service.getJiaBlogWSPort();

    String customId = "100";
    //below invoice should be Invoice 
    List invs = port.callSP(customId);
    //below invoice should be Invoice 
    Iterator it = invs.iterator();

    while( it.hasNext()){
        Invoice inv = it.next();
        System.out.print("Invoice number: "+inv.invoiceNum + " Name: "+inv.getName());
        for(int i=0; i < inv.getItems().size(); i++){
               System.out.println(" item" + i +": "+inv.getItems().get(i).itemNum);
         }
    }
  }
}

The netbeans projects can be downloaded here: jiaMetroWS.zip and jiaMetroWSClient.zip .