In addition, there is a tremendous market need to simplify Java and J2EE development. Although J2EE has become a de facto enterprise platform, much as COBOL was in the ’80s and ’90s, there is a scarcity of developers who have the skill set necessary to build J2EE applications. It’s estimated that fewer than 10% of developers available in the enterprise have the skills to build applications in J2EE. In contrast, the majority of developers in the enterprise are application developers who are far more likely to have skill sets in procedural or visual languages, such as Microsoft Visual Basic, PowerBuilder, or COBOL. In addition, J2EE development still requires a great deal of low-level plumbing code that is not necessarily related to the business problem at hand.

Web services hold incredible promise for solving many of today’s enterprise integration problems. However, today’s tools and technologies are optimized for an implementation of Web services that does not easily support the typical requirements of any realistic enterprise integration scenario. Instead, most tools help you easily build a simple, synchronous “stock ticker” Web service. However, to support any realistic integration use case between two enterprise systems, Web services must go beyond the simple synchronous Remote Procedure Call (RPC) paradigm first introduced in the early Web services hype and easily support key requirements, such as asynchrony.

For Web services to support today’s enterprise integration requirements, developers must be able to build enterprise-class Web services that support the following requirements:

A good framework must not only make enterprise-class Web services possible, but also make it possible for developers to build them. The framework must abstract the plumbing code required to implement asynchronous, loosely coupled, coarse-grained messaging from the developer. Whether developers are enterprise J2EE experts or application developers with no previous J2EE experience, they shouldn’t have to spend most of their effort solving plumbing problems. This is where WebLogic Workshop comes in. WebLogic Workshop is a framework that enables any developer to build enterprise-class Web services.

WebLogic Workshop is a simplifying framework for enterprise-class Web services, similar to the way Visual Basic drove the explosion in client/server development in the early ’90s. Before Visual Basic, few developers had the sophisticated skills in Microsoft APIs required to implement a client/server application. Visual Basic came along and provided a visual development approach for specifying application design and business logic, with a runtime framework that implemented the plumbing details.

Similarly, JavaServer Pages (JSP) provide a simplifying framework for servlets to enable a typical user interface (UI) developer to build Web applications on J2EE. JSP enables an important type of enterprise developer resource—the UI developer—to contribute and be productive using J2EE.

A .jws file is a standard Java source file with special javadoc-style annotations prefixed with @jws:. These files declare the Web service’s functionality (such as message queuing or conversations) and expose specific logic as Web services. A .jws file strives to produce a clean separation between Web service plumbing and business logic. In development mode, the Workshop VDE provides on-the-fly compilation and execution of .jws files, giving them a write-and-run lifecycle akin to JSP. However, a JWS-enabled container and compiler must be used to compile or run a .jws file because these processors can understand JWS construction rules.

A .jws file contains the following items:

Of course, you can use the WebLogic Workshop VDE to handle all these details for you.

import Weblogic.jws.*;

class HelloWorld {

   /**
    *
    * @jws:operation
    *
    */
   public String sayHello(String name) {
      return "Hello" + name;
   }
}

/**
 * @jws:operation
 */

/**
 * @jws:operation
 * @jws:conversation phase="start"
 * @jws:message-buffer enable="true"
 * @jws:protocol jms-soap="false" http-soap="true"
 * @jws:control
 * @jws:parameter-xml xml-map::
 * <purchaseOrder>
 *      <customerInformation>
 *         <customerNumber>{customerNo}</customerNumber>
 *      </customerInformation>
 * </purchaseOrder>
 ::
 */

Workshop supports the use of asynchronous communications in several ways—namely, conversations, callbacks, and buffering. The following sections illustrate where and why such features can be used.

Conversations

A conversation is a long-running interaction between a client and a service, in which state information is maintained throughout the conversation’s duration. A single instance of a Web service conversation has associated state that persists for the conversation’s lifetime. At a minimum, this state includes a “conversation ID, ” which is proposed by the client and used to correlate incoming and outgoing messages with a specific conversation instance. By definition, each conversation has a Start, Continue, and Finish phase. Often a conversational Web service method, when invoked, indicates the start of a conversation, and then continues its execution thread. When the service is completed, it invokes a callback on the client, indicating the finish of the conversation. A more elaborate conversation is shown in Figure 32.2.

