Step 2: Add Support for Asynchronous Communication
In this step, you will solve a problem 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 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 it receives the return value from the web service. As you might imagine, this won't work well when it is difficult to predict the time it will take for the client to receive a response.
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 a Class and Member Variable to the Web Service
The code you add below has two parts: a class, called Applicant, and a member variable, called m_currentApplicant. This variable is an instance of the Applicant class, which serves as a data structure to record the information about credit applicants. Its fields hold information about an applicant's name, currently available credit, and so on. While the member variable m_currentApplicant stores data about a particular applicant, the web service builds a profile about that particular applicant.
Click the Source View tab. From this tab you can view the web service's Java code.
Place the following code within public class Investigate:
public static class Applicant implements java.io.Serializable { public String taxID; public String firstName; public String lastName; public boolean currentlyBankrupt; public int availableCCCredit; public int creditScore; public String approvalLevel; public Applicant(String taxID) { this.taxID = taxID; } public Applicant() {} } Applicant m_currentApplicant = new Applicant();
To Add a requestCreditReportAsynch Method to the Web Service
Next you will add a method to be invoked by client software applications that receives a report on an applicant's credit worthiness. The method itself simply returns an acknowledgement to the invoking client without returning any substantial information on the applicant. The finished report on the applicant's credit worthiness is returned in the onCreditReportDone callback, which you will add later.
Click the Design View tab.
From Add Operation drop-down list, select Add Method.
In the input box that appears, type the method name requestCreditReportAsynch and press Enter.
Click the method name, as shown here:
The method code appears in Source View.
Edit the requestCreditReportAsynch method code so that it appears as follows:
/** * @jws:operation */ public void requestCreditReportAsynch(String taxID) { m_currentApplicant.taxID = taxID; }
To Add an onCreditReportDone Callback to the Web Service
Once the web service is finished building a credit profile of a credit applicant, you want to add a callback to send a credit report back to a client application. The callback you add below will return the finished report on an applicant's credit worthiness.
Click the Design View tab to return to Design View.
From the Add Operation drop-down list, select Add Callback.
In the input field that appears, type the callback name onCreditReportDone and press Enter.
Double-click the arrow associated with the onCreditReportDone callback. The Edit Maps and Interface dialog box appears.
In the Java pane, edit the text so that it appears as follows:
public void onCreditReportDone(Applicant currentApplicant, String responseMessage)
Click OK. The Edit Maps and Interface dialog closes.
To Add Code that Sends Data Back to the Client
Next, you can edit the requestCreditReportAsynch method so that it initiates the onCreditReportDone callback .
If you are not in Source View, click the Source View tab.
Modify the requestCreditReportAsynch method to look like the following:
/** * @jws:operation */ public void requestCreditReportAsynch(String taxID) { m_currentApplicant.taxID = taxID; callback.onCreditReportDone(m_currentApplicant, null); }
To Add a 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 requestCreditReportAsynch method, serves two purposes. First, it saves client requests in a message queue which prevents requests from being lost during server outages. Second, it immediately returns an acknowledgement to the requesting client, which allows the client to continue processing 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 returned result 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_applicantID 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 (requestCreditReportAsync) 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.
Click the Design View tab to return to Design View.
Edit the Properties Pane associated with the requestCreditReportAsynch method. To edit the Properties Pane for this method click the arrow next to the method name requestCreditReportAsynch. Note: do not click the method name requestCreditReportAsynch, instead click its associated arrow, as shown here:
In the Properties pane, from the phase drop-down list, select start, as shown here:
In the message-buffer section, from the enable drop-down list, select true, as shown here:
Click the arrow next to the onCreditReportDone callback.
In the Properties pane, from the phase drop-down list, select finish, as shown here:
In the message-buffer
section, from the enable drop-down
list, select true, as shown here:
Press Ctrl+S to save the service.
Now you are ready to compile and test the service.
Compile and test the web service by clicking the Start button, shown here:
Your web service compiles and a browser window is launched that displays the Test page.
Type a number value in the taxID field, as shown below.
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.
Click requestCreditReportAsynch. The Test page refreshes to display a summary of the request parameters sent by the client and your service's response, as shown here:
Note: Under Service Request, the summary displays what the client sent to the web service to invoke the requestCreditReportAsynch method. Notice that is displays the taxID which you sent to the web service as well as the conversation identification number, which the service uses to associate the initial client request and the callback response it will later send back to the client.
Under Service Response, the summary displays what the web service has sent back (so far) to the client. In this case it sends back an XML file serving as an acknowledgement to the client that its request has been received.
Refresh the browser. Notice that the Message Log has the new entry callback.onCreditReportDone.
Click callback.onCreditReportDone to view the contents of the callback sent from the web service to the client, as shown here:
The contents display the SOAP message that the client receives, including data about the current applicant. Of course, since our web service has no way of learning anything about a credit applicant, the information sent back to the client consists of the taxID originally entered, along with default values for the other fields.
In the next step of the tutorial you will add a database control to your web service, which will enable your web service to acquire substantive data about a credit applicant.