• 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

How to comment adapter classes

 
Ranch Hand
Posts: 56
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
I will have a couple of adapter classes with the same public interface as the Data class: the same close(), criteriaFind(), lock() and so on.
When commenting these adapter classes (javadoc), should I replicate the same comments of the Data class? Or I could just use a "@see suncertify.db.method()" in the adapter linking to each method's counterpart in Data? What do you think?
[ March 27, 2003: Message edited by: Marcos Motta ]
 
ranger
Posts: 17347
11
Mac IntelliJ IDE Spring
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
If you have the Javadoc in the interface, all classes that implement that interface will get those Javadocs automatically. So you only need to Javadoc the interface.
Mark
 
Marcos Motta
Ranch Hand
Posts: 56
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
I see, but, the reason why I am creating an adapter class is that the interfaces are incompatible to each other.
My adapter class makes an instance of RemoteDataInterface (full of RemoteExceptions) look like a DataInterface, which never throws RemoteException.
The RemoteInteface can not extend DataInterface. So how can I javadoc a single interface and reuse these docs in the others. I am stuck on this again .
Guys (Mark?), be patient with me. I know my english sucks. I am trying hard....
 
Mark Spritzler
ranger
Posts: 17347
11
Mac IntelliJ IDE Spring
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Ah, now I see. Can you change your DataInterface to throw either Exception(this is what I did) or RemoteException, then your RemoteDataImplementation can implement DataInterface and you won't need that extra Adapter class. You can also have your DataInterface extend Remote, there for you can have both your RemoteDataImplementation and LocalDataImplementation implement the DataInterface and you are good to go.
Mark
 
Marcos Motta
Ranch Hand
Posts: 56
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
You are right! I will do the same.
How do you think I should comment (javadoc) the Exception?
...
@throws Exception thrown when ???
...
 
Mark Spritzler
ranger
Posts: 17347
11
Mac IntelliJ IDE Spring
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
* @throws Exception
That is all I had, and I got perfect in Documentation. I didn't even make it more specific in the implementation classes. Go Figure.
Mark
 
Greenhorn
Posts: 8
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Dear Marcos
i have the same problem as u had with exception and i wonder how did mark solve this problem, so if u kindley explain to me the suggested soulution of mark's since he had elimenated one of the adapter classes and i don't know how and why ?
thank u so much for ur help
 
Marcos Motta
Ranch Hand
Posts: 56
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
After reading Marks comments, I realized that my knowledge of Java interfaces was incomplete (really embarrassing). Look this code:

I thought that the Data.getRecordCount() was required to declare Exception just because it is implementing DataInterface, which throws Exception for this method. I also thought that any client of a class derived from DataInterface would have to catch(Exception) as well. That misconception took me 1 month. Be sure you are not like me.
[ March 30, 2003: Message edited by: Marcos Motta ]
 
Ranch Hand
Posts: 2937
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
It's hardly ever a good a idea to to declare that a method throws a generic Exception. This is a "shortcut" that leaves the caller in complete darkness regarding the potential problems and their causes in the method call. The caller is left with no option but catching this amorphous exception without any meaningful processing or error mapping. The concept of programming to interface does not apply to exception declaration!
Eugene.
 
Marcos Motta
Ranch Hand
Posts: 56
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Eugene,
I understand your point.
What if I replace the "throw Exception" in DataInterface to "throw IOException"?
Here is my argument:
DataInterface is used to hide the actual location of the database from the FBN client. When using a DataInterface, the client know that it might be accessing a local file or a remote through RMI.
The design of DataInterface must antecipate and reflect all sort of things that might happen in both modes (Exception is too mush, I agree). Since a failure in accessing a local file or a network connection are both an IO failure, I think that IOException correctly expresses this situation and would not leave the clients in the darkness, as you correctly pointed out.
 
Don't get me started about those stupid light bulbs.
reply
    Bookmark Topic Watch Topic
  • New Topic