Figure 32.2. An intelligent conversation between client and service.

WebLogic Workshop developers need not worry about handling the complex plumbing details associated with converations (such as persisting state and member variables, correlating unique conversation IDs, and keeping track of callback locations). Instead, developers can use the WebLogic Workshop framework to manage this plumbing and need specify only the conversation phase for the appropriate service method by setting the Conversation property in the WebLogic Workshop VDE.

Any JWS method can be designated as participating in a conversation by using this annotation:

/**
 * @jws:conversation phase="start"
 */

In this annotation, the phase can be "start", "continue", or "finish". Conversations can occur only between a client and a Web service. This annotation is inserted whenever the developer sets the Conversation property to "start" in the WebLogic Workshop VDE.

An external Web service need not be built in WebLogic Workshop to participate in a conversation, but it does need to support the Conversation parameters in the SOAP headers that specify the conversation ID and callback locations.

Callbacks

A callback is a method that a service invokes to contact its client, either to inform the client of an event or to return some requested information. The client actually defines and hosts this callback method for the service (that it’s requesting something of) to asynchronously contact its client. The point is that with a callback, the client does not need to wait (suspend execution) for a response from the service, assuming it does not need a response to proceed. There are two kinds of callbacks, client and handler callbacks, illustrated later in Figure 32.3. Both kinds of callbacks are defined in the .jws file, but in different ways, as discussed in the following sections.

Figure 32.3. A Web service (JWS) using controls (.ctrl files).

Client Callback

A client callback refers to a callback to a Web service client. A client (Java or otherwise) built and run outside of Workshop can participate in conversations, but it must support the conversation ID and include the callback location (the location of the client) in the SOAP headers. Also, the client must be a server, capable of supporting a method being invoked on it. Otherwise, the client must substitute the callback mechanism with a process such as a polling strategy.

A client callback is defined in a .jws file. To define a callback, simply use the VDE’s Add Operation drop-down box to see the correct JWS annotations being added to the .jws file in the Source View pane. Listing 32.2 shows a simple example of how a callback is implemented in JWS.

Example 32.2. A Simple Client Callback Definition in a .jws File

 1  public Callback callback;

 2  public interface Callback
    {
 3     /**
       * @jws:conversation phase="finish"
       * @jws:message-buffer enable="true"
       *
       * ::
       */
 4     public void onCreditReportDone(Applicant applicant, String response);
    }

    // Let's ping the client
 5   callback.onCreditReportDone(null, "No bankruptcy data found for" +
                                     taxID + ".");

If you wanted to code this allback yourself in JWS without using the VDE, you’d start by declaring a global callback variable in the public class of your .jws file, in Line 1. This type of variable is an inner interface class (within the main JWS class) you define next, in Line 2. The annotations starting in Line 3 pertain to the callback method onCreditReportDone() defined in Line 4. Because every callback must participate in a conversation, you need to specify the @jws:conversation tag to declare the conversation phase this callback invocation will result in. In Listing 32.2, the onCreditReportDone() method ends the current conversation between the client and this Web service. Optionally, you can enable buffering for this callback (discussed in the “Buffering” section, later in this chapter). Of course, you can use the VDE to correctly add these annotations, and then you need worry about just the business logic in your callback.

You might wonder why a callback is merely an interface, and who will implement this interface? Because a client callback’s sole purpose is to return information to a client, and no business logic should need to reside in a callback, Workshop needs to know only the interface of your callback, and it does the rest. All you need to do is invoke the callback when your Web service is ready, as shown in Line 5.

Control Handler

WebLogic Workshop controls are discussed in “JWS Controls” later in this chapter, but in essence a control is a simplified way for your Workshop Web service to access an enterprise resource, such as a database, another Web service, or an EJB. Because these resource requests usually possess inherent response delays, your Workshop Web service can define handlers for a control to “ping” it when resource requests are completed or responses are available. The only controls that can be configured to invoke control handlers (also called “control callbacks”) are Service, JMS, Timer, and Application View controls.

A control handler is also defined in the .jws file, as shown in Listing 32.3.

