Java programming course: 2.4 The Java APIs

In the previous lesson you saw how to deal with errors.

• Previous lesson 2.3 Dealing with errors
• Course contents

The Java APIs

Java contains many pre-built classes to facilitate programming for graphics, networking, multi-threading[1], etc. You can access the Application Programming Interface (API) documentation for all of Java supplied classes from the following link:

You can scroll through the alphabetical list of classes in the bottom left margin (under the heading All Classes) and select the required class. The currently selected class API appears in the main section.

The String class

Open the API in your browser and select the String class. Your screen should look something like this:

The above web-based documentation is known as Javadoc. After some header information you will see a description of the class. Scroll through the main body until you reach the section headed Method Summary, where you will see an alphabetic list of all available methods that can be invoked on String objects. Scroll to the method named toUpperCase() and click its link. You should now see a description of what the method does:

This tells you that the method converts all of the characters to upper-case; but note that it doesn't actually modify the object on which it operates but instead returns a new String with its characters in upper-case; the original String object is unchanged!

String word = "banana";
String anotherWord = word.toUpperCase();

// At this point:
//   word still contains "banana"
//   anotherWord contains "BANANA"
 

If you want to modify the content of the original String you would need to assign the returned String reference to itself:

String word = "banana";
word = word.toUpperCase(); // Now word contains "BANANA"
 

In fact, there are no methods within the String class that modify the object on which it is applied; instead, a new String object is returned. It is therefore an immutable class. Immutable classes provide several advantages (including but not limited to being simple to use in multi-threaded applications), and many built-in Java classes are immutable.

In the examples just given note the way in in which the String object was created above: the new keyword was not used. This feature is unique to the String class; all other classes require new to instantiate objects. This feature exists for convenience to the programmer since strings are so frequently used. You are still allowed to use new when instantiating, however:

String word1 = new String(“apple”); // this is perfectly valid
String word2 = "orange"; // this is the shortcut technique
 

Another aspect of String that differs from other classes is the fact that Java pools unique strings in memory:

String name1 = “Bob”;
String name2 = “Bob”;
// At this point there is only ONE object of type String in
// existence, and both name1 and name2 point to that same object.
// This is because name2 had the same content as name1 when created.
 

It is important to note, though, that when new is used for String (and all other classes) you always get separate objects, even if the values passed in are the same.

String name3 = new String(“Thelma”);
String name4 = new String(“Thelma”);
// name3 and name4 are TWO separate objects
 

Primitive data types

You have already seen that int is a primitive type that can store integer values. You should note the following about the int primitive:

• It is signed; meaning it can store negative as well as positive integers
• It is stored using 32 bits (i.e., 4 bytes), so its range of values is -2³¹ to 2³¹ - 1

There are three other signed integer primitives of different sizes:

• byte: 8 bits, range -128 to 127
• short: 16 bits, range -32,768 to 32767
• long: 64 bits, range -2⁶³ to 2⁶³ – 1

byte b = 47
short s = -12345
long g = 1234567890
 

There is a separate primitive called char which is used to hold Unicode[1] characters. This is unsigned and 16 bits, holding the range of values \u0000 to \uFFFF (in hexadecimal[2]):

// Examples (note must use single quotes for char)
char letterA = 'A';		// the letter A
char tab = '\t';		// the tab character
char greekLetterPi = '\u03c0';
 

There are two primitives which hold floating-point numbers and which allow decimal places to be stored:

• float: 32 bits, range ± 3.4 x 10³⁸ to ± 1.4 x 10^-45
• double: 64 bits, range ± 1.8 x 10³⁰⁸ to ± 4.9 x 10^-324

// Examples
float f = 123.45f; // the 'f' is required for floats
double d = 123.45; // 'd' at end is optional so is omitted here
 

An important point to note about the floating-point types of float and double is that they are intended for scientific and engineering uses and as such are not suitable for storing or doing calculations with monetary amounts. This will be explored in a later section.

The final primitive type is boolean, which can only be one of the values true or false:

// Examples
boolean raining = true;
boolean sunny = false;
 

Each of the eight primitives above have wrapper classes within Java, although they are not used anywhere near as frequently as the primitives. They can be distinguished due to their class names beginning with a capital letter (as per the normal Java naming conventions), and have similar (but not always identical) names:

Enhancements in Java 7

If you are using Java 7 or later, then you can use the underscore character as a separator for numeric literals, as a means of making the number easier to read. For example, to define an int with the value of one million, contrast the following two statements:  

// Pre-Java 7...
int million = 1000000;

// Java 7 onwards...
int million = 1_000_000;
 

In the next section you will learn more about classes and methods.

Lesson 3.1 Using classes and methods