A class can have three kinds of members:

In this chapter we concentrate on the basic members: fields and methods. Nested members are discussed in Chapter 5.

A class declaration can be preceded by class modifiers that give the class certain properties:

A class cannot be both final and abstract.

A class declaration can be preceded by several modifiers. Modifiers are allowed in any order, but we recommend that you adopt a consistent order to improve the readability of your code. We always use, and recommend, the order listed.

While we won't be concerned about class modifiers in this chapter you need to know a little about public classes. Most Java development tools require that a public class be declared in a file with the same name as the class, which means there can only be one public class declared per file.

Exercise 2.1: Write a simple Vehicle class that has fields for (at least) current speed, current direction in degrees, and owner name.

Exercise 2.2: Write a LinkedList class that has a field of type Object and a reference to the next LinkedList element in the list.

When a field is declared it can be initialized by assigning it a value of the corresponding type. In the Body example, the nextID field is initialized to the value zero. The initialization expression, or more simply the initializer, need not be a constant, however. It could be another field, a method invocation, or an expression involving all of these. The only requirement is that the initializer be of the right type and, if it invokes a method, no checked exceptions may be thrown because there is no surrounding code to catch the exception. For example, the following are all valid initializers:

double zero = 0.0;             // constant
double sum = 4.5 + 3.7;        // constant expression
double zeroCopy = zero;        // field
double rootTwo = Math.sqrt(2); // method invocation
double someVal = sum + 2*Math.sqrt(rootTwo); // mixed

Although initializers provide a great deal of flexibility in the way fields can be initialized, they are only suitable for simple initialization schemes. For more complex schemes we need additional tools—as we shall soon see.

If a field is not initialized a default initial value is assigned to it depending on its type:

Sometimes you want only one instance of a field shared by all objects of a class. You create such fields by declaring them static, so they are called static fields or class variables. When you declare a static field in a class only one copy of the field exists, no matter how many instances of the class are created.

In our case, Body has one static field, nextID, which contains the next body identifier to use. The nextID field is initialized to zero when the class is initialized after it is loaded (see “Loading Classes” on page 435). You will see that each newly created Body object will be assigned the current value of nextID as its identifier, and the value of nextID will be incremented. Hence, we only want one copy of the nextID field, to be used when creating all Body instances.

Within its own class a static field can be referred to directly, but when accessed externally it must usually be accessed using the class name. For example, we could print the value of nextID as follows:

System.out.println(Body.nextID);

The use of System.out itself illustrates accessing a static field. When a static member of a class is referenced many times from another class, or when multiple static members of a class are referenced from another class, you can clarify the code, and perhaps save some typing, by using a static import statement to name the class of the static member once. This is discussed in detail in Section 2.9 on page 71.

A static member may also be accessed using a reference to an object of that class, such as

System.out.println(mercury.nextID);

You should avoid this form because it gives the false impression that nextID is a member of the object mercury, not a member of the class Body. It is the type of the reference, not the type of the object it refers to, that determines the class in which to look for the static variable.

In this book when we use the term field, we usually mean the non-static kind. When the context makes it ambiguous, we use the term non-static field to be clear.

Exercise 2.3: Add a static field to your Vehicle class to hold the next vehicle identification number, and a non-static field to the Vehicle class to hold each car's ID number.

A final variable is one whose value cannot be changed after it has been initialized—any attempt to assign to such a field will produce a compile-time error. We have seen final fields used to define named constants because constants don't change value. In general, a final field is used to define an immutable property of a class or object—a property that doesn't change for the lifetime of the class or object. Fields that are marked final also have special semantics with regard to concurrent access by multiple threads, this is discussed in more detail in Chapter 14.

If a final field does not have an initializer it is termed a blank final. You would use a blank final when simple initialization is not appropriate for a field. Such fields must be initialized once the class has been initialized (in the case of static final fields) or once an object of the class has been fully constructed (for non-static final fields). The compiler will ensure that this is done and refuse to compile a class if it determines that a final field does not get initialized.

A final field of a primitive type, or of String type, that is initialized with a constant expression—that is, an expression whose value can be determined at compile time—is known as a constant variable. Constant variables are special because the compiler treats them as values not fields. If your code refers to a constant variable, the compiler does not generate bytecode to load the value of the field from the object, it simply inserts the value directly into the bytecode. This can be a useful optimization, but it means that if the value of your final field needs to be changed, then every piece of code that refers to that field also has to be recompiled.

