Chapter 9  Immutable Objects

Java is an object-oriented language, which means that it uses objects to (1) represent data and (2) provide methods related to them. This way of organizing programs is a powerful design concept, and we will introduce it gradually throughout the remainder of the book.

An object is a collection of data that provides a set of methods. For example, Scanner, which you saw in Section 3.2, is an object that provides methods for parsing input. System.out and System.in are also objects.

Strings are objects, too. They contain characters and provide methods for manipulating character data. Other data types, like Integer, contain numbers and provide methods for manipulating number data. We will explore some of these methods in this chapter.

9.1  Primitives vs Objects

Not everything in Java is an object: int, double, char, and boolean are primitive types. When you declare a variable with a primitive type, Java reserves a small amount of memory to store its value. Figure 9.1 shows how the following values are stored in memory:

---

Figure 9.1: Memory diagram of two primitive variables.

---

As you learned in Section 7.2, an array variable stores a reference to an array. For example, the following line declares a variable named array and creates an array of three characters:

Figure 9.2 shows them both, with a box to represent the location of the variable and an arrow pointing to the location of the array.

---

Figure 9.2: Memory diagram of an array of characters.

---

Objects work in a similar way. For example, this line declares a String variable named word and creates a String object, as shown in Figure 9.3:

---

Figure 9.3: Memory diagram of a String object.

---

Objects and arrays are usually created with the new keyword, which allocates memory for them. For convenience, you don’t have to use new to create strings:

Recall from Section 6.10 that you need to use the equals method to compare strings. The equals method traverses the String objects and tests whether they contain the same characters.

To test whether two integers or other primitive types are equal, you can simply use the == operator. But two String objects with the same characters would not be considered equal in the == sense. The == operator, when applied to string variables, tests only whether they refer to the same object.

9.2  The null Keyword

Often when you declare an object variable, you assign it to reference an object. But sometimes you want to declare a variable that doesn’t refer to an object, at least initially.

In Java, the keyword null is a special value that means “no object”. You can initialize object and array variables this way:

The value null is represented in memory diagrams by a small box with no arrow, as in Figure 9.4.

---

Figure 9.4: Memory diagram showing variables that are null.

---

If you try to use a variable that is null by invoking a method or accessing an element, Java throws a NullPointerException:

On the other hand, it is perfectly fine to pass a null reference as an argument to a method, or to receive one as a return value. In these situations, null is often used to represent a special condition or indicate an error.

9.3  Strings Are Immutable

If the Java library didn’t have a String class, we would have to use character arrays to store and manipulate text. Operations like concatenation (+), indexOf, and substring would be difficult and inconvenient. Fortunately, Java does have a String class that provides these and other methods.

For example, the methods toLowerCase and toUpperCase convert uppercase letters to lowercase, and vice versa. These methods are often a source of confusion, because it sounds like they modify strings. But neither these methods nor any others can change a string, because strings are immutable.

When you invoke toUpperCase on a string, you get a new String object as a result. For example:

After these statements run, upperName refers to the string "ALAN TURING". But name still refers to "Alan Turing". A common mistake is to assume that toUpperCase somehow affects the original string:

The previous code displays "Alan Turing", because the value of name, which refers to the original String object, never changes. If you want to change name to be uppercase, then you need to assign the return value:

A similar method is replace, which finds and replaces instances of one string within another. This example replaces "Computer Science" with "CS":

As with toUpperCase, assigning the return value (to text) is important. If you don’t assign the return value, invoking text.replace has no effect.

Strings are immutable by design, because it simplifies passing them as parameters and return values. And since the contents of a string can never change, two variables can reference the same string without one accidentally corrupting the other.

9.4  Wrapper Classes

Primitive types like int, double, and char cannot be null, and they do not provide methods. For example, you can’t invoke equals on an int:

But for each primitive type, there is a corresponding wrapper class in the Java library. The wrapper class for int is named Integer, with a capital I:

Other wrapper classes include Boolean, Character, Double, and Long. They are in the java.lang package, so you can use them without importing them.

Like strings, objects from wrapper classes are immutable, and you have to use the equals method to compare them:

Because x and y refer to different objects, this code displays only “x and y have the same value”.

Each wrapper class defines the constants MIN_VALUE and MAX_VALUE. For example, Integer.MIN_VALUE is -2147483648, and Integer.MAX_VALUE is 2147483647. Because these constants are available in wrapper classes, you don’t have to remember them, and you don’t have to write them yourself.

