Win a copy of Programmer's Guide to Java SE 8 Oracle Certified Associate (OCA) this week in the OCAJP forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

How to comment adapter classes

 
Marcos Motta
Ranch Hand
Posts: 56
  • Mark post as helpful
  • send pies
  • 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 ]
 
Mark Spritzler
ranger
Sheriff
Posts: 17278
6
IntelliJ IDE Mac Spring
  • Mark post as helpful
  • send pies
  • 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
  • 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
Sheriff
Posts: 17278
6
IntelliJ IDE Mac Spring
  • Mark post as helpful
  • send pies
  • 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
  • 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
Sheriff
Posts: 17278
6
IntelliJ IDE Mac Spring
  • Mark post as helpful
  • send pies
  • 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
 
ehab emara
Greenhorn
Posts: 8
  • Mark post as helpful
  • send pies
  • 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
  • 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 ]
 
John Smith
Ranch Hand
Posts: 2937
  • Mark post as helpful
  • send pies
  • 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
  • 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.
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic