Defines mappings between the return type of the method marked by this annotation and XML message data.
Note: The Web Service control uses the @jc:return-xml annotation instead of the @jws:return-xml annotation. The functionality is the same.
@jws:return-xml
[schema-element="schemaPrefix:schemaType"]
[xquery=""]
[xquery-ref=""]
[xml-map=""]
[include-java-types="javaTypes"]
Optional. The name of an XML schema type, such as "xsd:string". Schema types are defined in the file(s) specified by the service's @common:schema tag.
Optional. Specifies an XQuery expression to be run on the values passed as parameters to this operation.
Optional. Specifies a file containing an XQuery expression to be run on the values passed as parameters to this operation.
Optional. Indicates that parameters in the annotated declaration should be mapped to XML message values as described in an XML map or script.
Optional. One or more Java types that should be used for serializing message data.
Remarks
Use the @jws:return-xml annotation to define how the data received or sent via the return value should be treated. Each of the annotation's attributes represents a characteristic of the translation between Java data types and XML values. (The @jws:parameter-xml annotation applies the same functionality to a method or callback's parameter values.)
The include-java-types attribute lists Java data types that should be used when the Java type sent or received in an XML message may be a subclass of a type in the declaration. Consider the following declaration:
public Address getCurrentAddress(String employeeID)
{...}
To support addresses in the United States and Great Britain, the Address object returned by this method would need to support data for the postal code formats of either nation. To enable this support, and to keep things simple, you might implement two subclasses of the Address object—one including a field for usPostalCode, the other with a field for gbPostalCode. Either of these subclasses, USAddress and GBAddress, are (from the Java perspective) legal as a type to return from the updateAddress method because they are subclasses of Address.
However, as the updateAddress method is declared, WebLogic Server has no way of knowing which subclasses of Address the method should be sent. To respect the exact interface you have defined with this declaration, WLS will serialize all outgoing compatible objects as Address—the type you have specified in the declaration.
To specify that USAddress and GBAddress (along with data members unique to those types) should be appropriately returned by your method, specify them with the include-java-types attribute, as follows:
/**
* @common:operation
* @jws:return-xml include-java-types="com.myCompany.USAddress
* com.myCompany.GBAddress"
*/
public Address updateAddress(String employeeID)
{...}
The include-java-types attribute is also useful when a Java Collection class is being converted. Java Collection classes contain Objects, which cannot be successfully converted to or from XML without additional information. The include-java-types attribute may contain a space-separated list of Java types that are stored in the Collection. For example, if a method returns an ArrayList that may contain Integers and Strings, specify include-java-types as "Integer String".
Use the xquery attribute to specify an XQuery expression for mapping an XML message to the operation's return value. Use the xquery-ref attribute to specify a file that contains an XQuery expression.
For more information about XQuery, see Introduction to XQuery Maps.
Use the xml-map attribute to specify that the return value of the declaration should be mapped to XML values using the XML map provided. The xml-map attribute may include either the text of an XML map or code to invoke one, or code to invoke a script. Note that although XML maps are still supported in WebLogic Workshop 8.1, they are deprecated in favor of XQuery expressions. For more information on XML maps, see Why Use XML Maps?
Use the schema-element attribute to indicate to that this method or callback supports a specific complex schema type. You should only use this attribute when your implementation is aware of the type you and handles it appropriately.