The following guidelines apply to mapping of JavaBeans properties and Java fields, but for brevity Java fields are used.
Guideline: The @XmlElement annotation maps a property or field to an XML element. This is also the default mapping in the absence of any other JAXB 2.0 annotations. The annotation parameters in @XmlElement can be used to specify whether the element is optional or required, nillable or not. The following examples illustrate the corresponding bindings in the .NET client.
Example: Map a field or property to a nillable element
//-- Java code fragment public class PurchaseOrder { // Map a field to a nillable XML element @javax.xml.bind.annotation.XmlElement(nillable=true) public java.math.BigDecimal price; } //-- Schema fragment <xs:complexType name="purchaseOrder"> <xs:sequence> <xs:element name="price" type="xs:decimal" nillable="true" minOccurs="0" /> </xs:sequence> </xs:complexType> // .NET auto generated code from schema public partial class purchaseOrder { private System.Nullable<decimal> priceField; private bool priceFieldSpecified; public decimal price { get { return this.priceField; } set { this.priceField = value; } } public bool priceSpecified { { get { return this.priceFieldSpecified; } set { this.priceFieldSpecified = value;} } }
Example: Map a property or field to a nillable, required element
//-- Java code fragment public class PurchaseOrder { // Map a field to a nillable XML element @XmlElement(nillable=true, required=true) public java.math.BigDecimal price; } //-- Schema fragment <xs:complexType name="purchaseOrder"> <xs:sequence> <xs:element name="price" type="xs:decimal" nillable="true" minOccurs="1" /> </xs:sequence> </xs:complexType> // .NET auto generated code from schema public partial class purchaseOrder { private System.Nullable<decimal> priceField; public decimal price { get { return this.priceField; } set { this.priceField = value; } } }
Guideline: A property or field can be mapped to an XML attribute using @XmlAttribute annotation. .NET binds an XML attribute to a property.
Example: Mapping a field or property to an XML attribute
//-- Java code fragment public class UKAddress extends Address { @XmlAttribute public int exportCode; } //-- Schema fragment <! XML Schema fragment --> <xs:complexType name="ukAddress"> <xs:complexContent> <xs:extension base="tns:address"> <xs:sequence/> <xs:attribute name="exportCode" type="xs:int"/> </xs:extension> </xs:complexContent> </xs:complexType> // .NET auto generated code from schema public partial class ukAddress : address { private int exportCodeField; public int exportCode { get { return this.exportCodeField; } set { this.exportCodeField = value; } } }
Guideline: @XmlElementRefs maps to a xs:choice. This binds to a property with name item in the C# class. If there is another field/property named item in the Java class, there will be a name clash that .NET will resolve by generating name. To avoid the name clash, either change the name or use customization, for example @XmlElement(name="foo").
Example: Mapping a field or property using @XmlElementRefs
//-- Java code fragment public class PurchaseOrder { @XmlElementRefs({ @XmlElementRef(name="plane", type=PlaneType.class), @XmlElementRef(name="auto", type=AutoType.class)}) public TransportType shipBy; } @XmlRootElement(name="plane") public class PlaneType extends TransportType {} @XmlRootElement(name="auto") public class AutoType extends TransportType { } @XmlRootElement public class TransportType { ... } //-- Schema fragment <!-- XML schema generated by wsgen --> <xs:complexType name="purchaseOrder"> <xs:choice> <xs:element ref="plane"/> <xs:element ref="auto"/> </xs:choice> </xs:complexType> <!-- XML global elements --> <xs:element name="plane" type="autoType" /> <xs:element name="auto" type="planeType" /> <xs:complexType name="autoType"> <!-- content omitted - details not relevant to example --> </xs:complexType> </xs:complexType name="planeType"> <!-- content omitted - details not relevant to example --> </xs:complexType> // .NET auto generated code from schema public partial class purchaseOrder { private transportType itemField; [System.Xml.Serialization.XmlElementAttribute("auto", typeof(autoType), Order=4)] [System.Xml.Serialization.XmlElementAttribute("plane", typeof(planeType), Order=4)] public transportType Item { get { return this.itemField; } set { this.itemField = value; } } public partial class planeType { ... } ; public partial class autoType { ... } ;