Building JAX-WS 2.0 Services with NetBeans


by Bobby Bissett
December 2005

This article explains how you can use the built-in features of NetBeans 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 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. The latest jdk may be downloaded from http://java.sun.com.

Note: To create web services using GlassFish rather than the jax-ws-sources workspace, see this version of the article instead.

Contents

  1. Setting Up NetBeans
  2. Creating the JAX-WS 2.0 Library
  3. Building an Application
  4. Tips

 

Setting Up NetBeans

This article was written using NetBeans 4.1, though the same steps may be used with NetBeans 5.0 Beta 2. More information about NetBeans, including the application, may be found at the NetBeans.org web site. If you are new to the integrated development enviroment, the site has guides and tutorials to get you up and running.

For the examples in this article, there are only a couple steps to getting NetBeans configured. The first is to remove or rename the JAXP jar files that are included in the version of Tomcat included in NetBeans 4.1. These jars are older than the ones included in JDK 1.5 (a JAX-WS requirement). These jars are located in <netbeans_home>/enterprise1/jakarta-tomcat-5.5.7/common/endorsed. You may change the .jar extension so that they are not loaded without removing them. If you are using NetBeans 5.0 Beta 2, the jars are in <netbeans_home>/enterprise2/jakarta-tomcat-5.5.9/common/endorsed.

The second step is to make sure that the internal web server is running on port 8080 (or change the examples in this article to match your desired port). If you have changed the port to another value, it can be changed by going to the Runtime tab, opening the Servers node, and right-clicking Bundled Tomcat (5.5.7). Choose Properties, then set Server Port to 8080. With Netbeans 5.0, open the Bundled Tomcat (5.5.9) properties and set the server port.

Creating the JAX-WS 2.0 Library

The JAX-WS code is located in the "jax-ws-sources" repository on java.net. For help in checking out the sources, see the cvs help page. Once you have checked out the sources, you are ready to build the JAXWS-RI project.

In NetBeans, click File in the menu bar, then Open Project, then choose the "jaxws-ri" directory under your "jax-ws-sources" installation and click Open Project Folder. To build, choose Build and select Build Main Project, or use the F11 shortcut.

After the workspace is built, you can create a NetBeans library to use with your web service applications. Click Tools in the menu bar and then Library Manager. Click the New Library button, enter "JAX-WS", and click OK. With the "Classpath" tab open in the new library, click Add JAR/Folder and add the jars under the jax-ws-sources/jaxws-ri/build/lib directory. Open the "Sources" tab, click Add JAR/Folder, and add these directories:

  • jax-ws-sources/jaxws-ri/rt/src (the runtime sources)
  • jax-ws-sources/jaxws-ri/tools/wscompile/src (the tool sources)

Note: If you would like to use the source or binary bundle from java.net rather than using cvs to check out a workspace, see this page for instructions.

Building an Application

Creating a service from Java

To create a web service, start with a NetBeans web application project. The extra step that is needed to turn a Java class into a web service is to run wsgen on the class file before deployment (which can be done by adding one target to your build.xml file). You will also need to include another configuration file in the generated war, as well as adding some information to web-xml. The steps are below.

Start by creating a new web application project. In NetBeans, choose File from the menu bar and select New Project. Under "Categories," select Web, and under "Projects" select Web Application. Click Next. Enter "SampleApp" for the "Project Name" field and choose the location in which to save your project. Set "Server" to the "Bundled Tomcat" server and make sure that "Set Source Level to 1.4" is unchecked. Click Finish. (Now that the project has been created, you may remove "index.jsp" if you wish. The project does not need to contain any jsp/html pages or any servlets, as the JAX-WS runtime servlet will be used to handle requests to your web service.)

Add the JAX-WS classes to the new project. In the Projects tab, right-click "Libraries" and select Add Library. Choose the "JAX-WS" library and click Add Library.

Add the service class. Right-click "Source Packages" and select New and Java Package. Enter "my.sample.server" and click Finish. To add a class to the package, you would normally right-click on the package node and choose New and Java Class. Because the example class is already written, instead you can save the file ServiceImpl.java to the SampleApp/src/java/my/sample/server/ directory and NetBeans will find it. Double-click the file name in the package node if you wish to see the file's contents. You can see that it is a simple Java class with one method and a few annotations that will be used by the JAX-WS 2.0 runtime.

