Properties

Consider the Person class that we introduced when discussing constructors:

import java.time.LocalDate

class Person(var name: String, val birth: LocalDate) {
    var isMarried = false
}

This class has three properties:

• name, a writeable property representing the person’s name
• birth, a read-only property representing date of birth
• isMarried, a writeable property recording marital status

Let’s dig into how these properties are represented in the code generated by the compiler.

Probing The Bytecode

1. Examine Person.kt, in the tasks/task12_5_1 subdirectory of your repository. This file contains the implementation of Person shown above.

2. Compile Person.kt in the normal way. This should generate a new file Person.class, containing the Java bytecode representation of the class.

3. In a terminal window, in the same directory as the bytecode file, run the Java class disassembler tool on it, like so¹:

   javap -p Person
   

   Study the output carefully.

You should see clear correspondences between the bytecode representation and the properties of the Kotlin class. For example, the Kotlin property birth is represented in the bytecode by a combination of two things:

• A private variable birth, of type LocalDate
• A public method getBirth(), which returns a LocalDate object

whereas the Kotlin property name is represented by a combination of three things:

• A private variable name, of type String
• A public method getName(), which returns a String object
• A public method setName(), which accepts a String as an argument

The Kotlin property isMarried is represented in a similar way to name, by a combination of private variable, ‘getter’ method and ‘setter’ method.

When you read the value of a property in Kotlin code, the corresponding getter method is called in the Java bytecode to retrieve the value of the associated private variable.

Similarly, when you assign a new value to a property in Kotlin code, the corresponding setter method is called in the Java bytecode, and this updates the value of the associated private variable.

Here’s an example:

val p = Person("Joe", birth=LocalDate.of(1992, 8, 23))

println(p.name)    // JVM calls getName()
p.name = "David"   // JVM calls setName("David")

It’s useful to know all of this because it is possible in Kotlin to customize the getter or setter code associated with a property.

Custom Getter

Let’s change the behaviour of the name property so that we always see a person’s name represented with uppercase characters, regardless of letter case in the stored name. This isn’t especially useful, but it will serve to illustrate the process.

1. Edit the file Getter.kt, in the tasks/task12_5_2 subdirectory of your repository. This contains the implementation of the Person class seen earlier.

   Modify the class definition so that it looks like this:

   class Person(_name: String, val birth: LocalDate) {
   
      var isMarried = false
   
      var name = _name
          get() {
              return field.uppercase()
          }
   }
   

   Note carefully the differences between this and the original version of the Person class:

   • The name property is now defined in the body of the class, and it is initialized using the value supplied via the _name parameter of the primary constructor².

   • An additional piece of code, customizing the getter for name, appears immediately after the definition of the property.

   The new getter code is written as a function, with the name get and an empty parameter list. Inside the body of this function, we use the special name field to refer to the backing field of the property.

2. Add a main() function that creates a Person object and then prints that person’s name.

3. Compile and run the program. You should see the name displayed in uppercase.

Custom Setter

The procedure here is similar to that for customizing a getter. The property needs to be defined in the body of the class and not as part of the primary constructor. You then need to follow the property definition with a special set() function.

Let’s do this for our Person class, customizing the setter for the name property so that a person cannot be given a blank name.

1. Edit the file Setter.kt, in the tasks/task12_5_3 subdirectory of your repository. This contains the implementation of the Person class seen earlier.

   Modify the class definition so that it looks like this:

   class Person(_name: String, val birth: LocalDate) {
   
      var isMarried = false
   
      var name = _name
          set(value) {
              require(value.isNotBlank()) { "Name cannot be blank" }
              field = value
          }
   }
   

   (Note: to keep things simple, we’ve customized only the setter code here, but you are allowed to customize getter and setter at the same time.)

   The set() function takes a single parameter. You can call this anything you like, but value is a sensible choice. This represents the value that appears on the right-hand side of any assignment operation involving the property. You don’t specify a type for this parameter, as type of the corresponding property is already known.

   The body of the function assigns this value to the special variable field, which represents the backing field of the property. Before doing that, value is checked and an exception is thrown if it is not acceptable. The most concise way of doing this is via the require() precondition function.

2. Add a main() function that creates a Person object and then attempts to assign an empty string to its name property.

3. Compile and run the program. It should crash with an IllegalArgumentException. Examine the exception traceback carefully.

Computed Properties

The property examples considered above all have backing fields, but we can also have properties that don’t have backing fields.

For example, if you define a property with a custom getter and that getter doesn’t use the special field variable to reference a backing field, the compiler will not bother creating a backing field for the property. We sometimes describe this as a computed property, because its value is determined solely by computation and not by accessing a backing field associated with the property.

As an example, let’s return to the Circle class discussed earlier:

class Circle(val centre: Point, val radius: Double) {
    fun area() = PI * radius * radius
    fun perimeter() = 2.0 * PI * radius
}

In this implementation, circle area and perimeter are computed via explicit method calls, but area and perimeter could also be viewed as characteristics that are intrinsic to circles. This makes them good candidates for implementation as computed properties.

To achieve this, all we need to do is redefine area() and perimeter() to be val properties with a custom getter:

class Circle(val centre: Point, val radius: Double) {
    val area get() = PI * radius * radius
    val perimeter get() = 2.0 * PI * radius
}

Now, we can use the class like this:

val centre = Point(4.0, 1.0)
val circ = Circle(centre, radius=2.5)

println(circ.area)
println(circ.perimeter)

Note the absence of parentheses here!

Another Example

Let’s return to the Person class for a final example of a computed property.

Imagine that we need to know the age in years of a person. We could write a method to compute this, but age feels much more like an intrinsic attribute of a person than a calculation that needs to be performed. This makes it an ideal candidate for implementation as a computed property.

1. Edit Age.kt, in the tasks/task12_5_4 subdirectory of your repository. This contains a now familiar version of the Person class:

   import java.time.LocalDate
   
   class Person(var name: String, val birth: LocalDate) {
       var isMarried = true
   }
   

   This implementation uses Java’s time API to represent date of birth with the LocalDate class. We can continue using this API to perform calculations such as determining the time interval between two dates.

   To calculate time intervals, we can use the ChronoUnit enum class—specifically the YEARS object of this class. To gain access to this, add the following import to the file:

   import java.time.temporal.ChronoUnit.YEARS
   

2. The YEARS object has a method between(), which accepts a pair of LocalDate objects as arguments. The method computes the interval between the two given dates in units of years, returning it as a long integer.

   The birth property provides the first of the two required dates. The second should be today’s date, which is obtained easily enough by invoking the method LocalDate.now(). Thus our implementation of the age property looks like this:

   val age get() = YEARS.between(birth, LocalDate.now()).toInt()
   

   Add this code to the class, then check that it compiles successfully.

3. Finally, add a main() function to Age.kt. This program should create a Person object and then print the value of that object’s age property.

4. Compile and run the program. Check that it is calculating age correctly.

1. Note: for this to work, a Java Development Kit (JDK) needs to be available on the system you are using, and the JDK’s bin directory needs to be included in your PATH variable. ↩

2. We’ve used _name as the name of the constructor parameter, for clarity, but it would have been OK to give it the same name as the property. ↩