A Short Tutorial

In this section, you walk through the Workshop VDE performing a simple task of creating an asynchronous Web service that checks an applicant 's credit history (used throughout discussions in this chapter) by using a Database control and an EJB control. The completed source files for this task are shown in Listing 32.6.

Listing 32.6 Source Code for the creditCheck Web Service

  Investigate.jws  package creditCheck; import Weblogic.jws.control.JwsContext; public class Investigate { /** * @jws:control */ private ValidateCreditControl validateCreditEJB; /** * @jws:control */ private BankruptciesDatabaseControl bankruptciesDB; public Callback callback; public interface Callback { /** * @jws:conversation phase="finish" * @jws:message-buffer enable="true" */ public void onCreditReportDone(Applicant applicant, String responseMsg); } /** @jws:context */ JwsContext context; 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(); /** * @jws:operation * @jws:conversation phase="start" * @jws:message-buffer enable="true" * @jws:parameter-xml xml-map:: * <requestCreditReportAsync xmlns="http://www.openuri.org/"> * <taxID>{taxID}</taxID> * <name>*</ name > * <address>*</address> * </requestCreditReportAsync> * * :: */ public void requestCreditReportAsync(String taxID) throws java.rmi.RemoteException, java.sql.SQLException { m_currentApplicant.taxID = taxID; String summary = null; Applicant dbApplicant = bankruptciesDB.checkForBankruptcies(taxID); if (dbApplicant != null) { m_currentApplicant = dbApplicant; if (m_currentApplicant.currentlyBankrupt == true) summary = "Currently Bankrupt."; else summary = "Not currently bankrupt."; } else { m_currentApplicant.approvalLevel = validateCreditEJB.validate(2000); summary = "No bankruptcy information found."; } callback.onCreditReportDone(m_currentApplicant, summary); } } 

Listing 32.7 shows the source code for the creditCheck Web service's controls.

Listing 32.7 Source Code for the Web Service's Controls

