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:
Add the Investigate Java Control
In this task you will add the functionality provided by the Investigate Java control.
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.
/** * <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); }
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.
public interface Callback extends com.bea.control.ServiceControl { void onCreditReportDone(investigateJCS.Applicant applicant); }
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.
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.
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.
Now you are ready to compile and test your web service.
Note: Use one of the following (9 digit) taxID's to test your web service throughout the tutorial:
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.