Chapter:Objects - Java API documentation
- 1 Meta information about this chapter
- 2 The Java API online documentation
- 3 Links
Meta information about this chapter
Expand using link to the right to see the full content.
The purpose of this chapter, is to introduce the online Java API documentation. Without the documentation of the fairly huge API which comes with the SDK, it would be impossible to work as a Java programmer. The sheer amount of classes makes it impossible to remember what classes exists and what they consist of.
Introducing the online documentation at this early stage in the course material makes students used to looking up classes and their use, even before the students know how to write classes on their own.
We think that using the online API documentation also works as a compromise when teaching about objects before teaching about classes and how to write them. Having the huge API with prefab well-documented classes, allows us to create and use objects without having to know how to write classes!
We can now talk about constructors of a class, or methods of a class, without knowing the details of what the code for a constructor or method looks like.
- Creating a habit of the student to look at the documentation and understand how to read it
- Giving the student a basic understanding of packages - by looking at some basic packages in the Java API
- Making the student understand that you can't know everything about every class, but documentation solves that problem
Instructions to the teacher
As usual, beware that talking about classes before the student knows what the source code of a class looks like might be a challenge. You can motivate this by explaining that the only thing you need to know about a class, in order to use and object of that class, is the public API of the class - that is, what public constructors, variables and methods exist. With a well documented class, like
java.lang.String, there is no need to look at the source code, neither in order to find out that there is a
charAt() method, nor how to use it.
This is also a good opportunity to bring up the difference between the roll of the API programmer (those who wrote e.g. String) and the role of an application programmer (the ones writing programs using Strings).
The Java API online documentation
You might (rightfully) wonder how we could know what classes exist in the Java API and, perhaps even more so, how we knew what constructors and instance methods existed in those classes. The answer is, that we cheated and looked in the API documentation!
The thing is, that Java comes with quite an extensive library, what is often called the Java API. There are so many classes included in the API and many of the classes are quite large, so that no one is expected to learn all the classes and how to use them by heart. For this, the good people at Oracle have created an online API where you can explore the API and examine the classes.
The API is divided in packages, and the packages include related classes (and so called interfaces, which we haven't learned about yet). To examine for instance the ArrayList class (in the java.util package) you can navigate to the java.util package and click on the ArrayList class. You are then presented with a web page describing the ArrayList class. First on such a class page in the API documentation is a descriptive text about the class, its purpose and sometimes some example uses. Next the public parts of the class (public parts are such parts which you can use as a programmer) such as variables (fields), constructors (if any) and methods.
In this chapter (videos and the next chapter exercises) we show you how to find the Java online documentation, how to navigate it and how to read about constructors for some classes and about instance methods. Later in the course, we will learn that we can create such documentation pages in HTML ourselves using a certain type of comments directly in our source code.
Chapters about Objects
Here are the chapters about objects in this book:
- Chapter:Objects_-_Java_API_documentation « you are here!
Lecture slides and Videos
English Live videos
- Java - Objects - Java's API documentation - Live (Full playlist) | Introduction to Java's API documentation | How to read about a class in Java's API documentation | Documentation page for ArraryList | Documentation page for Properties | Documentation page for System
Swedish live videos
- Java - Objekt - API-dokumentaion - Live-videor (Full playlist) | Introduktion till Javas API-dokumentation (Live) | Hur man läser om en klass i API-dokumentationen | Dokumentation för ArraryList | Dokumentation för Properties | Dokumentation för System
See some English live videos right here
If you don't want to head on to Vimeo for the English videos, you can watch them right here.
- Java™ Platform, Standard Edition 8 API Specification - Always keep this one open in a browser when writing Java!
- Java Platform Standard Edition 8 Documentation
- Java Platform, Standard Edition (Java SE) 8
Where to go next
Next page has the exercises for this chapter: Objects_-_Java_API_documentation_-_Exercises