GeeCON Prague 2014*
The moose likes Developer Certification (SCJD/OCMJD) and the fly likes Interfaces, exceptions and javadoc Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login


JavaRanch » Java Forums » Certification » Developer Certification (SCJD/OCMJD)
Bookmark "Interfaces, exceptions and javadoc" Watch "Interfaces, exceptions and javadoc" New topic
Author

Interfaces, exceptions and javadoc

Jim Howard
Greenhorn

Joined: Sep 01, 2011
Posts: 3
Hi Guys,

I'm beginning to tie myself in knots and wondered if anyone could help.

I'm using {@inheritDoc} to propagate documentation from an interface definition to an implementing class.

An implementation method needs to throw several IllegalStateExceptions, (as well as some checked exceptions) all of which I subsequently shifted up to the corresponding interface method definition.

However, I now notice that I have to list each and every exception in the throws clause of the method, (in the class) instead of just the exceptions' super class, in order to get the corresponding exception comments to be visible - for the concrete method. Reading a bit more, this seems to be just how javadoc works, oh well.

Plus, I can only get the first IllegalStateException to propagate from the interface and that's by listing it too, (as "IllegalStateException") in the throws clause of the concrete method.

I can of course get around this by moving the IllegalStateExceptions (they aren't sub-classed) back to the implementing class, but that rather seems to defeat the object of using {@inheritDoc}.

This is a slightly alarming since I have already converted my DB interface instructions into javadoc and then inherited it (the javadoc) in the Data classes' method implementations.

I added some additional IllegalStateExceptions to some of Data's methods (and hence in the Data javadoc) and also, I don't implement a couple of the DB interface checked exceptions. So, these are simply not listed in the relevant Data method throws clauses.

In summary, I'm wondering if I really understand the philosophy behind interfaces and checked/unchecked exceptions. Is javadoc trying to tell me something ?

Thanks in advance Jim
Roel De Nijs
Bartender

Joined: Jul 19, 2004
Posts: 5300
    
  13

My code is exactly structured like yours:



My generated javadoc looks exactly like you described. I never noticed the runtime exceptions were not generated in the implementation class (until this post ). I don't want to change anything in the code, just to generate a bit more javadoc. In the javadoc you'll see something like

Specified by:
create in DBMain

So if they want to read the full documentation, just have a look at the interface (and that's something you'll do if your class implements an interface, because the interface describes the contract an implementing class should meet)


SCJA, SCJP (1.4 | 5.0 | 6.0), SCJD
http://www.javaroe.be/
Chris Zaremba
Ranch Hand

Joined: Nov 22, 2010
Posts: 54

Roel, I've never seen the same exception listed more than once in javadoc. I realise they can be throw more than once and possibly with different messages but you way seems to go against the grain. Could you explain your choice please.


SCJA, OCPJP, OCMJD
Jim Howard
Greenhorn

Joined: Sep 01, 2011
Posts: 3
Hi Roel,

Thanks for the advice.

A couple of things - I'm probably obsessing.

Have you really duplicated the create method definition in your custom interface DBMain ?

I wanted to keep DB exactly as it was specified, which is why, in that case, I added the runtime exceptions at the implementation level.

Also, if I don't want to implement a checked exception from the interface, should I leave it off the throws clause in the implementation or include it, for decorative purposes ;-)

cheers
Roel De Nijs
Bartender

Joined: Jul 19, 2004
Posts: 5300
    
  13

Chris Zaremba wrote:Roel, I've never seen the same exception listed more than once in javadoc. I realise they can be throw more than once and possibly with different messages but you way seems to go against the grain. Could you explain your choice please.

I think it's just more clear to have a seperate @throws for every possibility when the exception is thrown instead of having just 1 @throws and then have to combine several explanations with OR. So no real reason, just clarity (in my opinion that is of course).

Chris Zaremba wrote:Have you really duplicated the create method definition in your custom interface DBMain ?

In my own interface (extending the given interface) I had the create-method defined again (exactly the same method signature), so I was able to add the necessary javadoc and keep the given interface as-is.

Chris Zaremba wrote:Also, if I don't want to implement a checked exception from the interface, should I leave it off the throws clause in the implementation or include it, for decorative purposes ;-)

In my opinion it depends if the throws clause could be useful in maybe a next version (e.g. the DuplicateKeyException of the create-method) or the exception would never be thrown (e.g. the RNFE of the update-method). With the create-method I didn't change anything at all, because throwin a DuplicateKeyException could be the case in a next version of the application. But for the update/delete/unlock methods I removed the throws clause, because it's simply impossible that these methods will throw a RNFE.

Hope it helps!
 
GeeCON Prague 2014
 
subject: Interfaces, exceptions and javadoc