Top-Level Property

A top-level property in Kotlin is a property declared directly at the root of a .kt file, outside the scope of any class, interface, or object declaration. It is scoped to the package in which it is defined and is initialized when the file’s corresponding generated class is loaded by the ClassLoader.

Syntax

Top-level properties are declared using standard val (read-only) or var (mutable) keywords. They support explicit initialization, type inference, and custom accessors.

package com.example.core

// Read-only top-level property
val systemVersion: String = "1.0.0"

// Mutable top-level property
var activeConnections: Int = 0

// Compile-time constant top-level property
const val MAX_RETRIES: Int = 3

// Top-level property with custom accessors (no backing field generated)
var connectionMultiplier: Int
    get() = activeConnections * 2
    set(value) {
        activeConnections = value / 2
    }

JVM Compilation Mechanics

Because the Java Virtual Machine (JVM) requires all fields and methods to be encapsulated within a class, the Kotlin compiler generates a facade class to host top-level properties. By default, if the file is named Network.kt, the compiler generates a public final class named NetworkKt.

The compilation behavior depends on the property declaration:

1. Standard val and var:

   The compiler generates a private static backing field. It then generates a public static final getter method (and a setter method for var) to control access to that field.

2. const val:

   The compiler generates a public static final field. No getter is generated. The value is inlined at the call site during compilation.

3. Custom Accessors (without field reference):

   The compiler generates public static final getter/setter methods but omits the private static backing field entirely.

Visibility Modifiers

Visibility modifiers applied to top-level properties dictate their accessibility across the codebase:

• public (default): The property is accessible from anywhere in the project.
• internal: The property is accessible from anywhere within the same compiled module.
• private: The property is accessible only within the specific .kt file where it is declared. The generated static field and methods are marked private in the bytecode.
• protected: Not allowed on top-level declarations.

Java Interoperability

When accessing Kotlin top-level properties from Java code, developers must invoke the generated static accessors on the file’s facade class.

// Java code accessing properties from Network.kt
String version = NetworkKt.getSystemVersion();
NetworkKt.setActiveConnections(5);

// const val is accessed directly as a static field
int retries = NetworkKt.MAX_RETRIES;

Modifying Java Interoperability

You can alter how the JVM compiles top-level properties using annotations:

• @file:JvmName("CustomName"): Placed at the very top of the .kt file (before the package declaration), this changes the name of the generated facade class.
• @JvmField: Instructs the compiler not to generate getters/setters, but instead expose the property as a public static field.

@file:JvmName("NetworkUtils")
package com.example.core

@JvmField
val defaultTimeout: Int = 5000

// Java access after applying annotations
int timeout = NetworkUtils.defaultTimeout;

Master Kotlin with Deep Grasping Methodology!

Learn More