Fields and Properties

The following guidelines apply to mapping of JavaBeans properties and Java fields, but for brevity Java fields are used.

@XmlElement Annotation

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; }
    }
}

@XmlAttribute Annotation

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; }
    }
}

@XmlElementRefs Annotation

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 { ... } ;