Example 32.3. A Simple Handler in a .jws File, for a Control to Ping Its JWS Caller

 1  private void creditCardReportTimer_onTimeout(long time) {

      // Because the credit card service has not returned, cancel the request.
 2    creditCardReportControl.cancelRequest();

      // Send a response to the client, saying something about what happened.
      // Remember that this will also effectively finish the conversation.
 3    callback.onCreditReportDone(null, "Unable to get credit card info.");

    }

Unlike a client callback, a control handler contains business logic pertinent for the event that is implied by a handler being invoked. Line 1 defines a control handler named creditCardReportTimer_onTimeout(), with an access modifier of private, even though it is called from outside this .jws file! The construction of this two-part method name is significant: The first part of the name creditCardReportTimer is the control name, and the second part, onTimeout, is the control handler name. (Remember that the Workshop VDE constructs all this infrastructure when you create .jws and .ctrl files.) When this handler is invoked, a timeout has occurred. Earlier in this .jws file, a Timer control was engaged to start a timer, probably right after a getCreditReport method was invoked. In fact, that is exactly the case, as you will see in the section “A Short Tutorial,” later in this chapter. There is a Service control (for accessing another Web service) called creditCardReportControl, and Line 2 cancels the getCreditReport request because it is taking longer than the time allowance allocated for this operation. Line 3 pings the Web service client, using the callback defined in Listing 32.2, to indicate that a credit report couldn’t be acquired in a timely manner.

The Workshop VDE generates all the callback and handler definitions for you in the .jws file. You need to manually add only business logic in control handlers.

Note

Control handlers cannot participate in a Web service conversation.

    /**
     * @jws:message-buffer enable="true"
     */

A control is a JWS construct that simplifies the task of accessing enterprise resources (such as a database) or J2EE resources (for example, EJBs, JMS queues) via Java APIs. A control, representing a resource, is essentially a Java class that you instantiate and then invoke methods on it to accomplish tasks on that resource. Each control possesses a unique set of methods pertaining to the resource it represents. Some controls might require callbacks to the JWS, in which case control handlers need to be defined. Workshop provides the following control types:

Control interactions can be synchronous or asynchronous, depending on your design needs. For instance, a Database control that reads data might be synchronous if the returned information is necessary to proceed with execution. On the other hand, a Web service control might incur latency in its response and suspend client (Web service) execution inordinately, so a callback to the Web service client would be more appropriate. Figure 32.3 shows how your Web service can interact with various resources through controls.

It is important to note the following:

Each type of control you create is a separate class defined in a file with the .ctrl extension, and extends a particular base class for that control type. For instance, to define a Database control, you might create a file called BankruptciesDatabaseControl.ctrl where you define a class called BankruptciesDatabaseControl that extends the Workshop class Weblogic.jws.control.DatabaseControl. The “Controls—A Closer Look” section later in this chapter describes the details and implementation of .ctrl files.

Recall that standard Web services communicate via SOAP, an XML-based specification for how to encode an operation request with its parameters and how to format XML-based responses. By default, WebLogic Workshop accepts incoming and creates outgoing SOAP messages by directly and naturally mapping them to the structure and signature of your Web service method implementation, as illustrated in Figure 32.4.

Figure 32.4. Direct mapping of SOAP messages to JWS method implementations.

However, as you’ll see, the real power behind XML Maps is that they enable you to easily map to your specific XML shape requirement, even if it isn’t the default. This is how XML Maps provide true “loose coupling” and facilitate the separation between interface and implementation. You can fix your XML document shape as the Java implementation evolves (or vice versa), so that consuming Web services are unaffected by your change.

WebLogic Workshop can actually show you the default mapping SOAP message for any method in your Web service. In the Web service’s Design View pane, click on a method name to see its default mapping. Then position your cursor by the fat arrow icon in the center of the method bar, as shown in Figure 32.5.

Figure 32.5. Link to the Edit Maps and Interface dialog box of a method.

Double-clicking the fat arrow icon opens the Edit Maps and Interface dialog box, shown in Figure 32.6.

Figure 32.6. The Edit Maps and Interface dialog box for the getQuote() method.

The dialog box has tabs for Parameter XML (the request format) and Return XML (the response format), and you are currently looking at the naturally mapped request. (The Default option has been selected.) Fields that you want to map from your XML document to Java are indicated by terms in curly brackets ({ }) corresponding to the same terms in the method declaration in the lower Java section.

