aspose file tools*
The moose likes Developer Certification (SCJD/OCMJD) and the fly likes B&S: Documenting RuntimeException in DBAccess interface Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login


Win a copy of Spring in Action this week in the Spring forum!
JavaRanch » Java Forums » Certification » Developer Certification (SCJD/OCMJD)
Bookmark "B&S: Documenting RuntimeException in DBAccess interface" Watch "B&S: Documenting RuntimeException in DBAccess interface" New topic
Author

B&S: Documenting RuntimeException in DBAccess interface

Derek Canaan
Ranch Hand

Joined: Nov 05, 2003
Posts: 64
Hi,
One of the ways of handling IOException thrown in methods in Data that implements the DBAccess interface is to re-throw it as a RuntimeException.
In the javadoc of Data, these Runtime exceptions are documented. What about the DBAccess that is provided for us?
package suncertify.db;
public interface DBAccess
{
// Reads a record from the file. Returns an array where each
// element is a record value.
public String [] readRecord(long recNo)
throws RecordNotFoundException;

For submission, should we change it to:

1. Is it allowed to add MyRuntimeException in the method signature?
2. Is it allowed to change description of the method (for eg. file -> cache)?
rgds,
derek
George Marinkovich
Ranch Hand

Joined: Apr 15, 2003
Posts: 619
Hi Derek,
I would not modify the interface provided by Sun in any way.
If it's a runtime exception it isn't a checked exception, so you needn't include it in the throws list. Right?
I wouldn't even change the description in the interface. If you feel you need to do these things to the supplied interface then maybe you should look into creating a new interface and then adapt the new interface to the one provided by Sun.
Hope this helps,
George


Regards, George
SCJP, SCJD, SCWCD, SCBCD
Terry Martinson
Ranch Hand

Joined: Oct 18, 2003
Posts: 293
George - when you say not to modify it in any way, do you also mean that we shouldn't change their comments to javadoc style?
Or do you just mean to leave their basic info in the comment as is and ok to change to appropriate javadoc style?
TJ


SCJP, SCJD, SCWCD, SCBCD
George Marinkovich
Ranch Hand

Joined: Apr 15, 2003
Posts: 619
Terry,
Originally posted by Terry Martinson:
George - when you say not to modify it in any way, do you also mean that we shouldn't change their comments to javadoc style?
Or do you just mean to leave their basic info in the comment as is and ok to change to appropriate javadoc style?
TJ

You caught me. I did change the comments in DBMain into appropriate javadoc style. I think this is OK since it can have no adverse effect on any automatic testing Sun does based on the DBMain interface. To leave the interface comments in their original form is inconsitent with javadoc and therefore the java documentation that would be produced would be missing DBMain (a pretty big omission it seems to me).
Hope this helps,
George
Terry Martinson
Ranch Hand

Joined: Oct 18, 2003
Posts: 293
George - thanks for clarifying.
TJ
Derek Canaan
Ranch Hand

Joined: Nov 05, 2003
Posts: 64
Hi,
If it's a runtime exception it isn't a checked exception, so you needn't include it in the throws list. Right?

One of the things I learnt thru this assignment is design around interfaces. For instance, it's 'better' to code:

than

So if DBAccess does not document the MyRuntimeException, user of DBAccess will not know to catch it! That's why i would like to doc it in DBAccess, but not sure if this is a violation.
maybe you should look into creating a new interface and then adapt the new interface to the one provided by Sun.

I wish not create a new interface just for this documentation need.
Comments?
rgds,
derek
George Marinkovich
Ranch Hand

Joined: Apr 15, 2003
Posts: 619
Hi Derek,
1) Changing the method comment in the Sun-provided interface (DBMain) is probably not a problem. It's not going to interfere with any automated testing of the interface by the grader. I just didn't find a good reason to change any of the method comments in the DBMain interface. I still wouldn't modify the method's throws list, but if you want to document the MyRuntimeException that can be thrown it's probably not a bad thing. As you say clients of the interface would like to know the possible exceptions that can be thrown. One minor point: if you document the MyRuntimeException using the javadoc @throws, then if you subsequently run DocCheck (Sun's check tool that makes sure everything has a javadoc comment that needs one, and among other things, tries to verify the javadoc comment against the code that's being commented) it will complain that you have a @throws MyRuntimeException but that exception is not actually listed in the throws clause of the method declaration.
2) I take your point that it's a pretty weak reason to justify an additional interface, but if you're going to have an additional interface for some other reason, then I would be tempted to leave the DBMain interface alone and make the necessary modification in the additional interface.
Hope this helps,
George
[ January 20, 2004: Message edited by: George Marinkovich ]
Derek Canaan
Ranch Hand

