DatatypeConverter / DatatypeConverterInterface are underspecified

[glassfishrobot]

It doesn't say what happens in case of an error. Does it throw an exception?
Does it just return null?

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 v0.4]

[glassfishrobot]

Reported by kohsuke

[glassfishrobot]

@jfialli said:
Assumed clarification: Issue is to specify error behavior case when a
DatatypeConverter parse method is unable to parse a string in order
to convert the string value into the target datatype of the parse method.

Survey of existing package java parse methods favors
throwing runtime exception over returning null for
the exception case. Thus, there is existing Java bias
towards stating that a runtime exception is thrown.

Examples of existing Java parse methods for various datatypes:

java.lang.Integer.parse(String) throws NumberFormatException.
(Assume same for rest of java.lang.Number subclasses.)

java.text.DateFormat.parse(String) returns null when String value does not
follow date format.

java.net.URI.URI(String value) throws URISytntaxException when given
string violates RFC 2396.

javax.xml.datatype.DatatypeFactory.newDuration(String value)
javax.xml.datatype.DatatypeFactory.newXMLGregorianCalendar(String value)
are javadoc'ed to throw IllegalArgumentException when lexical
value does not conform to XML Schema specified lexical representations for these
datatypes.

---

Discussion points:

Should a DatatypeConverter parse methods just state that SOME runtime exception
is thrown for the error case? Or does each method need to specify a precise
runtime exception that would be thrown. (i.e. NumericFormatException when unable
to parse a string into a specific Java Number subclass.) There is a fine line
between over and under specifying when documenting the precise unchecked
exception thrown in the javadoc. Examples above tend to be precise, not
completely certain if that is appropriate for this case.

[glassfishrobot]

This issue was imported from java.net JIRA JSR222-42