This article is for you, if:
- You understand the basics of Java but do not know how to understand and user third party libraries
- You are a Java programmer, and you trying to find out the way you can communicate to your collegues, how they can use the components created by you
This article is not for you, if:
- You are not aware of methods, classes etc of Java
What is an API document?
API document are also called Java docs and is used to communicate the low level programming interface to programmers. API docs highlight one of the important principles of OOPs, which is 'abstraction'. These documents gives only the programming interface and hide the complexity of the interface. In simple terms, it means, the API docs tells what arguments a method will take and what will be the result returned. However, it will not provide the details of how the result is reached.
Understanding elements in API document
Let us take the API document for J2SE 1.4 from Sun Java website.
The document with Frames are convenient to use.
You must have noticed that, the docs are divided into three sections.
- Package explorer
- Class and Interface explorer
- Description section
Let us dig deep with examples for each element to understand this better:
The left top section contains all the packages for the library in question. For this example, it is the packages present in J2SE 1.4 like java.lang, java.io etc. Clicking any of the package in the package explorer will provide only the list of classes & interface in the class explorer. Also, there is a 'All classes' link, which is show all the classes & interfaces in J2SE 1.4.
Class and Interface explorer
This section is present in the left bottom of the Java docs, just below the package explorer section. It shows all classes, interfaces, exceptions and errors present in the selected package. All interface names are italics styled for differenciation.
The description section contains all the details. When you click on a package, it shows the details of that package and when you click on a class/interface it shows the details of it.
Let us check an Interface. Click on the class List present in java.util package.
We get the following information reading the description section:
- List interface extends Collection interface
- It provide links to all known classes which implement this interface
- A detailed description of the interface itself
- Method summary provide the details of all the methods that are defined in the interface. The method summary provide the method signature and return type. Since the methods in an interface are by default abstract, we do not see this variation for List interface. For viewing details of a particular method we can click on that method. We can see the details of the method like what each argument means and what will be the logic of the method. For example, check the add(int, Object) method. It also provides details of the exceptions which the method throws.
Lets check the information displayed for a class. Let us take the Integer wrapper class present in java.lang.
- In the description top, the class name will be marked with abstract to indicate if the class in abstract class.
- The field summary shows any public instance variables present in the class. Example MAX_VALUE variable. Once clicking it, we see that this field is also defined as public static final variable.
- When you want to create an instance of a class, you need to know, which constructors are present for that class. How do we get this information? Constructor summary provides this information.
- The Integer wrapper class can be instantiated using String parameter or primitive int parameter. We get to know, that it does not have a empty constructor. So, Integer intTotal = new Integer(); will give compilation error. Clicking a constructor gives more information. We can see that the Integer constructor using String parameter throws a NumberFormatException, if the String is not parsable to integer.
- In the method summary, we see some methods marked as static. This helps us understand that the method can be called without creating an instance. For example intValue() is not marked static but parseInt is marked as static. So, we can use both the methods as below:
Integer intObj = new Integer(10);
int i = intObj.intValue();
int j = Integer.parseInt("10");
- The method summary also shows if a particular method is abstract.
- After the method summary, there are sections which show the methods which were inherited from parent class.
- Next >>