This week's book giveaway is in the Servlets forum.
We're giving away four copies of Murach's Java Servlets and JSP and have Joel Murach on-line!
See this thread for details.
The moose likes Developer Certification (SCJD/OCMJD) and the fly likes Javadoc question and exception question Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login


Win a copy of Murach's Java Servlets and JSP this week in the Servlets forum!
JavaRanch » Java Forums » Certification » Developer Certification (SCJD/OCMJD)
Bookmark "Javadoc question and exception question" Watch "Javadoc question and exception question" New topic
Author

Javadoc question and exception question

Hank Gran
Greenhorn

Joined: Aug 27, 2002
Posts: 2
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.
Michael Morris
Ranch Hand

Joined: Jan 30, 2002
Posts: 3451

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


Any intelligent fool can make things bigger, more complex, and more violent. It takes a touch of genius - and a lot of courage - to move in the opposite direction. - Ernst F. Schumacher
Hank Gran
Greenhorn

Joined: Aug 27, 2002
Posts: 2
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

Joined: Jan 30, 2002
Posts: 3451
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
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: Javadoc question and exception question
 
Similar Threads
How to comment adapter classes
Data Interface definition for server and client
factory question
FBN : Exception in High level Data Interface
Please review Server design