API's and Javadoc: What are they?

API's and Javadoc: What are they?

An API stands for a "Java Application Programming Interface". It is like a super dictionary of the Java language, that one uses to look something up in. It has an index or collection of all Java packages, classes and interfaces, with all of their methods, fields and constructors, and how to use them. When one programs, there are many classes that are commonly used, and therefore pre created, so that the programmer doesn't need to create them from scratch. Let's look, for example, at a computer window frame. If the programmer had to create one from scratch, he would have to write hundreds of lines of code, to create the scroll down menu, the exit box, etc. Since a window frame is very popular, Sun has written the code for one, and all that you have to do is import the package that contains the window frame, and instantiate one with a new statement.

As with all of Sun's classes, we do not care how it is implemented, all we need to know are what the methods are, the constructors, and it's fields. Hence the name Java Application Programming Interface, the API is a collection of interfaces telling us what each class can do, not telling us how it is done. The API contains many packages for many different purposes, among them, the applet package for creating applets, the awt and swing packages for graphics and GUI, the io package for input and output, the sql package for Java databasing, and many many more. For every package that you use a class from you must import it, with the exception of the java.lang package that deals with basic programming classes, that is automatically imported into your program.

Each API is organized in the following way. When you start the API you are given three frames, the first listing all of the Java packages in that API, and when you click on any particular package, the second frame lists all of the interfaces, classes, and exceptions in that package. The main frame starts with an overview of all of the packages, and shows the index, class hierarchy for each package, and help section when you click for it on the top menu. Also, it gives you the details for each class document. The Index contains an alphabetic list of all classes, interfaces, constructors, methods, and fields. The class document is set up with the top showing that class inheritance diagram and subclasses, the middle showing the field, method, and constructor summaries, and the bottom giving details for the fields, methods, and constructors.

In short, when you start programming, you're constantly going to have to look up something in the API. There's going to be some class or method that you don't know how to use, you're not sure what parameters it takes, etc, and you can find out all of the information in the API. When Shlomo started writing Java, a certain program always crashed during some String methods, and Shlomo spent hours trying to figure it out unsuccessfully. Finally someone looked up the String methods in the API, noticed that the method substring() was spelled substring() instead of the assumed subString(). Well, Shlomo was extremely impressed, until he himself figured out how to use the API, and realized how easy it was.

Javadoc is the ability to create these API looking documents out of your own code. When you write your code you place html tags and javadoc tags in special comments (that look like this)

/*

*

* place comments here

*

*/

These comments you place before the beginning of the code for your class, and before most of your methods. Then instead of typing in java or javac on the CMD console, you type "javadoc nameOfClass" or "javadoc NameOfPackage". The compiler will then create an html document, that explains your methods, fields and constructors, plus whatever HTML that you added, in the same exact way that the API looks.

For more information on javadoc, check out Sun's official tool section .