Section 2.6. Understanding the API

   

---

2.6 Understanding the API

In the last section you recall that we created a String object and that (almost) everything in Java is an object. We are able to create an object of type String because this class is defined by Sun. The SDK contains hundreds and hundreds of classes developed by Sun that are part of the core packages. java.lang , for instance, is the package containing the String class. A set of predefined code definitions is referred to as a library.

Note

The concept of core Java libraries is much like the <cf> tag library that ships with ColdFusion Server, which offers about 90 predefined tags and more than 250 functions. Together, these make up the core ColdFusion language. But if ColdFusion MX did not come with a <cfchart> tag, you could create <cf_chart> yourself (which people have done). It would be a drag if you had to make your own <cfset> tag, though, as it is such a fundamental aspect of working with code. So Sun includes these extensive libraries for convenience, ease of use, rapid adoption of the language, performance, and standardization.

The API is the collection of these libraries. It defines what you can do with the SDK to make Java programs. The API is very, very large. You can read it online at the Sun site. It can be somewhat confusing at first, if for no other reason than that you have to remember where things are (what package the class you want is in) or if the method you want even exists.

To read the API online, go to http://java.sun.com. Click on Products and APIs and then Java 2 Platform, Standard Edition. If the site has changed when you read this, you can also search for documentation. This is convenient if you want to check something quickly.

You can also download the documentation (it's about 30 MB) so that you can view it locally. Figure 2.1 shows the Overview page.

Figure 2.1. API documentation.

2.6.1 Unpacking an Archive

Once you have downloaded the . zip file (Windows), you need to unpack it. Go ahead and move it into your JAVA _ HOME directory. If you don't have a Zip utility, you can unpack the . zip file using Java. Java lets you create archive files called jars (Java ARchives); these use the same compression algorithm as Zip does. So you can interchangeably pack and unpack zips and jars with this utility.

To unpack the documentation, open a command prompt and type cd jdk1.4 . Assuming this directory is where you placed the documentation zip file, you can now type the command jar -xf j2sdk-1_4_0-doc.zip (or the name of your documentation's zip file, if different). Now navigate to the docs subdirectory and open the index.html page. This is the API documentation.

2.6.2 Reading the API

The API documentation was itself generated by a Java tool called javadoc . When a library is created, the programmer can specify comments in a special way that allows the javadoc tool to read over the file and automatically generate this style of documentation for the code. This is a very useful tool that merits quick consideration in later chapters. The code in the Java library is well commented, and, as noted above, its source code is freely available.

Successfully using the API requires some getting used to. The frame in the upper left-hand corner contains all of the packages in the current release. The larger frame below it contains an alphabetical list of all the interfaces, classes, and exceptions in that package. Clicking on an item displays detailed information on the item in the main frame. This information describes the methods of the class, its constructors, and the error conditions and exceptions it throws. This is just the information you need to write Java programs.

For instance, java.lang is one of the most basic packages in Java. It is automatically imported into (made available for use) every Java application. Clicking on the java.lang package expands a number of interfaces (which we will discuss later), classes, exceptions, and errors. Click on the java.lang.Math class. This class defines certain fields ”such as pi ”and methods ”such as cos() ”that allow you to easily reference and use common mathematical properties and functions.

Note

ColdFusion defines a number of these same methods, such as cos() , tan() , round() , and so forth, that work much as they do in Java. You will notice that Java defines more methods, however. Some of this is due to Java automatically defining things like pi for you. Some of it is due to the fact that Java is a strongly typed language, whereas ColdFusion is not.

You may notice a small set of + and “ signs that form a rudimentary sort of graphical tree that points from java.lang.Object to java.lang.Math . This indicates that java.lang.Math inherits the properties and behavior of the java.lang.Object class. In fact, every class in Java inherits from java.lang.Object ”both those predefined in the library and those that you make yourself.

Note

java.Math and java.lang.Math are different. java.Math was added in a later version of Java in order to allow for arbitrary precision decimals and integers to aid in precise rounding. The distinction is not necessarily important here; the point is that it can be hard to find things in the API documentation when you're getting started.

We can test how to use the classes we find in the API by printing out Java's value for pi.

2.6.3 PItest.java

 /* file: PItest.java     purpose: print the value of PI    author: E Hewitt    version 1.0 */ public class PItest { public static void main (String [] args) { System.out.println("value of PI:" + java.lang.Math.PI);    } } 

This program prints the following to the command line:

 value of PI: 3.141592653589793 

We could just as easily have replaced the call to java.lang.Math.PI in the above program with a simple call to Math.PI , and the program would run exactly the same way. That is because the java.lang package is automatically included with each Java application, so we don't need to use the fully qualified name.

Note

Other packages that you use may need to be imported to be referenced in this direct manner. We will look more closely at importing later. But this command in Java is the reason for the introduction in ColdFusion MX of the <cfimport> tag.

In the next chapter we will look at what kinds of data Java makes available and write a number of procedural programs to illustrate their use.

---

Top