In XML Schema, elements may be declared to be nillable. Within the XML instance document, nillable elements might or might not be nilled. A nilled element must have no text or element content, but it may still have attributes. To model nillable elements, XBinder uses a generic class, XBNillableElem. XBNillableElem simply combines a value with an isNilled flag.

Example: consider the following XSD:

            <xsd:complexType name="MyComplex">
            <xsd:sequence>
               <xsd:element name="an_element" type="xsd:string"/>
               </xsd:sequence>               
               <xsd:attribute name="an_attribute" type="xsd:string" use="required"/>
            </xsd:complexType>
            
            [...]
               <!-- An element inside some complex type -->
               <xsd:element name="myComplexElem" type="MyComplex" nillable="true"/>
            [...]
         

This will produce the following field:

            protected XBNillableElem<MyComplex> myComplexElem;
         

When creating a value for myComplexElem, you may create a nilled or not-nilled element. If you create a nilled element, you will not need to populate an_element, but you will need to populate an_attribute, since it is for a required attribute. Here is an example of populating myComplexElem as being nilled:

            MyComplex myComplex = new MyComplex();
            myComplex.setAn_attribute("attribute value");
            outerobj.setMyComplexElem( new XBNillableElem<MyComplex>(myComplex, true /*nilled*/) );
         

When encoding a nilled element, the element must have an xsi:nil attribute encoded. The XSI namespace will automatically be declared in the output XML. However, to avoid having many such namespace declarations encoded, you may wish to invoke

               root.addNamespace("http://www.w3.org/2001/XMLSchema-instance", "xsi");
            

on your root element type before encoding.