However, you might need to specify a different SOAP format or shape for incoming or outgoing SOAP messages, different from what Workshop can glean directly from the implementation interface. Reshaping is sometimes necessary for the following reasons:

In these cases, reshaping can be accomplished through XML Maps and scripting. Figure 32.7 shows a map/script in action.

Figure 32.7. Reshape SOAP messages through static maps.

How to Map

There are actually two ways of accomplishing mapping:

• Simple mapping—. Specify which XML elements and/or XML attribute values correspond to which arguments in your Java Web service method and return values. Use this technique if the mapping is static, simple, and straightforward, similar to the one-to-one mapping shown in Figure 32.6.

• Script mapping—. If you need finer control and some data transformation logic to produce the reshaping, you can divert processing to a script file or a more extensive XML Map file.

Simple mapping and script mapping are not mutually exclusive. Each can be used standalone or in combination (a script can be used inside a mapping), as is shown later in this chapter. Figure 32.8 illustrates this mapping process.

Figure 32.8. Use XML Maps and mapping scripts for more sophisticated message transformations.

Simple Mapping

Simple mapping inline with Java code is also done with JWS annotations. For instance, Listing 32.4 shows a simple map in which the input message specifies two arguments; the Java method implementation takes only one argument.

Example 32.4. Mapping a Two-Argument SOAP Request to a One-Argument JWS Method

   /**
     * @jws:conversation phase="start"
     * @jws:parameter-xml xml-map::
     *  <getQuote xmlns="http://www.openuri.org/">
     *      <customerID>1234567890</customerID>
     *      <tickerSymbol>{tickerSymbol}</tickerSymbol>
     *  </getQuote>::
     */
    public void getQuote (String tickerSymbol);

Remember that you can also locate the map specification in a file external to the .jws file. This method allows multiple .jws files to potentially share an XML Map. An external mapping file has a .xmlmap extension and must contain special <xm:..> tags. For more information on XML Map files, see the Workshop online documentation.

Script Mapping

At times your XML message differs dramatically from your Java method signature, or calculations and transform logic become necessary while mapping. In these cases, you need to use ECMAScript (discussed later in this chapter, under “ECMAScript”) to augment your static map statements. ECMAScript code resides in .jsx files and can be invoked from within a map.

Mapping from XML to Java

Figure 32.9 shows an example of a script invocation from inside a map specification converting from XML to Java.

Figure 32.9. Invoking an XML-to-Java script from within a map.

This particular mapping converts an XML message to Java objects. When this function completes, the two arguments shown, currentOrder and currentCustomer, will reference real Java object instances of the appropriate type. The ECMAScript function definition, however, looks somewhat odd, as shown in Figure 32.10.

Figure 32.10. The ECMAScript function definition.

First, the function name differs slightly from the function call: It always has the suffix FromXML (for functions converting from XML to Java) or ToXML (for functions converting from Java to XML). Second, the argument list does not match the function invocation, either, because the function call is not a direct execution branch to the function definition. Instead, it is a directive to WebLogic Server to perform some predefined tasks, one of which is to determine what function to call and what argument value to pass it, and eventually to invoke the script. Figure 32.11 shows what transpires when converting from XML to Java.

Figure 32.11. Steps in converting from an XML request to Java objects.

When scripting from an XML request to the JWS method, the one input parameter is the XML document, and the return value is one or more Java objects.

Mapping from Java to XML

The corollary script call for the placeOrder service shown in the previous section might be as follows:

<placeOrderResponse>
   {CustomerServices.OrderScripts.convertOrderResponse(return)}
</placeOrderResponse>

This would be the corresponding ECMAScript definition (note the boldface ToXML suffix of the script name mentioned previously):

convertOrderResponseToXML(returnValue) {
   ...
   return xmlResponse;
}

That is, the return value of the Java Web service method is passed in to the ECMAScript function, which then crafts the appropriate response XML string incorporating this return value, and returns the XML string as a response. Again, WebLogic Server automatically connects the script invocation to the script definition, passing in parameters and passing on return values appropriately. Figure 32.12 illustrates this flow.

Figure 32.12. Steps in converting from a Java return object to an XML response.

When scripting from Java to an XML response, the one input parameter is the return value of the JWS Web service method, and the return value is the crafted XML response.

