Remaining doclint issues in java.net

[Stuart Marks]

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