Web Services: Hello World Application

Expected duration: 60 minutes

Exercise 1: Build "HelloWorld" Web Service and Client using POJO class with Annotations

1. Build, deploy, and test "HelloWorld" Web service
   
2. Build and run "HelloWorld" Web service client
   

(1.1) Build, deploy, and test "HelloWorld" Web service

0. Start NetBeans IDE if you have not done so yet.
1. Create a new NetBeans project.

• Select File->New Project (Ctrl+Shift+N). 

• Observe that the New Project dialog box appears.
• Under Choose Project pane, select Web under Categories and Web Application under Projects.
  
• Click Next.

• For the Project Name field, type in HelloWebService as project name.
• Click Next.
  

Figure-1.11: New Web Application

• Observe that the Server and Setting pane appears.
• Click Finish.
  

• Observe that HelloWebService project appears and IDE generated index.jsp is displayed in the source editor window of NetBeans IDE.

• Select HelloWebService project node and select New->Java Class.
  

Figure-1.12: Create Hello.java POJO class

• For the Class Name field, fill it with Hello.
• For the Package field, fill it with mypackage. (Figure-1.13 below)
• Click Finish.
  

Figure-1.13: Name the class as Hello.java under mypackage

• Observe that the IDE generated Hello.java is displayed in the source editor.
  

3. Add a business method to the Hello.java.

• Modify the Hello.java as shown in Code-1.14 below.  The change is to add a simple method called sayHello(String name) that will be exposed as a Web service operation in subsequent steps.  The code fragments that need to be added are highlighted in bold and red-colored font.
  

