NetBeans IDE 5.0 Quick Start Guide for Web Service Clients

Feedback

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

This quick start shows you how to use NetBeans IDE 5.0 to consume live web services quickly and easily. It demonstrates the web service facilities available in NetBeans IDE 5.0, but does not delve into too much detail. Detail is provided in the NetBeans IDE 5.0 Tutorial for Web Service Clients.

In this quick start, you can implement a Java project for consuming a web service that unjumbles anagrams.

The scenario is intentionally simple, although you can, of course, extend it. The NetBeans IDE 5.0 Tutorial for Web Service Clients provides a more useful example, which is also more complex and robust.

This tutorial covers the following topics:

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

Note: An application using web services is as strong as its weakest web service. Should a web service be taken out of circulation, or should it not be functioning for any reason whatsoever, the entire application on which it is based falls apart. The same is true for this quick start and the web services on which it is based. There is no guarantee that the services consumed in this tutorial will always be available. However, even if they aren't, the steps below should provide enough general information for the consumption of a service other than the demonstrated services.

Setting Up Your Environment

Before you start writing code, you have to make sure you have all of the necessary software.

Installing the Software

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


Consuming a Web Service in a Java Project

Consuming a web service involves four steps—using the Web Service Client wizard to create a basic web service client from the web service's WSDL file, testing the web service using the IDE's built-in client, developing the client with your own code, and, finally, deploying the result.

Creating the Client

  1. Choose File > New Project (Ctrl-Shift-N). Under Categories, choose Samples and then select General. Under Projects, choose Anagram Game. Click Next and then click Finish.

    The AnagramGame sample opens in the IDE.

  2. Right-click the AnagramGame project node and choose New > Web Service Client. The Web Service Client wizard appears. This wizard is used for retrieving the WSDL file on which your client will be based and for generating the files and code snippets that enable the client to connect to the web service.

  3. In the Web Service Client wizard you specify the WSDL file that you want to consume. In this case, we'll consume a service that unjumbles anagrams. In the WSDL URL field, enter the following URL:

    http://services.aonaware.com/CountCheatService/CountCheatService.asmx

    Click Retrieve WSDL to download it. If you are behind a firewall, you might need to set a proxy—otherwise the WSDL file cannot be downloaded. If so, click Proxy Settings and set your proxy host and port number.

  4. Enter com.toy.anagrams.cheat as the package name. The package name specifies the package to which the client files will be generated.

  5. Click Finish.

    In the Projects window, within the Web Service References node, you should see the following:

    Projects window

    The Projects window shows that a web service called 'CountCheatService' has made the operations 'letterSolutions' and 'letterSolutionsMin' available to your application. In the Files window, you can see the files generated by the Web Service Client wizard in the project's build folder.

Testing the Web Service

  1. In the Projects window, within the Web Service References node, double-click the 'letterSolutionsMin' operation. The Test Web Service Operation dialog box appears.

  2. Type 'batsartcoin' for the anagram parameter and '11' for the 'minLetters' parameter.

  3. Click on the Submit button. When you do this, the web service is contacted and the operation is invoked.

  4. Wait for the quotation to be retrieved (it should not take long), click on the Value at the bottom of the dialog box, and you should then see something similar to the following:

    Projects window

Note: If you see something similar to the results displayed in the above illustration, your test has succeeded. The web service is up and running and has returned a quotation. If a quotation is not returned and you are behind a firewall, see the second part of Troubleshooting for help.

Developing the Client

  1. In the Projects window, expand Source Packages and then expand com.toy.anagrams.ui. Double-click Anagrams.java so that it opens in the Source Editor.

  2. Double-click the Guess button and change the text to Cheat.

  3. Right-click the Cheat button and choose Events > Action > actionPerformed[guessedWordActionPerformed].

    The guessedWordActionPerformed source is displayed in the Source Editor.

  4. Add some empty lines at the start of the guessedWordActionPerformed method, right-click, and choose Web service Client Resources > Call Web Service Operation.

  5. In the Select Operation to Invoke dialog box, choose letterSolutionsMin and click OK.

    At the top of the method you see a snippet of code that invokes the web service. Add some code to pass the anagram from the game to the web service and then rearrange the generated code in the method, so that the whole method looks as follows (the code in red below is new to this method):

     private void guessedWordActionPerformed(java.awt.event.ActionEvent evt) {                                            
            
      String anagram = scrambledWord.getText();
      int no_of_letters = anagram.length();
            
      try {
          com.toy.anagrams.cheat.CountCheatService countCheatService = new com.toy.anagrams.cheat.CountCheatService_Impl();
          com.toy.anagrams.cheat.CountCheatServiceSoap countCheatServiceSoap = countCheatService.getCountCheatServiceSoap();
          String[] s = countCheatServiceSoap.letterSolutionsMin(anagram,no_of_letters).getString();
                
          if (s.length > 0) {
    	 for (int i = 0; i < s.length; i++) {
                  guessedWord.setText(s[i]);
    	 }
             if (WordLibrary.isCorrect(wordIdx, guessedWord.getText())){
                feedbackLabel.setText("Correct! Try a new word!");
                getRootPane().setDefaultButton(nextTrial);
             } else {
                feedbackLabel.setText("Incorrect! Try again!");
                guessedWord.setText("");
             }
          } else {
             feedbackLabel.setText("Sorry... word not recognized!");
          }
                
      } catch(javax.xml.rpc.ServiceException ex) {
           // TODO handle ServiceException
      } catch(java.rmi.RemoteException ex) {
           // TODO handle remote exception
      }      
      guessedWord.requestFocusInWindow();
     }

Deploying the Client

  1. Right-click the project node and choose Run Project.

  2. The project runs. You should see the Anagram Game with a Cheat button instead of a Guess button.

  3. Click Cheat. The scrambled word is sent to the web service, unscrambled, returned, displayed in the text box, and checked by the Anagram Game:

    Projects window

Note: If you are behind a firewall and have not set your proxy host and port number for the project, nothing will be displayed in the Anagram Game instead of an unjumbled anagram from the web service. See Troubleshooting for help.

That's it. You're done. Without very much coding, you consumed an anagram unjumbling web service.


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 a Java Application. If you run a Java application in the IDE without setting the proxy host and port number, an unjumbled anagram will not be returned.

    To fix this problem, do the following:

    1. Right-click the project and choose Properties.

    2. In the Project Properties dialog box, click Run and set the proxy host and port in the VM Options dialog box, in this format:
      -Dhttp.proxyHost=my.host -Dhttp.proxyPort=my.port.number

  • 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.