On 7/29/13 7:28 AM, Chris Hegarty wrote:
There are two remaining doclint warnings in the java.net package.
>:javac -Xdoclint:all/protected src/share/classes/java/net/DatagramPacket.java
src/share/classes/java/net/DatagramPacket.java:142: warning: no @throws for
java.net.SocketException
public DatagramPacket(byte buf[], int offset, int length,
^
src/share/classes/java/net/DatagramPacket.java:178: warning: no @throws for
java.net.SocketException
public DatagramPacket(byte buf[], int length,
^
These are caused by no @throws SE declaration on the constructors.
As it happens 'throws SE' was incorrectly added to these constructors when
introduced in 1.4. The original API specified that SE was thrown when the given
SocketAddress was not supported. That was later changed to throw IAE, in 1.4.2.
These constructor now can never throw SE.
Removing 'throws SE' from the method declaration is a binary compatible change,
but not source compatible ( XXX is never thrown in body of corresponding try
statement ). I don't think breaking source compatibility for this kind of
change is justified. If it is, then the solution is to simply remove 'throws
SE'.
Back in the real world, I guess we need to come up with some wording for the
'@throws SE' declaration. Something vague like "If an I/O Exception occurs", or
can we put something stronger like "will never be thrown" ??
I'd like to make a case for removing 'throws SE' even though it's a source
incompatible change.
It's not that source incompatibilities are strictly prohibited. They are
allowed, and it depends on how often they occur and how difficult they are to
fix. I seem to recall there was a similar issue when "more precise rethrow" was
added in Java 7; this was indeed a source incompatibility but a survey was done
and it was quite rare.
How often are these DatagramPacket constructors used? I'd have to say, probably
more often than the fairly obscure cases that the "more precise rethrow"
feature caused issues with.
On the other hand, fixing up code that constructs a DatagramPacket ought to be
pretty simple: removing the catch of SocketException. This is already known to
be dead code, so it can simply be removed.
The alternative is to add "@throws SocketException never" to the javadoc, just
to get rid of the doclint warning, but this has the consequence of requiring
people to keep dead code around indefinitely, and furthermore it requires them
to add new dead code every time they create a DatagramPacket.
I'm not claiming that removing 'throws SE' is obviously the right answer, but
I'd like to see it considered seriously.
s'marks