Whether a property is immutable is determined by the semantics of the application for which the class was designed. When you decide whether a field should be final, consider three things:

If the property is merely infrequently changed rather than truly immutable then a final field is not appropriate. If the value of the field is not known when the object is created then it can't be made final, even if it is logically immutable once known. For example, in a simulation of celestial bodies a comet may become trapped by the gravitational pull of a star and commence to orbit that star. Once trapped the comet orbits the star forever or until it is destroyed. In this situation the orbits field will hold an immutable value once set, but that value is not known when the comet object is created and so the field cannot be final. Finally, if initialization of the field is expensive and the field's value is infrequently needed, then it may be more practical to defer the initialization of the field until its value is needed—this is generally termed lazy initialization—which cannot be done to a final field.

There are additional considerations concerning final fields if your object must be clonable or serializable. These are discussed in “Cloning Objects” on page 101 and “Object Serialization” on page 549, respectively.

Exercise 2.4: Consider your solution to Exercise 2.3. Do you think the identification number field should be final?

For purposes other than simple initialization, classes can have constructors. Constructors are blocks of statements that can be used to initialize an object before the reference to the object is returned by new. Constructors have the same name as the class they initialize. Like methods, they take zero or more arguments, but constructors are not methods and thus have no return type. Arguments, if any, are provided between the parentheses that follow the type name when the object is created with new. Constructors are invoked after the instance variables of a newly created object of the class have been assigned their default initial values and after their explicit initializers are executed.

This improved version of the Body class uses both constructors and initializers to set up each new object's initial state:

class Body {
    public long idNum;
    public String name = "<unnamed>";
    public Body orbits = null;
    private static long nextID = 0;

    Body() {
        idNum = nextID++;
    }
}

A constructor declaration consists of the class name followed by a (possibly empty) list of parameters within parentheses and a body of statements enclosed in curly braces. Constructors can have any of the same access modifiers as class members, but constructors are not members of a class—a distinction you can usually ignore, except when it comes to inheritance. Constructors can also have annotations applied to them; see Chapter 15.

The constructor for Body takes no arguments, but it performs an important function—assigning a proper idNum to the newly created object. In the original code, a simple programmer error—forgetting to assign the idNum or not incrementing nextID after use—could result in different Body objects with the same idNum. That would create bugs in code that relies on the part of the contract that says “All idNum values are different.”

By moving responsibility for idNum generation inside the Body class, we have prevented errors of this kind. The Body constructor is now the only entity that assigns idNum and is therefore the only entity that needs access to nextID. We can and should make nextID private so that only the Body class can access it. By doing so, we remove a source of error for programmers using the Body class.

We also are now free to change the way idNum values are assigned to Body objects. A future implementation of this class might, for example, look up the name in a database of known astronomical entities and assign a new idNum only if an idNum had not previously been assigned. This change would not affect any existing code, because existing code is not involved at all in the mechanism for idNum allocation.

The initializers for name and orbits set them to reasonable values. Therefore, when the constructor returns from the following invocations, all data fields in the new Body object have been set to some reasonable initial state. You can then set state in the object to the values you want:

Body sun = new Body();   // idNum is 0
sun.name = "Sol";

Body earth = new Body(); // idNum is 1
earth.name = "Earth";
earth.orbits = sun;

The Body constructor is invoked when new creates the object but after name and orbits have been set to their default initial values.

The case shown here—in which you know the name of the body and what it orbits when you create it—is likely to be fairly common. You can provide another constructor that takes both the name and the orbited body as arguments:

Body(String bodyName, Body orbitsAround) {
    this();
    name = bodyName;
    orbits = orbitsAround;
}

As shown here, one constructor can invoke another constructor from the same class by using the this() invocation as its first executable statement. This is called an explicit constructor invocation. If the constructor you want to invoke has arguments, they can be passed to the constructor invocation—the type and number of arguments used determines which constructor gets invoked. Here we use it to invoke the constructor that has no arguments in order to set up the idNum. This means that we don't have to duplicate the idNum initialization code. Now the allocation code is much simpler:

Body sun = new Body("Sol", null);
Body earth = new Body("Earth", sun);

