where are methods of interface implemented?

[Zo Ve]

I am currently learning Orace Java tutorial , about basic I/O.

There is example:

Path p1 = Paths.get("/home/logfile");
System.out.format("%s%n", p1.toUri());

Problem that i am facing with is when i look description, in API documentation, of some interface, how can i know that methods of that interface are already implemented, so i can freely use them, without implementing them by myself?

In this peace of code that i posted, there is interface Path, when i look description for that interface there are lot of methods, one of them is toUri(). How can i know from API documentation, that those methods are already implemented somewhere? And where are they implemented at all, in which class?

[Emil Jennings]

The docs will state what implements an interface. Look at java.util Interface Set<E> for example, it lists the type parameters, all superinterfaces, all known subinterfaces, and all known implementing classes.

[Jesper de Jong]

You cannot instantiate an interface directly. A method like Paths.get(...) actually returns an instance of a class that implements interface Path. All the methods that are available on interface Path are implemented, so you can call them as you like.

It is not possible to have an object that implements only part of the methods of an interface. You're worrying about a problem that doesn't exist...

[Zo Ve]

@Emil Jennings
If you go in API documentation, and look on interface that i used in my example: java.nio.file.Path, there is not section like: All Known Implementing Classes.
But methods of interface Path are somewhere implemented, so I can use them. I don't see that class from API documentation, that implements those methods?

[Zo Ve]

@Jesper de Jong
You wrote:

All the methods that are available on interface Path are implemented, so you can call them as you like.

How do you know from API doc. that they are implemented?
(ok, i know that they are implemented somewhere, as far as i can use them, but how can i know that from API doc).

[Paul Clapham]

If your code is getting a Path object (and it surely is if it calls a method which returns a Path object), that means that it's getting an object of a class which isn't documented in the API. That would imply that that class isn't a public class. The standard Java code includes numerous non-public classes which are used to support the public classes which are documented. In this case there's a good chance that the class of the Path object you get depends on the operating system where your code is running.

[Paul Clapham]

By the way you can find out what class an object belongs to simply by calling its getClass() method. Try that on the code you posted and examine the result.

[Jesper de Jong]

Zo Ve wrote:How do you know from API doc. that they are implemented?
(ok, i know that they are implemented somewhere, as far as i can use them, but how can i know that from API doc).

You don't need to know from the API doc. They are always implemented, because it is simply not possible that you get an object for which some of the methods are not implemented.

Is your question really: where are the methods implemented, rather than: are the methods implemented? The API doc doesn't say where the methods are implemented; where they are implemented, is an implementation detail. You don't need to know where they are implemented to be able to use the Path object.

[Zo Ve]

Ok Paul, that sounds like reasonable explanation. I didn't know before for non-public classes.
Problem that I think exists is following:
Suppose i write some interface with some methods and i document it in some API doc. And I give that interface to you to use it. You will not know that methods of my interface are implemented somewhere or not. So you have to test it with some peace of code. It would be easier that somewhere is written: "methods of this interface are already implemented, you can overwrite them if you're not satisfied with our implementation" or "methods of this interface are not implemented, you have to implement them yourself".
I think that i see flaw in documentation, but i am not sure. I don't know Java that good, so I have dilemma, am I asking a stupid question or there is flaw for real... or thing is totally irrelevant, but i can't yet figure out that with my knowledge of Java.

[Jesper de Jong]

You're thinking the wrong way about interfaces.

You can only use the interface if it is fully implemented somewhere.

If you write an interface and document it in some API doc, and you give just the interface to me, then the only thing I can do to use it is write my own class that implements the interface. You can also give me other classes that implement the interface, but you'd have to give me those classes too and tell me about it.

Methods of an interface are not implemented in one single place. You can create as many classes as you want that implement the interface, with different implementations. Look for example at the List interface. There are different classes that implement interface List, for example class ArrayList and class LinkedList. There's not just one implementation of interface List.

[Steve Luke]

Because Paths.get() returns a Path, and it is compiled to a .class file, you know that there are really just two possible scenarios:
1) it returns null
2) it does not return null, and therefore returns an Object that implements Path.

