Step 3: Add Support for Synchronous Communication

The Investigate web service sends callbacks to its clients. But not all clients can hear callbacks, so not all clients can use the Investigate web service as an access point to the Investigate Java control. In this step you will build a synchronous web service interface that allows non-callbackable clients to access the Investigate Java control.

The tasks in this step are:

To Create a Web Service

  1. On the Application tab, right-click the investigateJWS folder and select New-->Web Service.
  2. In the New File dialog, in the File name field, enter InvestigateSync.jws, and click Create.

To Add the Investigate Java Control

  1. On the Data Palette, in the section labeled Controls, select Add-->Application Controls-->Investigate.
  2. In the Insert Control - Insert Investigate dialog, enter investigateControl and click Create.
    The Investigate Java control is added to your web service.

To Add Two Member Variables

In this step you will add two member variables to the InvestigateSync web service: one to store the credit report returned by the Investigate Java control, the other to record the status of the investigation process.

  1. Click the Source View tab to view the source code for InvestigateSync.jws
  2. Add the following code to the body of InvestigateSync.jws. Code to add is shown in red.
    /*
     * m_applicant stores the credit report returned by the Investigate Java control
     * for retrieval at a latter time by the client.
     */
    public investigateJCS.Applicant m_applicant = new investigateJCS.Applicant();
    
    /*
     * m_isReportReady is set to true when the credit report from the Investigate Java control
     * has been received, signaling the client to retrieve the report.
     */
    public boolean m_isReportReady = false; 

To Add Polling Logic

In this task you will add the methods through which the client will request and collect the credit report from the InvestigateSync web service. These methods are designed to work in the following way: (1) the client invokes the web service's requestCreditReport method. (2) The web service pass the request onto the Investigate Java control and waits for a callback containing the credit report. (3) When the callback from the Investigate Java control arrives the Investigate web service stores the report in the member variable m_applicant and sets m_isReportReady to true. (4) If the client has been checking the value of m_isReportReady (through the isReportReady method), it now knows that it can collect the credit report through the getCreditReport method.

These methods are collectively referred to as "polling logic" because the client polls the methods, asking for the status of the credit report.

  1. If InvestigateSync.jws is not displayed in Source View, click the Source View tab.
  2. Add the following methods to the body of InvestigateSync.jws. Code to add is shown in red.
  3.     /**
         * Calling this method requests a credit report from the Investigate Java control.
         * 
         * @common:operation
         * @common:message-buffer enable="true"
         * @jws:conversation phase="start"
         */
        public void requestCreditReport(String taxID)
        {
            investigateControl.requestCreditReport(taxID);
        }
    
        /**
         * After making a request for credit report, clients check this method periodically
         * to see if the report is ready.  When this method returns true, clients should invoke
         * the getCreditReport method to retrieve the credit report.
         * 
         * @common:operation
         * @jws:conversation phase="continue"
         */
        public boolean isReportReady()
        {
           return m_isReportReady;
        }
    
        /**
         * Clients collect the completed credit report by invoking this method.
         *
         * @common:operation
         * @jws:conversation phase="continue"
         */
        public investigateJCS.Applicant getCreditReport()
        {
            /*
             * If m_isReportReady is true (i.e., if the callback handler investigateControl_onCreditReportDone
             * has been invoked) return the results to the client.
             * If m_isReportReady is false, tell the client to check back later for the results.
             */
            if(m_isReportReady)
            {
                return m_applicant;
            }
            else
            {
                m_applicant.message = "The report is not yet ready.  Please check back later.";
                return m_applicant;   
            }
        }
        
        /**
         * This method allows the client to cancel the request for a credit report.
         * 
         * @common:operation
         * @jws:conversation phase="finish"
         * @jws:message-buffer enable="true"
         */
        public void cancelInvestigation()
        {
            investigateControl.cancelInvestigation();
        }  
    
        /*
         * When the callback handler is invoked by the Investigate Java control,
         * store the credit report in the member variable m_applicant
         * and set m_isReportReady to true.
         */ 
        public void investigateControl_onCreditReportDone(investigateJCS.Applicant applicantReport)
        {
            m_applicant = applicantReport;
            
            m_isReportReady = true;
        }
  4. Press Ctrl+S to save your work.
  5. Click the Design View tab. You web service should look like the following illustration.

To Add Code to End the Conversation

There is one problem yet to be solved: how will the web service's conversation ever end, since the client will typically never invoke a method marked with the annotation @jws:conversation phase="finish"? You will solve this problem by adding an API call to the getCreditReport method.

  1. If InvestigateSync.jws is not displayed in Source View, click the Source View tab.
  2. Add the following code to the body of InvestigateSync.jws
        /**
         * @common:context 
         */ 
        com.bea.control.JwsContext context;
  3. Edit the getCreditReport method to look like the following. Code to add appears in red.
        public investigateJCS.Applicant getCreditReport()
        {
            /*
             * If m_isReportReady is true (i.e., if the callback handler investigateControl_onCreditReportDone
             * has been invoked) return the results to the client.
             * If m_isReportReady is false, tell the client to check back later for the results.
             */
            if(m_isReportReady)
            {
                /* 
                 * Calling context.finishConversation ends the current conversation.
                 *
                 * Although the call to context.finishCoversation() appears before the return
                 * statement, it is executed after the return statement.
                 */
                context.finishConversation();
                return m_applicant;
            }
            else
            {
                m_applicant.message = "The report is not yet ready.  Please check back later.";
                return m_applicant;   
            }
        }
  4. Press Ctrl+S to save your work.

To Test InvestigateSync.jws

The Workshop Test Browser is an appropriate client for testing InvestigateSync.jws because it is a client that cannot hear callbacks from web services.

  1. Confirm that InvestigateSync.jws is displayed in the main work area.
  2. Click the Start button, shown below.


    Your web service compiles and Workshop Test Browser launches.
  3. In the taxID field, enter 222222222 and click the requestCreditReport button.

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

    123456789, 111111111, 222222222, 333333333, 444444444, and 555555555.
  4. Click Continue this Conversation.
  5. Click the isReportReady button.
    If the isReportReady method returns false, then go back to step 4 above.
    If the isReportReady method returns true, then continue to step 6 below.
  6. Click Continue the Conversation.
  7. Click the getCreditReport button.
    The complete credit report appears in the Service Response section.
  8. Return to WebLogic Workshop, and click the Stop button (shown below) to close the Workshop Test Browser.

  9. Press Ctrl+F4 to close the InvestigateSync.jws web service.

Related Topics

Using Polling as an Alternative to Callbacks

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