Joined: Nov 05, 2003
Posts: 64
Hi George,
Thanks for your helpful comments.
Taking into account possible automatic testings, which of the two is better:
1. Document the Runtime exceptions in the methods that throw them (so that user can catch and handle them), but omit the MyRuntimeException from the methods' signature and also remove the javadoc @throws.
2. Document the Runtime exceptions in the methods that throw them. Explicitly declare these methods throw MyRuntimeException and include the javadoc @throws.
Does anyone know of a precedence/example in SUN's API where Runtime exceptions are documented in the class methods but they do not appear in the throw clause.
Examples I know such as Integer.parseInt(String) throws NumberFormatException (a Runtime exception) and it has a throw clause in the API method declaration:
parseInt
public static int parseInt(String s)
throws NumberFormatException
Parses the string argument as a signed decimal integer...
Parameters:
s - a String containing the int representation to be parsed
Returns:
the integer value represented by the argument in decimal.
Throws:
NumberFormatException - if the string does not contain a parsable integer.

Have not seen one class with method that describes possible Runtime exception that can be thrown but omit them in its method signature and without the javadoc @throw clause in the documentation. Would be grateful if anyone can point me to one.
rgds,
Derek
[ January 20, 2004: Message edited by: Derek Canaan ]
Jacques Bosch
Ranch Hand

Joined: Dec 18, 2003
Posts: 319
Hi there.
Yes, I would also like to know the answer to that question.
Is the best thing to do to document our RuntimeExceptions with an @throws tag?


Jacques<br />*******<br />MCP, SCJP, SCJD, SCWCD
Jacques Bosch
Ranch Hand

Joined: Dec 18, 2003
Posts: 319
OK sorry.
I see Phil has already answered that question for me in the following thread.
http://www.coderanch.com/t/183999/java-developer-SCJD/certification/URLyBird-SecurityException
Ulrich Heeger
Ranch Hand

Joined: Jun 06, 2003
Posts: 266
Hi,
George wrote:
One minor point: if you document the MyRuntimeException using the javadoc @throws, then if you subsequently run DocCheck (Sun's check tool that makes sure everything has a javadoc comment that needs one, and among other things, tries to verify the javadoc comment against the code that's being commented) it will complain that you have a @throws MyRuntimeException but that exception is not actually listed in the throws clause of the method declaration.

So, it's not recommendable to have a RuntimeException within the @throws without having declared it in the method signature?
Derek wrote:

Does anyone know of a precedence/example in SUN's API where Runtime exceptions are documented in the class methods but they do not appear in the throw clause.

For example java.lang.Thread:
public static void sleep(long millis,int nanos) has an IllegalArgumentException within @throw which isn't declared in the signature.
Concerning the RuntimeExceptions which are wrapping the IO- and InterruptedException:
I don't know if I should include these also in the DBAccess interface or only in the Data-Class. If I assume that the client is knowing only the interface I should include them in the DBAccess, thus enabling him to handle these exceptions explicitly?
Regards
Ulrich
Derek Canaan
Ranch Hand

Joined: Nov 05, 2003
Posts: 64
Hi Ulrich,
Thanks for the example. I will document the DBAccess similarly and defend this decision in choices.txt by quoting the example provided. If Sun does it, it's safe.
thanks,
derek
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: B&S: Documenting RuntimeException in DBAccess interface