NetBeans IDE 5.0 Quick Start Guide for Web Services

Feedback

Sample Projects
Just want to play with some web services? In the IDE, choose File > New Project, then expand Samples folder. The IDE includes samples from the Java BluePrints Solution Catalogue.

Web services are distributed application components that conform to standards that make them externally available. The proliferation of distributed environments has created a need for an enterprise to be able to expose all or part of the functionality of an application to other applications over an open network. Web services solve the problem of integrating applications that have been developed independently and run on a variety of software and hardware platforms.

NetBeans IDE 5.0 comes bundled with web service support based on JSR-109, which is a development paradigm that is suited for J2EE development, based on JAX-RPC (JSR-101). Web service functionality in NetBeans IDE 5.0 is part of an end-to-end set of J2EE features. Also, NetBeans IDE 5.0 provides wizards to create web services and web service clients.

In this tutorial, you implement one of the following scenarios:

  • A web service exposed by a servlet.
  • A web service exposed by a session bean.
Note that you must choose which of these two scenarios you want to implement.

This tutorial covers the following topics:

After you have installed and set everything up, this tutorial can be completed in 30 minutes.

Setting Up Your Environment

Before you start writing code, you have to make sure you have all of the necessary software and that your server is set up correctly.

Installing the Software

Before you begin, you need to have the following software installed on your computer:

  • NetBeans IDE 5.0 (download).
  • Sun Java System Application Server Platform Edition 8 2005Q1 (download)
  • Java Standard Development Kit (JDKTM) version 1.4.2 (download) or 5.0 (download)

Registering the Server

Before you can work with web services, you have to register an instance of the Sun Java System Application Server. If you installed the NetBeans IDE 5.0/Sun Java System Application Server bundle, the local Sun Java System Application Server is registered automatically.

  1. Choose Tools > Server Manager from the main window.
  2. Click Add Server. Select the server and give a name to the instance. Then click Next.
  3. Specify the installation directory of the application server (for example, C:\Sun\Appserver).
  4. Leave the Register Local Default Domain radio button selected and select a domain.
  5. Optionally, click Next and enter your administrator username and password. If you do not want to store the username and password in your IDE user directory, you can leave these fields blank. The IDE will prompt you every time it needs the information.
    Note: The default admin password for the Sun Java System Application Server is adminadmin.
  6. Click Finish.
  7. Click the Runtime window and expand the Servers node. The new server instance is listed.
  8. Right-click the application server's node and choose Start Server.

Developing the Web Service

Coding web services is easy. The IDE takes care of all the implementation details for you, so you can concentrate on coding the business logic of your web service.

Create the Project

  1. Decide whether you want to expose the web service from a web application or from a session bean.
  2. Choose File > New Project (Ctrl-Shift-N) and, depending on your decision in the previous step, do one of the following:
    • Under Categories, select Web. Under Projects, select Web Application. Click Next.
    • Under Categories, select Enterprise. Under Projects, select EJB Module. Click Next.
  3. Name the project HiWS, change the Project Folder to any folder on your computer, and make sure that the server of your choice is selected in the Server drop-down list. Note that only servers that have been registered with the IDE are available in the Server drop-down list.
  4. Click Finish.

Create the Web Service

  1. Right-click the project node and choose New > Web Service. Name the web service HiWS, type org.me.hi in the Package field, and click Finish.

    Wait a few seconds while the web service is created and compiled. An implementation class called HiWSImpl.java (in web applications) or a session bean called HiWSBean.java (in EJB modules) opens in the Source Editor.

  2. In the Projects window, expand the Web Services node, right-click the HiWS web service node, and choose Add Operation. Type sayHi in the Name field and type String in the Type drop-down list. Click Add and define a parameter named s of type java.lang.String. Click OK.

  3. Click OK in the Add Operation dialog box to create the operation skeleton.
  4. Expand the Source Packages node and the org.me.hi node. Double-click the HiWSSEI.java node and notice that the operation has been declared in the interface class and that the java.rmi.RemoteException exception is thrown.

  5. In the Source Editor, fill out the operation skeleton in the implementation class or session bean. This class is either HiWSImpl.java (in web applications) or HiWSBean.java (in EJB modules). Do this by replacing "return null;" with the following code in the body of the sayHi operation:
  6.    
        return "Hi " + s + "!";
    
    

    The new sayHi method should now look as follows:

       
        public java.lang.String sayHi(java.lang.String s) throws java.rmi.RemoteException {
    	   return "Hi " + s + "!";
        }
    
    

Generate and Configure a SOAP Message Handler for Logging

