Internal Property

An internal property in Kotlin is a class member or top-level property whose visibility is strictly scoped to the module in which it is declared. Any code residing within the same compiled module can access the property, while code outside the module cannot resolve the reference.

In Kotlin’s compilation model, a “module” is defined as a set of Kotlin files compiled together. This specifically includes:

• An IntelliJ IDEA module.
• A Maven project.
• A Gradle source set (note that main and test are considered separate source sets, but Kotlin provides special compiler flags to allow tests to access internal members of main).
• A set of files compiled with a single invocation of the <kotlinc> Ant task.

Syntax

The internal modifier is placed before the val or var keyword. It can be applied at the file level or within a class/object declaration.

// Top-level internal property
internal val defaultTimeout: Int = 5000

class ConnectionPool {
    // Class-level internal property
    internal var activeConnections: Int = 0
    
    // Internal property with a restricted setter
    internal var isRunning: Boolean = false
        private set 
}

Access Rules and Inheritance

• Getters and Setters: By default, the getter and setter of an internal property inherit the internal visibility. You can restrict the setter further (e.g., to private), but you cannot make it more permissive than the property itself.
• Overriding: If an internal property is declared in an open class, any subclass overriding that property must maintain at least internal visibility. It cannot be restricted to protected or private in the subclass. If no visibility modifier is provided on the override, it implicitly inherits the internal visibility.
• Constructors: If a property is declared directly in a primary constructor using internal val or internal var, the property is internal, regardless of the visibility of the class itself.

open class Base {
    internal open val identifier: String = "base_id"
}

class Derived : Base() {
    // Valid: Overriding implicitly maintains internal visibility
    override val identifier: String = "derived_id"
    
    // Valid: Overriding explicitly expands visibility to public
    // public override val identifier: String = "public_derived_id"
}

JVM Compilation and Name Mangling

Because the Java Virtual Machine (JVM) lacks a native visibility modifier equivalent to Kotlin’s module-level scope (Java’s default visibility is package-private, which is fundamentally different), the Kotlin compiler implements internal visibility using a workaround in the bytecode.

When compiled to the JVM, the backing field of an internal property is generated as private by default, exactly like standard Kotlin properties. However, the generated getter and setter methods are made public. To enforce the module restriction and prevent external Java code from inadvertently accessing these members, the Kotlin compiler applies name mangling.

The compiler appends the module name to the generated public getter and setter methods. For example, an internal property named config in a module named core will result in a generated getter method resembling getConfig$core().

While this prevents accidental access from external Java code, it does not provide cryptographic security; the mangled methods are technically public in the bytecode and can still be invoked via Java reflection or by explicitly calling the mangled name from Java.

Master Kotlin with Deep Grasping Methodology!

Learn More