[View full width]

  BankruptciesDatabaseControl.ctrl  package creditCheck; import weblogic.jws.*; import weblogic.jws.control.*; import java.sql.SQLException; /** * Defines a new database control. * * The @jws:connection tag indicates which WebLogic datasource will be used by * this database control. Please change this to suit your needs. You can see a * list of available data sources by going to the WebLogic console in a browser * (typically http://localhost:7001/console) and clicking Services, JDBC, * Data Sources. * * @jws:connection data-source-jndi-name="cgSampleDataSource" */ public interface BankruptciesDatabaseControl extends DatabaseControl { // Sample database function. Uncomment to use // static public class Customer // { // public int id; // public String name; // } // // /** // * @jws:sql statement="SELECT ID, NAME FROM CUSTOMERS WHERE ID = {id}" // */ // Customer findCustomer(int id); // Add "throws SQLException" to request that SQLExeptions be thrown on errors. /** * @jws:sql statement:: * SELECT TAXID, FIRSTNAME, LASTNAME, CURRENTLYBANKRUPT FROM BANKRUPTCIES WHERE  TAXID={taxID} * :: */ public Investigate.Applicant checkForBankruptcies(String taxID); }  ValidateCreditControl.ctrl  package creditCheck; import weblogic.jws.*; import weblogic.jws.control.*; /** * @jws:ejb home-jndi-name="financial.ValidateCredit" * @editor- info :ejb home="ValidateCreditBean.jar" * bean="ValidateCreditBean.jar" */ public interface ValidateCreditControl extends financial.ValidateCreditHome, // home interface financial.ValidateCredit, // bean interface weblogic.jws.control.SessionEJBControl // control interface { } 

Of course, because you're using the Workshop VDE to create this Web service, you are not going to be typing all this code in by hand. Workshop generates all the infrastructure and plumbing code, so you should concern yourself only with business logic. Here are the steps and specifications:

1. Create the creditCheck Web service, with two methods that are both conversational and buffered:

   • requestCreditReportAsync(taxID) This asynchronous call starts a conversation ( @jws:conversation phase=start ). By doing so, Workshop immediately returns control back to the client, while this method proceeds to fulfill the request. In addition, you will specify a custom mapping scheme because your Web service client already has a predefined SOAP message it wants to use.

   • OnCreditReportDone(applicant, responseMessage) This client callback is invoked when the information requested by the requestCreditReportAsynch method is available. Make this method end the conversation (use the finish phase).

2. Create the BankruptciesDatabaseControl Database control, which reads from the BANKRUPTCIES database table, with each row of data being mapped to the Applicant Java object.

3. Create the validateCreditEJB EJB control. The back-end EJB component has already been written and deployed into the default project, so all you need to do is create the EJB control. You won't even need to create any methods in the EJB control because Workshop reflects on the EJB and creates the appropriate methods automatically.

4. Test the Web service, using some canned taxID s that have data in the BANKRUPTCIES database.

Preliminaries

To start WebLogic Workshop, click Start, Programs, WebLogic Platform 7.0, WebLogic Workshop. Workshop ships with a project called Sample, which you'll use to build the tutorial Web service. Choose File, Open Project to open the Open Project dialog box. Select the Samples item in this dialog box.

To do this tutorial, you need to start WebLogic Server by choosing Tools, Start WebLogic Server. It takes some time for the server to come up, but when it does, you should see the green light icon on the bottom status bar of Workshop, which indicates that the server is running.

Create the creditCheck Web Service

To create the creditCheck Web service, follow these steps:

1. In the project tree ( upper-left side of the Workshop window), right-click the Project Samples node and select New Folder. When the Create New Folder dialog box opens, enter creditCheck , and click OK.

2. The new creditCheck folder appears under the Project Samples node. Right-click it, and choose New File. In the Create New File dialog box (see Figure 32.26), type Investigate in the File Name text box, and click OK. You have just created the Investigate.jws file for your Web service.

   Figure 32.26. Create a new Web service ( .jws file).

   

3. Now you need to add two methods to your Web service. Click the Design View tab (if you are not already there). From the Add Operation drop-down list, select Add Method. In the space provided, type requestCreditReportAsync and press Enter. Again, from the Add Operation drop-down list, select Add Callback. In the space provided, type onCreditReportDone . Your new design should now look like Figure 32.27.

   Figure 32.27. Your new Web service in the Design View pane.

   

4. Next, you need to use the Properties pane (to the right of the Design View pane) to make the requestCreditReportAsync method an initiator of a new conversation and to turn on buffering. First, select this method by clicking the requestCreditReportAsync icon. Under the Conversation box, click the drop-down arrow and select Start, as shown in Figure 32.28.

   Figure 32.28. Enable a method to start a conversation.

   

5. Under the Message-Buffer box, click the drop-down arrow and select True, as shown in Figure 32.29.

   Figure 32.29. Specify that a method will use buffering.

   

6. Repeat step 5 for the callback method onCreditReportDone , except this time choose the Finish conversation phase. Your Design View pane should now look like Figure 32.30.

   Figure 32.30. The Design View pane with methods that participate in a conversation and use buffering.

   

7. Notice the "s" icon in the requestCreditReportAsync method, which indicates that it starts a conversation. (The "f" icon in the callback method indicates that it finishes the conversation.) The coil-like icons indicate that buffering is turned on.

8. Next, customize these methods by adding input parameters to their signatures. Double-click the fat arrow icon in the middle of the requestCreditReportAsync icon in the Design View pane. The Edit Maps and Interface dialog box opens. In the Java section, replace the default signature with the following:

     public void requestCreditReportAsync(String taxID)  

9. While you're in this dialog box, specify your custom XML Map. In the XML box, select the Parameter XML tab, click the Custom radio button, and then enter the XML text shown in Figure 32.31. This text indicates that the client is sending two additional pieces of information (name and address) that you will ignore.

   Figure 32.31. Create a custom XML Map for your Web service.

   

10. Then replace the generated default signature for the onCreditReportDone method in the Java section with the following code to specify that the method return a response string indicating the credit report result:

      public void onCreditReportDone(Applicant applicant, String responseMsg)  

11. Next, you need to add a business object and instance to your .jws file. In Source View mode, insert the following code snippet into Investigate.jws , after the jwsContext declaration:

      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();  

If you have not done so already, save your work by clicking the Save icon in the toolbar or choosing File, Save from the menu bar.

Create the Bankruptcies Database Control

To create the Bankruptcies Database control, follow these steps:

1. Click the Add Control drop-down list to the right of the Design View pane for Investigate, and select Add Database Control. When the Add Database Control dialog box opens, fill it out as shown in Figure 32.32.

   Figure 32.32. Create a Database control.

   

   When you click the Create button, a new file called Bankruptcies.ctrl is created under the creditCheck folder in the project tree (upper left), and a corresponding Database control icon is added to the Design View pane. In addition, a new instance variable declaration for bankruptciesDB (STEP1 in Figure 32.32) is automatically added to Investigate.jws .

2. A control is useless without methods, so add one named checkForBankruptcies that retrieves information from the database. Normally, you would need to code several JDBC statements in your client, including setting up connection pools, building a SQL statement programmatically, parsing the result set, and releasing resources. However, you don't need to do that with Workshop. Next, right-click the Database control icon in the Design View pane and select Add Method. In the space provided for the method name, type in checkForBankruptcies .

3. To complete this control, you need to specify this method's correct signature and function. Double-click the fat arrow icon in the center of the Database control icon (in the Design View pane), and fill it in as shown in Figure 32.33.

   Figure 32.33. Specify a SQL map for a Database control.

   

Create the Validate Credit EJB Control

To create the Validate Credit control, follow these steps:

1. In the Add Control drop-down list (refer to step 1 in the previous section), select Add EJB Control. Fill in the Add EJB Control dialog box as shown in Figure 32.34.

   Figure 32.34. Create an EJB control.

   

2. Click the Create button, and you're done. As with the Database control, an EJB control variable called validateCreditEJB (STEP1 in Figure 32.34) has been automatically added to Investigate.jws . You might be wondering about adding methods. As mentioned before, Workshop reflects on the target EJB and generates the necessary methods automatically. Your Design View pane should now look like Figure 32.35.

   Figure 32.35. The Web service's Design View pane with controls.

   

Make Investigate.jws Call These Controls

The Database control is finished, but how does Investigate.jws know when or where to invoke it? You need to tell it by adding business logic. Back in the Design View pane, click the requestCreditReportAsync method (to the left of the Investigate.jws icon), which takes you to the Source View pane for that method. Type in the following code:

 public void requestCreditReportAsync(String taxID) throws java.rmi.RemoteException, java.sql.SQLException { m_currentApplicant.taxID = taxID; String summary = null; Applicant dbApplicant = bankruptciesDB.checkForBankruptcies(taxID); if (dbApplicant != null) { m_currentApplicant = dbApplicant; if (m_currentApplicant.currentlyBankrupt == true) summary = "Currently Bankrupt."; else summary = "Not currently bankrupt."; } else { m_currentApplicant.approvalLevel = validateCreditEJB.validate(2000); summary = "No bankruptcy information found."; } callback.onCreditReportDone(m_currentApplicant, summary); } 

This code basically checks the BANKRUPTCIES database for history on the applicant. It invokes the EJB control to validate the applicant's credit score (hard-coded at 2000), and then calls back the client. Remember that the client had execution control before either control was invoked. The callback with conversation implements a true asynchronous communication model.

If you look at the Source View pane for the Investigate.jws , BankruptciesDatabaseControl.ctrl , and ValidateCreditControl.ctrl files, they should all match the source files shown in Listing 32.6 and Listing 32.7.

Test the Service

Workshop enables you to write and run your code using the Test Harness pane, a browser-based tool through which you can call your Web service's methods. To start it, click the Start icon on the toolbar. Click the Stop button to halt execution of your Web service.

Clicking the Start icon causes Workshop to build your project, checking for errors along the way. It then launches your Web browser to display a page you can use to test the service method with possible values. Figure 32.36 shows the Test Harness pane for the Investigate Web service.

Figure 32.36. The Test Harness pane for Investigate.jws .

Because an incoming XML Map is in place, the only way to specify input is through XML. Otherwise, the Test Harness pane can provide input fields for each parameter of the method being invoked. Try entering some meaningful values. The shipped BANKRUPTCIES database has values for known users, such as 111111111, 222222222, and so forth. In Figure 32.37, a taxID of 222222222 has been substituted for the placeholder string Value_taxID .

Figure 32.37. Results of invoking the requestCreditReportAsync method.

Clicking the requestCreditReportAsync button sends a SOAP message to the Investigate Web service, and the results window in Figure 32.37 is displayed, where you actually see the SOAP request and response messages.

Because this method starts a conversation, control immediately returns to the caller without any real return value, while the request is still being processed (notice the "Processing Request" label at the bottom). When the callback has finished, as shown in the upper-left Message Log section in Figure 32.37, you can click on the callback (in this case, onCreditReportDone ) and get the real results that came back in the callback (see Figure 32.38).

Figure 32.38. Results returned in the client callback.

It all works.