Remaining doclint issues in java.net
stuart.marks at oracle.com
Thu Aug 1 14:18:01 PDT 2013
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
> 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
* * *
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(":
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.
More information about the net-dev