Building WebLogic Web Services Manually


The preceding section showed how WebLogic Web services can be created relatively easily with the tools and tricks provided. After you create your back-end components , exposing them as Web services is an almost trivial task because most of the needed files are generated for you. One of these files is the Web-services deployment descriptor, a new construct that someday should become part of J2EE (refer to JSR 109). In some instances, creating this file manually or editing a generated file is necessary, as in these examples:

  • If you are using a JMS destination for a back-end component. (However, in WLS SP1 the ServiceGen Ant task can now also generate a JMS-based Web service.)

  • If you are using handlers or non-conforming user -defined types.

The Web Service Deployment Descriptor

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.

graphics/30fig11.gif

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:

  • Back-end components ” Contain business logic for fulfilling a service operation request. They reference deployed EJBs, classes, or objects in the JNDI tree. This section is optional.

  • User-defined data types ” Used in the Web service calls, defined in XML Schemas. These data types are non “built-in types and therefore must be specified by the user for publishing in the WSDL file. You can specify as many data types as necessary. This section is optional.

  • UDT mappings ” Specify what Java class and serializer/deserializer class each UDT corresponds to. This section is required if UDTs are defined.

  • Operations section ” Lists what operations are available in this service and what business logic back-end component will be invoked to fulfill the request. This section is required.

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.

Listing 30.3 The Sample web-services.xml File
 <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-INF\classes 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.

graphics/30fig12.gif



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