# Step 2: Add Support for Asynchronous Communication

In this step you will construct a web service entry point for the Investigate Java control (the Investigate Java control is the subject of Tutorial: Java Controls). Making a web service entry point for the Investigate Java control solves one of the problems inherent in communication across the web: the problem of network latency. Network latency refers to the time delays that often occur when transmitting data across a network.

This can be a particular problem on the internet, which has highly unpredictable performance characteristics and uncertain reliability. There may be additional latency if it takes a long time for a web service to process a request (for example, if a person "behind" the web service must review the applicant's credit before a response can be returned).

So far, the design of the Investigate web service forces the client calling the requestCreditReport method to halt its own processes and wait for the response from the web service. This is called a synchronous relationship, in which the client software invokes a method of the web service and is blocked from continuing its own processes until that method returns a value.

You will solve the latency problem by enabling your web service to communicate with its clients asynchronously. In asynchronous communication, the client communicates with the web service in such a way that it is not forced to halt its processes while the web service produces a response. In particular, you will add a method to the web service that immediately returns a simple acknowledgement to the client, thereby allowing the client to continue its own processes. You will also add a callback that returns the full results to the client at a later time. Finally, you will implement support for conversations that enable your web service to remember which client to send the full response to via the callback.

The tasks in this step are:

- To add the Investigate Java control
- To edit the requestCreditReport method
- To add a callback
- To edit the callback handler
- To add a buffer and conversation support
- To test the Investigate web service

Add the Investigate Java Control

In this task you will add the functionality provided by the Investigate Java control.

1. Confirm that Investigate.jws is displayed in the main work area.
2. Click the Design View tab.
3. Click View->Windows->Data Palette.
4. On the Data Palette, in the section labeled Controls, select Add-->Investigate.
5. In the Insert Control - Insert Investigate dialog, enter investigateControl and click Create.
   The Investigate Java control is added to your web service.

To Edit the requestCreditReport Method

In this task you will edit your web service's requestCreditReport method so that (1) it returns an acknowledgement to the invoking client without returning any information about the applicant and (2) invokes the requestCreditReport method on the Investigate Java control. The Investigate Java control will respond by sending a callback containing the credit report to your web service.

1. Confirm that Investigate.jws is displayed in the main work area.
2. If necessary, click the Design View tab.
3. Click the link text for the requestCreditReport method.
4. Edit the requestCreditReport method code so that it appears as follows. Code to edit appears in red.

   >         /**
   >          * <p>Use the following taxID's to test the Investigate web service.</p>
   >          *
   >          * <blockquote>111111111<br>
   >          * 222222222<br>
   >          * 333333333<br>
   >          * 444444444<br>
   >          * 555555555<br>
   >          * 123456789</blockquote>
   >          *
   >          * @common:operation
   >          */
   >         public void requestCreditReport(String taxID)
   >         {
   >             /*
   >              * Invoke the requestCreditReport method on the
   >              * Investigate Java control passing in the taxID
   >              * as a parameter.
   >              */
   >             investigateControl.requestCreditReport(taxID);
   >         }

To Add a Callback

Once the web service gets the credit report from the Investigate Java control, you want to be able to pass the credit report along to the client. The callback you add below will send the credit report to your web service's clients.

1. Confirm that Investigate.jws is displayed in the main work area.
2. Click the Design View tab.
3. Right-click the picture of the Investigate web service and select Add Callback.
4. In the input field that appears, replace newCallback1 with onCreditReportDone and press Enter.
5. Click the link text for the onCreditReportDone callback.
6. Edit the code for onCreditReportDone so that it appears as follows. Add the code appearing in red.

          public interface Callback extends com.bea.control.ServiceControl
          {
               void onCreditReportDone(investigateJCS.Applicant applicant);
          }

To Edit the Callback Handler

When the Investigate Java control sends a callback message to your web service, your web service needs to know how to handle the message. In this task you will edit the handler for callbacks sent from the Investigate Java control.

1. Confirm that Investigate.jws is displayed in the main work area.
2. Click the Design View tab.
3. Click the link text for the investigate Java Control callback handler onCreditReportDone.
4. Edit the callback handler investigateControl_onCreditReportDone to look like the following. Code to edit appears in red.

        public void investigateControl_onCreditReportDone(investigateJCS.Applicant m_currentApplicant)
        {
            /*
             * When the callback message from the Investigate control arrives,
             * then pass the message along to the Investigate web service callback
             * onCreditReportDone.
             */
            callback.onCreditReportDone(m_currentApplicant);
        }

Note: Callback handlers always have a name composed of the name of the control, plus the underscore character, plus the name of the callback method being handled. So "investigateControl_onCreditReportDone" means: the handler for investigateControl's callback method onCreditReportDone.

The request/response cycle now works like this: (1) a client invokes your web service's requestCreditReport method; (2) your web service then invokes the Investigate Java control's method requestCreditReport; (3) when the Investigate Java control has assembled the credit report, it send a callback to your web service; (4) your web service's callback handler investigateControl_onCreditReportDone invokes your web service's callback onCreditReportDone; (5) finally your web service's callback onCreditReportDone sends the complete credit report to the original client.

To Add Buffer and Conversation Support to the Web Service

Now you are ready to add a buffer and conversation support to your web service.

The buffer, which you will add to the requestCreditReport method, serves two purposes. First, it saves client requests in a message queue which prevents requests from being lost during server outages. Second, the buffer immediately returns an acknowledgement to the client, which allows the client to continue its own processes without waiting for the full response from the web service.

Adding conversation support to your web service lets the client know for sure that the result your service sends back through the onCreditReportDone callback is associated with the request the client originally made. If the same client makes two independent calls with the same taxpayer ID (say, for separate loan applications from the same applicant), how will it know which finished report corresponds to which request? With all the interaction back and forth between the client and your web service, your service needs a way to keep things straight.

Also, if the server goes down (taking the m_applicant member variable with it), the data that the client sent as a parameter is lost. The service not only loses track of the client's request, but of who the client was in the first place.

You can solve these problems by associating each exchange of information (request, response, and any interaction needed in between) with a unique identifier—an identifier known to both the client and the service.

In web services built with WebLogic Workshop, you do this by adding support for a conversation. For services participating in a conversation, WebLogic Server stores state-related data, such as the member variable you added, on the computer's hard drive and generates a unique identifier to keep track of the data and of which responses belong with which requests. This infrastructure remains in place as long as the conversation is ongoing. When the conversation is finished, the resources allocated to the infrastructure are released.

When you add methods to a web service that supports conversations, you can indicate whether each method starts, continues or finishes a conversation. Adding support for a conversation is very easy. With methods that represent both the first step of the transaction (requestCreditReport) and the last step (onCreditReportdone), you want to indicate when the conversation starts and when it finishes. To add a buffer and conversation support to your web service follow the steps below.

1. Confirm that Investigate.jws is displayed in the main work area.
2. Click the Design View tab.
3. Click the arrow icon associated with the requestCreditReport method.

4. On the Property Editor tab, in the section labeled conversation, set the phase property to start, as shown in the following illustration.

5. In the message-buffer section, set the enable property to true, as shown in the following illustration.

6. In Design View, click the arrow icon next to your web service's onCreditReportDone callback.
7. On the Property Editor tab, in the section labeled conversation, set the phase property to finish, as shown in the following illustration.

8. In the message-buffer section, set the enable property to true, as shown in the following illustration.

9. Press Ctrl+S to save your work.
   After modifying your web service through the Property Editor, the Design View picture of your web service should look like the following image. Notice the new conversation and buffer icons associated with the requestCreditReport method and the onCreditReportDone callback.

To Test the Investigate Web Service

Now you are ready to compile and test your web service.

1. Confirm that Investigate.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 the 9 digit number 222222222.

   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 the requestCreditReport button.
   The Test Browser refreshes to display a summary of the request parameters sent by the client and your service's response, as shown here:

   Note: The Service Request section displays what the client (in this case, the Workshop Test Browser) sent to the Investigate web service to invoke the requestCreditReport method. Note the conversation identification number, this is a unique number generated for each time a converstation starting method is invoked. The web service uses this id to associate the initial client request and the callback response it will later send back to the client.
   The Service Response section shows what the Investigate web service has sent back (so far) to the client. In this case it sends back an XML message, <Void xmlns:xsi..., serving as an acknowledgement to the client that its request has been received.
5. Click Refresh until the Message Log shows an entry for callback.onCreditReportDone.
6. Click callback.onCreditReportDone to view the contents of the callback sent from the Investigate web service to the client, as shown here:

   The Client Callback section displays the SOAP message that the client receives, including data about the credit applicant. The two other entries in the Message Log show some of the activity of the Investigate Java control as it assembles the report on the credit applicant.

7. Return to WebLogic Workshop, and click the Stop button (shown below) to close the Workshop Test Browser.

Related Topics

Overview: Conversations

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