• 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

Need Help to Understand the Terms Used in the Book "Effective Java"

 
Ranch Hand
Posts: 39
Eclipse IDE Firefox Browser Java
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Hi everyone,
Please help me in understanding the following paragraph used in the book "Effective Java" -

A well-designed module hides
all of its implementation details, cleanly separating its API from its implementation.
Modules then communicate only through their APIs and are oblivious to
each others’ inner workings.



The user of a module should
never be surprised by its behavior. Modules should be as small as possible but no
smaller. (As used in this book, the term module refers to any reusable software
component, from an individual method to a complex system consisting of multiple
packages.) Code should be reused rather than copied. The dependencies between
modules should be kept to a minimum.



The term exported API, or simply API, refers to the classes,
interfaces, constructors, members, and serialized forms by which a programmer
accesses a class, interface, or package. (The term API, which is short for application
programming interface, is used in preference to the otherwise preferable term
interface to avoid confusion with the language construct of that name.) A programmer
who writes a program that uses an API is referred to as a user of the API.
A class whose implementation uses an API is a client of the API.



Please explain the terms "API" and "module" as in used here. Also, I don't understand by what the author means when he is saying "separating its API from its implementation" & "Modules then communicate only through their APIs" in the first para.

Thanks
 
Bartender
Posts: 11497
19
Android Google Web Toolkit Mac Eclipse IDE Ubuntu Java
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

Please explain the terms "API" and "module" as in used here. Also, I don't understand by what the author means when he is saying "separating its API from its implementation" & "Modules then communicate only through their APIs" in the first para.



I promise to give you Rs.100.00 per mail ID from your friend list (I promise not to spam)
This can be translated roughly as
Do you know or even care why I want those mail IDs or where I get the money from? No.
Thats the API part. Think of it as taking things at face value. In other words, hiding the implementation.

Consider an application which monitors the logs. When it encounters any errors/warnings it sends out mail notifications.
Ideally this application will have a(minimum) of two modules.
1) The monitoring module (which monitors the logs)
2) The mail module (which will send out the mails)
Both these modules will speak to each other in terms of the API cited above.

Does that help you understand a bit better?
 
Eshan Kapoor
Ranch Hand
Posts: 39
Eclipse IDE Firefox Browser Java
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
@Maneesh Godbole - In this example, what is the API and what is its implementation? How do we separate them?
Or are we supposed to create an interface/abstract class in order to separate them?




 
Marshal
Posts: 79076
376
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
The API consists of all the methods, public fields (which there ought not to be any of) and similar which other code can use to communicate with objects of your class. It is described in this format.
 
Rancher
Posts: 1044
6
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Protected fields and methods can also be considered as belonging to the API because you can access them through inheritance.
The Java platform API documentation includes the protected fields and methods.

And if you are very pedantic, you can also include the serialized format.
 
Eshan Kapoor
Ranch Hand
Posts: 39
Eclipse IDE Firefox Browser Java
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Ok I understand what API is now. But please explain how to separate it from its implementation. I posted a program and a question - "Are we supposed to create an interface/abstract class in order to separate them? " in my earlier reply. Please explain that to me.

Thanks
 
Ivan Jozsef Balazs
Rancher
Posts: 1044
6
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Not forcibly.
Suppose wen have a class with public setMass(double mass) and double getMass() methods.
Whether the class has a private variable "mass" or whether it store the property in another form, is a part of its implementation.

There is a public toString() method.
Whether the string representation is "computed" and stored at construction time,
or it is "computed" and cached at the first invocation ("lazy evaluation") or whether it is computed every time the method is invoked,
is part of the implementation.
If there were a public field toString, then this would not allow all the above techniques.

Having a public toString() method is one thing, and we can not (and will not) deduce the way it is implemented.
The way it is implemented could change over time, if we are isolated from the implementation.
 
Eshan Kapoor
Ranch Hand
Posts: 39
Eclipse IDE Firefox Browser Java
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
@Ivan Jozsef Balazs - I still can't get how to separate them. This is the line I don't understand - "A well-designed module hides all of its implementation details, cleanly separating its API from its implementation."

How to separate API from its implementation? By implementation do we mean the code that goes inside the methods of a class? OR Does it mean that we need to first create an abstract class/interface and then implement their methods in our own classes?
 
Campbell Ritchie
Marshal
Posts: 79076
376
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Implementation means the code inside the class. The fields should all be private, so they don't form part of the public API. The API should appear identical to an interface with the same methods.
No, you do not have to create such an interface nor an abstract class. You hide all the implementation details in whichever class you are using.
 
Eshan Kapoor
Ranch Hand
Posts: 39
Eclipse IDE Firefox Browser Java
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
@Campbell Ritchie-

The API should appear identical to an interface with the same methods.



Please tell what the "same methods" mean here.

I posted a program here in one of my earlier replies. Could you please tell me if that program hides all the implementation details? What I am unclear about is that how to separate the implementation part. Please help me.
 
Bartender
Posts: 10780
71
Hibernate Eclipse IDE Ubuntu
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

Eshan Kapoor wrote:How to separate API from its implementation? By implementation do we mean the code that goes inside the methods of a class?


Yes.

It's all about separating what from how.

The what is: "I want to sort a bunch of Customers".
The how is: "I want to sort a bunch of Customers with QuickSort".

If you see a method called:
public Collection<Customer> sort(Collection<Customer> customers) { ...

You don't need to know HOW the method does its sort in order to use it - all you need to know is that it takes a Collection of Customers and returns you a sorted one.

And if you do know how it sorts - ie, that it uses Quicksort - that means that the writer of the method can never change it, even if he finds a sort algorithm that's 10 timers faster; because you may be relying on the fact that it uses Quicksort.

And that's why, when you're writing a Java class, you go (or you should go) to great lengths to hide the HOW (ie, the implementation) from the users of your class.

Winston
 
Eshan Kapoor
Ranch Hand
Posts: 39
Eclipse IDE Firefox Browser Java
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
@Winston Gutkowski -

And that's why, when you're writing a Java class, you go (or you should go) to great lengths to hide the HOW (ie, the implementation) from the users of your class.



In order to do this, taking your Sorting example, do I need to first make an interface with some methods, then create a class which implements those methods and adds the logic - Quicksort. And then finally, the class which needs to sort the customers uses the implementing class? Just like List--> ArrayList ---> and finally we use ArrayList in our classes.
Is it something like this?
 
Winston Gutkowski
Bartender
Posts: 10780
71
Hibernate Eclipse IDE Ubuntu
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

Eshan Kapoor wrote:In order to do this, taking your Sorting example, do I need to first make an interface with some methods, then create a class which implements those methods and adds the logic - Quicksort.


That's certainly one way.

And then finally, the class which needs to sort the customers uses the implementing class? Just like List--> ArrayList ---> and finally we use ArrayList in our classes.


Kind of, except that you shouldn't use ArrayList anywhere except at the point where you initialise; you should use List, viz:

List<X> list = new ArrayList<X>();

Why? Because ArrayList is an implementation. If I write my program as above, I can change that initializer to use a LinkedList, or a SkipList later on, and nothing else in my program has to change. If I write:

ArrayList<X> list = new ArrayList<X>();

I'm now stuck with an ArrayList; and refactoring to use another type of List will be a LOT harder.

It's called programming to the interface, and I suggest you read up on it.

Winston
 
Consider Paul's rocket mass heater.
reply
    Bookmark Topic Watch Topic
  • New Topic