• 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

B&S: Documenting RuntimeException in DBAccess interface

 
Ranch Hand
Posts: 64
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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
 
Ranch Hand
Posts: 619
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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
 
Ranch Hand
Posts: 293
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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
 
George Marinkovich
Ranch Hand
Posts: 619
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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
Posts: 293
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
George - thanks for clarifying.
TJ
 
Derek Canaan
Ranch Hand
Posts: 64
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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
Posts: 619
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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
Posts: 64
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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 ]
 
Ranch Hand
Posts: 319
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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 Bosch
Ranch Hand
Posts: 319
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
OK sorry.
I see Phil has already answered that question for me in the following thread.
https://coderanch.com/t/183999/java-developer-SCJD/certification/URLyBird-SecurityException
 
Ranch Hand
Posts: 266
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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
Posts: 64
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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
 
ice is for people that are not already cool. Chill 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