Skip navigation.
Downloads | Product Documentation | Support

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.

Table C-1 Attributes of the @wlws:webservice source2wsdd Tag

Attribute Name | Description | Default Value if Attribute is Not Specified
--- | --- | ---
Name | The name of the Web Service, published in the WSDL. | The name of the class in the annotated source code.
portName | Name of the `<port>` child element of the `<service>` element of the dynamically generated WSDL of this Web Service. | The name of the Web Service with `Port` appended. For example, if the name of this Web Service is `TraderService`, the default port name is `TraderServicePort`.
portTypeName | Name of the default `<portType>` element in the dynamically generated WSDL of this Web service. | The name of this Web Service with `Port` appended. For example, if the name of this Web service is `TraderService`, the default portType name is `TraderServicePort`.
protocol | Protocol over which the Web Service is invoked. Valid values are `http` and `https`. | Default value is `http`.
Style | Specifies whether the Web Service has RPC-oriented or document-oriented Web Service operations. RPC-oriented WebLogic Web Service operations use SOAP encoding. Document-oriented WebLogic Web Service operations use literal encoding. You can use the following two values to generate document-oriented Web Service operations: `document` and `documentwrapped`. If you specify `document` for this attribute, the resulting Web Service operations take only one parameter. This means that the methods that implement the operations must also have only one parameter. In this case, if `source2wsdd` encounters methods that have more than one parameter, `source2wsdd` ignores the method and does not generate a corresponding Web Service operation for it. If you specify `documentwrapped`, the resulting Web Service operations can take any number of parameters, although the parameter values will be wrapped into one complex data type in the SOAP messages. If two or more methods of your stateless session EJB or Java class that implement the Web Service have the same number and data type of parameters, and you want the operations to be document-oriented, you must specify `documentwrapped` for this attribute rather than `document`. Valid values for this attribute are `rpc`, `documentwrapped`, and `document`.Because the `style` attribute applies to an entire Web Service, all operations in a single WebLogic Web Service must be either RPC-oriented or documented-oriented; WebLogic Server does not support mixing the two styles within the same Web Service. | Default value is `rpc`.
targetNameSpace | The namespace URI of the Web Service. | Default value is `http://tempuri.org`.
Uri | Web Service URI portion of the URL used by client applications to invoke the Web Service. Note: Be sure to specify the leading "/", such as `/TraderService`. Note: You can also specify the URI using the `serviceURI` attribute of the `source2wsdd` Ant task. If you specify the URI in both places, and they are different from each other, the URI specified by the `@wlws:webservice` Javadoc tag takes precedence. | Although you are not required to specify the `Uri` attribute of the `@wlws:webservice` tag, you are required to specify the `serviceURI` of the `source2wsdd` Ant task. This means that there is no default value and that at some point you must specify the Web Service URI.

# @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.

Table C-2 Attributes of the @wlws:operation source2wsdd Tag

Attribute Name | Description | Default Value if Attribute is Not Specified
--- | --- | ---
Handler-chain | Name of the SOAP message handler chain that, together with the method, implements the operation. The name of this attribute corresponds to the `name` attribute of the appropriate `<handler-chain>` element in the file that contains the SOAP handler chain information. You must write this file manually and specify its location with the `handlerInfo` attribute of the `source2wsdd` Ant task. | If you do not specify this attribute, no handler-chain information is added to the `<operation>` element in the `web-services.xml` file.
invocation-style | Specifies whether the operation both receives a SOAP request and sends a SOAP response (request-response), or whether the operation only receives a SOAP request but does not send back a SOAP response (one-way). Valid values are `request-response` and `one-way`. Note: If the back-end component that implements this operation is a method of a stateless session EJB or Java class and you set this attribute to `one-way`, the method must return `void`. | Default value is `request-response`.
Name | The name of the operation. This is the name that is published in the WSDL of the Web Service. | The name of the method in the Java source file.

# @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.

Table C-3 Attributes of the @wlws:part source2wsdd Tag

Attribute Name | Description | Default Value if Attribute is Not Specified
--- | --- | ---
class-name | Java class name of the Java representation of the data type of the inpur or return parameter. | The data type of the parameter or return value of the operation. Note: If the mapping between the XML and Java representations of the parameter or return value is ambiguous (such as `xsd:int` mapping to either the `int` Java primitive or `java.lang.Integer`), and you do not specify this attribute, WebLogic Server makes its best as to which mapping is correct.
location | Part of the request or response SOAP message (header, body, or attachment) that contains the value of the input or return parameter. Valid values for this attribute are Body, Header, or `attachment`. If you specify `Body`, the value of the input or return parameter is contained in the SOAP Body (of either the request or response, depending on whether the parameter is input or return). If you specify `Header`, the value contained in a SOAP Header element whose name is the value of the `type` attribute. If you specify `attachment`, the value of the parameter is contained in the SOAP Attachment rather than the SOAP envelope. As specified by the JAX-RPC specification, only the following Java data types can be contained in the SOAP Attachment: `java.awt.Image` `java.lang.String` `javax.mail.internet.MimeMultiport` `javax.xml.transform.Source` javax.activation.DataHandler | The default value is Body.
name | The name of the parameter. This is the name that is published in the WSDL of the Web Service in the `<part>` element. | For input parameters, the default value is the name of the parameter in the method's signature. The default value of the return parameter is `results`.
style | Style of the input parameter: either a standard input parameter, an out parameter used as a return value, or an in-out parameter for both inputting and outputting values. Valid values for this attribute are `in`, `out`, and `inout`. If you specify a parameter as `out` or `inout`, the Java class of the parameter in the back-end component's method must implement the `javax.xml.rpc.holders.Holder` interface. | The default value is `in`.
type | XML Schema data type of the parameter. If you specify this attribute of the `@wlws:part` tag, you must also specify a `types.xml` file using the `typesInfo` attribute of the `source2wsdd` Ant task. You must also ensure that the XML Schema data type you specify for this tag exists in the `types.xml` file, and that the two element names match exactly. If the `source2wsdd` Ant task does not find the name of this XML Schema data type in the`types.xml` file, the Ant task generates its own data type mapping information, which could lead to incorrect behavior of your Web Service. | If you do not specify this attribute, the XML data type is based on the Java data type of the parameter.

# @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.