Remaining doclint issues in java.net

[Chris Hegarty]

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" ??

Thanks,
-Chris.