Java Classes

A Java class can be mapped to different XML schema type and/or an XML element. The following guidelines apply to the usage of annotations at the class level.

@XmlType Annotation - Anonymous Type

Guideline: Prefer mapping class to named XML schema type rather than an anonymous type for a better .NET type binding.

The @XmlType annotation is used to customize the mapping of a Java class to an anonymous type. .NET binds an anonymous type to a .NET class - one per reference to the anonymous type. Thus, each Java class mapped to an anonymous type can generate multiple classes on the .NET client.

Example: Mapping a Java class to an anonymous type using @XmlType

//-- Java code fragment
public class PurchaseOrder {
    public java.util.List<Item> item;
}
@XmlType(name="")
public class Item {
    public String productName;
    ...
}

//-- Schema fragment
<xs:complexType name="purchaseOrder">
    <xs:sequence>
        <xs:element name="item">
            <xs:complexType>
                <xs:sequence>
                    <xs:element name="productName" type="xs:string"/>
                </xs:sequence>
            </xs:complexType
>        </xs:element>
    </xs:sequence>
</xs:complexType>

// C# code generated by svcutil
public partial class purchaseOrder
{
    private purchaseOrderItem[] itemField;
    System.Xml.Serialization.XmlElementAttribute("item", 
        Form=System.Xml.Schema.XmlSchemaForm.Unqualified, IsNullable=true, Order=0)]
    public purchaseOrderItem[] item
    {
        get {
            return this.itemField;
        }

        set {
            this.itemField = value;
        }
    }
}

// .NET auto generated code from schema
public partial class purchaseOrderItem
{
    private string productNameField;
    public string productName {
        get { return this.productNameField; }
        set { this.productNameField = value; }
    }
}

@XmlType Annotation - xs:all

Guideline: Avoid using XmlType(propOrder=:{}).

@XmlType(propOrder={}) maps a Java class to an XML Schema complex type with xs:all content model. Since XML Schema places severe restrictions on xs:all, the use of @XmlType(propOrder={}) is therefore not recommended. So, the following example shows the mapping of a Java class to xs:all, but the corresponding .NET code generated by svcutil is omitted.

Example: Mapping a class to xs:all using @XmlType

//-- Java code fragment
@XmlType(propOrder={})
public class USAddress {
    public String name;
    public String street;
}

//-- Schema fragment
<xs:complexType name="USAddress">
    <xs:all>
        <xs:element name="name" type="xs:string"/>
        <xs:element name="street" type="xs:string"/>
        ...
    </xs:all>
</xs:complexType>

@XmlType Annotation - Simple Content

Guideline: A class can be mapped to a complexType with a simpleContent using @XmlValue annotation. .NET binds the Java property annotated with @XmlValue to a property with name "value".

Example: Class to complexType with simpleContent

//-- Java code fragment
public class InternationalPrice
{
    @XmlValue
    public java.math.BigDecimal price;
    
    @XmlAttribute public String currency;
}

//-- Schema fragment
<xs:complexType name="internationalPrice">
    <xs:simpleContent>
        <xs:extension base="xs:decimal">
            xs:attribute name="currency" type="xs:string"/>
        </xs:extension>
    </xs:simpleContent>
 </xs:complexType>

// .NET auto generated code from schema
public partial class internationalPrice
{
    private string currencyField;
    private decimal valueField;
    public string currency
    {
        get { return this.currencyField; }
        set { this.currencyField = value;}
    }

    public decimal Value
    {
        get { return this.valueField; }
        set { this.valueField = value;}
    }
}