Remaining doclint issues in java.net

[Stuart Marks]

On 7/31/13 2:39 PM, Matthew Hall wrote:
> On Wed, Jul 31, 2013 at 02:38:26PM -0700, Stuart Marks wrote:
>> 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 have never understood in many years using Java why the compiler generates
> errors about attempting to catch supposedly-impossible exceptions, instead of
> warnings.
>
> For me it only leads to difficulties when I'm trying to write prototypes or
> refactor and clean up some old brittle code, and I run into that rather
> dubious sort of error.
>
> This is a good example of where it causes more harm than good. Is there still
> a really good reason for this over-paranoid compiler error given that checked
> exceptions aren't as popular as they used to be anyways?

I don't have the definitive answer, but it was a very early Java design 
decision to make unreachable code be a compilation error instead of a warning. 
This is a matter of judgment, of course; reasonable people come down on 
different sides of this, for different cases. For example, see this 
Stackoverflow conversation:

http://stackoverflow.com/questions/3795585/why-does-java-have-an-unreachable-statement-compiler-error

* * *

Meanwhile, I did a little bit of studying about DatagramPacket. The doclint 
warnings occur on two of the six DatagramPacket constructors:

     DatagramPacket(byte[] buf, int len, SocketAddress sa)
     DatagramPacket(byte[] buf, int off, int len, SocketAddress sa)

There are two other equivalent overloaded constructors that take InetAddress 
and port arguments:

     DatagramPacket(byte[] buf, int len, InetAddress ia, int port)
     DatagramPacket(byte[] buf, int off, int len, InetAddress ia, int port)

To my eye the InetAddress/port constructors are used quite a bit more often 
than the SocketAddress ones. I did a web search for "java DatagramPacket 
example" and looked at all the examples on the first page of hits. All of them 
used the InetAddress+port constructor overloads (including the Oracle Java 
tutorial). I didn't see any uses of the SocketAddress overloads.

I also did an ohloh search for "new DatagramPacket(":

http://code.ohloh.net/search?s=%22new%20DatagramPacket%28%22&p=2&pp=0&fl=Java&mp=1&ml=1&me=1&md=1&ff=1&filterChecked=true

(HT: Dalibor)

I looked through around 100 examples, and the vast majority of them use the 
InetAddress+port overloads. I saw three examples that use the SocketAddress 
overloads. Two of them were within methods that declared "throws Exception." 
The third was within a try/catch block that catches IOException. None of the 
three cases would suffer a source incompatibility.

This isn't definitive, of course, but it does seem to supply some evidence that 
making this change would result in a relatively minor source incompatibility.

s'marks