Building JAX-WS 2.0 Services with NetBeans 5.0 and GlassFish


by Bobby Bissett
(Updated March 2006 to use NetBeans 5.0 and GlassFish build 40)

This article explains how to create JAX-WS 2.0 web services using NetBeans and the GlassFish application server. Using the built-in features of NetBeans and GlassFish, you can create a web services project that can be built and tested with one command.

The first section describes setting up the NetBeans IDE and creating a GlassFish library. Section 2 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 the JAX-WS 2.0 workspace rather than using GlassFish, see this version of the article instead.

Contents

  1. Setting Up NetBeans and GlassFish
  2. Building an Application
  3. Tips

 

Setting Up NetBeans and GlassFish

This article was written using NetBeans 5.0. 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.

To get the GlassFish application server, visit the GlassFish web site and click the Download Now button. Follow the instructions to install a GlassFish binary build. This article will refer to the installation directory as simply the "glassfish" directory. Note: The latest version of this article was tested with GlassFish build 40.

With NetBeans and GlassFish installed, use these steps to add the server to NetBeans and create the GlassFish library that your project will use. In NetBeans, click Tools in the menu bar and select Server Manager. Click Add Server, choose "Sun Java System Application Server" from the "Server" menu and enter a name for the server such as "GlassFish." Click Next. Enter the path to your "glassfish" directory on the next screen, accept the default domain to register, and click Next. On this last screen, enter the admin password and click Finish. The default password that comes with the bundle is given on the GlassFish Quick Start Guide page. Click Close to exit the Server Manager. Note that there are now two servers available under the "Servers" node in the "Runtime" tab.

To create the library that your project will use, click Tools in the menu bar and select Library Manager. Click New Library and enter a library name such as "GlassFish." Press OK. With the "Classpath" tab still open, click Add JAR/Folder. Browse to your glassfish/lib directory and select all the jar files (hold down Shift and click). Click Add JAR/Folder. Then click OK. This library is not needed for creating the service since some of the GlassFish jars are included in the NetBeans classpath when running. The library is used later when running the test client.

Building an Application

Creating a service from Java

The steps for creating a web service using GlassFish are easier than when using just the JAX-WS code and the Tomcat server included with NetBeans. Unlike those steps, outlined in this version of this article, you do not need to run wsgen to create the server artifcats before creating the war file. You only need to create the service endpoint class, change the default web.xml file, and you are ready to deploy.

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. Make sure that "Server" is set to your GlassFish application server and that "Set Source Level to 1.4" is unchecked (JDK 5 is required for JAX-WS 2.0). Click Finish. Now that the project has been created, you may delete "index.jsp" if you wish. The project will use your service endpoint class as the servlet class, and GlassFish will turn the class into a web service at deployment time.

Add the GlassFish library to the new project. In the Projects tab, right-click "Libraries" and select Add Library. Choose the "GlassFish" library and click Add Library. You should now tell NetBeans not to include the GlassFish jar files in your generated war (since they are already included in the server). Right-click the SampleApp project name and choose Properties. Click the Libraries node on the left, and uncheck the box next to "GlassFish" in the "Compile-time Libraries" table. As an optional (but helpful!) step, also click the Run node and enter "/hello?wsdl" in the "Relative URL" field. This will open a browser to the web service's wsdl file when the application is run. Click OK.

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.

Save the config file web.xml to the SampleApp/web/WEB-INF/ directory. This will overwrite the default version and specify the ServiceImpl class as the servlet, along with the servlet name, which is the same as the name in the WebService annotation in ServiceImpl.java. The application server will use this information to run wsgen as needed to create the web service.

To create and start the service, choose Run and Run Main Project from the menu bar, or use the keyboard shortcut F6. NetBeans will compile the service class, create the war file, start the application server, and deploy the application. If your installation of NetBeans is properly set up, a browser will be started and will be directed to the web service's wsdl file. 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.

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 project's build.xml file. To edit the 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. 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 in NetBeans. 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 Cancel 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 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 restart the GlassFish 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. 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, follow the above steps to create a new web project. You still need to copy web.xml to your WEB-INF directory and change it as necessary. In web.xml, you should only have to change the <servlet-name> and <servlet-class> (and the url pattern if you'd like to). You can use this build.xml file which has the added target 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 GlassFish 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 web.xml file to use the new servlet class name (as noted in GlassFish log).
  2. Change the <servlet-name> in web.xml to match the new service name.

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 GlassFish 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. The web.xml file is the version used in the standalone version of this article. Only the service name needs to be changed. The sun-jaxws.xml file has 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