Introducing the WebLogic Build Tools


WebLogic provides tools for assembling your components into a Web service. The components include the following prebuilt items:

  • Server-side components ” Compiled Java classes and EJBs. In addition, EJBs must have appropriate deployment descriptors and have been successfully run through the EJBC compiler and optionally packaged in a JAR (Java Archive) file.

  • User -defined types (UDTs) ” Compiled and in your CLASSPATH . User-defined types are Java classes that you have defined as opposed to object types that are native to Java. If your UDTs are conforming JavaBeans and you are depending on WebLogic to generate the serializers and deserializers for you, make sure that these UDTs are well formed (see the section Using User-Defined Data Types later in this chapter).

  • XML Serializers and deserializers ” Compiled and in your CLASSPATH .

  • Message handlers ” Compiled and in your CLASSPATH .

  • Holder classes ” Compiled and in your CLASSPATH .

    Figure 30.1 shows conceptually what the supplied tools and Ant tasks actually do for you.

    Figure 30.1. How WebLogic Server build tools work.

    graphics/30fig01.gif

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 Page

One 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.

graphics/30fig02.gif

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.

graphics/30fig03.gif

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.

graphics/30fig04.jpg

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.

graphics/30fig05.gif

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 Service

A 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.

graphics/30fig06.gif

 
 <  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:

  1. Trader.jar is the same EJB JAR file that was input to ServiceGen ; it contains the back-end EJB TraderBean for this Web service, as well any user-defined classes used in the EJB method signatures. The EJB is included here because it will be deployed as part of the enterprise application.

  2. application.xml is the enterprise application configuration file. It deploys a Web application called trader_service.war and maps it to the context root webservice . It then deploys the back-end EJB trader.jar .

  3. trader_service.war is the actual Web service implemented as a J2EE Web application. It is composed of the client file TraderService_client.jar and the basic components of the Web application, WEB-INF .

  4. TraderService_client.jar contains all the classes, proxies, and so on needed by a client when invoking this Web service. Its contents will be discussed later. It is needed in this Web application because the service home page has a link for downloading this client file. If the Web service EAR file contains more than one Web service (that is, the deployment descriptor web-services .xml contains more than one Web service definition), there will be one client JAR file per service.

  5. WEB-INF contains this Web application s resources, as described in points 6 through 9.

  6. web.xml is required in any Web application, but in this case it is empty by default. If you need to secure this Web service, you can add a security constraint clause here (discussed later).

  7. web-services.xml is the deployment descriptor for this Web service. It specifies every detail of a Web service, from its name to its back-end component, its serializers and deserializers, handlers, and so on. This file will be discussed in detail later.

  8. The CLASSES folder contains all necessary Java code to run this Web service (including Java source files). As shown in Figure 30.6, it contains any user defined types ( TradeResult.class ), any generated serializers/deserializers ( xxx Codec.class ) for user-defined types, and generated Holder classes for output parameter support ( xxx Holder.class ). Holder classes are generated by default. If this Web service has any back-end Java classes that house business logic, they are also found here. And, of course, any other user-written supporting classes are also included here.

  9. The LIB folder contains any supporting JARs for the service or its components.

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 File

The 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

Content Item

Files in This Example

Comments

User-defined types (UDTs)

TradeResult.class

These types are written by the user.

UDT serializers/deserializers

TradeResultCodec.*

The * indicates Java and Class files.

Specific service factory interface

TraderService.*

Specific service factory implementation

TraderService_Impl.*

The client instantiates this object to obtain a port.

Specific service port interface

TraderServicePort.*

This object is used for invoking operations.

Specific service port implementation

TraderServicePort_Stub.*

Holders (for inout parameters)

TradeResultHolder.*

Service WSDL file

TraderService.wsdl

This file is for convenience only so that the client does not need to retrieve it from the server. It is not used by WebLogic.

Web service client-side deployment descriptor

TraderService.xml

This file contains UDT-to-ser/deser mapping.

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.



BEA WebLogic Platform 7
BEA WebLogic Platform 7
ISBN: 0789727129
EAN: 2147483647
Year: 2003
Pages: 360

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net