Add the two config files web.xml and sun-jaxws.xml to SampleApp/web/WEB-INF/ as well. The sun-jaxws.xml file is used by the JAX-WS runtime, and web.xml will overwrite the generated one to specify the JAX-WS servlet class. Both files contain a reference to the "/hello" url pattern.

The last step is to add the following xml to SampleApp/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 "SampleApp" 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 SampleApp/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.

Note: When the service war file is built by NetBeans, it includes the jar files in the project library inside the WEB-INF/lib directory. This makes the war file portable to any web container, but also makes it quite large. When deploying to a different container that already has the JAX-WS code integrated, you can remove these jars from the war file. To tell NetBeans to not include the jars when building, right-click the project name and select Properties. Select the Libraries node on the left and uncheck "JAX-WS" in the "Compile-time Libraries" table. Click OK. To run this smaller war file in the Tomcat server built into NetBeans, you can copy the JAX-WS 2.0 jars (in the workspace, these would be in jax-ws-sources/jaxws-ri/build/lib) to <netbeans_home>/enterprise1/jakarta-tomcat-5.5.7/common/lib. If using NetBeans 5.0 Beta 2, the Tomcat installation is in enterprise2/jakarta-tomcat-5.5.9 instead.

Creating a client

For a full-fledged application that consumes a web application, you would normally create a new project for the application. To easily create a client for testing our new web service, however, you can use the unit test capability of NetBeans.

Start by creating a new test package. Right-click "Test Packages" in the Projects tab and select New and Java Package. Enter "my.sample.test" and click Finish. In general, you can add tests by right-clicking the test package and choosing New and Empty Test. For this example, you can save the file ServiceTest.java to your SampleApp/test/my/sample/test/ directory. Open the file to see how the test creates a Service, then the Proxy for the service, and calls hello(String) on it. Note: When adding your own client code as a JUnit test, NetBeans expect the name to be of the form "*Test.java".

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:8080/SampleApp/hello?wsdl"/>
    </target>

To run the test, select Run from the menu bar and Test Project. Or use the keyboard shortcut Alt-F6. In the output, you should see "hello world" that was returned from the service.

Using the NetBeans Web Services Registry

As an alternate way to test the service, you can use the Web Services Registry included in NetBeans 5.0 Beta 2. In the Runtime tab, right-click Web Services and choose Add WebService. In the "URL" field, enter the address of the web service, in this case "http://localhost:8080/SampleApp/hello?wsdl" and click Get Web Service Description. This will bring up a description of the web service. To test the "hello" operation, click TestOperation next to the operation name. Then you can enter a value to send and see what is returned (at this point, it might be useful to change the service impl class to add some text to the returned String). Click Close to exit the test, and then Add if you wish to add the service to the registry.

Debugging the application

Stepping through the code in your application (and the JAX-WS code) is simple. Start by placing a breakpoint on the System.out.println("Service received: " + s); line in ServiceImpl.java (line 15). The fastest way is to open the file and click on the left border of the editor at the appropriate line. Or place the cursor on the line and use Ctrl-F8 (see NetBeans users guide for full information on using the debugger).

At this point you could start the server in the debug mode with Run -> Debug Main Project, but instead you can run the client code as well in one step. To do this, in the project's build.xml file, change the "antcall" line of the "-pre-compile-test" target from <antcall target="run"/> to <antcall target="debug"/>.

        <!-- Use "debug" or "run" here. -->
        <antcall target="debug"/>

Now run the client test again (i.e., press Alt-F6). Before building the tests, NetBeans will start the Tomcat server in debug mode. After the client starts, the debugger should stop on the appropriate line in ServiceImpl and you can step through the server code. Note: If you add a breakpoint to a line in the JAX-WS workspace, Alt-F6 will not work until you move focus back to a file in the SampleApp project, by bringing up a file in the editor, clicking the project in the Projects tab, etc. If you make any changes to your application, everything will be rebuilt as needed when you run the test again. Remember to stop the debugging session when you are done by choosing Run in the menu bar and Finish Debugger Session, or by clicking the stop button in the tool bar.

To debug code on the client side, start by placing a breakpoint in ServiceTest.java inside the test1() method. Then right-click on the file in the Project view and select Debug File (or simply use Ctrl-Shift-F5 with ServiceTest as the active file in the editor). This will start the client as well as the service in the debugger.