So the only thing you need to do to 'know' that what you get back fully implements Path is to check if the return is null. Why do you know this? It would be a compile-time error if it weren't true: the object returned from Paths.get() would have to be some type that does not implement Path, which would not match Paths.get()'s signature, and so would not compile. Since it did compile, then you can be sure that, if the return value is not-null then the returned Object implements Path (and its methods).

If you gave me an interface, and nothing else, then I would have no indication that the interface has been implemented. If you gave me an interface and a class which returned an object with the type of your interface, then I would know that there is an implementation in your code somewhere. If you don't make that implementation coderanch, then you are telling me that I don't need to know about it, I should just use the method's return value.

[Zo Ve]

Jesper I think that I have understood much of what you've written. But let me ask you new question.
Lets say that you see for the first time interfaces: java.awt.event.ActionListener and java.nio.file.Path.
Both of that interfaces have they own methods. But usually i have always to write my own implementation for method actionPerformed() in interface ActionListener. In case of Path interface, you can use those methods as you wish (don't need to implement them if you're satisfied with their implementation). If I use method actionPerformed() as they gave us, it want do nothing, but in case of Path methods, all the methods do something.
So, how do you know in which interface you have to implement methods, and in which interface you don't. Does it come from experience, or I have something missed to learn about interfaces?

[Zo Ve]

@Jasper
...it will do nothing...
instead of
...it want do nothing...

(error in my comment)

[Zo Ve]

@Steve

If you gave me an interface, and nothing else, then I would have no indication that the interface has been implemented. If you gave me an interface and a class which returned an object with the type of your interface, then I would know that there is an implementation in your code somewhere. If you don't make that implementation coderanch, then you are telling me that I don't need to know about it, I should just use the method's return value.

Using this criteria, how would you treat interface Path?
When you go in API documentation, class Paths (whose method returns object of type Path) isn't mentioned at all in description of Path interface.
So if i haven't gone through tutorial i wouldn't see any connection between Path and Paths?
In tutorial they say that interface Path is one of the entry points for package java.nio.file, but when i go in API documentation, nothing suggests in description that i have to go first in class Paths, if I want to get objects of type Path.

[Jesper de Jong]

The interfaces ActionListener and Path are used in different ways.

You create a class that implements interface ActionListener and then you pass an instance of your class to for example a JButton, by calling the JButton's addActionListener() method - you pass your own ActionListener to the method as an argument.

With interface Path, the method Paths.get(...) returns an object that is an instance of a class that implements interface Path.

Do you see that difference: in the first one, you pass an object to the method, and in the second one, the method returns an object to you.

What you're supposed to do with an interface entirely depends on what the purpose of that interface is exactly.

Zo Ve wrote:In case of Path interface, you can use those methods as you wish (don't need to implement them if you're satisfied with their implementation). If I use method actionPerformed() as they gave us, it want do nothing, but in case of Path methods, all the methods do something.

You seem to have a misunderstanding about what interfaces, classes and objects are, but I find it hard to understand what exactly your misunderstanding is.

Interfaces and classes aren't "things". They are only a contract, or a plan to create "things". Objects are "things".

Objects are instances of classes. A class is a "plan" that describes what data an object contains (member variables) and what you can do with the object (the methods).

Classes can implement interfaces. An interface is a contract, it lists a set of methods, and a class that implements the interface, has specific implementations for all the methods of the interface.

A method, such as Paths.get(...) doesn't give you an interface. It gives you an object of a class that implements the interface.

If you just have the interface, such as the ActionListener interface, you can't do anything with it directly. Before you can do anything with the interface, you need to have an object that is an instance of a class that implements the interface.

A method like JButton.addActionListener(...) expects you to pass it an object that is an instance of a class that implements the ActionListener interface to it. Normally, you have to write that class, create an instance of the class (an object) and pass it to the method.

A method like Paths.get(...) returns an object that is an instance of a class that implements interface Path. Note that the Paths.get(...) method creates that object for you, and returns it to you.

[Zo Ve]

