Installing the Software

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

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

Registering the Sun Java System Application Server

Before you can compile web services, you have to register a local instance of the SJS Application Server. If you installed the NetBeans IDE 4.1/SJS Application Server bundle, the local application server is registered automatically.

1. Choose Tools > Server Manager from the main window.
2. Click Add Server. Select Sun Java Systems Application Server 8.1 and give a name to the instance. Then click Next.
3. Specify the server information, the location of the local instance of the application server, and the domain to which you want to deploy.

Create the Project

1. Decide whether you want to implement the web service as a web application or as a session bean.
2. Choose File > New Project (Ctrl-Shift-N) and do one of the following:
   • Under Categories, select Web. Under Projects, select Web Application. Click Next.
   • Under Categories, select Enterprise. Under Projects, select Enterprise JavaBeans Module. Click Next.
3. Name the project HiWS, change the Project Folder to any folder on your computer, and make sure that the Sun Java System Application Server is selected in the Server drop-down. 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. 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 select String in the Type combo box. Click Add and define a parameter named s of type java.lang.String. Click OK to create the operation skeleton.
3. 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.
4. In the Source Editor, fill out the operation skeleton in the implementation class or session bean. Do this by replacing "return null;" with the following code in the body of the sayHi operation:

    return "Hi " + s + "!";

The code should now look as follows:

    package org.me.hi;

    public class HiWSImpl implements HiWSSEI {

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

Generate and configure a SOAP Message Handler

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, and click Finish. An implementation class called HiWSLogger.java is created and opens in the Source Editor.
3. In the handleRequest method, note that the message that will be logged is defined as follows:

       StringBuffer message = new StringBuffer();
       while (childElems.hasNext()) {
           child = (SOAPElement) childElems.next();
           message.append(new Date().toString() + "--");
           formLogMessage(child, message);
       }
   
       System.out.println("message: " + message.toString());
   
   

4. In the Projects window, expand the Web Services node, right-click the node for the web service 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.

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

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. 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 in both the Context Path textbox and the Relative URL textbox. Click OK.
  2. Right-click the HiWS project in the Projects window and choose Run Project.

     The J2EE-compliant server is started and the web service is deployed. You should see a message similar to the following displayed in the IDE's default browser:

         Invalid wsdl request http://localhost:8080/HiWS/HiWS for web service HiWS
     

• For web services implemented as session beans, right-click the HiWS project in the Projects window and choose Deploy Project. The J2EE-compliant server is started and the web service is deployed.

Note that the web service must remain deployed for you to be able to create the web service client in the next 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, 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.
4. Expand the Servers node, right-click the Sun Java System Application Server 8.1 node, and choose View Server Log. The server.log file is displayed and a message similar to the following is included:

       message: Wed Jan 12 16:56:48 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 is useful to you, you can integrate its functionality with a web service client.

Create the Web Application Project

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

Discover Information About the Web Service

1. Right-click the project node and choose New > Web Service Client. Copy and paste the URL of the running web service in the WSDL URL text box and 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 and click Finish.
2. 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 create a client to consume it.
3. Right-click the HiWSClient project node and choose New > Servlet. Name the web service HiServlet, type org.me.hi in the Package field, click Next and then Finish. The servlet HiServlet.java opens in the Source Editor.

Create the Web Service Client

1. 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. Cut and paste the skeleton operation so that it is positioned above the out.close(); line.
2. Now fill out the skeleton operation so that it looks as follows:

      try {
          out.println(getHiWSSEIPort().sayHi("Ludwig"));
      } catch(java.rmi.RemoteException ex) {
          out.println("<p>Caught an exception <p>" + ex);
      }
   
   

   Optionally, if you want the user to be able to interact with the web service, delete the code above and add the following code between the processRequest method's <body> tags:

      out.println("<p>Enter your name:
   ");
      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);
         }
      }
   
   

Create the J2EE Application Project

1. Choose File > New Project (Ctrl-Shift-N). Under Categories, select Enterprise. Under Projects, select Empty Enterprise Application. Name the project HiApp and change the Project Folder to any folder on your computer. Click Finish.
2. Expand the HiApp project node and right-click the J2EE Modules node. Choose Add J2EE Module. Select HiWSClient and click OK. Then repeat this step and select HiWS.

Deploy the J2EE Application

1. Right-click the HiApp project node in the Projects window and choose Properties. In the Project Properties dialog box, select Execution. Make sure that HiWSClient.war is filled in the Client Module URI text box. Type /HiServlet in the Relative URL text box. Click OK.
2. Right-click the HiApp project in the Projects window and choose Run Project.

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

      Deploying application in domain failed; Cannot deploy. Application already exists.
      Please select the redeploy option. ; requested operation cannot be completed
   
   

   If you receive this error message, expand the Sun Java System Application Server 8 node within the Server Registry node in the Runtime window. Next, expand the Applications node and then both the Enterprise Applications node and the Web Applications node. If HiApp, HiWS, or HWSClient are listed, you need to undeploy them. Right-click the nodes and choose Undeploy. In the Projects window, run the HiApp project again.

   The J2EE-compliant server is started, the application is deployed, and the result is displayed in the IDE's default web browser.

3. If you added a user interface to the application, as described in the previous section, enter a name and click submit. The client consumes the "Hi" and "!" strings from the web service, inserts the name that you enter, and displays the greeting in the browser. If you did not add a user interface, the browser displays the message "Hi Ludwig!".