Specifies characteristics for marshaling data between XML messages and the data in a Java declaration's parameters.
Note: The Web Service control uses the @jc:parameter-xml annotation instead of the @jws:parameter-xml annotation. The functionality is the same.
@jws:parameter-xml
[schema-element="schemaPrefix:schemaType"]
[xquery=""]
[xquery-ref=""]
[xml-map=""]
[include-java-types="javaTypes"]
Required if the xquery or xquery-ref attributes are specified; otherwise 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.
Use the @jws:parameter-xml annotation to define how the data received or sent via parameters should be treated. Each of the annotation's attributes represents a characteristic of the translation between Java data types and XML values. (The @jws:return-xml applies the same functionality to a method or callback's return 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.
public void updateAddress(Address newAddressData)
To support addresses in the United States and Great Britain, the Address object passed to 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 legal as parameters to the updateAddress method.
However, as the updateAddress method is declared, WebLogic Server has no way of knowing which subclasses of Address the method should accept as parameter types. To respect the exact interface you have defined with this declaration, WLS will serialize all incoming 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 passed to your method, specify them with the include-java-types attribute, as follows:
/**
* @common:operation
* @jws:parameter-xml include-java-types="com.myCompany.USAddress
* com.myCompany.GBAddress"
*/
public void updateAddress(Address newAddressData)
{...}
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 accepts 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 parameters. 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 parameters 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 your service supports specific complex schema types. You should only use this attribute when your implementation is aware of the type and handles it appropriately.