Want this course?
Course: JVM Fundamentals for Clojure
This lesson goes over the structure of the Javadocs and some tricks for making the most of them.
So when Java came out, this was like 90, 96 or so, maybe earlier than that, one of the cool things it had was a documentation system where you would put the docs right in the code and then there was a tool that would read-in your code and generate an HTML page.
Now back in 1996, HTML pages for your docs automatically generated that was a big deal and it really helped improve the quality of the documentation. Standardized it, there's a lot of good information in that. That system is called Javadoc. So sometimes you just have to read the Javadocs and I've read so many, I've forgotten really all the tidbits that I found in the Javadocs. But I'll share the ones that, the big ones, the obvious ones with you.
So first things first, there have many versions of Java and sometimes the standard library changes. Usually it grows, so there's new methods, there's new classes in the newer version of Java. They're pretty good about keeping the old stuff around. But what it means is, is that you're gonna have to figure out what version of Java you're running on.
The version of Java, the JVM that you're running on is gonna determine what methods you have available. As I say this, the current version is Java 8. Java 7 has been end of life, so you shouldn't be doing new projects on it anymore. But it's pretty new, relatively speaking, so a lot of the code out there, a lot of the Javadocs that have been indexed are going to be using Java 7. So if I do, let's say I want to look up what are the methods on strings. So I would do this, java string. You notice it is seven, Java 7. SE, that's standard edition, Java Platform Standard Edition 7. So this is the one that's indexed by Google as number one, because probably most people link to this one and Google is not smart enough yet to determine that really you should be showing eight.
Okay so what I do is eight, look other people do that too, Java 8 string. Now you get the eight. So be careful when you're clicking on links, make sure that it's tuned to the one that you are looking for. Now the one you're looking for also should be the one that is the JVM version you're running on. And you could do that with a simple command, java-version, and I go over that in another lesson. But it's real simple, java-version. You cannot abbreviate it, you can't do -v. You do -version, and it'll tell exactly what is being run.
Okay so let's look at this Javadoc. Okay this is quite a long document because is has every method in string. But at the top, and like documentation for them. Which is nice, it's really nice documentation. You don't really want to scroll around to much in this, I just wanted to show you how long it is, it's quite long. But what you've got is a summary up at the top. So this is the package right above the class. And this is trying to mimic that you're declaring a class so it'll say class string.
There's interfaces and other stuff, but in this one it's a class. And this shows you the hierarchy. So string is a subclass of object only. It also has interfaces that it implements. Okay and look these are all clickable. This one is clickable too, this java.lang.Object and this will bring you to the page for that, which is fantastic.
Okay now it's showing you the code that was the first line in this class. Notice it's final, like there's a lot of good information in here, but I'm a big doc string about string. Some CL also, so okay here's where it gets interesting. You have a table with all of the fields. There's a short piece of documentation here and if you click here, it jumps you, it's the same file, but it jumps you down to the field's longer documentation. So that's why I say you don't want to be scrolling around. You want to be working in that table. So back out of this.
The other thing is, notice it gives you the return type, or the type of it 'cause this is just a field, and that's clickable too. So it's really well, it's like a very good way to navigate around to the docs. Anytime you see a class name, it's going to be clickable. Look String, String, Charset, String, String. Okay here's all the constructors, after the fields.
Constructors are how you build it. And this one has quite a few, some are deprecated but you notice you get the type signature, and what it means to call this constructor. That's all great. After the constructors, you're going to have the methods. This is nice, it's showing you the different types of methods that you can filter by. So the static methods on a string, these are nice, you got some formatting and stuff.
Instance methods, these are methods for an instance in this class. Okay, and of course you click on one of them and it's going to jump you to where you need to go. The documentation for these kinds of things is actually pretty good. It's not perfect but it's pretty good.
Concrete methods, these are, wow that's a different thing, I've never seen that. Deprecated methods, there you go. I guess now with Java 8, I haven't really used Java 8 but Java 8 has a thing where you can give a, on a class you can have a method without an implementation that subclasses are expected to implement. So I guess these are all the implemented ones.
Let's go back to all methods. Okay, very long list. But here's the other thing, classes inherit the methods and fields from their parent. So you can get these methods on object right here. So if you don't find what you're looking for in this list, sometimes it's pretty short because a class will only override one method from the superclass. You go down here and you see, oh I see all the stuff is defined in here. In fact, let's look up a different thing. I'm going to back out, back to Java, and back to Google. I'm going to do Java 8 inputstream. Okay, so then click on that. Now let's pick a particular inputstream.
How about FileInputStream? These are all the subclasses, so I'm clicking on a subclass, and we notice FileInputStream is a subclass of InputStream. I'm gonna go scroll down to, ah sorry, it's so short I've skipped it. Method summary, so these are all the methods that it overrides, that might have special meaning. In addition to the inputstream meaning, these have meaning for files that are different. And now we can see that inputstream, well there are three that aren't overridden that are defined only in inputstream, and so those you click and they bring you to the inputstream page.
If we look at another one, oh let's look at StringBufferInputStream. Right, that's mostly deprecated. Yeah it's all deprecated. Another one. ByteArrayInputStream. Right, so this one overrides more methods so you don't see it. So there's a lot of information in here. And I refer to these all the time, especially if you want something like super standard that you know must be in Java.
Okay one more tip. So we're looking at one class right here, what we can do is hit this frames. Remember this is done back in the 90s, early 90s, mid 90s, when frames were still a thing.
Browsers still understand them but look now we get all the classes. We have the packages up here, we have all the classes and all packages or we can filter in this old style. So like, let's say I want to see what's in java.net it redoes this one and I can see this. So one thing I do a lot is I'll load all classes because I don't know where it is. I know the one I want but I can't remember the package name. So I'll then do a search. So I want to search for standard, all the standard things. So I just do the in-browser search and I get the one I'm looking for.
We can look at all these things up here. We can see the whole class hierarchy for this package. We can see the package in big expanded form. We can see everything deprecated. Really nice. Okay go back to the class because it lost its context. So let's open one. There we are. Okay, so Javadocs are really helpful. I often don't leave it open, I just Google search it because it will jump right there. And then once I'm there, I'll be browsing around and using it to choose which methods I'm gonna call.
Java has had a way to package compiled code and resources and share them around since almost the beginning. It's called the JAR (Java Archive). Combine that with an artifact, versioning, and dependency management system (called Maven), and we have a complete dependency management system.