aspose file tools*
The moose likes Developer Certification (SCJD/OCMJD) and the fly likes How to comment adapter classes 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 "How to comment adapter classes" Watch "How to comment adapter classes" New topic
Author

How to comment adapter classes

Marcos Motta
Ranch Hand

Joined: Apr 28, 2002
Posts: 56
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

Joined: Feb 05, 2001
Posts: 17257
    
    6

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


Perfect World Programming, LLC - Two Laptop Bag - Tube Organizer
How to Ask Questions the Smart Way FAQ
Marcos Motta
Ranch Hand

Joined: Apr 28, 2002
Posts: 56
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

Joined: Feb 05, 2001
Posts: 17257
    
    6

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

Joined: Apr 28, 2002
Posts: 56
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

Joined: Feb 05, 2001
Posts: 17257
    
    6

* @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

Joined: Nov 07, 2002
Posts: 8
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

Joined: Apr 28, 2002
Posts: 56
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

Joined: Oct 08, 2001
Posts: 2937
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

Joined: Apr 28, 2002
Posts: 56
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.
 
Consider Paul's rocket mass heater.
 
subject: How to comment adapter classes