ECMAScript

ECMAScript, formally known as ECMA 262, is the international Web standard for scripting languages. That is, ECMAScript is not a language implementation, but a scripting language specification. Some popular examples of ECMA implementations are JavaScript and JScript. WebLogic Workshop provides an ECMAScript implementation so that you can use its script language for data conversions or XML mapping. In fact, Workshop’s implementation contains extensions that, among other things, support XML elements as first-class script objects, which greatly facilitates XML text creation and manipulation. For information on the WebLogic Workshop ECMAScript implementation, consult the Workshop online documentation under “Guide to Building Web Services.”

To give you an idea of what Workshop ECMAScript code looks like, Figure 32.13 shows a scriptlet that converts from Java to XML.

Figure 32.13. ECMAScript that converts from Java to XML.

Line 1 defines a new variable, orderMessage, that starts out as an empty order element. Lines 2 and 3 then add two child elements to <order>. Finally, the returned XML string looks like that shown in Listing 32.5 (if orderInfo.name = "Dog Brush" and customerInfo.name = "Debbie").

Example 32.5. The Converted XML String from the convertOrderToXML Function

   <order>
     <item_name>Dog Brush</item_name>
     <customer_name>Debbie</customer_name>
   </order>

Conversely, Figure 32.14 shows a scriptlet that converts from XML to Java objects.

Figure 32.14. ECMAScript that converts from XML to Java.

Say that the XML to be converted (passed into convertOrderFromXML) is what’s shown in Listing 32.5. Line 1 defines a variable that extracts the value of the <order_info> element. The dot operator (.) is used to construct a direct path through an XML document hierarchy, much like XPath. Line 3 returns an array of two Java strings to a .jws file.

For more information on map scripting, consult the Workshop online documentation under “Guide to Building Web Services.”

Where to Map

You can apply XML maps to a method or callback exposed to clients as well as to the methods and handlers of a Service control, a JMS control, and an Application View control. Figure 32.15 points out where XML mapping can be defined in the Workshop Design View pane.

Figure 32.15. Where XML mapping can occur.

The numbers in Figure 32.15 correspond to the numbers in the following list:

1. Through XML maps on methods and callbacks exposed to the client, you control how data in XML messages is translated to Java types needed by your code, and vice versa.

2. On a Service control, you can apply maps to preserve a message shape required by the other Web service while using types specific to your own Web service.

3. On a JMS control, you can use maps to control a message’s body, header, and properties.

4. Similar to maps on a Service control, maps on an Application View control preserve a message shape required by an Application View while using types specific to your own Web service.

In the following sections, take a look at a few of these controls in detail because you will be using them in the tutorial that follows.

The VDE enables you to quickly develop and test your Web services. Your Web services are stored as Projects, which are initially composed of your Web service’s source files (.jws and .ctrl files). After you run your Web service (after starting WebLogic Server from within the VDE), the VDE automatically generates all necessary J2EE components and deploys them to the running WebLogic server. For quick and easy testing, debugging, and fixing your Web services under development, these underlying components are deployed in expanded form.

When you have finished developing your Web services, somehow you need to make them publicly available to clients running outside the WebLogic Workshop VDE. Also, you should not require the VDE to be up and running just to implement your Web service. This is where deployment comes in. You must take your Workshop VDE Project and convert it to a more compact and static format: a standard J2EE Enterprise Application Archive (EAR) file. This EAR file can then be deployed to a running production-mode WebLogic Server instance, ready to serve client requests, without needing the Workshop VDE to be running. Figure 32.17 illustrates this process.

Figure 32.17. The WebLogic Workshop development lifecycle.

The rounded icons in Figure 32.17 represent actions or processes, and the rectangular icons represent an aggregated or single file. The following numbered points correspond to those in Figure 32.17:

A Project is a collection of Web services or Web service components, much like your typical IDE project. In Workshop, an individual Web service resides in a folder under the Project. That Web service can be self-contained or use components found in other folders. Figure 32.19 shows a Project’s logical organization.

Figure 32.19. How a Workshop Project is organized.

A Web service folder should contain only one .jws file, one Web service. The WEB-INF folder is a special location containing JAR files for any back-end code or J2EE resource (such as EJBs) that any Web service in this project can access. The Xmlmap and Controls folders can be used for storing logic shared among multiple Web services. This structure is certainly not the only way to organize components; folders can actually accommodate any kind of files.

