Programming WebLogic Web Services

source2wsdd Tag Reference

The following topics describe the source2wsdd Javadoc tags:

• Overview of Using source2wsdd Tags
• @wlws:webservice
• @wlws:operation
• @wlws:part partname
• @wlws:exclude

 

---

Overview of Using source2wsdd Tags

The source2wsdd Ant task generates a web-services.xml deployment descriptor file from the Java source file for a stateless session EJB- or Java class-implemented WebLogic Web Service. The web-services.xml deployment descriptor file contains information that describes one or more WebLogic Web Services. This information includes details about the back-end components that implement the operations of a Web Service, the non-built-in data types used as parameters and return values, the SOAP message handlers that intercept SOAP messages, and so on. As is true for all deployment descriptors, web-services.xml is an XML file.

This chapter describes the optional Javadoc tags you can include in the Java source file that the source2wsdd Ant task uses to automatically generate the web-services.xml file. If your Java source file does not contain any Javadoc tags, the source2wsdd Ant task makes a best guess when adding elements to the file, such as the name of the Web Service, the operations that should be exposed, and so on. If, however, you want more control over the generated web-services.xml file, use the source2wsdd Javadoc tags to specify exactly what your Web Service looks like.

There are three source2wsdd Javadoc tags:

• @wlws:webservice, used in the Javadoc for the class that implements your Web Service.
• @wlws:operation, used in the Javadoc for a method that you want to expose as a Web Service operation.
• @wlws:part partname used in the Javadoc for a method that has been exposed as an operation and you want to customize the description of its parameters and return values.

Each tag has a set of attributes which correspond to the appropriate element in the web-services.xml file that it is describing.

 

---

@wlws:webservice

The source2wsdd Ant task uses the @wlws:webservice tag to populate the <web-service> element of the generated web-services.xml file.

You specify the @wlws:webservice tag in the Javadoc of the class that implements your Web Service.

The following example shows how to use the @wlws:webservice tag in the Javadoc that documents a Java class:

/** 
 * PurchaseOrderService - a service to show different features of 
 * Weblogic Web Services.
 * 
 * @wlws:webservice 
 *    targetNamespace="http://www.bea.com/po-service/"
 *    name="PurchaseOrderService"
 *    portName="POPort"
 *    portTypeName="POPort"
 *    protocol="https"
*/
public class POService {
  ...
}

In the example, the POService Java class is the back-end component that implements a Web Service whose name is PurchaseOrderService (specified with the name attribute of the @wls:webservice tag). The <port> and <portType> elements in the generated WSDL for the Web Service are both POPort. Finally, client applications access the Web Service using HTTPS rather than the default HTTP.

The following table lists all the attributes of the @wlws:webservice tag.

 

---

@wlws:operation

The source2wsdd Ant task uses the @wlws:operation tag to populate the corresponding <operation> element in the generated web-services.xml file.

By default, every public method of the Java class or EJB that implements a Web Service is exposed as an operation in the generated WSDL. The source2wsdd Ant task uses information from the method, such as its signature, to populate the <operation> element; use the @wlws:operation Javadoc tag to change some of the default information, such as the operation name. Use the @wlws:exclude tag to specify that a public method not be exposed as a Web Service operation.

You specify the @wlws:operation tag in the Javadoc of the method that implements the operation.

The following example shows how to use the @wlws:operation tag in the Javadoc that documents a method:

/** 
   * A one way call. Client will not wait for this method to
   * complete.
   *
   * Note: A one way call must have a void return type.
   *
   * @wlws:operation 
   *       invocation-style="one-way"
   *       Name="sendTime"
   */
  public void oneWayCall( long time ){
    .....
  }

In the example, the oneWayCall method implements an operation of a Web Service called sendTime, which is the published name of the operation in the WSDL. The operation is one-way, which means that the client application does not receive a return value.

The following table lists all the attributes of the @wlws:operation tag.

 

---

@wlws:part partname

The source2wsdd Ant task uses the @wlws:part tag to populate the corresponding <param> and <return-param> elements that describe the parameters and return values for the operation in the generated web-services.xml file.

Every public method of the Java class or EJB that implements a Web Service is exposed as an operation in the generated WSDL. The source2wsdd Ant task uses information from the method signature to determine basic information about the parameters and return value of the operation. If, however, you want to change some of this default information, specify the @wlws:part tag in the Javadoc of the method. In particular, use the attributes of the tag when you want:

• The name of the parameters and return values in the generated WSDL to be different from those of the method that implements the operation.
• To map a parameter to a name in the SOAP header request or response.
• To use out or in-out parameters.
• To explicitly specify the XML and Java represenation of the data type of the paramter or return value.

Use the @wlws:part tag in the Javadoc of the method that implements the operation. Specify the name of the parameter right after the tag and before the attributes, as shown:

@wlws:part paramName attribute="value" 

To specify the return value, use the hard-coded word return, as shown:

@wlws:part return attribute="value" 

The following example shows how to use the @wlws:part tag in the Javadoc that documents a method:

/** 
   * operation with headers
   *
   * @wlws:part addressInHeader location="header" 
   * @wlws:part dataInHeader location="header" 
   *
   * @wlws:part return location="body" 
   */
  public BaseData methodWithHeaders( String addressInHeader, 
      int idInBody, BaseData dataInHeader ){

    dataInHeader.setAddress( addressInHeader );
    dataInHeader.setId( idInBody );

    return dataInHeader;
  }

In the example, when a client application invokes the methodWithHeaders operation, the addressInHeader and dataInHeader input parameters are located in the header of the SOAP request. When WebLogic Server responds to the invocation of the operation, the return value is located in the body of the SOAP response.

The following table lists all the attributes of the @wlws:part tag.

 

---

@wlws:exclude

The source2wsdd Ant task uses the @wlws:exclude tag to exclude public methods of the Java source file from the list of generated Web Service operations.

By default, every public method of the Java class or EJB that implements a Web Service is exposed as an operation in the generated WSDL. If you do not want to expose a public method, you must explicitly add the @wlws:exclude tag to the method's Javadoc.

The following example shows how to use the @wlws:exclude tag:

  /**
   * A public method that is not exposed as a Web Service operation.
   *
   * @wlws:exclude
   */
  public void dontExposeThisMethod(){

  }

In the example, the source2wsdd will not add the public method dontExposeThisMethod() to the list of Web Service operations in the generated webservices.xml file, and thus it will also not appear in the generated WSDL file.

The @wlws:exclude tag does not have any attributes.

Contact BEA |  Feedback |  Privacy  |