Javadoc question and exception question

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.

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

posted Aug 27, 2002 20:39:00

0

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

posted Aug 28, 2002 07:10:00

0

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’ve looked at a lot of different solutions, and in my humble opinion Aspose is the way to go. Here’s the link: http://aspose.com