The argument list determines which version of the constructor is invoked as part of the new expression.

If provided, an explicit constructor invocation must be the first statement in the constructor. Any expressions that are used as arguments for the explicit constructor invocation must not refer to any fields or methods of the current object—to all intents and purposes there is no current object at this stage of construction.

For completeness, you could also provide a one-argument constructor for constructing a Body object that doesn't orbit anything. This constructor would be used instead of invoking the two-argument Body constructor with a second argument of null:

Body(String bodyName) {
    this(bodyName, null);
}

and that is exactly what this constructor does, using another explicit constructor invocation.

Some classes always require that the creator supply certain kinds of data. For example, your application might require that all Body objects have a name. To ensure that all statements creating Body objects supply a name, you would define all Body constructors with a name parameter and you wouldn't bother initializing the name field.

Here are some common reasons for providing specialized constructors:

Constructors without arguments are so common that there is a term for them: no-arg (for “no arguments”) constructors. If you don't provide any constructors of any kind in a class, the language provides a default no-arg constructor that does nothing. This constructor—called the default constructor—is provided automatically only if no other constructors exist because there are classes for which a no-arg constructor would be incorrect (like the Attr class you will see in the next chapter). If you want both a no-arg constructor and one or more constructors with arguments, you must explicitly provide a no-arg constructor. The default constructor has the same accessibility as the class for which it was defined—if the class is public then the default constructor is public.

Another form of constructor is a copy constructor—this constructor takes an argument of the current object type and constructs the new object to be a copy of the passed in object. Usually this is simply a matter of assigning the same values to all fields, but sometimes the semantics of a class dictate more sophisticated actions. Here is a simple copy constructor for Body:

Body(Body other) {
    idNum = other.idNum;
    name = other.name;
    orbits = other.orbits;
}

Whether this is correct depends on the contract of the class and on what the uniqueness of idNum is supposed to indicate—for this example we won't concern ourselves with that.

This idiom is not used much within the Java class libraries, because the preferred way to make a direct copy of an object is by using the clone method—see “Cloning Objects” on page 101. However, many classes support a more general form of construction that “copies” another object. For example, the StringBuilder and StringBuffer classes (described in Chapter 13) each have a constructor that takes a single CharSequence argument that allows you to copy an existing String, StringBuffer, or StringBuilder object; and the collection classes (described in Chapter 21) each have a constructor that takes another Collection as an argument and so allow one collection to be initialized with the same contents as another (which need not be of exactly the same type). Writing a correct copy constructor requires the same consideration as writing a correct clone method.

Constructors can also be declared to throw checked exceptions. The throws clause comes after the parameter list and before the opening curly brace of the constructor body. If a throws clause exists then any method that invokes this constructor as part of a new expression must either catch the declared exception or itself declare that it throws that exception. Exceptions and throws clauses are discussed in detail in Chapter 12.

Exercise 2.7: Add two constructors to Vehicle: a no-arg constructor and one that takes an initial owner's name. Modify the main program so that it generates the same output it did before.

Exercise 2.8: What constructors should you add to LinkedList?

Another way to perform more complex initialization of fields is to use an initialization block. An initialization block is a block of statements that appears within the class declaration, outside of any member, or constructor, declaration and that initializes the fields of the object. It is executed as if it were placed at the beginning of every constructor in the class—with multiple blocks being executed in the order they appear in the class. An initialization block can throw a checked exception only if all of the class's constructors are declared to throw that exception.

For illustration, this variant of the Body class replaces the no-arg constructor with an equivalent initialization block:

class Body {
    public long idNum;
    public String name = "<unnamed>";
    public Body orbits = null;

    private static long nextID = 0;

    {
        idNum = nextID++;
    }

    public Body(String bodyName, Body orbitsAround) {
        name = bodyName;
        orbits = orbitsAround;
    }
}

Now the two-argument constructor doesn't need to perform the explicit invocation of the no-arg constructor, but we no longer have a no-arg constructor and so everyone is forced to use the two-argument constructor.

