# Step 3: Add a Web Service Control

In this step you will add a web service control to the Investigate Java control. A web service control allows your Java control to communicate with a web service. This web service control is, like the database control in the previous step, a pre-built control provided by WebLogic Workshop. In this case, you will add a control for the Credit Card Report web service, a web service that provides credit card data on loan applicants. You should imagine that the Credit Card Report web service is an independent application that exists externally out on the Internet; but for the purposes of this tutorial, it has been included as a project within the Tutorial: Java Control application.

Because Credit Card Report is a web service, it returns an XML document to its clients. (By definition, web services return XML documents, typically SOAP XML documents.) In this task you will learn how to process these XML documents using XMLBean classes.

The tasks in this step are:

- To generate a WSDL file from a JWS file

- To generate a web service control from a WSDL file

- To add the web service control file to the Investigate Java control

- To add code to invoke the web service

- To add code to handle callbacks from the web service

- To test the Investigate Java control

To Generate a WSDL File from a JWS File

Web services advertise their functionality through WSDL files. WSDL files are like instruction manuals for a web service: they set out the available functionality of a web service and how to access that functionality. In this step you will generate a WSDL file for the Credit Card Report web service. In the next task you will generate a web service control from the WSDL file.

1. On the Application tab, navigate to JavaControlTutorial/CreditCardReport_JCSTutorial/webservice/CreditCardReport.jws.
2. On the Application tab, right-click the CreditCardReport.jws file and select Generate WSDL File.
   A new WSDL file, CreditCardReportContract.wsdl, is generated and placed underneath CreditCardReport.jws.
3. Hold the mouse button down over CreditCardReportContract.wsdl and drag it into the JavaControlTutorial/JavaControlTutorialWeb/investigateJCS folder.

To Generate a Web Service Control from a WSDL file

- On the Application tab, right-click CreditCardReportContract.wsdl and select Generate Service Control.
  A new web service control file, CreditCardReportControl.jcx, is created and placed in the investigateJCS folder.
  Note that the CreditCardReportControl.jcx file is a pre-built Workshop control that allows easy access to the CreditCardReport web service.

To Add a Web Service Control to The Investigate Java Control

In this task you will add the web service control CreditCardReportControl.jcx to the Investigate Java Control.

1. On the Application tab, double-click InvestigateImpl.jcs.
2. Click the Design View tab, if necessary. (Note make sure that InvestigateImpl.jcs is displayed in Design View and not InvestigateTest.jws. It is very easy to confuse a Java control and its test web service.)
3. From the Application Tab, click CreditCardReportControl.jcx and drag and drop it into Design View. A new web service control is added to the Investigate Java control.
   The web service control is added to the Investigate Java control.
4. Press Ctrl+S to save your work.

To Add Code that Invokes the Web Service

In this task you will add code that invokes the Credit Card Report web service. When the Credit Card Report web service is ready to provide data to the Investigate Java control, it will send it through a callback. Note that data provided by the Credit Card Report web service is in the form of an XML document. In the next task you will modify the Investigate Java control so it can process XML documents.

1. Confirm that InvestigateImpl.jcs is displayed in the main work area.
2. Click name of the requestCreditReport method.
3. Edit the source code for the requestCreditReport method as shown below. Replace the crossed-out lines of code with the code shown in red.

           public void requestCreditReport(String taxID)
           {
               m_currentApplicant.taxID = taxID;

               /*
                * Retrieve data from the database and store it in the rec object.
                */
               Record rec = bankruptciesDB.checkForBankruptcies(taxID);
               /*
                * If the database returns substantial data, then store that data
                * in the m_currentApplicant object.
                */
               if(rec != null)
               {
                   m_currentApplicant.firstName = rec.firstname;
                   m_currentApplicant.lastName = rec.lastname;
                   m_currentApplicant.currentlyBankrupt = rec.currentlyBankrupt;

                   /*
                    * Send the credit report to the client via a callback.
                    */
                   callback.onCreditReportDone(m_currentApplicant);

                   /*
                    * Invoke the Credit Card Report web service.
                    * Results from the web service will be provided via a callback.
                    */
                   creditCardReportControl.getCreditCardData(taxID);
               }
               /*
                * If the database does not return substantial data, notify the client
                * that there is a problem.
                */
               else
               {
                   m_currentApplicant.message = "No data could be found on the applicant. Please call (555) 555-5555 for assistance. ";
                   /*
                    * Send an error message to the client via a callback.
                    */
                   callback.onCreditReportDone(m_currentApplicant);
               }
           }

To Add Code to Handle Callbacks from the Web Service

