Consuming Web Services in NetBeans IDE 4.1(2)

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 create, compile, and deploy 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.

If you are behind a firewall, you need to set a proxy host and port number on the SJS Application Server. See the first part of Troubleshooting for help.

Getting to Know the Sample

1. Unzip the sample attached to the top of this page.

2. In the IDE, choose File > Open Project and browse to the folder that contains the unzipped file. Open the project. It should look as follows:

   

3. Right-click the project node and choose Run Project. The user interface, consisting of a JSP page, should be displayed. Enter some text:

   

   Make sure that you provide a few incorrectly spelled words!

   If the application does not deploy or if the JSP page is not displayed, see the Troubleshooting section at the end of this tutorial.

4. Click Spell Check. The entered text is sent by a servlet to the spell checker web service. The spell checker web service then processes the text. It works out how many words are wrong, identifies the wrong words, and generates a list of suggested alternatives. Once it has completed its work, it returns the information to the servlet, which organizes it and produces a report:

   

Now that you are familiar with the sample, you are ready to find out how to build it from scratch.

Creating the Client

1. Choose File > New Project (Ctrl-Shift-N). Under Categories, choose Web. Under Projects, choose Web Application. Click Next. Name the project SpellCheckService and make sure that you specify the Sun Java System Application Server as your target server. Click Finish.

2. In the Projects window, right-click the SpellCheckService project node and choose New > File/Folder. In the New File wizard choose Web Service > Web Service Client. In the Web Service Client wizard, specify the URL to the web service:

   http://ws.cdyne.com/SpellChecker/check.asmx

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

3. Enter org.netbeans.end2end.check.client as the package name. The package name specifies the package to which the client files will be generated.

4. Click Finish.

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

   

   The Projects window shows that a web service called 'Check' has made the operations 'checkTextBody' and 'suggestWord' available to your application. The 'checkTextBody' operation checks a string for spelling errors and returns data to be processed by the client. You will use this operation throughout this tutorial. The 'suggestWord' operation, for suggesting words to the web service's dictionary, will not be used.

   In the Files window, within the build node, you should see the following:

   

   The Files window shows five files:

   • Check.java. Interface that extends javax.xml.rpc.Service.
   • CheckSoap.java. Interface that extends java.rmi.Remote.
   • CheckSoap_Impl.java. Implementation class for CheckSoap.java. Two operations are implemented, checkTextBody(java.lang.String bodyText, java.lang.String licenseKey) and suggestWord(java.lang.String word).
   • DocumentSummary.java. Complex DocumentSummary object for accessing the returned text, the Words object containing the misspelled words, the number of misspelled words, and the version of the web service.
   • Words.java. Complex Words object for accessing an array of data for each misspelled word. The data consists of the misspelled word itself, an integer containing the number of suggested alternatives, and an array containing the suggested alternatives.

Testing the Web Service

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

2. Type values for the arguments required by the operation:

   • bodyText. The text that you want to have checked. Remember to include a few incorrectly spelled words.
   • licenseKey. The license key required by the web service. Type 0.

3. Click Submit. When you do this, the web service is contacted and the operation is invoked. Wait for the text to be checked and returned (it should not take long). You should then see something similar to the following:

   

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 processed your text. The built-in client has contacted the web service, passed it your values, and retrieved a result. If a result is not returned and you are behind a firewall, see the second part of Troubleshooting for help.

Analyzing the Web Service

When the IDE generates the web service client's files, using the information you specify in the Web Service Client wizard, it generates a Java object for each complex data type defined in the WSDL file. The spell checker WSDL file contains two complex data types, DocumentSummary and Words:

<s:complexType name="DocumentSummary">
 <s:sequence>
   <s:element minOccurs="0" maxOccurs="unbounded" name="MisspelledWord" type="s0:Words" />
   <s:element minOccurs="0" maxOccurs="1" name="ver" type="s:string" />
   <s:element minOccurs="0" maxOccurs="1" name="body" type="s:string" />
   <s:element minOccurs="1" maxOccurs="1" name="MisspelledWordCount" type="s:int" />
 </s:sequence>
</s:complexType>

<s:complexType name="Words">
 <s:sequence>
   <s:element minOccurs="0" maxOccurs="unbounded" name="Suggestions" type="s:string" />
   <s:element minOccurs="0" maxOccurs="1" name="word" type="s:string" />
   <s:element minOccurs="1" maxOccurs="1" name="SuggestionCount" type="s:int" />
 </s:sequence>
</s:complexType>

In order to successfuly implement the client, you need to work with these complex data types and the data each provides. The IDE provides several tools to enable you to graphically examine each complex data type, represented by its related Java object, and unpack its data. Below you are shown how to do this, using the WSDL for CDYNE's spell check web service as an example.