This wasn't a particularly interesting use of an initialization block but it did illustrate the syntax. In practice, initialization blocks are most useful when you are writing anonymous inner classes—see Section 5.4 on page 144—that can't have constructors. An initialization block can also be useful to define a common piece of code that all constructors execute. While this could be done by defining a special initialization method, say init, the difference is that such a method would not be recognized as construction code and could not, for example, assign values to blank final fields. Initialization is the purpose of having initialization blocks, but in practice you can make it do anything—the compiler won't check what it does. Spreading initialization code all through a class is not a good design, and initialization blocks should be used judiciously, when they express something that cannot easily be done by constructors alone.

The static fields of a class can have initializers as we have already seen. But in addition we can perform more complex static initialization in a static initialization block. A static initialization block is much like a non-static initialization block except it is declared static, can only refer to static members of the class, and cannot throw any checked exceptions. For example, creating a static array and initializing its elements sometimes must be done with executable statements. Here is example code to initialize a small array of prime numbers:

class Primes {
    static int[] knownPrimes = new int[4];

    static {
        knownPrimes[0] = 2;
        for (int i = 1; i < knownPrimes.length; i++)
            knownPrimes[i] = nextPrime();
    }
    // declaration of nextPrime ...
}

The order of initialization within a class is first-to-last—each field initializer or initialization block is executed before the next one, from the beginning of the source to the end. The static initializers are executed after the class is loaded, before it is actually used (see “Preparing a Class for Use” on page 441). With this guarantee, our static block in the example is assured that the knownPrimes array is already created before the initialization code block executes. Similarly, anyone accessing a static field is guaranteed that the field has been initialized.

What if a static initializer in class X invokes a method in Y, but Y's static initializers invoke a method in X to set up its static values? This cyclic static initialization cannot be reliably detected during compilation because the code for Y may not be written when X is compiled. If cycles happen, X's static initializers will have been executed only to the point where Y's method was invoked. When Y, in turn, invokes the X method, that method runs with the rest of the static initializers yet to be executed. Any static fields in X that haven't had their initializers executed will still have their default values (false, '/u0000', zero, or null depending on their type).

A static method is invoked on behalf of an entire class, not on a specific object instantiated from that class. Such methods are also known as class methods. A static method might perform a general task for all objects of the class, such as returning the next available serial number or something of that nature.

A static method can access only static fields and other static methods of the class. This is because non-static members must be accessed through an object reference, and no object reference is available within a static method—there is no this reference.

In this book when we use the term method, we usually mean the non-static kind. When the context makes it ambiguous, we use the term non-static method to be clear.

Exercise 2.9: Add a static method to Vehicle that returns the highest identification number used thus far.

Methods are invoked as operations on objects via references using the dot (.) operator:

reference.method(arguments)

In the BodyPrint example we invoke the println method on the object referred to by the static reference System.out and passing a single String argument formed by concatenating a number of other strings.

Each method is declared to have a specific number of parameters, each of a specific type. The last parameter of a method can be declared as a sequence of parameters of a given type. This is indicated by an ellipse (...) after the type name. For example, String... is a sequence of zero or more String objects. Sequence parameters allow you to invoke the method by passing in a variable number of arguments, some of which will correspond to that sequence. These variable argument methods are described in the next section.

When a method is invoked the caller must provide an argument of the appropriate type for each of the parameters declared by the method. An argument need not be exactly the same type as its corresponding parameter because some automatic conversions are applied. For example, a byte argument can be converted to an int parameter, and wrapper objects can be converted to their primitive values (and vice-versa) as needed—see “Boxing Conversions” on page 198.

Methods also have a return type, either a primitive type or a reference type. If a method does not return any value, the place where a return type would go is filled with a void.

The BodyPrint example illustrates a common situation in which you would like to examine the state of an object. Rather than providing access to all the fields of the object, a class can define a method that returns a string representation of the state of the object. For example, here is a method of the Body class to return a String that describes the particular Body object it is invoked upon:

public String toString() {
    String desc = idNum + " (" + name + ")";
    if (orbits != null)
        desc += " orbits " + orbits.toString();
    return desc;
}

This method uses + and += to concatenate String objects. It first builds a string that describes the identifier and name. If the body orbits another body, we append the string that describes that body by invoking its toString method. This recursion builds a string of bodies orbiting other bodies until the chain ends with an object that doesn't orbit anything. The resulting string is then returned to the caller by the return statement.

The toString method of an object is special—it is invoked to get a String when an object is used in a string concatenation expression using the + operator. Consider these expressions:

System.out.println("Body " + sun);
System.out.println("Body " + earth);

The toString methods of sun and earth are invoked implicitly and produce the following output:

Body 0 (Sol)
Body 1 (Earth) orbits 0 (Sol)

All objects have a toString method whether their class explicitly defines one or not—this is because all classes extend the class Object and it defines the toString method. Class extension and the Object class are discussed in Chapter 3.

Exercise 2.10: Add a toString method to Vehicle.

Exercise 2.11: Add a toString method to LinkedList.

The last parameter in a method (or constructor) parameter list can be declared as a sequence of a given type. To indicate that a parameter is a sequence you write an ellipse (...) after the parameter type, but before its name. For example, in

public static void print(String... messages) {
    // ...
}

the parameter messages is declared to be a sequence of String objects. Sequence parameters allow a method to be invoked with a variable number of arguments (including zero) that form the sequence. Such methods are known as variable-argument, or more commonly varargs methods; methods that don't declare a sequence parameter are known as fixed-argument methods.^[2]

The need to process a variable number of arguments can arise in many situations. For example, our Body objects already track which other body they orbit, but it can be useful to know which Body objects they are orbited by. While a given body generally only orbits one other body, it may itself be orbited by many other bodies. To track this we could define an array of Body objects and provide a method to add each orbiting body, one at a time, to that array. That is not an unreasonable solution, but it is much more convenient if we just define a method that can take a sequence of Body objects:

public void setOrbiters(Body... bodies) {
    // ... store the values ...
}

You could then use this method in the following way:

Body sun = new Body("Sol", null);
Body earth = new Body("Earth", sun);
Body moon = new Body("Moon", earth);
Body mars = new Body("Mars", sun);
Body phobos = new Body("Phobos", mars);


Body deimos = new Body("Deimos", mars);

earth.setOrbiters(moon);
mars.setOrbiters(phobos, deimos);

You may be wondering what type the parameter sequence bodies has inside setOrbiters—quite simply it is an array of Body objects. Declaring a parameter as a sequence is nothing more than asking the compiler to construct an array for you and to set its elements to be the arguments actually passed for the sequence. When you invoke a method, the compiler will match each supplied argument to a named parameter. If the compiler finds a sequence parameter then it will bundle all the remaining arguments into an array of the type specified by the sequence parameter—remember a sequence parameter must be the last declared parameter. Of course, those arguments must be of the right type to be stored in the array. If no arguments are left to store in the array then a zero-length array is created and passed as the argument. Knowing this, you could save the compiler the trouble and pass an array yourself:

Body[] marsMoons = { phobos, deimos };
mars.setOrbiters(marsMoons);

But in most cases it is easier to just let the compiler do its job.

Sometimes the compiler will need some help working out what you intended a particular method invocation to mean. For example, suppose you invoke setOrbiters with the single argument null. Does that mean to pass null as the array (and so have no array) or does it mean to have an array of length one with a null entry? The compiler can't be sure so it will give you a warning. To remove the ambiguity you need to cast null to a suitable type—for a sequence parameter of type T, if you cast to T then you get an array of T of length one with a null entry; if you cast to T[] then you get a null array reference. Other ambiguities can arise in the context of method overloading, but we'll get to those later (see “Overloading Methods” on page 69).

You've already seen an example of another varargs method in use, but may not have realized it. The printf method that was introduced on page 23 is declared to take a String and a sequence of Objects. For each format specifier in the format string, the method expects a corresponding object argument to be passed in.

Exercise 2.12: Considering your Vehicle and LinkedList classes, can you think of a need for any methods that take a variable number of arguments?

When a method is invoked, the flow of control passes from the calling method into the invoked method and the statements of that method are executed in sequence according to the semantics of those statements. A method completes execution and returns to the caller when one of three things happens: a return statement is executed, the end of the method is reached, or an uncaught exception is thrown.

If a method returns any result, it can only return a single result—either a primitive value or a reference to an object. Methods that need to return more than one result can achieve this effect in several ways: return references to objects that store the results as fields, take one or more parameters that reference objects in which to store the results, or return an array that contains the results. Suppose, for instance, that you want to write a method to return what a particular person can do with a given bank account. Multiple actions are possible (deposit, withdraw, and so on), so you must return multiple permissions. You could create a Permissions class whose objects store boolean values to say whether a particular action is allowed:

