Programming WebLogic Web Services
source2wsdd Tag Reference
The following topics describe the source2wsdd
Javadoc tags:
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:
|
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.