1.14 Calling Instance Methods

1.14 Calling Instance Methods

An instance method is called through a particular object, because its behavior may depend on that object’s instance variables. The receiver—the object on which the method operates—can be stored in an instance variable, parameter variable, or local variable.

For example, if company refers to a dog-walking company, then company.numAvailableDogs(hour) asks that particular company how many dogs remain available at a particular hour. The method name alone is not enough to identify the object unless the call occurs inside an instance method where the receiver is implicitly this.

Receivers: which object gets the call?

Learning Objective 1.14.A: Call instance methods on objects. This directly develops Skill 3.A: Write program code to call methods and supports Skill 3.C: Write program code to satisfy method specifications using expressions, conditional statements, and iterative statements.

Where the object is stored	Example call	Receiver
Instance variable	company.numAvailableDogs(hour)	The object referenced by company
Parameter variable	walker.walkDogs(dogs)	The object referenced by walker
Local variable	shift.getLength()	The object referenced by shift
Current object	this.updateDogs(hour)	The object currently executing the method
Different class’s object	company.reserveBlock(period, start, duration)	The company object

Inside an instance method, writing numAvailableDogs(hour) is shorthand for this.numAvailableDogs(hour) when no other interpretation applies. The omitted receiver is therefore not automatically an error. Outside an applicable instance context—or when calling a method on a different object—a receiver such as company or walker is required.

Calling methods on the current object

The keyword this refers to the object that called the current instance method. It makes the receiver explicit:

this.walkDogs(hour);

The explicit keyword does not prevent duplicate calls. If walkDogs changes the company’s available-dog count, calling it twice in one loop iteration changes the state twice. The programmer must decide how many calls are intended and ensure that a state-changing method is called only that many times.

Parameters belong in the call, not the declaration

A method declaration states parameter types; a method call supplies argument values. Do not repeat the types in a call.

public boolean isMinuteFree(int period, int minute) {
    // method body
}

boolean free = company.isMinuteFree(period, minute);  // correct

The call must provide every required argument in the correct order. A nested call can supply one argument, but it does not erase the other arguments:

int start = findFreeBlock(period, duration);
company.reserveBlock(period, start, duration);

A common misconception is to write company.isMinuteFree(int period, int minute). That syntax belongs to a declaration, not an invocation. Another is to call an instance method with a class name, such as DogCompany.numAvailableDogs(hour); that would be appropriate only for a class method, not for an instance method.

Return values versus void

A void method performs an action but returns no value. A method with another return type produces a value that can be assigned, printed, compared, or used inside a larger expression.

company.updateDogs(hour);                 // void: action only
int available = company.numAvailableDogs(hour); // int: value returned

Because numAvailableDogs returns an int, its result can be compared with maxDogs:

if (company.numAvailableDogs(hour) == maxDogs) {
    System.out.println("No dogs have been scheduled yet.");
}

A void method cannot be used as an operand in an expression. For example, assigning company.updateDogs(hour) to an int is invalid because the call produces no value.

Worked example: calls inside selection and iteration

Suppose a method counts how many dogs can be walked during a range of hours. Each hour is examined once. If dogs are available, the method calls walkDogs once and adds the returned number to the running total.

public int dogsWalked(int startHour, int endHour) {
    int total = 0;

    for (int hour = startHour; hour <= endHour; hour++) {
        if (company.numAvailableDogs(hour) > 0) {
            total += company.walkDogs(hour);
        }
    }

    return total;
}

The algorithm has four deliberate parts: initialize the accumulation variable total, loop through the inclusive hour range, test the value returned by numAvailableDogs, and accumulate the value returned by walkDogs. The call to walkDogs appears once in the loop, so its state-changing effect is not accidentally repeated.

For a peak-hour condition from hour $9$ through hour $17$, Java requires a compound Boolean expression:

if (hour >= 9 && hour <= 17) {
    // peak-hour work
}

The expression 9 <= hour <= 17 is not valid Java syntax. Java compares two values at a time, so the two comparisons must be joined with &&.

Misconception check

Misconception: “If a method call has no receiver written before the dot, it always lacks an object.”
Correction: Within an instance method, an omitted receiver is implicitly this. The real question is whether the call should target the current object or a different object such as company.

Misconception: “A returned value and a changed object are the same thing.”
Correction: A method may return a value, change instance variables, do both, or do neither. Track both the value produced and the object state affected by every call.

Retrieval check

A method contains the parameter duration, a local variable period, and an instance variable company. Write the call that checks whether minute 30 is free in that period, then explain why company.numAvailableDogs(hour) may be compared with maxDogs but company.updateDogs(hour) cannot appear inside that comparison.
Answer: company.isMinuteFree(period, 30); numAvailableDogs returns a value, while updateDogs is void and performs an action.