Wrapper classes also provide methods for converting strings to and from primitive types. For example, Integer.parseInt converts a string to an int. In this context, parse means “read and translate”.

Other wrapper classes provide similar methods, like Double.parseDouble and Boolean.parseBoolean. They also provide toString, which returns a string representation of a value:

The result is the String object "12345".

It’s always possible to convert a primitive value to a string, but not the other way around. For example, say we try to parse an invalid string like this:

parseInt throws a NumberFormatException, because the characters in the string "five" are not digits.

9.5  Command-Line Arguments

Now that you know about strings, arrays, and wrapper classes, we can finally explain the args parameter of the main method, which we have been ignoring since Chapter 1. If you are unfamiliar with the command-line interface, please read Appendix A.3.

Let’s write a program to find the maximum value in a sequence of numbers. Rather than read the numbers from System.in by using a Scanner, we’ll pass them as command-line arguments. Here is a starting point:

You can run this program from the command line by typing this:

The output indicates that args is an empty array; that is, it has no elements:

If you provide additional values on the command line, they are passed as arguments to main. For example, say you run the program like this:

The output is shown here:

It’s not clear from the output, but the elements of args are strings. So args is the array {"10", "-3", "55", "0", "14"}. To find the maximum number, we have to convert the arguments to integers.

The following code uses an enhanced for loop (see Section 7.8) to parse the arguments and find the largest value:

We begin by initializing max to the smallest (most negative) number an int can represent. That way, the first value we parse will replace max. As we find larger values, they will replace max as well.

If args is empty, the result will be MIN_VALUE. We can prevent this situation from happening by checking args at the beginning of the program:

It’s customary for programs that require command-line arguments to display a “usage” message if the arguments are not valid. For example, if you run javac or java from the command line without any arguments, you will get a very long message.

9.6  Argument Validation

As we discussed in Section 5.9, you should never assume that program input will be in the correct format. Sometimes users make mistakes, such as pressing the wrong key or misreading instructions.

Or even worse, someone might make intentional “mistakes” to see what your program will do. One way hackers break into computer systems is by entering malicious input that causes a program to fail.

Programmers can make mistakes too. It’s difficult to write bug-free software, especially when working in teams on large projects.

For all of these reasons, it’s good practice to validate arguments passed to methods, including the main method. In the previous section, we did this by ensuring that args.length was not 0.

As a further example, consider a method that checks whether the first word of a sentence is capitalized. We can write this method using the Character wrapper class:

The expression str.charAt(0) makes two assumptions: the string object referenced by str exists, and it has at least one character. What if these assumptions don’t hold at run-time?

• If str is null, invoking charAt will cause a NullPointerException, because you can’t invoke a method on null.
• If str refers to an empty string, which is a String object with no characters, charAt will cause a StringIndexOutOfBoundsException, because there is no character at index 0.

We can prevent these exceptions by validating str at the start of the method. If it’s invalid, we return before executing the rest of the method:

Notice that null and empty are different concepts, as shown in Figure 9.5. The variable str1 is null, meaning that it doesn’t reference an object. The variable str2 refers to the empty string, an object that exists.

---

Figure 9.5: Memory diagram of null and empty string.

---

Beginners sometimes make the mistake of checking for empty first. Doing so causes a NullPointerException, because you can’t invoke methods on variables that are null:

Checking for null first prevents the NullPointerException. If str is null, the || operator will short circuit (see Section 5.5) and evaluate to true immediately. As a result, str.isEmpty() will not be called.

9.7  BigInteger Arithmetic

It might not be clear at this point why you would ever need an integer object when you can just use an int or long. One advantage is the variety of methods that Integer and Long provide. But there is another reason: when you need very large integers that exceed Long.MAX_VALUE.

BigInteger is a Java class that can represent arbitrarily large integers. There is no upper bound except the limitations of memory size and processing speed. Take a minute to read the documentation, which you can find by doing a web search for “Java BigInteger”.

To use BigIntegers, you have to import java.math.BigInteger at the beginning of your program. There are several ways to create a BigInteger, but the simplest uses valueOf. The following code converts a long to a BigInteger:

You can also create BigIntegers from strings. For example, here is a 20-digit integer that is too big to store using a long:

Notice the difference in the previous two examples: you use valueOf to convert integers, and new BigInteger to convert strings.

Since BigIntegers are not primitive types, the usual math operators don’t work. Instead, we have to use methods like add. To add two BigIntegers, we invoke add on one and pass the other as an argument:

Like strings, BigInteger objects are immutable. Methods like add, multiply, and pow all return new BigIntegers, rather than modify an existing one.

Internally, a BigInteger is implemented using an array of ints, similar to the way a string is implemented using an array of chars. Each int in the array stores a portion of the BigInteger. The methods of BigInteger traverse this array to perform addition, multiplication, etc.

For very long floating-point values, take a look at java.math.BigDecimal. Interestingly, BigDecimal objects represent floating-point numbers internally by using a BigInteger!

9.8  Incremental Design

One challenge of programming, especially for beginners, is figuring out how to divide a program into methods. In this section, we present a design process that allows you to divide a program into methods as you go along. The process is called “encapsulation and generalization”. The essential steps are as follows:

1. Write a few lines of code in main or another method, and test them.
2. When they are working, wrap them in a new method and test again.
3. If it’s appropriate, replace literal values with variables and parameters.

To demonstrate this process, we’ll develop methods that display multiplication tables. We begin by writing and testing a few lines of code. Here is a loop that displays the multiples of two, all on one line:

Each time through the loop, we display the value of 2 * i, padded with spaces so it’s four characters wide. Since we use System.out.printf, the output appears on a single line.

After the loop, we call println to print a newline character. Remember that in some environments, none of the output is displayed until the line is complete. The output of the code so far is shown here:

The next step is to encapsulate the code; that is, we “wrap” the code in a method:

Finally, we generalize the method to print multiples of other numbers by replacing the constant value 2 with a parameter n. This step is called “generalization”, because it makes the method more general (less specific):

Invoking this method with the argument 2 yields the same output as before. With the argument 3, the output is as follows:

By now, you can probably guess how we are going to display a multiplication table: we’ll invoke printRow repeatedly with different arguments. In fact, we’ll use another loop to iterate through the rows:

And the output looks like this:

9.9  More Generalization

The previous result is similar to the “nested loops” approach in Section 6.4. However, the inner loop is now encapsulated in the printRow method. We can encapsulate the outer loop in a method too:

The initial version of printTable always displays six rows. We can generalize it by replacing the literal 6 with a parameter:

Here is the output of printTable(7):

That’s better, but it always displays the same number of columns. We can generalize more by adding a parameter to printRow:

Now printRow takes two parameters: n is the value whose multiples should be displayed, and cols is the number of columns. Since we added a parameter to printRow, we also have to change the line in printTable where it is invoked:

When this line executes, it evaluates rows and passes the value, which is 7 in this example, as an argument. In printRow, this value is assigned to cols. As a result, the number of columns equals the number of rows, so we get a square 7 x 7 table, instead of the previous 7 x 6 table.

When you generalize a method appropriately, you often find that it has capabilities you did not plan. For example, you might notice that the multiplication table is symmetric. Since ab = ba, all the entries in the table appear twice. You could save ink by printing half of the table, and you would have to change only one line of printTable:

This means the length of each row is the same as its row number. The result is a triangular multiplication table:

Generalization makes code more versatile, more likely to be reused, and sometimes easier to write.

9.10  Vocabulary

object-oriented:

A way of organizing code and data into objects, rather than independent methods.

object:

A collection of related data that comes with a set of methods that operate on the data.

primitive:

A data type that stores a single value and provides no methods.

immutable:

An object that, once created, cannot be modified. Strings are immutable by design.

wrapper class:

Classes in java.lang that provide constants and methods for working with primitive types.

parse:

In Chapter 2, we defined parse as what the compiler does to analyze a program. Now you know that it means to read a string and interpret or translate it.

empty array:

An array with no elements and a length of zero.

design process:

A process for determining what methods a class or program should have.

encapsulate:

To wrap data inside an object, or to wrap statements inside a method.

generalize:

To replace something unnecessarily specific (like a constant value) with something appropriately general (like a variable or parameter).

9.11  Exercises

The code for this chapter is in the ch09 directory of ThinkJavaCode2. See page ?? for instructions on how to download the repository. Before you start the exercises, we recommend that you compile and run the examples.