Once an object is instantiated, as in “Let there be light,” we can use the object by calling its methods. As I mentioned in the previous post, the authors of classes publish their API so that their clients know what methods are available and how to call those methods. The figure below illustrates how calling a class method alters the flow of control in your program. When this program starts running, the JVM executes instruction 1, then instruction 2, then it encounters a method call.
At that point, the JVM transfers control to the method and starts executing instructions in the method. When the method finishes executing, the JVM transfers control back to the program immediately after the point the method was called and continues executing instructions in the program.
A class API consists of the class method names, their return values, and their argument lists.
The argument list for a method indicates the order and number of arguments to send to the method, along with the data type of each argument. Each item in the argument list consists of a data type and a name. The arguments can be literals, constants, variables, or any expression that evaluates to the data type specified in the API of the method.
For example, the API in the table below shows that the setMonth method takes one argument, which must evaluate to an integer value. A method may or may not return a value, as indicated by a data type, class type, or the keyword void in front of the method name. If the method returns a value, then the data type or class type of its return value will precede the method’s name.
For instance, in the previous post, a getDay method would return an integer value. The call to a value-returning method will be used in an expression. When the method finishes executing, its return value will replace the method call in the expression. If the keyword void precedes the method name, the method does not return a value. Because methods with a void return type have no value, they cannot be used in an expression; instead, a method call to a method with a void return type is a complete statement. In the previous post’s scheme, a setYear method would be a void method.
Another keyword you will see preceding the method call in an API is public. This keyword means that any client of the class can call this method. If the keyword private precedes the method name, only other methods of that class can call that method. Although I will not formally include the public keyword in the API, all the methods I plan to discuss in the following posts are public.
To call a method for an object of a class, we use dot notation, as follows:
The object reference is followed immediately by a dot (a period), which is followed immediately by the method name. (Later, when we call static methods, we will substitute the class name for the object reference.) The arguments for the method are enclosed in parentheses. Let’s look again at the methods of the EndOfTimes class. The first three methods in the hypothetical EndOfTimes class API take an empty argument list and return an int; thus, those methods have a return value of type int. You can call these methods in any expression in your program where you could use an int.
The value of the first method, getMonth( ), is the value of the month in the object. Similarly, the value of getDay( ) is the value of the day in the object, and the value of getYear( ) is the value of the year. These “get” methods are formally called accessor methods; they enable clients to access the value of the instance variables of an object.
The next three methods in the EndOfTimes class API take one argument of type int and do not return a value, which is indicated by the keyword void. These methods are called in standalone statements. The first method, setMonth( int mm ), changes the value of the month in the object to the value of the method’s argument, mm. Similarly, setDay( int dd ) changes the value of the day in the object, and setYear( int yy ) changes the value of the year in the object to the value of the method’s argument. These “set” methods are formally called mutator methods; they enable a client to change the value of the instance variables of an object.
The code below illustrates how to use some of the methods of the EndOfTimes class.
EndOfTimes is underlined red because this API class doesn’t exist and is therefore merely hypothetical. The year of Kali Yuga is too far so it is also not useful to place an end to time so far away.
Line 10 calls the getMonth method for the maitreya object. When line 10 is executed, control transfers to the getMonth method. When the getMonth method finishes executing, the value it returns (7) replaces the method call in the statement. The statement then effectively becomes:
In lines 16–17, we print the value of the day in the kaliYuga object. Again, control transfers to the getDay method, then its return value (30) replaces the method call. So the statement effectively becomes:
Line 16 calls the setDay method, which is used to change the value of the day for an object. The setDay method takes one int argument and has a void return value. Line 17 is a complete statement, because the method call to a method with a void return value is a complete statement. The method changes the value of the day in the kaliYuga object. Then, on line 19, we instantiate another object, christ, with a month, day, and year of 11, 12, 1817, which I demonstrate by printing the values returned by calls to the getMonth, getDay, and getYear methods. Baha u’llah was born on that day month and year, and claimed to be the return of Jesus. (This is not, however, the beginning of the new calendar for the Baha’i.)
On line 25, we call the nextDay method, which has a void return value, and increments the date to the next day, and then we print the new values of the christ object.