Building vJAX-WS 2.0 Services with NetBeans 5.0 (MSIS 531 specific)

Full article on netbeans.org is here

This article explains how you can use the built-in features of NetBeans 5.0 to create JAX-WS 2.0 services quickly. Once the project has been created, it can be rebuilt (and tested!) with one command. While newer versions of NetBeans include the ability to create JAX-RPC 1.X web services, the JAX-WS 2.0 code is still under development. The steps to create a web service with JAX-WS 2.0 have been simplified, and you can turn a web application project in NetBeans into a web service with very few steps.

The first two sections describe obtaining and setting up the NetBeans IDE and the JAX-WS code. Section 3 includes the information on creating a web service in web project along with the sample code used. The last section describes tips for using the project to create your own web service as well as instructions for creating a service starting from WSDL. Note that J2SE 5.0 is required for JAX-WS 2.0 applications.

This tutorial covers the following topics:

1. Setting Up Your Environment
2. Creating a new Web Application with JAX-WS 2.0 Library
3. Building a Service
   • Creating Service from Java
     
4. Testing and Debugging
   • Testing service in Web Services Registry
   • Creating a Unit Test

1. Setting Up Your Environment

Before you start writing code, you have to make sure you have all of the necessary software.

Since we have a JDK and Netbeans installed already, there's nothing more to install, other than the library files that were placed in c:\msis531\java\lib\jax-ws2.0. Follow the steps below to add the library files once you've created the project.

2. Creating a new Web Application with JAX-WS 20 Library

3. Building a Service

Creating Service from Java

Add the service class. Right-click JAX-WS20 node in Projects View and select New and Java Class. Enter "ServiceImpl" to Class Name field, "my.sample.server" to Package field and click Finish. Implement a web service hello(java.lang.String) operation and specify  the portType name, service name and target namespace using the JAX-WS2.0 annotations :

package my.sample.server;

import javax.jws.WebParam;
import javax.jws.WebService;
import javax.jws.WebMethod;

/**
 * A simple java class that will become a web service.
 */
@WebService(name="Hello", serviceName="HelloService", targetNamespace="http://example.com")
public class ServiceImpl {
    
    @WebMethod
    public String hello(@WebParam(name="name") String s) {
        System.out.println("Service received: " + s);
        return "Hello "+s;
    }
    
}

Compile (F9) the ServiceImpl class.

Warning: to enable the annotations support the Source Level should be set to 1.5 in the project: right click the project, select Properties, then under the Sources category, ensure that the source level is set to 1.5 as shown below.

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.4"
         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://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">
    <listener>
        <listener-class>com.sun.xml.ws.transport.http.servlet.WSServletContextListener</listener-class>
    </listener>
    <servlet>
        <servlet-name>my_service</servlet-name>
        <servlet-class>com.sun.xml.ws.transport.http.servlet.WSServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>my_service</servlet-name>
        <url-pattern>/hello</url-pattern>
    </servlet-mapping>
    <session-config>
        <session-timeout>
            30
        </session-timeout>
    </session-config>
    <welcome-file-list>
        <welcome-file>
            index.jsp
        </welcome-file>
    </welcome-file-list>
</web-app>

<?xml version="1.0" encoding="UTF-8"?>
<endpoints xmlns='http://java.sun.com/xml/ns/jax-ws/ri/runtime' version='2.0'>

  <endpoint
    name='Hello'
    implementation='my.sample.server.ServiceImpl'
    url-pattern='/hello'/>
</endpoints>

The last step is to add the following xml part to JAX-WS20/build.xml. To edit the project's build.xml file, you can use File -> Open File from the menu or switch to the Files tab instead of the Projects tab, open the JAX-WS20 node, and double-click build.xml. This target will be called by NetBeans after compiling your service class, but before creating the war file. The wsgen ant task will create JAXB and JAX-WS files that are needed for the service. See the JAX-WS documentation for more information on the wsgen tool.

    <!-- Overrides build-impl.xml target to create the server
         artifacts that will be included in the war file. -->
    <target name="-pre-dist">
        <taskdef name="wsgen" classname="com.sun.tools.ws.ant.WsGen">
            <classpath path="${javac.classpath}"/>
        </taskdef>
        <wsgen
            debug="true"
            keep="true"
            destdir="build/web/WEB-INF/classes"
            resourcedestdir="build/web/WEB-INF/classes" 
            sei="my.sample.server.ServiceImpl">
            <classpath>
                <pathelement path="${javac.classpath}"/>
                <pathelement location="${java.home}/../lib/tools.jar"/>
                <pathelement location="build/web/WEB-INF/classes"/>
            </classpath>
        </wsgen>
    </target>

To create and start the service, choose Run and Run Main Project from the menu bar, or use the keyboard shortcut F6. As an optional (but helpful) step, right-click the project name and choose Properties. Highlight the "Run" node and enter "/hello" in the "Relative URL" field on the right. By setting this value, NetBeans will bring up the "http://localhost:8084/JAX-WS20/hello" address in a web browser when you run the project. This allows you to verify that the service is deployed, and see the wsdl if you wish. You can make changes to the service class if you wish and see the changes in the wsdl reflected by just hitting F6 to rebuild and deploy the service.

Normally the hello service information should appear in the browser window. This indicates that the service was deployed successfuly:

 If not, look to the Bundlet Tomcat (5.5.9) log file in Output Window to see the source of problem.

4. Testing and Debugging

Testing service in Web Service Registry

Creating a Unit Test

Start by creating a new JUnit test case. Right-click Test Packages node in the Projects tab and select New -> File/Folder -> JUnit -> Empty Test. Enter "ServiceTest" to Class Name field, "my.sample.test" to Package field and click Finish. Implement the testService() method in a following way (copy and paste all text below, replacing what's supplied):

package my.sample.test;

import junit.framework.*;
import my.sample.test.generated.Hello;
import my.sample.test.generated.HelloService;

public class ServiceTest extends TestCase {
    
    public ServiceTest(String testName) {
        super(testName);
    }

    protected void setUp() throws Exception {
    }

    protected void tearDown() throws Exception {
    }
    
    // TODO add test methods here. The name must begin with 'test'. For example:
    public void testService() {
        HelloService service = new HelloService();
        Hello proxy = service.getHelloPort();
        
        String request = "Apples and Pears";
        String response = proxy.hello(request);       
        System.out.println(response);
    }

}

Before running, add this xml to your build.xml file. NetBeans will call this target before compiling and running your test client. When this target is run, it makes sure that the service is built and deployed (rebuilding if necessary). See the JAX-WS documentation for more information on the wsimport tool.

    <!-- Overrides build-impl.xml target to start server and
         generate client artifacts before building test. -->
    <target name="-pre-compile-test">
        <taskdef name="wsimport" classname="com.sun.tools.ws.ant.WsImport">
            <classpath path="${javac.classpath}"/>
        </taskdef>
    
        <!-- Use "debug" or "run" here. -->
        <antcall target="run"/>
        
        <echo>running wsimport</echo>
        <wsimport
            debug="true"
            keep="true"
            destdir="test"
            package="my.sample.test.generated"
            wsdl="http://localhost:8084/JAX-WS20/hello?wsdl"/>
    </target>

To run the test, select Run from the menu bar and Test "JAX-WS20". Or use the keyboard shortcut Alt-F6. In the output, you should see "Hello Apples and Pears" r that was returned from the service: