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.

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.

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.

<wl_home>weblogic700samplesserversrcexampleswebservicescomplex 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 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.

client.jar generally contains the files shown in Table 30.2 and can be generated by WebLogic unless specified otherwise.

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.

As shown in Figure 30.1, WebLogic provides two main Ant tasks for assembling Web services: ServiceGen and ClientGen. They are meant to be invoked from within an Ant build file, as part of building the components that constitute your Web service.

ServiceGen

A Web service provider uses the ServiceGen task to automatically assemble various components and resources into a WebLogic Web service. Figure 30.8 shows a schematic of the ServiceGen task.

Figure 30.8. The make-up of the ServiceGen task.

As you can see, it is possible to define more than one Web service in a single deployable Web service EAR. This topic is discussed in more detail later, in “Understanding Web Service Packaging Considerations.” Each service box represents the creation of a new Web service. A client subelement in a service directs the creation of a client JAR file for that service. Listing 30.1 shows the ServiceGen invocation for the TraderService example discussed previously.

Example 30.1. Ant Build Code Snippet for Invoking ServiceGen

1  <taskdef name="servicegen"
      classname="weblogic.ant.taskdefs.webservices.servicegen.ServiceGenTask"/>
  <target name="build-ear">
    <servicegen
2       destEar="trader.ear"
3       warName="trader_service.war"
4       contextURI="webservice">
5       <service
            ejbJar="traderBean.jar"
            targetNamespace="http://www.bea.com/examples/Trader"
            serviceName="TraderService"
            serviceURI="/TraderService"
            generateTypes="True"
            expandMethods="True" >
6            <client
                packageName="examples.webservices.complex.statelessSession"
                clientJarName="traderService_client.jar"
            />
        </service>
    </servicegen>
  </target>

First, you define a task called servicegen mapped to the WebLogic servicegen class (1). Actually, the first line of Listing 30.1 is unnecessary if you are using the Ant that is bundled with WLS. You then define an Ant target called build-ear requesting that it create an EAR file called trader.ear (2) and a WAR file called trader_service.war. If you do not specify a file extension here, servicegen will interpret these names as file folders where an expanded EAR and expanded WAR will be created. The next attribute, contextURI, defines the first part of the Web service URL, called the context root of this enterprise application. The URL of this service is defined as

http://<host>:<port>/<contextURI>/<serviceURI>

Line 5 starts a Web service definition, using traderBean.jar for back-end EJBs and TraderService as the Web service name in its WSDL file. The attribute serviceURI defines the last part of the preceding URL for this Web service. In WebLogic, each Web service is deployed as a Web application, so serviceURI is actually the Web application’s web-uri. Because the back-end EJB TraderBean uses the user-defined type TradeResult, you can specify generateTypes="True" so that ServiceGen will autotype and generate the serializer and deserializer class for it.

Line 6 requests that ServiceGen also generate the client JAR file and store it in the Web service EAR, which must be done if you want the client JAR to be downloadable from the Web service home page (and also not rename the client JAR, but assume its default name). See the next section, “ClientGen,” for details on clientgen parameters. The only difference between this <client> element of <service> and the ClientGen task is that with <client> you cannot specify a folder location for the destination client JAR; it must be a filename. Another difference is that <client> uses the deployment descriptor and back-end component interface when generating the client JAR, whereas ClientGen can take a WSDL file to generate the client JAR.

ClientGen

As Figure 30.1 shows, ClientGen can take a service description in the form of a WSDL file or an actual Web service EAR file and generate a client JAR file that contains everything a client needs to invoke the Web service. Listing 30.2 shows a simple ClientGen invocation.

Example 30.2. Sample ClientGen Invocation

<taskdef name="clientgen"
     classname="weblogic.ant.taskdefs.webservices.clientgen.ClientGenTask"/>
<target name="gen_clientjar" >
  <clientgen
     wsdl="http://localhost:7001/webservice/TraderService?WSDL"
     packageName="examples.wlbook.web.services"
     typePackageName="examples.wlbook.udt"
     autotype="True"
     clientJar=".	est-client.jar"
  />
</target>

This scriptlet obtains the WSDL of the TraderService example we’ve been discussing and then parses it to detect uses of any non–built-in types so it can generate Java source files for them. It also generates serializer and deserializer classes for each non–built-in type it finds (because you specified autotype="True"). Of course, the client proxies for this service are also generated into the client JAR. The output JAR file is also named.

Tip

When ClientGen generates the client proxies, what package should they reside in? ClientGen has no idea, so you must tell it using the packageName attribute. Similarly for generated non–built-in types and serializers, you specify their package name using the typePackageName attribute.

WebLogic also provides command-line versions of ServiceGen and ClientGen, for use in non-Ant build environments. In this case, the invocation attributes are specified as command-line options, named to match (more or less) with the Ant task interface.

In the spirit of J2EE deployment descriptors, WebLogic Server has formulated a declarative style of defining Web services: web-services.xml. Although allowing ServiceGen to generate this file for you is preferred, in some instances ServiceGen may not be adequate. You then need to code web-services.xml yourself. To aid you in this task, this section reveals the format and function of this file.

Figure 30.11 diagrams the major sections of the web-services.xml file. A box represents an enclosed XML element, usually with a begin and end tag. Embedded boxes represent embedded XML elements. An ellipsis (...) following a box name indicates an optionally repeating element.

Figure 30.11. The sections of a web-services.xml file.

The two major sections of a Web service deployment descriptor are handler chains and one or more Web service definitions. As you may recall from the preceding chapter, a handler accesses a SOAP request, possibly altering or enhancing it in some way, before passing it on to a back-end component that fulfills the service request. That same handler can also access the response before returning it to the client. In some cases, a handler can even fulfill a request without invoking a back-end component. A Web service section describes everything about a service, from its back-end components to data types to operations.

The handler chains box is optional and can be used to define one or more handler chains. A handler chain specifies a sequence of Handler classes to be invoked before a SOAP message reaches its destination. At this point, you are only defining them but not specifying which Web service will use them or where in the service process they might be invoked. A handler chain will be referenced in the operation element in a Web service, defined later. As you can see, Handler classes can be shared across different Web services.

The Web service box defines a single Web service. You can actually define more than one Web service in this file. If you do, all such Web services will be part of the same Web application, which means they will all have the same context root. For example, if you had a second Web service named TickerService defined in the web-services.xml file of the previous TraderService example, that second service’s URL would be