Sorry people, i know that I am annoying with my question, but i need this conversation, because i have feeling that i have missed something, when i tried to learn interfaces.

[Zo Ve]

@Jasper
This discussion went too wide.
Things about classes, objects and so on are not problem.
I used term "object of type Path", because of shorter conversation, not because i believe that I can instantiate object from interface. Consider that term as you wrote "object that is an instance of a class that implements interface Path".

I have to return to the beginning. Problem is following:
When I see in API documentation some interface, first thing that comes to my mind is that i have to write class with all implementation of interface methods. But in case of, for example Path interface, those implementations are already written for me. So how can i know for which interface those implementations are written and and for which interface they are not, reading just API documentation.

Or maybe, you want to say that for all interfaces in API doc, implementations of their methods are already written, excluding those specific interfaces for EventHandling (like ActionListener)?

[Jesper de Jong]

You don't know that by just reading the API documentation of the interface.

It depends on how the interface is used, and what the purpose of the interface is. I already explained how for example ActionListener and Path are used in different ways.

I don't understand why you think there is a problem or a flaw in the documentation.

[Jesper de Jong]

I've been thinking of an analogy to explain this. Maybe this helps:

You want to make a painting. So you buy different colors of paint. Then you read the manual that comes with the paint, and now you're asking "Why does the manual not tell me where the red paint should go on my painting? I think that's a problem with the manual of the red paint.".

[Winston Gutkowski]

Zo Ve wrote:I used term "object of type Path", because of shorter conversation, not because i believe that I can instantiate object from interface.

But in fact that is exactly what you are getting from the example in your initial post - an object of type Path - so your use is absolutely correct.

And because it's an object, you know that somebody must have implemented it for you; so the only thing left for you to find out is how to USE it. And to do that, you look at the API documentation for java.nio.file.Path.

When I see in API documentation some interface, first thing that comes to my mind is that i have to write class with all implementation of interface methods. But in case of, for example Path interface, those implementations are already written for me. So how can i know for which interface those implementations are written and and for which interface they are not, reading just API documentation.

In the case of your original example, you don't need to, for the reason I just mentioned. If a method returns something to you whose type is an interface, you know that it must already be implemented; you just may not be able to see that implemention.

Another common example of an "invisibly implemented" interface is:
String[] someStringArray = new String[] { a bunch of Strings );
List<String> stringsAsList = Arrays.asList(someStringArray);
which converts an array to a List.

You don't need to know the details of the implementation (in fact, it's a private class hidden inside Arrays); all you need to know is how to use it, and that's documented in the asList() method itself, and the java.util.List interface documentation.

HIH

Winston

[Paweł Baczyński]

And if you really need to know how it's done, you can check the source of java.nio.file.Paths.

If you run the code below, you'll get a name of an implementation of Path interface.

import java.nio.file.Path;
import java.nio.file.Paths;

public class Main {
    public static void main(String[] args) {
        Path p = Paths.get("C:\\");
        System.out.println(p.getClass().getCanonicalName());
    }
}

In my case it's sun.nio.fs.WindowsPath, but on Linux it will be a different one.
The point is, you don't need to know the name of an implementation to use it.

[Jayesh A Lalwani]

Zo,

A meta comment about this thread. The Java API is designed using some common design patterns. For example, Path is based on a factory pattern, and ActionListener is based on a Listener pattern. Things like your question in the OP will be a lot clear once you understand design patterns, and start seeing those patterns inside the Java API.

The catch22 situation is you need to have a fairly good grasp of being able to program before you start to learn design patterns. You don't need to be an expert programmer, but you need to be somewhere between junior and mid level programmer before you start learning design patterns. I don't know at what proficiency you are, but if you are just starting to learn java, focus on learning how to use java. Put your trust in the java gods, and believe that they have done things for a reason. Curiosity is good. You just might have to contain it for a while. If you are at a point where you are fairly comfortable with java, put java aside and start looking at design patterns. Things will be a lot clearer. You will start to see why Java gods created this universe the way they did.

Sorry, nothing to add that is useful to you immediately. It just sounded from your questions that learning design patterns might help you in the long run.

