WebLogic Workshop Architecture
| These are the three main components of Workshop:
This container can also, by working in concert with the Workshop VDE, enable you to run, test, and debug your visually authored Web services. When you're in development mode (as opposed to production mode), the Runtime Framework automatically generates a test harness for your Web service and facilities for your Web service clients ' use, such as client proxies and WSDL files. Figure 32.1 illustrates how these components work together and in concert with WebLogic Server. Figure 32.1. The main components of WebLogic Workshop. The window snapshot shown in Figure 32.1 is the Design View pane of the Workshop VDE. It offers an easy way of producing .jws and .ctrl files. You are not limited to using the VDE to build these files. Any text editor can be used to create .jws files. However, without a visual or semantically rich environment, you need to be familiar with JWS annotations and manually code them. Note that since the release of WebLogic Workshop, several IDE vendors have announced support for JWS development (for example, Together ControlCenter Accelerator for BEA WebLogic Workshop and JBuilder, WebLogic Edition by Borland). The JWS container does not get involved until the Web service is started (for testing or debugging in development mode or for client invocation in production mode), when it handles all complex J2EE mechanisms and marshals and unmarshals all Web service messages (SOAP, XML over HTTP, or JMS). JWS FilesA .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. JWS SyntaxListing 32.1 shows a simple but complete JWS Web service file, which is the HelloWorld.jws sample file that ships with Workshop. Listing 32.1 A Simple JWS Web Service File: HelloWorld.jws import Weblogic.jws.*; class HelloWorld { /** * * @jws:operation * */ public String sayHello(String name) { return "Hello" + name ; } } Normally, there would be javadoc tags in the comment block immediately preceding the sayHello() method, but instead there is a special annotated tag: /** * @jws:operation */ This tag informs the WebLogic Workshop Runtime Framework (the JWS container) that the sayHello() method should be exposed as a Web service operation. Although many defaults take place, this is a valid Web service file in a JWS-enabled J2EE Web server. In fact, deployed in such a server, this Web service is accessible via the service endpoint URL: http://server:port/app/HelloWorld.jws . You can use the URL directly or use the WebLogic Workshop Test Harness to test your Web service automatically. There are several other JWS annotations in the current specification. Here's a more complex example that uses a few more annotations: /** * @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> :: */ Each of the preceding annotations indicates to the server that the method following the declaration should support one of the features that has been detailed. Conversations are indicated by @jws:conversation , message buffers by @jws:message-buffer , and so on. (The WebLogic Workshop documentation contains a full reference manual, including detailed documention on each JWS tag.) Some common annotations are covered later in this chapter. In short, these annotations replace the need for you to code hundreds of lines of J2EE code to implement enterprise-class Web service features, such as asynchronous conversations and message buffering. You don't even need to code the annotationsyou can use the WebLogic Workshop VDE to do all this work by visually adding methods controls and setting properties. Asynchrony: Conversations, Callbacks, and BufferingWorkshop supports the use of asynchronous communications in several waysnamely, conversations, callbacks, and buffering. The following sections illustrate where and why such features can be used. ConversationsA 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. CallbacksA 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 CallbackA 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. Listing 32.2 A Simple Client Callback Definition in a .jws File1 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 HandlerWebLogic 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. Listing 32.3 A Simple Handler in a .jws File, for a Control to Ping Its JWS Caller1 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. BufferingBuffering can be turned on for any method in a Web service (JWS) for the following purposes:
Buffering is turned on by using the JWS tag. For developers using the WebLogic Workshop VDE, this tag is automatically inserted into the source code when the developer sets the message-buffering property to "true" , as follows : /** * @jws:message-buffer enable="true" */ JWS ControlsA 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 "ControlsA Closer Look" section later in this chapter describes the details and implementation of .ctrl files. XML MapsRecall 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 MapThere are actually two ways of accomplishing mapping:
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 MappingSimple 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. Listing 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 MappingAt 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 JavaFigure 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 XMLThe 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): convertOrderResponse ToXML (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. ECMAScriptECMAScript , 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" ). Listing 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 MapYou 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:
ControlsA Closer LookIn 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. Database ControlAlthough this section discusses a Database control, the example presented is akin to creating and using any control (with the exception of Timer controls, which are not stored as .ctrl files). To use a Database control in your Web service .jws file, you can simply use the WebLogic Workshop VDE to create a new control by selecting Database Control from the Add Control drop-down list. However, if you'd like to know the details or add the control in your own source code editor, you must do three things:
The import statement shown in Figure 32.16 is unnecessary because the JWS and CTRL classes belong to the same Java package, but it is there to remind you to do so when necessary. Note that the control annotation ( @jws:control ) is required along with a declaration of the control instance variable. Next, look at the .ctrl file. As you can infer , you need to create one .ctrl file for each datasource to be accessed. That is, you cannot use the same control class to access more than one datasource. The annotation @jws:connection binds this control to a datasource that must have been configured in WebLogic Server before running this control. Every method in a Database control must be annonated with the @jws:sql tag to identify the exact SQL statement to be executed when the method is invoked. In this case, the checkForBankruptcies method is reading a row from the BANKRUPTCIES table, and each row in this table is represented by the Java object Investigate.Applicant . You might find it odd that in Investigate.jws the bankruptciesDB variable did not get initialized before its use, but that is part of the magic of Workshop. It is automatically initialized to the appropriate control instance. You can also instantiate new controls on-the-fly by using a supplied Control Factory class. This method is useful when you need to handle one or more resources simultaneously , but the number and nature of these resources might not be known at development time. Web Service DeploymentThe 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:
|
EAN: 2147483647
Pages: 360