Tips

Writing your own service

To write your own service, you can remove the "my.sample.server" package from the project and add a new one, or you can follow the above steps to create a new web project. You still need to copy the two config files web.xml and sun-jaxws.xml to your WEB-INF directory and then change them as necessary. In web.xml, you should only have to change the <url-pattern> element, and the <servlet-name> if you'd like. You can use this build.xml file which has the two added targets in it to save a step.

To help with getting the values correct in the two config files and build.xml, the easiest path is to start trying to build and let the compiler or runtime errors tell you what to do (don't forget to watch the Tomcat output as well). With a new project and a new service file (NewService.java as an example), do a clean build with Build -> Clean and Build Main Project or Shift-F11 and then run the project. The changes needed from this point were:

  1. Change the sei="..." attribute in the "wsgen" element in the "-pre-dist" target in build.xml. (As noted in compiler error.)
  2. Change the sun-jaxws.xml file to use the new service class name and endpoint name/url. (As noted in Tomcat log.)
  3. Change the <url-pattern> in web.xml if you changed it in sun-jaxws.xml. (Update the URL in project properties as well if you want to see the service information in your browser.)

The only other step is to figure out the service name, port name, and port methods to use in your client code. This can be done by running a test (leave the test method empty first) and seeing what files were generated under build/test/classes. To point the wsimport tool to the correct location, change the "wsdl" attribute of the wsimport element in the "-pre-compile-test" target in build.xml. If NetBeans brought up the deployed service in your browser, you can cut/paste this information. Also change the "package" attribute of wsimport if desired.

Creating a service from WSDL

To create a service from a wsdl, the main steps are to add the wsdl file, add a skeleton service impl class, and add a "-pre-compile" target to your build.xml file rather than "-pre-dist". If you don't know what methods to add to your service impl class or what interface it should implement, you can start building the project and get this information quickly from the generated code and compiler errors. The steps are similar to generating the client code above. An example is used below to outline the steps rather than repeating all the details that are in the example starting from Java.

  1. Create a new web project as before, removing the index.jsp file if you wish. Add the JAX-WS project to the library.
  2. Under the WEB-INF directory, add a directory called "wsdl" and add the hello.wsdl file to the new directory.
  3. Add the two files web.xml and sun-jaxws.xml to your WEB-INF directory. Note that the web.xml file is the same as in the project starting from Java. The sun-jaxws.xml file has some new information in it: the service and port names from the wsdl file that define the endpoint, and the location of the wsdl file inside the war file.
  4. Create a source package "fromwsdl.sample.server" and copy HelloImpl.java to the package. Note that the classname matches the one specified in the sun-jaxws.xml file. When creating your own service, you may start with an empty class and add the interface and methods later based on code generated when the project is built.
  5. Overwrite the "-pre-compile" target in your build.xml file. You can use this build.xml file for the example. Note that the server package and wsdl information are already in this sample build.xml file, but the client test information is not.
  6. Once it is building, run the application as above. Don't forget to add the url-pattern to see the service in a browser by editing the project properties.

The general form of the -pre-compile is given below:

    <target name="-pre-compile">
        <taskdef name="wsimport" classname="com.sun.tools.ws.ant.WsImport">
            <classpath path="${javac.classpath}"/>
        </taskdef>

        <echo>running wsimport</echo>
        
	<-- The wsdl attribute is absolute path, so ${basedir} is included.
             The package name below will be used for the generated
             interface class that your impl class must implement. -->
        <wsimport
            debug="true"
            keep="true"
            destdir="src/java"
            package="YOUR_PACKAGE"
            wsdl="${basedir}/web/WEB-INF/wsdl/YOUR_FILE_NAME.wsdl"/>
    </target>

The steps for adding a client test to use the service are the same as above. Whether the service was generated from wsdl or from a Java class, the client is always generated from the wsdl file on the server.


Please send any feedback to users@jax-ws.java.net.

Bobby Bissett is a member of the JAX-WS 2.0 implementation team and full-time NetBeans user. Special thanks go to the NetBeans team for answering my questions, and a big thanks to "The NetBeans IDE Field Guide" for showing me I didn't have to do everything the hard way.

Terms of Use; Privacy Policy; Copyright ©2013-2016 (revision 20160708.bf2ac18)
 
 
Close
loading
Please Confirm
Close