When your Java control receives a callback from the Credit Card Report web service, it needs to know what to do with the data received. In this task you will add code to handle the XML document delivered by the Credit Card Report web service. The code you add does three things: first, extracts the relevant data from the XML document. Second, it stores the extracted data in the member variable m_currentApplicant. Third, it sends the applicant profile back to the client using the callback onCreditReportDone.
The first task, the extraction of data from the XML document, is accomplished with the help of a set of XMLBean classes (CreditCardDataDocument and others), classes that know how to parse the XML documents returned by the web service. These XMLBean classes can be viewed in the Schemas project.

These XMLBean classes were produced by compiling a schema file (XSD file). Schema files are like "meta XML" documents. Schema files are like ordinary XML documents in that they obey ordinary XML syntax; but they are special in that they define the general shape of other XML documents, called "instances" of the schema file. When you compile a schema file in Workshop, XMLBean classes are produced that know how to parse any instances of the schema file. (Schema files can be compiled in a Schema type project.)

In this case, the XML messages returned by the Credit Card Report web service are instances of the schema file CreditCardData.xsd. When CreditCardReport.xsd is compiled, a set of XMLBean classes (CardType, CardType.Name, etc.) is produced that know how to parse any of the XML instance documents returned by the Credit Card Report web service.

1. Confirm that InvestigateImpl.jcs is displayed in the main work area. If necessary, click the Source View tab.
2. Add the following import statements to the top of the InvestigateImpl.jcs file, directly underneath the package declaration.
   Note that these are the XMLBean classes that know how to parse the XML documents returned by the Credit Card Report web service.

       import com.bea.xml.XmlException;
       import org.openuri.bea.samples.workshop.CardType;
       import org.openuri.bea.samples.workshop.CustomerType;
       import org.openuri.bea.samples.workshop.CreditCardDataDocument.CreditCardData;
       import org.openuri.bea.samples.workshop.CreditCardDataDocument;

3. Click the Design View tab.
4. Click the link text for the callback handler onCreditCardDataReady.
5. Edit the callback handler creditCardReportControl_onCreditCardDataReady to look like the following. Add the code appearing in red.

           public void creditCardReportControl_onCreditCardDataReady(java.lang.String cardData)
           {
               try
               {
                   /*
                    * When the XML document containing the credit card report is delivered,
                    * extract the relevant credit card data, and store it in m_currentApplicant.
                    *
                    * Note that the data is extracted with the aid of XMLBean classes, classes
                    * produced from the compilation of the schema file CreditCardData.xsd.
                    */
                   CreditCardDataDocument cardInfo = CreditCardDataDocument.Factory.parse(cardData);
                   CustomerType[] customer = cardInfo.getCreditCardData().getCustomerArray();
                   CardType[] cards = customer[0].getCardArray();
                   for(int i = 0; i < cards.length; i++)
                   {
                       m_currentApplicant.availableCCCredit += cards[i].getAvailableCredit();
                   }

                  /*
                   * Send the complete report back to the client.
                   */
                  callback.onCreditReportDone(m_currentApplicant);
               }
               catch(XmlException xe)
               {
                   /*
                    * If there is a problem with extracting the credit card info,
                    * store an error message in m_currentApplicant.
                    */
                   m_currentApplicant.message =  "There was an error retrieving the credit card information.";

                   /*
                    * Send the the error message back to the client.
                    */
                   callback.onCreditReportDone(m_currentApplicant);
               }
           }

6. Press Ctrl+S to save your work.

To Test the Investigate Java Control

1. On the Application tab, double-click InvestigateTest.jws.
2. On the toolbar, click the Start button, shown here:

   Workshop builds InvestigateTest.jws and launches the Test Browser.

3. In the Workshop Test Browser, in the taxID field, enter the 9 digit number 222222222 and click the requestCreditReport button.

   Note: Use one of the following (9 digit) taxID's to test your Java control throughout the tutorial:

   123456789, 111111111, 222222222, 333333333, 444444444, and 555555555.

4. Click Refresh until callback.onCreditReportDone appears in the Message Log.

5. Under Message Log, click callback.onCreditReportDone.
   Notice that a new piece of information has been added to the applicant profile: <availableCCCredit>2000</availableCCCredit>. This information was provided by the Credit Card Report web service.
6. To see the entire credit card report provided by the web service, under Message Log, click the entry investigate:CreditCardReportControl.onCreditDataReady.
   Notice that the web service returns the credit card data in the form of an XML document. It is this XML document that the XMLBeans parse when they extract the credit card data.
7. Return to WebLogic Workshop, and click the Stop button to close the Workshop Test Browser

Related Topics

Web Service Control

Getting Started with XMLBeans

Click one of the following arrows to navigate through the tutorial: