Followup RFE for CCC 4959151: javax.xml.datatype classes should follow XML Schema spec closer


Following javadoc change will be made in javax.xml.datatype.Duration

- Change "Because" to "When" in following javadoc for
public final Duration multiply(BigDecimal factor)

    * "Because ==> When" fractions of month cannot be meaningfully carried down
    * to days, or year to months, this will cause an
    * {@link IllegalStateException} to be thrown.
    * For example if you multiple one month by 0.5.</p>

Also update spec to clarify "when" fractions of month or fractions of year can
not be meaningfully carried down to days or months field respectively.




Following javadoc changes will be made in javax.xml.datatype.XMLGregorianCalendar

public int getMillisecond()
    1. Change the formula in the Date/time datatype field mapping table from 'getSecond() + getMillisecond()' to 'getSecond() + getMillisecond()/1000'.


public GregorianCalendar toGregorianCalendar(TimeZone timezone, Locale aLocale,
                                             XMLGregorianCalendar defaults)
1 Add following javadoc on computation of timezone of result GregorianCalendar.
  * <p>To compute the return value's <code>TimeZone</code> field,
    * <ul>
    * <li>when parameter <code>timeZone</code> is non-null,
    * it is the return value's timezone field.</li>
    * <li>else when <code>this.getTimezone() != FIELD_UNDECLARED</code>,
    * create a <code>java.util.TimeZone</code> with a custom timezone id
    * using the <code>this.getTimezone()</code>.</li>
    * <li>else when <code>defaults.getTimezone() != FIELD_UNDECLARED</code>,
    * create a <code>java.util.TimeZone</code> with a custom timezone id
    * using <code>defaults.getTimezone()</code>.</li>
    * <li>else use the <code>GregorianCalendar</code> default timezone value
    * for the host as specified by
    * <code>java.util.TimeZone.getDefault()</code>.</li></p>

Add javadoc stating that the field by field conversion from XMLGregorianCalendar
to GregorianCalendar should not have side effects. The most stable order
of setting GregorianCalendar fields will be placed in the javadoc.
researching what this order is.

Potential writeups include:

if one created a GregorianCalendar
using the constructor with a TimeZone parameter and then set the fields in an order from the least significant to most significant (MILLSECOND, SECOND, HOUR, DAY, MONTH, YEAR, ERA) that there would be no side-effects between sets. Or is it the other way around and one needs to set from most significant to least significant field in GregorianCalendar to avoid
side-effects.