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.

Java Platform SE 8

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!

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

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:

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

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.

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

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]):

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

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:

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:

​ Primitive type​	​ Class wrapper type​
​ boolean​	​Boolean​
​ byte​	​Byte
char​	Character​
double​	Double​
float​	Float​
int​	Integer​
long​	Long​
short​	Short​

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:  

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

Lesson 3.1 Using classes and methods