public class Permissions {
    public boolean canDeposit,
                   canWithdraw,
                   canClose;
}

Here is a method that fills in the fields to return multiple values:

public class BankAccount {
    private long number;    // account number
    private long balance;   // current balance (in cents)

    public Permissions permissionsFor(Person who) {
        Permissions perm = new Permissions();
        perm.canDeposit = canDeposit(who);
        perm.canWithdraw = canWithdraw(who);
        perm.canClose = canClose(who);
        return perm;
    }

    // ... define canDeposit et al ...
}

In methods that return a value, every path through the method must either return a value that is assignable to a variable of the declared return type or throw an exception. The permissionsFor method could not return, say, a String, because you cannot assign a String object to a variable of type Permissions. But you could declare the return type of permissionsFor as Object without changing the return statement, because you can assign a Permissions object reference to a variable of type Object, since (as you know) all classes extend Object. The notion of being assignable is discussed in detail in Chapter 3.

All parameters to methods are passed “by value.” In other words, values of parameter variables in a method are copies of the values the invoker specified as arguments. If you pass a double to a method, its parameter is a copy of whatever value was being passed as an argument, and the method can change its parameter's value without affecting values in the code that invoked the method. For example:

class PassByValue {
    public static void main(String[] args) {
        double one = 1.0;

        System.out.println("before: one = " + one);
        halveIt(one);
        System.out.println("after:  one = " + one);
    }

    public static void halveIt(double arg) {
        arg /= 2.0;     // divide arg by two
        System.out.println("halved: arg = " + arg);
    }
}

The following output illustrates that the value of arg inside halveIt is divided by two without affecting the value of the variable one in main:

before: one = 1.0
halved: arg = 0.5
after:  one = 1.0

You should note that when the parameter is an object reference, it is the object reference—not the object itself—that is passed “by value.” Thus, you can change which object a parameter refers to inside the method without affecting the reference that was passed. But if you change any fields of the object or invoke methods that change the object's state, the object is changed for every part of the program that holds a reference to it. Here is an example to show this distinction:

class PassRef {
    public static void main(String[] args) {
        Body sirius = new Body("Sirius", null);

        System.out.println("before: " + sirius);
        commonName(sirius);
        System.out.println("after:  " + sirius);
    }

    public static void commonName(Body bodyRef) {
        bodyRef.name = "Dog Star";
        bodyRef = null;
    }
}

This program produces the following output:

before: 0 (Sirius)
after:  0 (Dog Star)

Notice that the contents of the object have been modified with a name change, while the variable sirius still refers to the Body object even though the method commonName changed the value of its bodyRef parameter variable to null. This requires some explanation.

The following diagram shows the state of the variables just after main invokes commonName:

At this point, the two variables sirius (in main) and bodyRef (in commonName) both refer to the same underlying object. When commonName changes the field bodyRef.name, the name is changed in the underlying object that the two variables share. When commonName changes the value of bodyRef to null, only the value of the bodyRef variable is changed; the value of sirius remains unchanged because the parameter bodyRef is a pass-by-value copy of sirius. Inside the method commonName, all you are changing is the value in the parameter variable bodyRef, just as all you changed in halveIt was the value in the parameter variable arg. If changing bodyRef affected the value of sirius in main, the “after” line would say “null”. However, the variable bodyRef in commonName and the variable sirius in main both refer to the same underlying object, so the change made inside commonName is visible through the reference sirius.

Some people will say incorrectly that objects are passed “by reference.” In programming language design, the term pass by reference properly means that when an argument is passed to a function, the invoked function gets a reference to the original value, not a copy of its value. If the function modifies its parameter, the value in the calling code will be changed because the argument and parameter use the same slot in memory. If the Java programming language actually had pass-by-reference parameters, there would be a way to declare halveIt so that the above code would modify the value of one, or so that commonName could change the variable sirius to null. This is not possible. The Java programming language does not pass objects by reference; it passes object references by value. Because two copies of the same reference refer to the same actual object, changes made through one reference variable are visible through the other. There is exactly one parameter passing mode—pass by value—and that helps keep things simple.

