@jws:return-xml Tag

Defines mappings between the return type of the method marked by this tag and XML message data.

# Syntax

    @jws:return-xml
    	[include-java-types="javaTypes"]
    	[schema-element="schemaPrefix:schemaType"]
    	[xml-map :: mapText ::]

# Attributes

include-java-types

Optional. One or more Java types that should be used for serializing message data.

schema-element

Optional. The name of an XML schema type, such as "xsd:string".

xml-map

Optional. Indicates that the return value in the annotated declaration should be mapped to XML message values as described in an XML map or script.

# Remarks

Use the @jws:return-xml tag to define how the data received or sent via the return value should be treated. Each of the tag's attributes represents a characteristic of the translation between Java data types and XML values. (The @jws:parameter-xml tag applies the same functionality to a method or callback's parameter values.)

##### include-java-types

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:

    /**
     * @jws: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".

##### schema-element

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.

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. For more information on XML maps, see Why Use XML Maps?

Related Topics

@jws:parameter-xml Tag

How Do XML Maps Work?

ConsolidateAddress.jws Sample

ExplicitTypes.jws Sample

InputMapMultiple.jws Sample

OutputMap.jws Sample

OutputScriptMap.jws Sample

SimpleMap.jws Sample