http://<host>:<port>/webservice/TickerService

The Web service box embeds four other subelements:

Figure 30.11 also shows schematically that, during operation definition, the UDTs, components, and handler chains are referenced and used in context.

A Sample web-services.xml File

This section takes apart a simple Web service to see what its web-services.xml file looks like. This sample Web service does the following:

• Uses a Java class back-end component (examples.ws.getTicker) for an operation named getTicker that returns an official ticker symbol given a company name string

• Uses a stateless session EJB back-end component with an operation named buy that executes a stock buy, returning true if the trade was successful

• Is a synchronous RPC service

• Has no user-defined types nor handlers

Its web-services.xml file is shown in Listing 30.3.

Example 30.3. The Sample web-services.xmlFile

<web-services>

1   <web-service name="Trader"
                 targetNamespace="www.bea.com/Trader"
                 uri="/TraderWS">

2      <components>
          <java-class name="getTickerClass"
                      class-name="examples.ws.getTicker" />
          <stateless-ejb name="Trader">
             <ejb-link path="trader.jar#TraderBean" >
          </stateless-ejb>
       </components>

3      <operations>

         <operation name="getTicker"
                     component="getTickerClass"
                     method="getTicker"
                     invocation-style="request-response" >
             <params>
                <param name="companyName" location="body"
                       style="in" type="xsd:string"
                       class-name="java.lang.String" />
                <return-param name="tickerSymbol"
                        location="body" type="xsd:string"
                        class-name="java.lang.String" />
             </params>
          </operation>

4          <operation name="getShares"
                     component="Trader"
                     method="buy" >
            <params>
5               <param name="ticker" location="body"
                       style="in" type="xsd:string"
                       class-name="java.lang.String" />
                <param name="numShares" location="body"
                       style="in" type="xsd:int"
                       class-name="int" />
6               <return-param name="result" location="body"
                       type="xsd:boolean"
                       class-name="Boolean" />
             </params>
          </operation>

       </operations>

    </web-service>

</web-service>

The following numbered list corresponds to the numbers shown in Listing 30.3:

1. Start a new Web service. The required attributes shown are

   • name—. The name of the Web service that will be used in its WSDL file

   • targetNamespace—. To be used for qualifying namespaces in the WSDL file as well as any generated SOAP message

   • uri—. To be used as part of the Web service URL

   You can define more than one Web service in a web-services.xml file.

2. List your back-end components here. At this point, you don’t know how, where, or if these components will be mapped to operations. It is just a list.

   The first component is a Java class. The class needs to be accessible to the Web service container at runtime. To make it accessible, you usually locate such a class in the WEB-INFclasses folder of the service Web application (or service WAR file).

   The second component is a stateless session EJB. Notice the <ejb-link> path attribute, which must point to the JAR file where the EJB is located, and the bean name as specified in the <ejb-name> element of the bean deployment descriptor. This JAR must have been successfully run through the EJB compiler.

   If your Web service uses only handlers exclusively for fulfilling service calls, you can omit the entire Components section.

   Now comes the task of defining the operations or calls available in this Web service.

3. The first operation will be named getTicker in the generated WSDL file. It is backed by the component getTickerClass, which you defined in the Components section. Specifically, when this service operation is called, the container needs to invoke the getTicker method of getTickerClass.

   What if you want every method in this class to be exposed as a service operation, where the operation names can equal the method names? Is there a shortcut for specifying that? Yes, you can just use the following:

   <operation component="getTickerClass"
       method="*">
   </operation>
   

   Obviously, you need to omit the <params> element in this case. What if your back-end component has overloaded methods, such that only referring to a method name would be ambiguous? In that case, you can specify a method signature as follows:

   <operation name="getTicker"
              component="getTickerClass"
              method="getTicker(java.lang.String)"
   </operation>
   

   The last attribute used here is invocation-style, which specifies whether this is synchronous (with a value of "request-response") or asynchronous (with a value of "one-way").

4. Now look at the optional <params> subelement in the next operation, getShares, which is backed by a stateless session bean. If <params> is omitted, the container will examine the back-end component to determine each parameter’s type and supply default parameter names. In that case, why specify <params> at all? Do so only if you need to do the following:

   • Give parameter names in the WSDL file that are more meaningful

   • Use output or inout parameters

   • Map a parameter to a name in the SOAP header of the request or response

5. The location attribute specifies where this parameter’s value can be found: the SOAP header, SOAP body, or SOAP attachment. That is, you can ask the container to extract a SOAP header element for you and pass it in to the back end component method. Typically, as it is in this case, the parameters are passed via the client’s service call parameters. The style attribute (different from invocation-style of <operation>) declares the mode of the parameter: in, out, or inout.

6. The next item to point out is the class-name attribute. Why do you need to specify the Java class name of the type attribute? Because type is required and points to an XML data type with a known mapping to a Java type, why specify another Java type in class-name? First, class-name is optional. Second, you specify class-name only to clearly identify an XML type because XML types do not distinguish between Java primitives and their corresponding wrapper classes (for example, boolean and java.lang.Boolean are both XML-typed as xsd:boolean). In Listing 30.3, the return type is explicitly defined to be a primitive boolean. Also, if your method takes a base class A and the client is supposed to pass a subclass B (class B extends class A), you can specify subclass B in web-services.xml, and the WSDL will be generated based on B, which more accurately reflects what type the user should pass.

You have just seen the basic elements of web-services.xml. This example does not cover user-defined types, output parameters, handlers, and asynchronous Web services. They are covered in the ensuing sections. Figure 30.12 shows what the web-services.xml file would look like with all possible elements.

Figure 30.12. The web-services.xml file with all possible elements.

You need to decide how your user-defined type will look in the XML representation. For instance, what element names and tag structure will be used? Which elements are required, and which ones are optional? How many times can a particular element occur? The XML representation you define will be used in the XML SOAP request and possibly in the SOAP response.

You define how your UDT will “look” in XML using the precise language of XML Schemas. Learning how to author XML Schemas is not a trivial task and is certainly beyond the scope of this book. We can, however, show a sample schema definition for a typical UDT, Employee, as defined in Listing 30.4. (Note that the Employee class conforms to the rules presented in the preceding section.)

