Win a copy of Functional Reactive Programming this week in the Other Languages forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

Interfaces, exceptions and javadoc

 
Jim Howard
Greenhorn
Posts: 3
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Sheriff
Posts: 10603
143
AngularJS Chrome Eclipse IDE Hibernate Java jQuery MySQL Database Spring Tomcat Server
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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)
 
Chris Zaremba
Ranch Hand
Posts: 54
Eclipse IDE Linux Spring
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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.
 
Jim Howard
Greenhorn
Posts: 3
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Sheriff
Posts: 10603
143
AngularJS Chrome Eclipse IDE Hibernate Java jQuery MySQL Database Spring Tomcat Server
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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!
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic