WebLogic provides tools for assembling your components into a Web service. The components include the following prebuilt items:
The circles in Figure 30.1 represent tool processes, and the arrows represent inputs to or outputs from these processes. Inputs and outputs are either J2EE or Java files. ServiceGen does not actually take any custom serializers/deserializers, custom Holder classes, or handlers into consideration when generating your Web service. It can generate serializers/deserializers for you, but you must post-process the Web service EAR file to configure handlers and holders into the Web service. The following sections describe each of these diagrams and components in greater detail. The Web Service Home PageOne nifty feature of the WebLogic Web service container is that it can generate a home page for each deployed Web service. Not only does it describe the service in a more friendly and human-comprehendable manner (as opposed to reading the WSDL file, which is intended more for a programmatic consumer), but it also allows you to test the service so that you can see both the outgoing SOAP message and the incoming SOAP response. You can also download the client JAR for this service from this page. Figure 30.2 shows the home page for the WebLogic-supplied example of a stock trader Web service. Figure 30.2. The WebLogic-generated Web service home page.
You can click the Service Description link to see the associated WSDL file. You get a bulleted list of available operations on this service, and each operation name is a link to its description/invocation page, shown in Figure 30.3. Obviously, there is some work ahead for WebLogic to provide ways to add documentation, most notably semantics, to both the operation and each parameter. The most logical place for housing such documentation would be the Web service deployment descriptor file (discussed later). Figure 30.3. The test page for invoking a Web service operation.
The first parameter in this example is the stock ticker symbol, and the second parameter is the number of shares to buy. Specifying BEAS and 100 and then clicking the Invoke button moves you to the results page shown in Figure 30.4. Figure 30.4. The results of testing a buy service operation.
You might be wondering what happens if your operation takes user-defined type parameters. There is a simple solution to that situation: Instead of providing input text boxes for what could potentially be a complex UDT structure with many fields in a hierarchy, the test page will display the XML representation of each parameter in a text box, for you to author. Figure 30.5 shows an example for the Tax Web service that comes with the WebLogic Portal s sample Commerce application. Figure 30.5. Sample WebLogic Commerce Tax Web service invocation, with a user defined data type.
Notice the service parameter is not a primitive Java type but a user-defined type called TaxRequest with two member fields: a string and an array. Note that if you secure your Web service with a security constraint, you will be prompted to log in when you try accessing its home page. This home page feature is quite nifty, considering all these pages are generated on the fly by the WebLogic Web service container. Anatomy of an Assembled Web ServiceA WebLogic Web service is conveniently packaged as a J2EE Enterprise Application Archive (EAR) file. Figure 30.6 shows a typical Web service EAR file, shown expanded for illustration purposes. This Web service is an example that comes with WebLogic Server: the TraderService Web Service based on a stateless session bean back-end using a complex (user-defined) data type called TradeResult for a return value. You can find the code for this example in Figure 30.6. The contents of a typical Web service EAR file.
< wl_home >\weblogic700\samples\server\src\examples\ webservices \complex\ statelessSession Because TradeResult is JavaBean conforming and simple, you can let WebLogic generate its serializer/deserializer class for you, a process known as autotyping . In fact, this EAR file was generated by the WebLogic build tool, an Ant task called ServiceGen . The trader.ear file is deployed like any other J2EE enterprise application in WebLogic Server. When you run the build script for TraderService , it not only builds the EAR but also copies it appropriately to the applications area of the Examples domain. When the Examples server starts, the TraderService EAR is deployed dynamically. The numbers in the following list correspond to those shown in Figure 30.6:
Notably missing from this list is the Web service WSDL file. And how about the Web Service home page ( .jsp )? These files are generated dynamically at runtime. When the Web service home page is requested via the home page URL, the Web services container will generate it based on the web-services.xml file. The same is true with the WSDL file: It is generated based on web-services.xml when its URL is requested or if the WSDL link of the service home page is clicked. The URL for a WebLogic Web service is patterned after http://<host>:<port>/< context - root >/< web - service - name > where <context-root> is what was defined in the enterprise application s application.xml file ”in this case, webservice (refer to Figure 30.6). Only one Web service, named TraderService , is defined in this EAR s web-services.xml file. Hence, this Web service will recognize a <web-service-name> of TraderService . So, the URL for this particular service would be http://<host>:<port>/webservice/TraderService If there is more than one Web service defined in web-services.xml , each unique service-name will yield a unique service URL (and unique home page and WSDL). When a GET command is sent to this URL, it generates the appropriate Web service home page and serves it back to the browser. If you add the URL parameter WSDL , as in http://<host>:<port>/webservice/TraderService?WSDL WLS will generate and return the appropriate WSDL file for the service. When a POST command with text/xml content type is sent to this URL, it interprets the command as a SOAP message, processes the request, and returns a SOAP response (unless the service is configured to return void ). The Client JAR FileThe client JAR file is an all-inclusive archive that can be supplied to a client; it contains everything that a client needs for invoking a specific Web service. As a Web service provider, you should provide this JAR file to your clients or make it available for download. Table 30.2 describes the items that come with this client file. – For a discussion of static proxies shown below, see Static, p. 1082 . client.jar generally contains the files shown in Table 30.2 and can be generated by WebLogic unless specified otherwise . Table 30.2. Contents of the WebLogic-Generated Client JAR File
The client also needs the serializers and deserializers because the Java call needs to be translated to an XML SOAP request, and the XML SOAP response from the server needs to be translated back to Java objects. A serializer/deserializer class is generated for each user-defined type that WebLogic encounters. A Holder class is generated for each UDT regardless of whether a UDT is used as an out or inout parameter. If you are using the dynamic client style of invocation, all the generic proxies you need are already in the WebLogic webserviceclient.jar file. But dynamic clients still need this client JAR for serializers, holders, client deployment descriptors, and so on. Service specific proxies (for static clients) are always generated so that the Web service can be invoked either statically or dynamically. |