public class Employee {
   private String fullname;
   private int id;
   public Employee() {}  // Create a default employee
   // set/get methods for each variable for JavaBean compliance
   public setFullname(String name) {
      fullname = name;
      }
   public getFullname() {
      return fullname;
   public setId(int serialNo) {
      id = serialNo;
      }
   public getId() {
      return id;
      }
}

A possible XML representation for an instance of Employee might be

<employee>
  <fullname>Christy Anne Go</fullname>
  <id>98345</id>
</employee>

Now you must codify the rules indicating how to convert an instance—in fact, any instance—of Employee into the preceding XML format. What you need is a meta language to describe a grammar for what are valid XML sequences that represent a correct Employee instance. That is exactly what an XML Schema is. A possible schema for Employee is shown in Listing 30.5.

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
           xmlns:stns="java:examples.webservices"
           attributeFormDefault="qualified"
           elementFormDefault="qualified"
           targetNamespace="java:examples.webservices">
   <xsd:complexType name="Employee">
       <xsd:sequence>
           <xsd:element name="fullname"
                        type="xsd:string"
                        maxOccurs="1" minOccurs="1">
           </xsd:element>
           <xsd:element name="id"
                        type="xsd:int"
                        maxOccurs="1" minOccurs="1">
           </xsd:element>
       </xsd:sequence>
   </xsd:complexType>
</xsd:schema>

This schema declares the following:

After you write the XML Schema for your UDT, you must add it to the <types> section of web-services.xml, as shown in the following code:

<types>
  <!-- One user-defined type -->
  <xsd:schema... >
    :
  </xsd:schema>