Operations

In addition to the usual operations allowed on hierarchy trees, you can also drag and drop files and folders within the project tree and between the project tree and the file system. You can also invoke code-generation facilities in the project tree. Because a .jws file is a Web service, you can request the following:

• JWS-to-WSDL file—. Generate the service description file for clients that are not JWS Web services.

• JWS-to-CTRL file—. Generate a service control file for clients that are JWS Web services.

To invoke code generation, select a .jws file and right-click it, as shown in Figure 32.20.

Figure 32.20. Select a .jws file.

This center pane presents a graphical and unified view of a .jws file, including all its interacting partners, such as clients and controls. The following parts of the main work area are shown in Figure 32.21:

Figure 32.21. Contents of the main work area.

Note that the Web service–to–control arrows do not indicate that the Web service business logic invokes the control method, only that it is available and can potentially be called. Note that callbacks (client or control) are rendered in a darker shade.

A JWS Web service can be rendered in two possible views:

These two views are not two separate objects; they are just two possible renderings or views of the .jws file.

The WebLogic Workshop Test Harness enables you to test and debug your Web service. To start it, click the Start icon (the right-pointing green arrow) on the toolbar.

By default, the Test Form is displayed (see Figure 32.24). The following sections go through each section of this Test Harness.

Overview Page

Click the Overview tab to see the Overview section shown in Figure 32.22.

Figure 32.22. Overview section of the Test Harness.

Think of the Overview section as the “home page” for your Web service, where a potential client can come to get information and tools for invoking your service. It contains the following information:

• Complete WSDL—. The service description is in standard WSDL format so that your non-Workshop clients know how and where to access your service.

• Callback WSDL—. Because Workshop Web services can invoke callback methods to the client, this is the callback service description. It tells a client how it might implement your service’s callback methods.

• Workshop control—. What if another Workshop Web service is interested in invoking your Web service? This link downloads code for a Service control to your Web service.

• Java proxy—. Java proxy code comes in handy if you need to write a Java client that invokes this service. The proxy can be made into a class that your Java client imports, allowing it to call your service methods without needing to create the SOAP request or parsing the SOAP response manually.

• Proxy support JAR—. Other code needed by the Java proxy.

• Service description (for each method)—. Links to the Test Form for each operation in your service.

• Useful links—. Links to various industry specifications (not visible in Figure 32.22).

Console Page

Think of the console page as the administration page for your Web service, much like the WebLogic Server Administration Console, except much simpler. Figure 32.23 shows the Workshop console page.

Figure 32.23. The WebLogic Workshop console page.

This page contains information pertaining to your Web service implementation and configuration (hence, non-public information), such as the following:

• Historical records of the time this service was built

• The back-end components and resources involved in your Web service

• The WebLogic Workshop build label

• Log settings to specify how much logging is needed and how many old messages to keep around

• Persistence and caching settings to reset log records and force component redeployment

Test Form Page

The Test Form page, shown in Figure 32.24, is where you get to test-invoke methods in your Web service.

Figure 32.24. The Test Form page of the Web service Test Harness.

There are two sections in this page:

• Message Log (left section)—. As you invoke the method and as any long-running conversations unfold, a list of methods being invoked (method traffic), including callbacks, is built and displayed in the Message Log section. You can click on any call that’s listed to reveal its input XML and output XML in the Method Details section.

• Method Details (right section)—. This section starts out as a list of methods that can be invoked, with input fields for call arguments. As a conversation unfolds or a method call ends, this section automatically switches to display input and output XML. The section “A Short Tutorial” later in this chapter illustrates this process in more depth.

Note

If a custom-requested XML Map is present for a method, the custom XML string is displayed instead so that you can fill in the actual values.

Test XML Page

The Test XML page (see Figure 32.25) is similar to the Test Form, except all inputs to method calls are specified in the actual XML request to be sent. All responses are also shown in XML format.

Figure 32.25. The Test XML page.

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.

To create the creditCheck Web service, follow these steps:

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.

To create the Bankruptcies Database control, follow these steps:

To create the Validate Credit control, follow these steps:

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.

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.