[Zo Ve]

Some things are clearer, some are not. But this conversation was useful for me.
Ok people, thanks to you all, on your time and your patience.

[Jesper de Jong]

Do you still have a specific question that we could try to answer?

[Zo Ve]

@Jasper
Actually I do.
There is one more problem for me that I noticed. Here is description:
When I read oracle tutorial about File I/O, they say that java.nio.file.Path interface is entry point for java.nio.file package. After that, i go in API documentation to see description for that interface. In description they don't say how can you get objects on which you can use methods of that interface.
See it, in tutorial they say that you have to create those objects from Paths class, but in API doc. they don't mention that at all.
So what I have to do? To read description for all classes in package java.nio.file just to get idea which class should I use, to get those objects, on which I can use methods from Path interface? Is there an easier way to do that?
Why is something called entry point if I have to visit something else before, to get to that entry point?

Let me clear this little bit more:
If i first go in API doc. to interface Path, nothing in that description suggests that I should use class Paths to create necessary objects.
But if I first go in API doc. to class Paths, I can figure out from method get(...) that i should go next to the Path interface.
How can i figure out, what is first place that i have to visit in API doc, when I start to study some package, to get idea where to go to the next place?

[Paul Clapham]

You're right, the API documentation for the Path interface doesn't tell you how you should use that interface. However if you look around, you'll find that none of the pages in the API documentation tell you how to use the classes and interfaces they describe. That isn't the purpose of the documentation.

But I see you found the tutorial. The tutorials are there specifically to tell you how you can use various features of Java and I highly recommend them. So to answer your question...

How can i figure out, what is first place that i have to visit in API doc, when I start to study some package, to get idea where to go to the next place?

You don't have to look in the API documentation at all. Read the tutorial first and that should get you started. The only reason to read the API is to find out what methods are available and what they do, that sort of thing. Don't expect it to tell you how to use them, that's what the tutorials are for.

[Winston Gutkowski]

Zo Ve wrote:When I read oracle tutorial about File I/O, they say that java.nio.file.Path interface is entry point for java.nio.file package. After that, i go in API documentation to see description for that interface. In description they don't say how can you get objects on which you can use methods of that interface.

I'm going to disagree slightly with my colleague Paul here, and say that the API docs do tell you how to use a specific class or interface; just as the manual for a car tells you how to start it, and where all the bits and pieces you need to know about are. But it doesn't tell you how to drive it, because it's assumed that you've learned that somewhere else.

And that's the business of tutorials - they provide the context. You don't learn a language by looking at a dictionary, do you? You learn it by study, and repetition. But a dictionary can be awfully useful if you're in a foreign country where you speak some of the language, but just don't happen to know a particular word.

Basically, the API is your dictionary, and when you get more familiar with it, you'll be amazed just how much you can get from it; but it's not there to teach you how to use whole packages or frameworks or extensions, like Collections or JDBC or (as in your case) I/O. For that, you need a tutorial.

HIH

Winston

PS: Just FYI, the API index also contains package documentation, which often provides a bit of background information - which is what you're lacking at the moment. Clicking on the 'java.file.nio' link gets you its summary page, and clicking on its 'Description' link gets you this page, which does contain some of the information you're looking for - but only some, and it's in pretty dry form.

[Zo Ve]

Nice example with learning of language and dictionary.

I was thinking that I am doing something wrong while I am reading API documentation, and because of that, i don't see connection between some things. I thought that I have to jump into some entry point of some package, and from there I'll be sent where I have to go, depending of what I need. But I have to have some basic knowledge from tutorial to see that connection.
Ok, thanks people, that would be all for now.
See you on some other topic, with new question (probably about concurrency, that is next topic I am going to study after File I/0).

[Winston Gutkowski]

Zo Ve wrote:See you on some other topic, with new question (probably about concurrency, that is next topic I am going to study after File I/0).

Good luck. Just remember: the main problem with concurrency is not that it's intrinsically complex, but that the situations that can arise are.

Perversely, this means that simple, easy-to-read code is usually the best solution.

Winston