  <!--Another user-defined type -->
  <xsd:schema... >
    :
  </xsd:schema>
</types>

You can define multiple UDTs within a schema section, but all UDTs in a schema section will share the same target namespace.

Exactly when is an XML Schema actually used by the container because, in a sense, a UDT’s type schema is already codified in its serializer class? The answer is: The schema is not used when a service call is made and fulfilled. It is used only in generating a service’s WSDL file. However, a UDT schema is still required regardless of whether you do or do not need the WSDL file.

A serializer converts a Java object to XML representation, and a deserializer converts an XML document to a Java object. The characteristics of WebLogic/JAX-RPC serializers are as follows:

Now look at a sample serializer class for the Employee user-defined type, as shown in Listing 30.6.

package examples.newTypes;

import weblogic.webservice.encoding.AbstractCodec;
import weblogic.xml.schema.binding.DeserializationContext;
import weblogic.xml.schema.binding.DeserializationException;
import weblogic.xml.schema.binding.Deserializer;
import weblogic.xml.schema.binding.SerializationContext;
import weblogic.xml.schema.binding.SerializationException;
import weblogic.xml.schema.binding.Serializer;

import weblogic.xml.stream.Attribute;
import weblogic.xml.stream.CharacterData;
import weblogic.xml.stream.ElementFactory;
import weblogic.xml.stream.EndElement;
import weblogic.xml.stream.StartElement;
import weblogic.xml.stream.XMLEvent;
import weblogic.xml.stream.XMLInputStream;
import weblogic.xml.stream.XMLName;
import weblogic.xml.stream.XMLOutputStream;
import weblogic.xml.stream.XMLStreamException;

public final class EmployeeCodec extends
      weblogic.webservice.encoding.AbstractCodec
{
  public void serialize(Object obj,
                        XMLName name,
                        XMLOutputStream writer,
                        SerializationContext context)
    throws SerializationException
  {
    Employee emp = (Employee) obj;
    try {
      //outer start element <Employee>
      writer.add(ElementFactory.createStartElement(name));
      //employee name element
      writer.add(ElementFactory.createStartElement("fullname"));
      writer.add(ElementFactory.createCharacterData(emp.getName()));
      writer.add(ElementFactory.createEndElement("fullname"));
      //employee id element
      writer.add(ElementFactory.createStartElement("id"));
      String id_string = Integer.toString(emp.getId());
      writer.add(ElementFactory.createCharacterData(id_string));
      writer.add(ElementFactory.createEndElement("id"));
      //outer end element </Employee>
      writer.add(ElementFactory.createEndElement(name));
    } catch(XMLStreamException xse) {
      throw new SerializationException("stream error", xse);
    }
  }

  public Object deserialize(XMLName name,
                            XMLInputStream reader,
                            DeserializationContext context)
    throws DeserializationException
  {
    // extract the desired information out of reader, consuming the
    // entire element representing the type,
    // construct your object, and return it.
    Employee employee = new Employee();
    try {
      if (reader.skip(name, XMLEvent.START_ELEMENT)) {
        StartElement top = (StartElement)reader.next();
        //next start element should be the employee name
        if (reader.skip(XMLEvent.START_ELEMENT)) {
          StartElement emp_name = (StartElement)reader.next();
          //assume that the next element is our name character data
          CharacterData cdata = (CharacterData) reader.next();
          employee.setName(cdata.getContent());
        } else {
          throw new DeserializationException("employee name not found");
        }
        //next start element should be the employee id
        if (reader.skip(XMLEvent.START_ELEMENT)) {
          StartElement emp_id = (StartElement)reader.next();
          //assume that the next element is our id character data
          CharacterData cdata = (CharacterData) reader.next();
          employee.setId(Integer.parseInt(cdata.getContent()));
        } else {
          throw new DeserializationException("employee id not found");
        }
        //we must consume our entire element to leave the stream in a
        //good state for any other deserializer
        if (reader.skip(name, XMLEvent.END_ELEMENT)) {
          XMLEvent end = reader.next();
        } else {
          throw new DeserializationException("expected end element not found");
        }
      } else {
        throw new DeserializationException("expected start element not found");
      }
    } catch (XMLStreamException xse) {
      throw new DeserializationException("stream error", xse);
    }
    return employee;
}

The following is the serialize method signature:

public void serialize(Object obj,
                      XMLName name,
                      XMLOutputStream writer,
                      SerializationContext context)
  throws SerializationException

The following are the parameters:

Now look at the deserializer method signature:

public Object deserialize(XMLName name,
                          XMLInputStream reader,
                          DeserializationContext context)
  throws DeserializationException

The following are the parameters:

When you’re converting an embedded user-defined type, there is no way to look up its serializer/deserializer class. You just need to hard-code any embedded serializer class invocations.

The last step in this process is to state which serializer/deserializer class should be called for each user-defined type. If WebLogic Server is generating your serializer class, its type mapping will also be generated for you. Otherwise, you need to add a type-mapping section to web-services.xml, as illustrated in Figure 30.12. The <type-mapping> element starts this section and encompasses one or more <type-mapping-entry> subelements, as shown in Listing 30.7.

<type-mapping>
  <type-mapping-entry
       class-name="examples.ws.Employee"
       xmlns:p1="java:examples.webservices"
       type="p1:Employee"
       serializer="examples.ws.EmployeeCodec"
       deserializer="examples.ws.EmployeeCodec" >
  </type-mapping-entry>
</type-mapping>

The following are the parameters:

You can specify multiple type-mapping entries, one for each of your user-defined classes. WebLogic Server presumes that your serializer class produces the correct Java object or XML document. It cannot verify correctness of your custom-created serializer class at build or deploy time.

Also, ServiceGen will not copy your custom serializer/deserializer classes into the ear file, and if you specify an input type mapping file, it will assume that there is no need to generate serializer/deserializer classes for the types that are already mapped.

Enterprise JavaBean classes used as back-end components are no different from any other EJB. The only special considerations are the following:

For lightweight business logic, you can use regular Java classes as Web service back end components. However, note the following limitations when doing so:

All Holder classes implement the javax.xml.rpc.holders.Holder interface. This interface dictates the following requirements of an implementation:

A holder object can simply be instantiated and given its initial content using the default constructor, as follows:

intHolder numShares = new intHolder(250);

Alternatively, you can change its value by using its value variable:

numShares.value = 100;

Writing a back-end component that takes output parameters is simple. The service methods just need to take holder-type arguments for any output parameter. Given that, the StockTrader.buy method has the following signature:

Buy (in String ticker, inout int numOfShares, out float sharePrice)

The back-end stateless session bean method that corresponds to this service call is shown in Listing 30.8.

public void buy (java.lang.String ticker, IntHolder inOutNumShares,
    StringHolder outBuyPrice )
{
// execute the trade using ticker and numShares (code not shown)
. . .

// Use the input parm and update it (inout)
inOutNumShares.value = inOutNumShares.value - 1;

// Set the buy price (out)
outBuyPrice.value = "$22.50";
}

The public variable value is used to both access and update the holder. Note that the same Holder class is used for both out and inout parameters. It is the business logic that decides how to use the holder object. This example shows how to use a built-in type as an output parameter, but using a Holder class for a user-defined type is just as simple. The back-end component accesses the UDT object through the public value variable and modifies the UDT accordingly.

You might be surprised to learn that Holder classes are never referenced inside a WSDL or the web-services.xml file. Each of these “service description” files has other, more subtle ways of indicating out or inout parameters. This makes perfect sense considering that a service description should not be programming language specific. In the JAX-RPC prescription for Java Web services implementation, Holder classes are used to implement output parameters. So how does a WSDL file express output parameters?

Recall that the <message> element of the tModel section in a WSDL file describes the data items (or data parameters) that are sent between the caller and service provider. Each <part> subelement of a <message> represents one call parameter. There is one <message> element for the input request and another <message> element for the output return. Normally, the return <message> would indicate a return value, but in this case, you can list the same <part> subelements in both the input and return <elements>. The WSDL specification dictates that such a scenario indicates out or inout parameters. Let’s quote the WSDL 1.1 specification to be precise:

These concepts will be clearer when you see the WSDL. Here again is the signature of the buy method:

Buy (in String ticker, inout int numOfShares, out float sharePrice)

Its corresponding input (message name="buy") and output (message name="buyResponse") message elements in WSDL look like Listing 30.9.

   <message name="buy" >
<part name="string" xmlns:partns=http://www.w3.org/2001/XMLSchema
     type="partns:string" />
<part name="numShares" xmlns:partns=http://www.w3.org/2001/XMLSchema
     type="partns:int" />
   </message>

   <message name="buyResponse" >
<part name="numShares" xmlns:partns=http://www.w3.org/2001/XMLSchema
     type="partns:int" />
<part name="sharePrice" xmlns:partns=http://www.w3.org/2001/XMLSchema
     type="partns:float" />
   </message>

Part name numShares occurs in both the input and output messages, making it an inout parameter. On the other hand, part name sharePrice occurs only in the output message, making it an out parameter.

In web-services.xml, you simply specify the style attribute in the <parm> element, as shown in Listing 30.10.

<operation method="buy"... >
 <params>
   <param location="body" class-name="java.lang.String" style="in"
     name="string" xmlns:xsd=http://www.w3.org/2001/XMLSchema type="xsd:string">
   </param>
   <param location="body" class-name="javax.xml.rpc.holders.IntHolder"
     style="inout" name="intHolder" xmlns:xsd=http://www.w3.org/2001/XMLSchema
     type="xsd:int">
   </param>
   <param location="body" class-name="javax.xml.rpc.holders.StringHolder"
     style="out" name="stringHolder" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
     type="xsd:float">
   </param>
 </params>
</operation>

Don’t forget that the WebLogic ServiceGen task will generate all these files for you if you give it a back-end component (a Java class or EJB) that uses Holder classes. However, the preceding discussion should prove helpful if, for some reason, you need to manually add output parameter support for an already-established Web service.

You might think that a UDT Holder class like AddressHolder is itself a UDT that needs an XML Schema and type mapping. That is not the case. Because a Holder class is never referenced inside a service description file, it is an “under-the-covers” UDT that is automatically configured, per JAX-RPC specifications, into the Web service for output parameters.

Now that you’ve seen the client, back-end component, and deployment descriptor of a Web service that uses output parameters, it should be evident that these Holder classes are really nothing special. Holder classes also need serializing/deserializing, except that you don’t need to define a distinct serializer/deserializer for each type of holder object. There is a built-in serializer/deserializer for the javax.xml.rpc.holders.Holder interface. While serializing/deserializing a particular holder object, it simply takes its holder.value object and calls its serializer/ deserializer. That is, your UDT classes always need serialzers/deserializers regardless of their use as in, out, or inout parameters. The only magic that WebLogic Server must perform is intelligently heed the service descriptions’ cues on output arguments and presume use of the appropriate Holder classes in both the client and back-end components.

As mentioned previously, our Web site contains an example called ws-inout that illustrates output parameters. You can find it in chap30ws-inout. This example assumes you already have the WebLogic Server component of WebLogic Platform 7.0 installed or accessible, including the WebLogic examples. You need the Examples server that comes with installing the WebLogic Server Examples bundle. The following are some relevant files you will find in ws-inout:

Follow these steps to run the example:

Try invoking the service to see the SOAP request and SOAP response, and note how the Holder classes are being serialized to XML. Are they? Why or why not?

If you need to create a service which returns an output parameter that is not a built in type, you need to create a Holder class for your user-defined type. In most cases, WebLogic Server’s ServiceGen task will generate these holders for you. In some cases, however, you must edit a generated holder or choose to write one yourself. All the points discussed in “The Holder Interface” section earlier in this chapter apply to UDT holders. In addition, you must follow a naming convention for your class that implements Holder: Type Holder, where Type is the name of your user-defined type. For example, if your UDT is named Address, its Holder class is AddressHolder, as shown in Listing 30.11.

package examples.webservice.holders;
public final class AddressHolder implements javax.xml.rpc.holders.Holder
{
    public Address value;
    public AddressHolder() {
       // set to default initial value
    }
    public AddressHolder(Address addr) {
       value = addr;
    }
}

Remember that you still need to define your user-defined type, with its XML Schema definition, type mapping to serializers/deserializers, as well as the serializer/ deserializer classes themselves (or have them all generated by ServiceGen). Making a Holder class is an additional step. However, the ServiceGen task, by default, attempts to create Holder classes for your UDTs automatically and places them in the package <UDT-package>. holders, where <UDT-package> is the package of its corresponding user-defined type class. You can find these generated Holder classes in the WEB-INFclasses folder of the generated Web service WAR file, or in the client JAR file, if one is available (refer to Figure 30.6).

A handler is simply a Java class that implements the javax.xml.rpc.handler.Handler interface, possessing methods (among others) that can preprocess or process a SOAP request (handleRequest()), SOAP response (handleResponse()), or SOAP fault or exception (handleFault()). All methods in a handler are callbacks; the Web service container will call these methods at the appropriate times. You should not invoke any of these methods from within the Handler class. Figure 30.13 shows how server-side handlers work.

Figure 30.13. Server-side handler data flow with a back-end component.

Note that the ensuing discussion pertains to server-side handlers only. Client-side handlers are not as commonly used and therefore not discussed, but they will have a different execution flow from what is shown here.

When handleRequest() is called, it has access to a SOAP request Msg that comes from the Web service client (unless it is part of a chain, discussed later). The handleRequest() method edits the SOAP message. When the method completes execution, the container then proceeds to invoke the back-end component, passing to it the possibly revised SOAP message Msg'. When the back-end component is complete, the container converts the result into a SOAP response Rsp and then invokes the handleResponse() method of the same handler instance. The XML SOAP response is accessible via the SOAPMessage and can be edited by handleResponse(). The possibly modified SOAP response Rsp' is then sent back to the client.

In the case of a Web service that consists exclusively of handlers and no back-end component, handleRequest() fulfills the request itself, and the response handler (not the container) must create the SOAP response, as shown in Figure 30.14.

Figure 30.14. Handler data flow without a back-end component.

To see a running example of this use case, see the example referenced by “The GenericHandler Class” section later in this chapter.

The Handler interface has the methods shown in Listing 30.12.

// life cycle methods
void init(HandlerInfo config);
void destroy();
// work methods
boolean handleRequest(MessageContext context);
boolean handleResponse(MessageContext context);
boolean handleFault(MessageContext context);
Qname[] getHeaders();

The methods are as follows:

MessageContext, which is actually a SOAPMessageContext object, contains a collection of messages of type SOAPMessage, from which you can retrieve the XML SOAP message parts that you can read or edit. Figure 30.15 illustrates the relationship of these objects.

Figure 30.15. Relationship of handler objects.

MyHandler is the custom Handler class that implements the javax.xml.rpc. handler.Handler interface. From SOAPMessageContext, you can make a series of calls to access any part of the SOAP message, both requests and responses, as shown in Figure 30.16.

Figure 30.16. Methods map for accessing SOAP message elements.

The SOAP message classes shown in Figure 30.16 are all in package javax.xml.soap and are documented in the SOAP with Attachments API for Java (SAAJ) specifications (formerly part of Java API for XML Messaging, or JAXM), accessible from http://java.sun.com/xml/saaj.

Listing 30.13 shows a simple Handler class example. This sample is actually shipped as part of the examples bundle in WebLogic Server 7.0, in

<wl_home>weblogic700samplesserversrcexampleswebserviceshandlerlog

where wl_home is the base install directory for WebLogic Platform. The handler prints out the SOAP request and response messages, but it does not alter them in any way.

package examples.webservices.handler.log;
import java.util.Map;
import javax.xml.rpc.handler.Handler;
import javax.xml.rpc.handler.HandlerInfo;
import javax.xml.rpc.handler.MessageContext;
import javax.xml.rpc.handler.soap.SOAPMessageContext;
import javax.xml.rpc.JAXRPCException;
import javax.xml.namespace.QName;
import weblogic.logging.NonCatalogLogger;
public final class LogHandler implements Handler
{
  private HandlerInfo handlerInfo;
  public void init(HandlerInfo hi) {
    handlerInfo = hi;
  }
  public void destroy() {}
  public QName[] getHeaders() { return handlerInfo.getHeaders(); }
  public boolean handleRequest(MessageContext mc) {
    SOAPMessageContext messageContext = (SOAPMessageContext) mc;
    System.out.println("** Request:" +
            messageContext.getMessage().toString());
    return true;
  }
  public boolean handleResponse(MessageContext mc) {
    SOAPMessageContext messageContext = (SOAPMessageContext) mc;
    System.out.println("** Response: " +
            messageContext.getMessage().toString());
    return true;
  }

  public boolean handleFault(MessageContext mc) {
    SOAPMessageContext messageContext = (SOAPMessageContext) mc;
    System.out.println("** Fault: " +
           messageContext.getMessage().toString());
    return true;
  }
}

This code should be self-explanatory. The passed-in MessageContext parameter in the handlerXXX methods is actually a SOAPMessageContext object and needs to be typecast.

Public myHandler extends GenericHandler {
   Public Boolean handleRequest(..) {
     /* process the request */
   }
   public Boolean handleResponse(..) {
      /* process the response */
   }
   public Boolean handleFault(..) {
      /* process the fault */
   }
}

For finer control and more effective error handling, you can actually delegate the SOAP processing task to multiple Handler classes in a chain. You not only define what particular Handler classes constitute a chain but also the order in which each handler is invoked. Figure 30.17 shows a chain made up of three Handler classes—HandlerA, HandlerB, and HandlerC, defined in that order—and a back-end component, which together work in concert to fulfill a service request.

Figure 30.17. The order of invocation in a handler chain.

Flow of Control

You can dynamically change the control flow among handlers in a chain. That is, you are not bound to always execute every handler in a chain, every time. For instance, in Figure 30.17, HandlerB might decide at execution time to entirely fulfill the request itself or determine that it should not proceed for some reason, such as an exception occurring. Figure 30.18 shows the typical flow of control in a handler chain. All handlers normally return true.

Figure 30.18. Typical handler chain execution.

Between steps 4 and 5 the container would have created an XML SOAP response from the back-end component’s resultset.

So, how can the chain be “blocked” at will? The answer lies in the following three rules:

1. If a handler in a chain returns true, execution proceeds to the next handler or back-end component.

2. If a handler (for example, HandlerB) returns false, however, the chain becomes blocked and the next handler, including the back-end component, is no longer invoked. Instead, that same blocking handler’s (HandlerB’s) handleResponse() method is invoked. From then on, all other preceding handler’s handleResponse() methods will also be invoked.

3. If a handler throws an exception, the chain also becomes blocked, and the next handler, including the back-end component, is no longer invoked. Instead, the same blocking handler’s handleFault() method is invoked. From then on, all other preceding handler’s handleFault() methods will also be invoked.

   Figure 30.19 illustrates the case of Rule 2 in the preceding list.

   

   Figure 30.19. How a false-blocking handler changes control flow.

In this case, who initially creates a SOAP response? The answer is either in step 2 (HandlerB.handleRequest) or step 3 (HandlerB.handleResponse), whichever is more appropriate. The two methods can either use private variables to collaborate or use a shared context, discussed later. In general, if a handler in a chain can potentially alter control flow, that handler should be able to create a specific SOAP response for that blocking situation.

Figure 30.20 illustrates the case of Rule 3.

Figure 30.20. How an exception-blocking handler changes control flow.

If any exception is thrown in a handler, the container will invoke that handler’s handleFault() method. In this case, the container will create the SOAP response in the shared context. If, in step 3, HandlerB.handleFault() returned false, it would block fault chain processing, and henceforth no other handleFault() methods would be called.

package javax.xml.rpc.handler;
public interface MessageContext {
   void setProperty(String name, Object value);
   Object getProperty(String name);
   void removeProperty(String name);
   boolean containsProperty(String name);
   java.util.Iterator getPropertyNames();
}

To instruct your Web service to utilize your Handler classes, you need to perform the following two steps:

<handler-chains>
   <handler-chain name="myChain">
     <handler class-name="myHandlers.HandlerA" >
         <init-params>
            <init-param name="debug" value="on" />
         </init-params>
     </handler>
     <handler class-name="myHandlers.HandlerB" />
     <handler class-name="myHandlers.HandlerC" />
   </handler-chain>
</handler-chains>

<operations>
   <operation name="getQuote"
            method="getQuote"
            component="myEJB"
            handler-chain="myChain" />
</operations>

What if business logic in the back-end component throws an exception? How does the container handle such exceptions? First, it is recommended that your Web service’s external exceptions be mapped to unique SOAP fault codes. External exceptions are those that can be thrown back to the client when an exposed service operation is invoked. Exceptions that may be thrown internally to the service logic do not need to be mapped, just the external ones. Then you should strive to throw SOAPFaultException only from your Web service methods, containing the unique fault code, instead of any user-defined or built-in exceptions. In the SOAPFaultException, a constructor looks like this:

public SOAPFaultException (javax.xml.namespace.QName faultcode,
                           String faultstring,
                           String faultfactor,
                           javax.xml.soap.Detail detail);

The faultcode parameter is the fault code you created to represent a particular business exception. Fault codes, by SOAP specifications, are two-part strings of "SOAP-fault-code.user-code". Because this input fault code string will become part of an XML SOAP message, it may need to be namespace-qualified; hence, it is of type QName. The other parameters help expound on the fault code, as described in the SOAP 1.2 specifications.

The following statement throws a new instance of SOAPFaultException, with a fault code of "Client.InvalidID" in namespace www.bea.com/ws (two arguments to the QName constructor):

throw new SOAPFaultException (new QName(www.bea.com/ws, "Client.InvalidID"),
                             "Employee ID must be numeric",
                             "urn:UserManagement", null);

The WebLogic Web service container takes a SOAPFaultException thrown by a back end component and serializes it into the SOAP response message. On the client side, the <fault> element is deserialized back into a SOAPFaultException. It actually throws a JAXRPCException to the client, with the SOAPFaultException embedded in it.

One distinct advantage of using SOAPFaultException (or one that extends it) exclusively is that your list of possible fault codes for each service method can be documented in the service WDSL file. That way, a client has a more complete description of the service and can program more effective error reporting or recovery mechanisms.

If your back-end component throws any other exception, the WebLogic container will attempt to map it to a SOAPFaultException as best it can. It cannot, however, embed your exception into a JAXRPCException and throw it on the client side because your client may not have access to your exception class definition. SOAPFaultException, on the other hand, is always available to a WebLogic Web service client.

As Figure 29.15 in Chapter 29 shows, you can create asynchronous Web services by using JMS destinations (queues) as back-end components. These queues act as temporary buckets for holding messages, be it input data or a return value. An object that puts a message on a queue is called a producer, and one that receives a message is called a consumer. Although a JMS destination is considered as a back-end component for a Web service, these destinations cannot execute business logic. A listener object such as a message-driven bean (MDB) or a Java class that listens and posts to these queues is needed to house business logic to process service requests.

This section assumes that you are generally familiar with Java Messaging Service and message-driven bean concepts.

JMS and Message-Driven Beans Example

The two types of JMS destinations are queues and topics. Because the use of JMS topics is deprecated in WLS 7.0, we will discuss only queues. A JMS queue implements point-to-point messaging, where a message is guaranteed to be delivered to only one consumer. The producer places a message in a queue, and a consumer who is subscribed to the queue (also called a listener) retrieves it. Perhaps these concepts are best explained in the context of an example that is provided on our Web site. Figure 30.21 shows the components in this example.

Figure 30.21. Players in a JMS-implemented Web service.

In this sample, the client is split into two separate programs:

• SubmitClient—. Invokes the submitData Web service operation, passing it data to be processed

• QueryClient—. Invokes the requestData operation, retrieving the results of invoking submitData

As you can see, the JMS producer for destination inqueue is actually the SOAP servlet for the submitData operation. The JMS consumer for inqueue is the listener ProcessorMDB, a message-driven bean that is invoked to process the service data. ProcessorMDB then places its processing results in outqueue, the requestData operation’s JMS queue. That is, ProcessorMDB is both a consumer (of inqueue) and a producer (to outqueue).

Like any message-driven bean, ProcessorMDB must implement an onMessage() method and subscribe to inqueue as a listener. When a message is produced in inqueue, the container automatically makes available an instance of ProcessorMDB (it instantiates one or gets one from the pool) and invokes its onMessage() method. The business logic for processing the input data to the submitData operation is embodied in the onMessage() method of ProcessorMDB.

This sample incorporates a very simple use case:

1. SubmitClient calls the submit operation, passing it a string. The message type of JMS destination inqueue is java.lang.String (this is specified in the serviceGen Ant task of Listing 30.21).

2. ProcessorMDB takes the input string, prefixes another string to it, and then posts the new concatenated string to outqueue.

3. QueryClient calls the query operation (with no arguments) and gets back the concatenated string.

public void onMessage(Message msg) {

  // WebLogic JMS-backed service always uses ObjectMessage
2 ObjectMessage om = (ObjectMessage) msg;

  try {
    String text = (String) om.getObject();

    // Get connection & start it
8   Context ctx = getInitialContext();
    QueueConnectionFactory factory = (QueueConnectionFactory)
       ctx.lookup("weblogic.jms.ConnectionFactory1");
    Queue queue = (Queue) ctx.lookup("weblogic.jms.outqueue");

13  QueueConnection connect = factory.createQueueConnection();

    QueueSession session = connect.createQueueSession(false, Session.AUTO_ACKNOWLEDGE);

17  QueueSender sender = session.createSender( queue );

19  connect.start();

    // Post the revised message in outqueue
    ObjectMessage outMsg = session.createObjectMessage();
23  outMsg.setObject(text + " stays mainly in the Plain.");
    sender.send(outMsg);
    connect.close();
  }
  catch(JMSException ex) {
    ex.printStackTrace();
  }
  catch (NamingException ne) {
    ne.printStackTrace();
  }
}

<ejb-jar>
 <enterprise-beans>
    <message-driven>
      <ejb-name>exampleMessageDriven1</ejb-name>
      <ejb-class>examples.webservices.message.ProcessorMDB</ejb-class>
      <transaction-type>Container</transaction-type>
      <message-driven-destination>
8       <destination-type>javax.jms.Queue</destination-type>
      </message-driven-destination>
    </message-driven>
 </enterprise-beans>
</ejb-jar>

<weblogic-ejb-jar>
  <weblogic-enterprise-bean>
    <ejb-name>exampleMessageDriven1</ejb-name>
    <message-driven-descriptor>
      <pool>
        <max-beans-in-free-pool>200</max-beans-in-free-pool>
        <initial-beans-in-free-pool>20</initial-beans-in-free-pool>
      </pool>
9     <destination-jndi-name>weblogic.jms.inqueue</destination-jndi-name>
    </message-driven-descriptor>
    <jndi-name>examplesMessageDriven1</jndi-name>
  </weblogic-enterprise-bean>
</weblogic-ejb-jar>

1   <servicegen  destEar="${source}jms_send_queue"
                 contextURI="WebServices" >
        <!-- PRODUCER WEB SERVICE DEFINITION -->
4       <service JMSDestination="weblogic.jms.inqueue"
                 JMSAction="send"
                 JMSDestinationType="queue"
                 JMSConnectionFactory="weblogic.jms.ConnectionFactory1"
                 JMSOperationName="submit"
                 JMSMessageType="java.lang.String"
                 generateTypes="True"
                 targetNamespace="http://tempuri.org"
                 serviceName="SubmitService"
                 serviceURI="/SubmitService"
                 expandMethods="True">
                 <client packageName="examples.message" useServerTypes="true" />
        </service>
        <!-- CONSUMER WEB SERVICE DEFINITION NOT SHOWN -->
    </servicegen>

<application>
  ...
 <module>
   <ejb>myMDB.jar</ejb>
 </module>
  ...
</application>

<web-services>
  <web-service ..>
     <components>
        <jms-send-destination name="inqueue"
              connection-factory="weblogic.jms.ConnectionFactory">
        </jms-send-destination>
        <jms-receive-queue>
              connection-factory="weblogic.jms.ConnectionFactory">
        </jms-receive-queue>
     </components>
     <operations ..>
        <operation invocation-style="one-way" name="submit" component="inqueue" >
        </operation>
        <operation invocation-style="request-response" name="query"
             component="outqueue" >
        </operation>
     </operations>
  </web-service>
</web-services>

There are several ways of protecting your WebLogic Web services:

You can choose to implement any or all of these techniques, and in any combination. You can set authorization for WebLogic Web services in varying degrees; they are listed here in order from most restrictive to least restrictive:

Figure 30.22 attempts to guide you through the process of deciding what security measures to implement for your Web service.

Figure 30.22. Deciding which Web service security features should be used.

The following sections explain each task shown in Figure 30.22.

java -Dweblogic.webservice.client.ssl.trustedcerts=c:democert.pem
     -Dbea.home=c:ea
     -Djava.protocol.handler.pkgs=weblogic.webservice.client TraderClient

<servicegen ... >
   <service ejbJar="traderBean.jar"
               protocol="https"
               serviceName="TraderService"
   ...
   </service>
</servicegen>

<web-service name="Trader"
             targetNamespace="www.bea.com/Trader";
             protocol="https"
             uri="/TraderWS" ... >
...
</web-service>

<web-app>
    ...
    <security-constraint>
      <web-resource-collection>
        <web-resource-name>TraderService</web-resource-name>
        <description>The Trader Web Service</description>
        <url-pattern>/TraderService</url-pattern>
        <http-method>GET</http-method>
        <http-method>POST</http-method>
      </web-resource-collection>
   </security-constraint>
   ...
</web-app>

TraderService_Impl ts = new TraderService_Impl();
TraderServicePort trader = ts.getTraderServicePort(";UserName";, "Password");
trader.buy("BEAS");

<ejb-jar>
  ...
  <assembly-descriptor>
    ...
    <security-role>
       <description>Gold Member Clients</description>
       <role-name>GoldStatusRole</role-name>
    </security-role>
    <method-permission>
       <description>Gold members can buy & sell</description>
       <role-name>GoldStatusRole</role-name>
       <method>
          <ejb-name>TraderBean</ejb-name>
          <method-name>buy</method-name>
          <method-name>sell</method-name>
       </method>
    </method-permission>
    ...
  </assembly-descriptor>
  ...
</ejb-jar>

<weblogic-ejb-jar>
   ...
   <security-role-assignment>
      <role-name>GoldStatusRole</role-name>
      <principal-name>gold_customer</principal-name>
   </security-role-assignment>
   ...
</weblogic-ejb-jar>

If you are able to bring up the Web service home page, chances are the Web service has been successfully deployed. On the home page, make sure that all the operations you intended are listed. Try invoking the service by clicking each operation name link. It is also important to click the WSDL file link and examine the WSDL file that is displayed. Make sure the service endpoint is correct. See Chapter 29 for more information on Web service home pages.

You can see the Web services components listed as deployed in the WebLogic Administration Console. After you invoke this console (for example, http://localhost:7001/console for the Examples server), go to examples, Servers, Deployments, Web Service Components. Figure 30.23 shows the console with these nodes expanded (refer to arrow D).

Figure 30.23. WebLogic Administration Console showing Web service components.

Recall that a WebLogic Web service is composed of the following J2EE components:

Now look for the Web services that are deployed and their WAR and JAR files. In Figure 30.23, you can see that two Web service applications are deployed, in the Application column of the right pane (arrow B). These are mangled application names derived from the actual Web service EAR file or folder name. The Name column (arrow A) of the same table shows their WAR files. You can see their JAR files, if any, by clicking (in this example) examples, Servers, Deployments, Applications, _appsdir_jms_send_queue_dir, where you will find both the Web service’s WAR and JAR files (arrow C).

If you are familiar with the format of the web-services.xml file, you can look at this generated file to ascertain that you have correctly defined your Web service characteristics to the ServiceGen task. You can see the serializer and deserializer classes that are being used during service invocation, as well as any user-defined type definitions.

You can cause the SOAP requests and responses to be displayed on either the client or server command prompts. To do so, specify the following system property when invoking your Java client:

java -Dweblogic.webservice.verbose=true yourPackage.YourJavaClient

To see the SOAP messages on the server side, specify the same system property when starting WebLogic Server, as follows:

java -Dweblogic.webservice.verbose=true ... weblogic.Server

Again, doing this shows the output of the server-side handlers, if any.

Sometimes stack traces and exception messages may not show up on the command console where WebLogic Server was started. This is the time to check the log files that WebLogic Server keeps on every client request and component execution. For the Examples server, you can check out the following log files:

<BEA-HOME>weblogic700samplesconfigexamplesexamplesServerexamplesServer.log

<BEA-HOME>weblogic700samplesserverconfigexampleslogswl-domain.log

One of the basic tenets of Web services is that they should employ coarse-grained interactions. This point is akin to the EJB design principle that entity beans are inherently fine-grained and hence should be fronted by session beans. In other words, a Web service interaction should be embodied in as few operation calls as possible. This approach has several advantages:

Remember to export services, not your application components. You should not be able to detect your component architecture through the Web service. Why? First of all, doing so would almost inevitably make your Web service too fine-grained. Second, you don’t want your Web service to be too tightly coupled with your component architecture. That way, your internal system architecture can change and evolve without necessarily affecting your published Web services. If possible, create a separate “front,” or layer of wrapper code (maybe EJBs), between your components and the Web service. This greatly increases flexibility and reduces fragility. Remember, your service description or WSDL will tend to outlive your application components.

Your Web service should offer interactions at a business level, utilizing the business vocabulary for the particular domain. In fact, the engineers and architects who are building such services may not be the best people to design the service interactions (operations); perhaps a business or corporate developer is more fitting. Incidentally, that is the goal of WebLogic Workshop: to empower business professionals—that is, non-programmer types—to create enterprise Web services.

Loose coupling means that the client should not in any way have knowledge or dependence on how a service is implemented. Also, a client’s interaction with the service should be within the confines of a published or public interface—no secret backdoors or clandestine agreements (especially error codes or function codes). Presume nothing about your client or server, except what is published in a service description, like a WSDL file. Now that we’ve said that, the truth is that WSDL files today do not carry enough semantic information, so some presumptions must be made; for instance, you can only deduce that a service named StockTrader with an operation called buy must be a request to buy shares of company stock.

Synchrony or asynchrony in a Web service solution can make or break the model. In general, you should use a synchronous (RPC) Web service when its operation response or result is necessary for the client process or execution to continue. Asynchronous interactions are generally more natural for application-to-application communications because they can hide mismatches in the performance and availability of the communicating systems. Asynchrony also tends to localize interaction failures; because timing is not an issue, there is likely no “Domino Effect.” Therefore, asynchrony is usually necessary in cases where there are complex, multi-party interactions or transactions.

The SOAP specification distinguishes operations only by name, without regard for their signatures. Whereas Java allows two methods of the same name to co-exist if they have different argument lists, a SOAP message or WSDL file cannot distinguish between the two. This is not to say that your Web service back-end Java components cannot have overloaded methods. It can; you just cannot expose all such overloaded methods without having to rename them for uniqueness in the web-services.xml file. You can also select one particular overloaded method for inclusion into the Web service without renaming it by specifying both the method name and its signature when mapping the method to an operation in the web-services.xml file.

Web services do not always provide the solution you’re seeking either. More well established distributed computing technologies such as RMI, JMS, or CORBA are still relevant and, in fact, solve many problems that Web services cannot yet address. A Web service is not meant to replace all binary protocols. The biggest claim about Web services thus far is that they can tie together totally disparate and incompatible systems, regardless of their programming language or platform legacies.