Examining the DocumentSummary Object

1. Open the Test Web Service Operation dialog box for the 'checkTextBody' operation, as described in the previous section. Fill in some text, type 0 for the licenseKey argument, and click Submit.

   The lower part of the Test Web Service Operation dialog box displays the following:

   

   This is the outermost layer of the web service. Before we can do anything else, we need to deal with this layer. Note that the highest node is called DocumentSummary.

2. In the Files window (Ctrl-2), expand the build folder until you get here:

   

   Now double-click the DocumentSummary.java node so that it opens in the Source Editor (and look at the nodes above as well). Doing this shows you what methods are made available by DocumentSummary.java. Once you've opened it in the Source Editor (accompanied by viewing its expanded nodes in the Files window), you can see that the corrected text returned by the SpellChecker service should be assigned to the DocumentSummary object. Once this is done, you can use its methods to interact with the corrected text. In the next section, you use the DocumentSummary object as follows (the bold code below highlights the methods provided by the DocumentSummary object):

       DocumentSummary doc = getCheckSoap().checkTextBody(text,"0");
       String allcontent = doc.getBody();
       int no_of_mistakes = doc.getMisspelledWordCount();
       Words[] allwrongwords = doc.getMisspelledWord();

   While the Words object needs to be processed before you can do anything with it, the allcontent string and the no_of_mistakes integer can be used right away. For example, at the top of the report you might want to display the text that you sent to the web service. This text is provided by allcontent (bold in the code below):

       out.println("<b>Your text:</b> \"" + allcontent + "\"<p>");

   Displayed in the browser, the result of the above line of code is as follows:

   

   There's another method, called getVer, but you do not need to use that in this tutorial. On the other hand, if you were going to make your client implementation generally available, and really use it in a business setting, it might be useful to run through a condition to check if the web service's version is the one that you expect it to be -- and produce some kind of error or message when the versions differ -- because subsequent versions of the web service might clash with your client implementation.

Examining the Words Object

1. In the Test Web Service Operation dialog box, expand the DocumentSummary node. Now expand the Words[] node and one of its subnodes. The lower part of the Test Web Service Operation dialog box now displays the following:

   

   This is the Words object. It contains an array called Words for each misspelled word. In the illustration above, you can see the Words array for the misspelled word "spelll".

2. In the Files window (Ctrl-2), expand the build folder until you get here:

   

   Now double-click the Words.java node so that it opens in the Source Editor (and look at the nodes above as well). Doing this shows you what methods are made available by Words.java. Once you've opened it in the Source Editor (accompanied by viewing its expanded nodes in the Files window), you can see that each misspelled word should be assigned to the Words array, which you access using the Words object. Once this is done, you can use the Words object's methods to interact with each misspelled word individually. In the next section, you use the Words object as follows (the bold code below highlights the methods provided by the Words object):

     for (int i = 0; i < allwrongwords.length; i++) {
   
       String onewrongword = allwrongwords[i].getWord();
       int onewordsuggestioncount = allwrongwords[i].getSuggestionCount();
       String[] allsuggestions = allwrongwords[i].getSuggestions();
   
       out.println("<hr><p><b>Wrong word:</b><font color='red'> " + onewrongword + "</font>");
       out.println("<p><b>" + onewordsuggestioncount + " suggestions:</b><br>");
   
       for (int k = 0; k < allsuggestions.length; k++) {
         String onesuggestion = allsuggestions[k];
         out.println(onesuggestion);
       }
   
     }

   Displayed in the browser, the result of the above lines of code is as follows:

   

   To round things off, you can provide a summary at the end:

     out.println("<font color='red'><b>Summary:</b> " + no_of_mistakes + " mistakes (");
     for (int i = 0; i < allwrongwords.length; i++) {
         String onewrongword = allwrongwords[i].getWord();
         out.println(onewrongword);
     }
     out.println(").");
     out.println("</font>");

   Displayed in the browser, the result of the above lines of code is as follows:

   

   Of course, many variations are possible. Once you can access the methods you need, you can loop through the returned data quite easily and do whatever you like with it.

Developing the Client

Deploying the Client

The IDE uses an Ant build script to build and run your application. The IDE generates the build script based on the options you entered when creating the project. You can finetune these options in the project's Project Properties dialog box (right-click the project node in the Projects window and choose Properties).

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

   After a while, the application should deploy and display the JSP page that you coded in the previous section. Enter some text, making sure that some of it is incorrectly spelled:

   

2. Use the application as described in Getting to Know the Sample. For troubleshooting, see Troubleshooting.