• Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other Pie Elite all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Jeanne Boyarsky
  • Ron McLeod
  • Paul Clapham
  • Liutauras Vilda
Sheriffs:
  • paul wheaton
  • Rob Spoor
  • Devaka Cooray
Saloon Keepers:
  • Stephan van Hulst
  • Tim Holloway
  • Carey Brown
  • Frits Walraven
  • Tim Moores
Bartenders:
  • Mikalai Zaikin

Javadoc question and exception question

 
Greenhorn
Posts: 2
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
I have three questions for everyone:
1)When writing javadocs for my code, do I need to create javadoc comments for private methods?
2)I have an interface, IData, which Data and a couple other classes implement. Since the public javadoc comments for the interface will cascade down to the implementing classes, should I delete the existing javadoc comments from Data.java and just rely on IData for my javadoc?
3) The Data methods getRecordCount, unlock, close, and getFieldInfo don't throw an exception. Has anybody decided to modify any of them to throw an exception? An example of why I'm concerned about this is that I have a class named FBNDataRemote which uses RMI to communicate with Data. Both Data and FBNDataRemote implement IData, and in IData getRecordCount does not throw anexception. The problem is that the stub used to connect to Data can throw RemoteException, and when FBNDataRemote.getRecordCount catches that exception it has to swallow it. If I made getRecordCount throw DataBaseException in IData, and therefore in Data and FBNDataRemote, I would not have this problem because I could catch hte RemtoeException and wrap it in a DataBaseException.
 
Ranch Hand
Posts: 3451
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator


1)When writing javadocs for my code, do I need to create javadoc comments for private methods?


I put javadoc comments on everything, even private references. I'm not sure that it is necessary to go to that much trouble. But you should certainly javadoc anything with public or protected access.


2)I have an interface, IData, which Data and a couple other classes implement. Since the public javadoc comments for the interface will cascade down to the implementing classes, should I delete the existing javadoc comments from Data.java and just rely on IData for my javadoc?


Good question. Unless there is a significant differnce from your interface comments, my instinct tells me no. But that's just an opinion. Hopefully others will look at this and give you some more opinions.


3) The Data methods getRecordCount, unlock, close, and getFieldInfo don't throw an exception. Has anybody decided to modify any of them to throw an exception? An example of why I'm concerned about this is that I have a class named FBNDataRemote which uses RMI to communicate with Data. Both Data and FBNDataRemote implement IData, and in IData getRecordCount does not throw anexception. The problem is that the stub used to connect to Data can throw RemoteException, and when FBNDataRemote.getRecordCount catches that exception it has to swallow it. If I made getRecordCount throw DataBaseException in IData, and therefore in Data and FBNDataRemote, I would not have this problem because I could catch hte RemtoeException and wrap it in a DataBaseException.


Why does FBNDataRemote have to swallow a RemoteException? It seems to me that a RemoteException has no logical connection to a DatabaseException and should not be treated as such. I just reported RemoteExceptions to the client as they occurred. I also think that candidates are skating on thin ice when they start tinkering with the Sun supplied classes. I know that most here have Data implement the interface used for client access, but quite frankly, I've never heard a good explanation as to why they think it is necessary. Just because it already fulfills the contract of the interface doesn't justify binding it to that contract henceforth and forevermore.
Hope this helps,
Michael Morris
 
Hank Gran
Greenhorn
Posts: 2
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Thanks for the feedback.

Originally posted by Michael Morris:

Why does FBNDataRemote have to swallow a RemoteException? It seems to me that a RemoteException has no logical connection to a DatabaseException and should not be treated as such...


When I read the requirements concerning the Data client and they stated that
"This implementation should include a class that implements the same public methods as the suncertify.db.Data class" it just seemed natural to me to bring an interface into the picture to enforce this. Because of this, FBNDataRemote is just an IData. So now, when my client needs to talk to Data, it gets an IData which at this point can be either a FBNDataLocal or FBNDataRemote. FBNDataLocal simply has a reference to a Data, and FBNDataRemote has a RMI reference to Data. The client doen't care though, it just knows it is talking to an IData. In my design speaking to an IData is synonymous with speaking to a Data, so I only want to throw DatabaseExceptions in any of the methods of IData. I still create a meaninb\gful message when the root exception is RemoteException, and print a detailed series of chained stack traces to the console for debugging.
 
Michael Morris
Ranch Hand
Posts: 3451
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
I'm not arguing that you should not use an interface to communicate with the Data object. You should absolutely do that. I just don't see why it is necessary to wrap a RemoteException in a DatabaseException since they are logically disparate types. The only advantage I can see is that you only have to catch one Exception type. You could do that anyway by just catching the generic Exception.
Michael Morris
 
No, tomorrow we rule the world! With this tiny ad:
a bit of art, as a gift, that will fit in a stocking
https://gardener-gift.com
reply
    Bookmark Topic Watch Topic
  • New Topic