Optionally, you can enrich the web service with functionality provided by SOAP message handlers. In this optional section you create a logger.

  1. Right-click the project node and choose New > File/Folder. Under Categories, choose Web Services. Under File Types, choose Message Handler. Click Next.
  2. Name the message handler HiWSLogger, select org.me.hi in the Package drop-down list, and click Finish.

    An implementation class called HiWSLogger.java is created and opens in the Source Editor. Without adding or changing any code, you now have a logger, because the default code provided by the IDE's message handler template provides complete logger functionality.

  3. In the Projects window, expand the Web Services node, right-click the HiWS node and choose Configure Handlers. In the Configure SOAP Message Handlers dialog box, click Add and browse to the HiWSLogger class. Click OK.

    The message handler class is listed in the dialog box.

  4. Click OK to complete the configuration of the SOAP message handler.

    Expand the Configuration Files node. Double-click the webservices.xml node and notice that the handler has been declared.


Exposing the Web Service

When you expose the web service, you make it available for consumption by clients. You can use the IDE as a client, so that you can test it after deployment.

Deploy the Web Service

Depending on how you have implemented the web service, do one of the following:

  • For web services implemented as web applications, do the following:
    1. Choose Tools > Options and select your browser from the Web Browser drop-down list. Click OK.
    2. Right-click the HiWS project node in the Projects window and choose Properties. In the Project Properties dialog box, select the Run pane. Type /HiWS?WSDL in the Relative URL text box. The Relative URL text box specifies the URL relative to the context path to run as entry point to the application. Click OK.
    3. If you are behind a corporate firewall and you need to set the proxy host and port number, see Troubleshooting.
    4. Right-click the HiWS project node in the Projects window and choose Run Project.

      The server is started and the web service is deployed. You should see the web service's WSDL file displayed in your browser. The WSDL file publishes the endpoints of your web service, so that the developer responsible for creating the web service client can know what kind of functionality the web service can provide.

  • For web services implemented as session beans, right-click the HiWS project in the Projects window and choose Deploy Project. The server is started and the web service is deployed. Note that session beans do not display in a browser.

The web service must remain deployed for you to be able to create the web service client in the "Consuming the Web Service" section.

Register and Test the Web Service

  1. In the Projects window, expand the Web Services node, right-click the HiWS web service node, and choose Add to Registry.

    You might receive an error message that looks similar to the following:

     
       Unable to add web service to registry. Make sure it has been deployed, 
       the server is running, and the correct WSDL URL was entered.
    
    

    If you receive this error message, make sure that the web service is deployed and then choose Add to Registry again.

    A dialog box appears with a suggested URL to be used to register the web service.

  2. Make a note of the URL because you will need it later when you create the web service client. Click OK.
  3. In the Runtime window (Ctrl-5), expand the Web Services node and keep expanding the nodes until you reach the sayHi node. Right-click the sayHi node and choose Test Operation. In the Test Web Service Operation dialog box, type "John" in the Value text box and click Submit. The result "Hi John!" is displayed at the bottom of the dialog box. Click Close.
  4. View the server log to see the log message generated by the message handler. For example, if you use the Sun Java System Application Server, expand the Servers node in the Runtime window, right-click the server's node, and choose View Server Log. The server.log file is displayed and a message similar to the following is included at the end:
       |Log message: Wed Sep 07 10:47:45 CEST 2005--sayHi String_1:John |#]
    

    This is the logging message generated by the SOAP message handler that you created in the previous section.

Now that you have tested the operation, and are satisfied that the web service works and is potentially useful to others, you can leave it deployed so that it can be consumed by clients that need it.


Consuming the Web Service

Consuming a web service is what a client does when it uses a web service. It is easy to use the IDE to set up a client so that it consumes a web service. You use a wizard to import the WSDL file that describes the web service's interface. Then you integrate it within the client so that the web service does something useful for you.

Note: A web service can be consumed in a web application or a Java application. In the example that follows, you will only consume the web service in a web application. For more information on web service clients, whether implemented in web applications or Java applications, see the NetBeans IDE 5.0 Quick Start Guide for Web Service Clients.

Create the Web Application Project

  • Choose File > New Project (Ctrl-Shift-N). Under Categories, select Web. Under Projects, select Web Application. Click Next. Name the project HiWSClient, change the Project Folder to any folder on your computer, and make sure that the server of your choice is selected in the Server drop-down list. Click Finish.

Discover Information About the Web Service

  1. Right-click the HiWSClient project node and choose New > Web Service Client. Copy and paste the URL of the running web service in the WSDL URL text box. For example, the URL might be as follows:
    http://localhost:8080/HiWS/HiWS?WSDL
  2. Click Retrieve WSDL. When the Local Filename text box is filled with the WSDL file's name, the WSDL file has been correctly retrieved. Type org.me.hi in the Package field.
  3. Depending on the server, do the following:
    • For the Sun Java System Application Server, choose J2EE Container-generated static stub.
    • For other servers, such as the JBoss Application Server or the Tomcat Web Server, you may have to choose IDE-generated static stub.
  4. Click Finish.
  5. Expand the Web Service References node and keep expanding the nodes until you reach the sayHi node. Right-click the sayHi node and choose Test Operation. In the Test Web Service Operation dialog box, type "John" in the Value text box and click Submit. The result "Hi John!" is displayed at the bottom of the dialog box. Now that you have tested the operation, and are satisfied that the exposed web service is useful to you, you are ready to develop a client-side application to interact with it.

Develop the Web Service Client

  1. Right-click the HiWSClient project node and choose New > Servlet. Name the web service HiServlet, type org.me.hi in the Package drop-down list, click Next and then click Finish. The servlet HiServlet.java opens in the Source Editor.
  2. In the Source Editor, right-click within the processRequest operation in the HiServlet class. Choose Web Service Client Resources > Call Web Service Operation, select the sayHi operation, and click OK.
  3. Now fill out the generated skeleton code so that it looks as follows:
       
       try {
           out.println(getHiWSSEIPort().sayHi("John"));
       } catch(java.rmi.RemoteException ex) {
           out.println("<p>Caught an exception <p>" + ex);
       }
    
    

  4. Rearrange the code snippet so that it is placed between the processRequest method's <body> tags:
     protected void processRequest(HttpServletRequest request, HttpServletResponse response)
      throws ServletException, IOException {
         response.setContentType("text/html;charset=UTF-8");
         PrintWriter out = response.getWriter();
           
         out.println("<html>");
         out.println("<head>");
         out.println("<title>Servlet HiServlet</title>");
         out.println("</head>");
         out.println("<body>");
          
         try {
             out.println(getHiWSSEIPort().sayHi("John"));
         } catch(java.rmi.RemoteException ex) {
             out.println("<p>Caught an exception <p>" + ex);
         }
          
         out.println("</body>");
         out.println("</html>");
         out.close();
     }

  5. Next, to enable the user to interact with the web service, add a form to the servlet and pass the user's input to the web service (only the code in red below is different to the code above):

     protected void processRequest(HttpServletRequest request, HttpServletResponse response)
      throws ServletException, IOException {
         response.setContentType("text/html;charset=UTF-8");
         PrintWriter out = response.getWriter();
           
         out.println("<html>");
         out.println("<head>");
         out.println("<title>Servlet HiServlet</title>");
         out.println("</head>");
         out.println("<body>");
    
    
         out.println("<p>Enter your name:</p>");
         out.println("<form method=\"get\">");
         out.println("<input type=\"text\" name=\"name\" size=\"25\">");
         out.println("<br>");
         out.println("<p>");
         out.println("<input type=\"submit\" value=\"Submit\">");
         out.println("</form>");
         String name = request.getParameter("name");
      
         if ( name != null ) {
            try {
        	  out.println(getHiWSSEIPort().sayHi(name));
            } catch(java.rmi.RemoteException ex) {
              out.println("<p>Caught an exception <p>" + ex);
            }
         }
         
         out.println("</body>");
         out.println("</html>");
         out.close();
     }

    Don't forget to change the String "John" to the variable name, as shown in the code above!

Deploy the Web Service Client

  1. Right-click the HiWSClient project node in the Projects window and choose Properties. In the Project Properties dialog box, select the Run pane. Do the following:
    • Select the server in the Server drop-down list.
    • Type /HiServlet in the Relative URL textbox.
    • Click OK.
  2. Right-click the HiWSClient project in the Projects window and choose Run Project.

    The web service client is deployed. You should see something similar to the following displayed in the IDE's default browser:

    Deployed client 1

  3. Type "John" and click Submit. You should now see the following:

    Deployed client 2


Troubleshooting

Since the IDE provides most of the code you need for communicating with the web service, the only problems you should encounter are errors in your own code. In addition, though, you might encounter a few problems if you are behind a firewall. The troubleshooting tips that follow attempt to resolve this problem.

  • Deploying to the Sun Java System Application Server. If you deploy the application without setting your proxy host and port correctly, you will see something similar to this in your browser:

    Proxy problem 1

    To fix this problem, do the following:

    1. In the Runtime window, make sure that the Sun Java System Application Server is running. If it is running, a green arrow is shown to the left of the server's name.
    2. Expand the Sun Java System Application Server node, right-click the JVMs node and choose Properties.
    3. Click the ellipsis to the right of the JVMOptions property.
    4. Add the following two properties to the list:

      • -Dhttp.proxyHost=my.host

      • -Dhttp.proxyPort=my.port.number

      Make sure that the values you set for these properties are appropriate to your environment.

  • Testing in the IDE. If you test the application in the IDE without setting your proxy host and port correctly, this error will be displayed in the IDE:

    Proxy problem 1

    To fix this problem, do the following:

    1. Choose Tools > Options.

    2. In the Options window, set the proxy host and port number.

Next Steps

For more information about using NetBeans IDE 5.0, see the following resources:

To send comments and suggestions, get support, and keep informed on the latest developments on the NetBeans IDE J2EE development features, join the nbj2ee@netbeans.org mailing list.