You can declare method parameters to be final, meaning that the value of the parameter will not change while the method is executing. Had bodyRef been declared final, the compiler would not have allowed you to change its value to null. When you do not intend to change a parameter's value, you can declare it final so the compiler can enforce this expectation. A final declaration can also protect against assigning a value to a parameter when you intended to assign to a field of the same name. The declaration can also help the compiler or virtual machine optimize some expressions using the parameter, because it is known to remain the same. A final modifier on a parameter is an implementation detail that affects only the method's code, not the invoking code, so you can change whether a parameter is final without affecting any invoking code.

The Body class with its various constructors is considerably easier to use than its simple data-only form, and we have ensured that the idNum is set both automatically and correctly. But a programmer could still mess up the object by setting its idNum field after construction because the idNum field is public and therefore exposed to change. The idNum should be read-only data. Read-only data in objects is common, but there is no keyword to apply to a field that allows read-only access outside the class while letting the class itself modify the field.

To enforce read-only access, you must either make the field final, which makes it read-only for the lifetime of the object, or you must hide it. You hide the field by making the idNum field private and providing a new method so that code outside the class can read its value using that method:

class Body {
    private long idNum;    // now "private"

    public String name = "<unnamed>";
    public Body orbits = null;

    private static long nextID = 0;

    Body() {
        idNum = nextID++;
    }

    public long getID() {
        return idNum;
    }

    //...
}

Now programmers who want to use the body's identifier will invoke the getID method, which returns the value. There is no longer any way for programmers to modify the identifier—it has effectively become a read-only value outside the class. It can be modified only by the internal methods of the Body class.

Methods that regulate access to internal data are sometimes called accessor methods. Their use promotes encapsulation of the class's data.

Even if an application doesn't require fields to be read-only, making fields private and adding methods to set and fetch them enables you to add actions that may be needed in the future. If programmers can access a class's fields directly, you have no control over the values they will use or what happens when values are changed. Additionally, making a field part of the contract of a class locks in the implementation of that class—you can't change the implementation without forcing all clients to be recompiled. For example, a future version of Body may want to look-up the ID number in a database indexed by the body's name and not actually store the ID number in the object at all. Such a change cannot be made if idNum is accessible to clients. For these reasons, you will see very few public or protected fields in subsequent examples in this book.

Methods to get or set a value in an object's state are sometimes said to define a property of that object. For example, the Body class's getID can be said to define an ID property for Body objects that is retrieved by the getID method, and implemented by the idNum field. Some automatic systems, including those for the JavaBeans^™ component architecture, use these conventions to provide automatic property manipulation systems; see Section 25.3 on page 721. We can and should define the name and orbits fields to be properties by making them private and providing set and get methods for them:

class Body {
    private long idNum;
    private String name = "<unnamed>";
    private Body orbits = null;

    private static long nextID = 0;

    // constructors omitted ...

    public long getID() { return idNum; }
    public String getName() { return name; }
    public void setName(String newName) {
        name = newName;
    }
    public Body getOrbits() { return orbits; }
    public void setOrbits(Body orbitsAround) {
        orbits = orbitsAround;
    }
}

Making a field final can be another way to prevent unwanted modifications to a field, but immutability and accessibility should not be confused. If a field is immutable then it should be declared final regardless of accessibility. Conversely, if you don't want a field to form part of the contract of a class you should hide it behind a method, regardless of whether the field is read-only or modifiable.

Now that we have made all the fields of Body private, we can return to an earlier remark that access control is per-class not per-object. Suppose that a body could be captured by another body and forced to orbit around it, we could define the following method in Body:

public void capture(Body victim) {
    victim.orbits = this;
}

If access control were per-object, then the capture method when invoked on one object would not be able to access the private orbits field of the victim body object to modify it. But because access control is per-class, the code of a method in a class has access to all the fields of all objects of that class—it simply needs a reference to the object, such as via a parameter as above. Some object-oriented languages advocate per-object access control, but the Java programming language is not one of them.

Exercise 2.13: Make the fields in your Vehicle class private, and add accessor methods for the fields. Which fields should have methods to change them, and which should not?

Exercise 2.14: Make the fields in your LinkedList class private, and add accessor methods for the fields. Which fields should have methods to change them, and which should not?

Exercise 2.15: Add a changeSpeed method that changes the current speed of the vehicle to a passed-in value and add a stop method that sets the speed to zero.

Exercise 2.16: Add a method to LinkedList to return the number of elements in a list.