javax.xml.datatype.Duration class has a bundle of methods returning values about internal state:
 - getField
 - getSeconds
 - getMinutes
 - getHours
 - getDays
 - getMonths
 - getYears
depending on the factory method of javax.xml.datatype.DatatypeFactory class and given parameters.

It should be described unambiguously what value should be returned if Duration object is created by either factory method of DatatypeFactory class.

###@###.### 2005-03-09 16:12:53 GMT
Each of the methods identified in this CR clearly states what value is returned. The general form of the statement is "the value or 0 if not present". So, for example, given a
Duration constructed with newDuration("P3M"), getMonths() will return 3, getYears() will return 0, etc.

Given the flexibility of the lexical representation, and the clear citation of the specification for dayTime and yearMonth durations, I think the descriptions are clear.

Can you identify a specific area where you think the spec is unclear?
For example, look at following mini-test:

===
import javax.xml.datatype.Duration;
import javax.xml.datatype.DatatypeFactory;
import java.math.BigInteger;
import java.math.BigDecimal;

public class Test1 {
    public static void main(String[] args) throws Exception {
        BigInteger Z = BigInteger.ZERO;

        Duration d;
        int time = 10000;

        d = DatatypeFactory.newInstance().newDuration(time*1000L);
        System.out.println("sec: " + d.getSeconds());
        System.out.println("min: " + d.getMinutes());

        d = DatatypeFactory.newInstance().newDuration("PT"+time+"S");
        System.out.println("sec: " + d.getSeconds());
        System.out.println("min: " + d.getMinutes());

        d = DatatypeFactory.newInstance().newDuration(true, 0, 0, 0, 0, 0, time);
        System.out.println("sec: " + d.getSeconds());
        System.out.println("min: " + d.getMinutes());

        d = DatatypeFactory.newInstance().newDuration(true, Z, Z, Z, Z, Z,
                new BigDecimal(time));
        System.out.println("sec: " + d.getSeconds());
        System.out.println("min: " + d.getMinutes());

        System.out.println("---------------------");
        d = DatatypeFactory.newInstance().newDurationDayTime(time*1000L);
        System.out.println("sec: " + d.getSeconds());
        System.out.println("min: " + d.getMinutes());

        d = DatatypeFactory.newInstance().newDurationDayTime("PT"+time+"S");
        System.out.println("sec: " + d.getSeconds());
        System.out.println("min: " + d.getMinutes());

        d = DatatypeFactory.newInstance().newDurationDayTime(true, 0, 0, 0, time);
        System.out.println("sec: " + d.getSeconds());
        System.out.println("min: " + d.getMinutes());

        d = DatatypeFactory.newInstance().newDurationDayTime(true, Z, Z, Z,
                new BigInteger(String.valueOf(time)));
        System.out.println("sec: " + d.getSeconds());
        System.out.println("min: " + d.getMinutes());

        System.out.println("---------------------");
        d = DatatypeFactory.newInstance().newDurationYearMonth(Long.MAX_VALUE);
        System.out.println("yea: " + d.getYears());
        System.out.println("mon: " + d.getMonths());
        System.out.println("day: " + d.getDays());

        d = DatatypeFactory.newInstance().newDurationDayTime(Long.MAX_VALUE);
        System.out.println("yea: " + d.getYears());
        System.out.println("mon: " + d.getMonths());
        System.out.println("day: " + d.getDays());

        d = DatatypeFactory.newInstance().newDuration(Long.MAX_VALUE);
        System.out.println("yea: " + d.getYears());
        System.out.println("mon: " + d.getMonths());
        System.out.println("day: " + d.getDays());

    }
}
===
The seconds sometimes is "normalized" and converted to minutes, hours etc. and sometime seconds stay unmodified.

The same situation with years:
all three methods newDurationYearMonth, newDurationDayTime and newDuration return the same year but the spec for newDurationDayTime says that All remaining seconds ... are discarded.