What's the purpose of minOccurs, nillable and restriction?

Question

Documentation for required says:

If required() is true, then Javabean property is mapped to an XML schema element declaration with minOccurs="1". maxOccurs is "1" for a single valued property and "unbounded" for a multivalued property.

If required() is false, then the Javabean property is mapped to XML Schema element declaration with minOccurs="0". maxOccurs is "1" for a single valued property and "unbounded" for a multivalued property.

Documentation for nillable says:

If nillable() is true, then the JavaBean property is mapped to a XML Schema nillable element declaration.

---

Code for xs:complexType:

public class WSData {
    //...

    @XmlElement(required = true, nillable = false)
    public void setMonth(XmlMonthType month) {
        this.month = month;
    }

    public void setUserLogin(String userLogin) {
        this.userLogin = userLogin;
    }
}

Code for xs:simpleType:

@XmlType
@XmlEnum(Integer.class)
public enum XmlMonthType {
    @XmlEnumValue("1")
    JANUARY,
    @XmlEnumValue("2")
    FEBRUARY,
    @XmlEnumValue("3")
    MARCH,
    /* ... months 4 ~9 ... */
    @XmlEnumValue("10")
    OCTOBER,
    @XmlEnumValue("11")
    NOVEMBER,
    @XmlEnumValue("12")
    DECEMBER;
}

---

Generated XML Schema:

<xs:complexType name="wsData">
  <xs:sequence>
    <xs:element name="month" type="xs:string"/>
    <xs:element minOccurs="0" name="userLogin" type="xs:string"/>
  </xs:sequence>
</xs:complexType>

<xs:simpleType name="xmlMonthType">
  <xs:restriction base="xs:int">
    <xs:enumeration value="1"/>
    <xs:enumeration value="2"/>
    <xs:enumeration value="3"/>
    <!-- ... months 4 ~9 ... -->
    <xs:enumeration value="10"/>
    <xs:enumeration value="11"/>
    <xs:enumeration value="12"/>
  </xs:restriction>
</xs:simpleType>

---

The facts:

1. The default value for minOccurs is 1. So, month is required (must exist);
2. The month has a restriction. So, month can only have a value defined by one of the 12 defined enumerations;
3. The default value for nillable is false. So, month can't have empty values;
4. The XML Schema is generated correctly.

The problems:

1. It is accepting month's abcense (mustn't exist);
2. It is accepting any values for month, like 13 (except when isn't parseable to Integer);
3. It is accepting empty values;

I wasn't expecting these problems, am I missing something?
If that behavior is correct, what is the purpose of required, nillable and xs:restriction?

Answer 1

Nillable allows empty values. For example, if you have an Integer or a Date, if it's nillable, the XML tag could be empty. If it's not nillable but not required, the XML element would either have to exist with a valid content, or not exist at all; an empty tag wouldn't be valid.

Answer 2

Make minOccurs 1, to make month required;

The default value for minOccurs is one, so the month element is required. Note how minOccurs="0" had to be added to userLogin to make it optional.

<xs:complexType name="wsData">
  <xs:sequence>
    <xs:element name="month" type="xs:string"/>
    <xs:element minOccurs="0" name="userLogin" type="xs:string"/>
  </xs:sequence>
</xs:complexType>

Validate month with its generated restriction (without a XmlAdapter).

You can set an instance of Schema on the Unmarshaller to have the input validated:

• http://blog.bdoughan.com/2010/12/jaxb-and-marshalunmarshal-schema.html

Demo

The following code can be used to generate the XML schema:

package forum9111936;

import java.io.IOException;

import javax.xml.bind.JAXBContext;
import javax.xml.bind.SchemaOutputResolver;
import javax.xml.transform.Result;
import javax.xml.transform.stream.StreamResult;

public class Demo {

    public static void main(String[] args) throws Exception {
        JAXBContext jc = JAXBContext.newInstance(WSData.class);
        SchemaOutputResolver sor = new SchemaOutputResolver() {

            @Override
            public Result createOutput(String namespaceUri,
                    String suggestedFileName) throws IOException {
                StreamResult result = new StreamResult(System.out);
                result.setSystemId(suggestedFileName);
                return result;
            }

        };
        jc.generateSchema(sor);
        System.out.println();
    }

}

---

UPDATE

The JAXB RI normally throws a ValidationEvent of severity 1 for conversion issues. The default ValidationEventHandler ignores all issues of severity less than 2. This normally results in the value being set to null. You can override the ValidationEventHandler as follows:

    unmarshaller.setEventHandler(new ValidationEventHandler() {
        @Override
        public boolean handleEvent(ValidationEvent event) {
            System.out.println(event);
            return event.getSeverity() < ValidationEvent.ERROR;
        }
    });

However the JAXB RI does not appear to throw events related to converting enum values (possible bug). If you happen to be using EclipseLink JAXB (MOXy) as your JAXB provider then you will get an exception like:

Exception in thread "main" Local Exception Stack: 
Exception [EclipseLink-116] (Eclipse Persistence Services - 2.4.0.qualifier): org.eclipse.persistence.exceptions.DescriptorException
Exception Description: No conversion value provided for the value [13] in field [month/text()].
Mapping: org.eclipse.persistence.oxm.mappings.XMLDirectMapping[month-->month/text()]
Descriptor: XMLDescriptor(forum9111936.WSData --> [])
    at org.eclipse.persistence.exceptions.DescriptorException.noFieldValueConversionToAttributeValueProvided(DescriptorException.java:1052)
    at org.eclipse.persistence.mappings.converters.ObjectTypeConverter.convertDataValueToObjectValue(ObjectTypeConverter.java:140)
    at org.eclipse.persistence.oxm.mappings.XMLDirectMapping.getAttributeValue(XMLDirectMapping.java:287)
    at org.eclipse.persistence.internal.oxm.XMLDirectMappingNodeValue.endElement(XMLDirectMappingNodeValue.java:190)
    at org.eclipse.persistence.oxm.record.UnmarshalRecord.endElement(UnmarshalRecord.java:910)
    at org.eclipse.persistence.internal.oxm.record.XMLStreamReaderReader.parseEvent(XMLStreamReaderReader.java:133)
    at org.eclipse.persistence.internal.oxm.record.XMLStreamReaderReader.parse(XMLStreamReaderReader.java:83)
    at org.eclipse.persistence.internal.oxm.record.XMLStreamReaderReader.parse(XMLStreamReaderReader.java:72)
    at org.eclipse.persistence.internal.oxm.record.SAXUnmarshaller.unmarshal(SAXUnmarshaller.java:838)
    at org.eclipse.persistence.oxm.XMLUnmarshaller.unmarshal(XMLUnmarshaller.java:626)
    at org.eclipse.persistence.jaxb.JAXBUnmarshaller.unmarshal(JAXBUnmarshaller.java:472)
    at forum9111936.Demo2.main(Demo2.java:30)

For More Information

• http://blog.bdoughan.com/2011/05/specifying-eclipselink-moxy-as-your.html