• Post Reply Bookmark Topic Watch Topic
  • New Topic

Why do API interfaces have method descriptions ?  RSS feed

 
Ranch Hand
Posts: 40
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi guys, I'm trying to figure out something :-)

An interface cannot have concrete methods. Why then does the API documentation for interfaces in the API (e.g. Collections) describe what the methods do ?

The sourcecode for the Collections interface has empty methods (as I would expect). But the API documentation for Collections says what the methods do. Where are the concrete methods implemented and where is the source code for these concrete methods ?

I'm confused :-(

Thanks, John
 
Ranch Hand
Posts: 934
4
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Interfaces describes what a behavior implementing class should have. Any calls which wants to implement any interfaces should provide implementation
for those methods.
 
Marshal
Posts: 56600
172
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
The reason for supplying descriptions of those methods is to create a general contract. That means if a method in an interface says that it makes smoke come out of your computer, then all implementing classes must make smoke come out of the computer, too. If you look at the add method in that interface you linked to, and then at the add method in the subinterface List, you will see a difference. Collections provides a very vague general contract which is greatly refined by List. That means the Collection version can be used in a set, too.

That means your implementing methods may cause white smoke or black smoke to come from your computer whilst still complying with their superinterfaces' general contracts
 
John Mulholland
Ranch Hand
Posts: 40
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Thanks Tushar, so the relationship between Collections and say ArrayList, is the following ?

Collection has a sub interface List, which is implemented by ArrayList. Therefore ArrayList (or its superclass) must provide a concrete implementation for abstract methods contained in List (and Collection) ?

Thanks, John



 
Campbell Ritchie
Marshal
Posts: 56600
172
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Yes.
 
It is sorta covered in the JavaRanch Style Guide.
  • Post Reply Bookmark Topic Watch Topic
  • New Topic
Boost this thread!