package mypackage; /**  *  * @author sang  */ public class Hello {     // Business method we want to expose as     // Web service operation     public String sayHello(String name) {         return "Hello " + name + "!";     } }

Figure-1.14: Add sayHello() method

4.  Expose all public methods of the Hello.java as Web service operations.

• Add @WebService() annotation to the Hello.java as shown in Code-1.15 below.  This will expose all public methods of the Hello class to be exposed as Web service operations.
  

package mypackage; /**  *  * @author sang  */ @WebService() public class Hello {     // Business method we want to expose as     // Web service operation     public String sayHello(String name) {         return "Hello " + name + "!";     } }

Code-1.15: Add @WebService annotation.

• Right click @WebService() and select Fix Imports from the pop-up menu.
  

• Make sure javax.jws.WebService is chosen.
  
• Click OK.
  

• Observe that the import javax.jws.WebService; is added.
  

---

<NetBeans tip>

• You might want to try code-completion feature of the NetBeans IDE of all annotations by just typing @W as shown in Figure-1.16 below and press CTRL+Space key combination to see all the possible Annotations that starts with @W. 
  
• Select @WebService(javax.ws).
• Press Enter.
  

Figure-1.16: Code-completion of annotation

5. Deploy the application.  Once deployed, the Web service can be accessed by a Web servlce client.  As part of the deployment process, WSDL document of the Web service  is also created and deployed. 

• Right click HelloWebService project node and then select Undeploy and Deploy.
  

Figure-1.17: Deploy the application

6. Test the Web service.

• Expand Web services and right click Hello Web service node and select Test Web Service. (Figure-1.18 below)
  

Figure-1.18: Test Web Service

• Observe HelloService Web Service Tester page is displayed.
  
• Type in your name, Sang Shin in this example.
  
• Click sayHello button.  (Figure-1.19 below)
  

Figure-1.19: HelloService Web Service Tester

• Observe that a new page is displayed with the result of the testing. (Figure-1.20 below) 
  
• Observe that the SOAP message request and response are also displayed.
  

Figure-1.20: Result of the HelloService Web service testing

7.  Access the WSDL document

• Click backward button of the browser to go the previous page.
• Click WSDL File link.  (Figure-1.21 below)
  

Figure-1.21: Access WSDL document

• Observe that the contents of the WSDL document is displayed in the browser.
• Observe the URL of the WSDL document is http://localhost:8080/HelloWebService/HelloService?WSDL.  You will use this URL later on when you create the corresponding Web service client.
  

Figure-1.22: WSDL document

                                                                                                                        return to top of the exercise

(1.2) Build and run Web Service client

In this step, you are going to build HelloWorld Web service client in the form of standalone Java application which accesses the Web service that is deployed in the above step.

1. Create a new NetBeans project.

• Select File->New Project (Ctrl+Shift+N). The New Project dialog box appears.
• Under Choose Project pane, select Java under Categories and Java Application under Projects.
  
• Click Next.

• Under Name and Location pane, for the Project Name field, type in HelloWebServiceClient as project name.
• Click Finish.

2. Create a Web Service client.

• Right click HelloWebServiceClient and select New->File/Folder (or New->Web Service Client if it is in the list already).
• Udder Categories, select Web Services and under File Types, select Web Service Client.
• Select Next. (Figure-1.23 below)
  

Figure-1.23: Create Web Service Client

• Observe WSDL and Client Location pane gets displayed
• Select WSDL URL and specify the location of the WSDL document you observed in Figure-1.22 above, which is http://localhost:8080/HelloWebService/HelloService?WSDL in this case.  (The port number 8080 is the default port number of the Sun Java System App Server.)
  
• For the Package field, type in mypackage.
  
• Click Finish. (Figure-1.24 below)

Figure-1.24: WSDL and Client Location

• You might observe that a Question dialog box is displayed.
  
• Click Yes if you see the diaglog box.  (Figure-1.25 below)
  

Figure-1.25: Click Yes for the question

Note: You can also select Project option (instead of WSDL URL option) as shown below in Figure-1.26, Figure-1.27, Figure-1.28.


Figure-1.26: Create a Web service client using Project


Figure-1.27: Select a Web service


Figure-1.28: Give a package name

3. Write Web service client code leveraging NetBeans code generation wizard.

• Double-click Main.java under HelloWebServiceClient->Source Packages->hellowebserviceclient to open it in the source editor (if it is not in the source editor already).
• Move your cursor under the line of  //TODO code application logic here (linenumber 26) within the main() metod.
• Right click and select Web Service Client Resources->Call Web Service Operation. (Figure-1.29 below)
  

Figure-1.29: Call Web Service Operation

• Observe that the Select Operation to Invoke dialog box appears.  Here you can select any operations you want to invoke as a client.
  
• Expand HelloWebServiceClient node until you see sayHello.
• Select sayHello.  (Figure-1.30 below)
  
• Click OK.
  

Figure-1.30: Select Operation to Invoke

• Observe that IDE generates code.
• Modify the code as shown in Code-1.31 below - you are basically providing the arguments, in this example, Sang Shin.

package hellowebserviceclient; /**  *  * @author sang  */ public class Main {         /** Creates a new instance of Main */     public Main() {     }         /**      * @param args the command line arguments      */     public static void main(String[] args) {         try { // Call Web Service Operation             mypackage.HelloService service = new mypackage.HelloService();             mypackage.Hello port = service.getHelloPort();             // TODO initialize WS operation arguments here             java.lang.String arg0 = "Sang Shin";             // TODO process result here             java.lang.String result = port.sayHello(arg0);             System.out.println("Result = "+result);         } catch (Exception ex) {             // TODO handle custom exceptions here         }                   }     }

Code-1.31: Provide argument value

4. Add JAX-WS 2.1 library.









5. Run the Web service client application

• Right click HelloWebServiceClient and select Run.
• Observe that the result is displayed in the Output window. (Figure-1.32 below)
  

Figure-1.32: Result of running Web Service client application

                                                                                                                        return to top of the exercise


Trouble-shooting: If you experience the following problem as shown in Figure-1.33 below, it is likely due to the fact that you did "Clean" for the project. 
Solution: Right click the project and select Clean and Build and then select Run.

Solution

Summary

In this exercise,  you have built and deployed a simple HelloWorld Web service.  You have learned building a Web service is a matter of adding @WebService() annotation to a POJO class.  You also have built and run the Web service client to access the Web service. 

                                                                                                                        return to the top

Exercise 2: Use WS Monitor to capture the SOAP traffic

2. Modify the Main.java to send SOAP requests to port 4040.  The code fragments that need to be added are highlighted in bold font.

package hellowebserviceclient; import javax.xml.ws.BindingProvider; /**  *  * @author sang  */ public class Main {         /** Creates a new instance of Main */     public Main() {     }         /**      * @param args the command line arguments      */     public static void main(String[] args) {         try { // Call Web Service Operation             mypackage.HelloService service = new mypackage.HelloService();             mypackage.Hello port = service.getHelloPort();                         // Change the destination port to 4040             BindingProvider bp = (BindingProvider) port;             String address = (String)bp.getRequestContext().get(BindingProvider.ENDPOINT_ADDRESS_PROPERTY);             address = address.replaceFirst("8080", "4040");             bp.getRequestContext().put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, address);             //                         // TODO initialize WS operation arguments here             java.lang.String arg0 = "Sang Shin";             // TODO process result here             java.lang.String result = port.sayHello(arg0);             System.out.println("Result = "+result);         } catch (Exception ex) {             // TODO handle custom exceptions here         }         // TODO code application logic here             }      }

3. Observe that the WS Monitor now captures the SOAP traffic.



  Note:  As a default, WS Monitor is configured to use port 8080 as a final destination port number.  If you want to change this default destination port number from 8080 to some another port number (for example,  port 8089) , take the following steps:

• Change the value of the targetport attribute in <WS-MONITOR-DIR>/etc/config.xml.
• Run the WS Monitor with the above file as command line argument after cha
  
• cd <WS-MONITOR-DIR>/bin
• Windows:  wsmonitor.bat ..\etc\config.xml
• Solaris/Linux: wsmonitor.sh ../etc/config.xml
  

Solution

Exercise 3: Perform context-sensitive Javadoc

(3.1)  Configure Javadoc zip file of JAX-WS library

1. Open Library Manager.

• Select Tools from top-level menu and select Libraries. (Figure-3.10 below)
  

Figure-3.10: Open Library Manager

2. Configure jaxws-2_1-api.doc.zip.

• Observe that the Library Manager is displayed.
• Select JAX-WS 2.1 under Libraries on the left and select Javadoc tab.
• Click Add ZIP/Folder button on the right. (Figure-3.11 below)
  

Figure-3.11: Add ZIP/Folder

• Browse down to <NetBeans installation directory>/java2/docs.
• Select jaxws-2_1-api.doc.zip.
• Click Add ZIP/Folder button.  (Figure-3.12 below)
  

Figure-3.12: Select jaxws-2_1-api.doc.zip

• Observe that you will encounter a benign error message dialog box as shown in Figure-3.13 below.
  
• Click OK.
  

Figure-3.13: Benign error dialog box

3. Restart NetBeans.

• Select File from top-level menu and select Exit. (Figure-3.14 below)

Figure-3.14: Exit NetBeans

• Start NetBeans.

                                                                                                                        return to top of the exercise

(3.2)  Perform context sensitive Javadoc

1. Display Javadoc on @WebService() annotation.

• Right click @WebServices() and select Show Javadoc. (Figure-3.21 below)
  

Figure-3.21: Show Javadoc on @WebService() annotation

• Observe that the Javadoc of the @WebService() annotation is displayed in your browser. (Figure-3.22 below)
  

Figure-3.22: Javadoc of the @WebService() annotation

Trouble-shooting: If you still encounter the following condition, restart NetBeans.  If you still encounter the same condition even after the restart of NetBeans, configure Javadoc zip file for the JDK 6 platform as well.












                                                                                                                        return to top of the exercise

Homework Exercise (for people who are taking Sang Shin's "Web Services & SOA Programming online course")