or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

class-metadata.mdindex.mdmember-signatures.mdmodule-metadata.mdversion-management.md
tile.json

tessl/maven-org-jetbrains-kotlin--kotlin-metadata-jvm

A Kotlin library for reading and modifying binary metadata in Kotlin/JVM compiler-generated files.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.jetbrains.kotlin/kotlin-metadata-jvm@2.2.x

To install, run

npx @tessl/cli install tessl/maven-org-jetbrains-kotlin--kotlin-metadata-jvm@2.2.0

index.mddocs/

Kotlin Metadata JVM

Kotlin Metadata JVM is a JVM-specific library for reading and modifying binary metadata in Kotlin/JVM compiler-generated files. It provides APIs for introspecting class metadata, transforming metadata objects, and creating metadata from scratch for Kotlin classes.

Package Information

  • Package Name: org.jetbrains.kotlin:kotlin-metadata-jvm

  • Package Type: Maven

  • Language: Kotlin

  • Installation:

    Maven:

    <dependency>
  <groupId>org.jetbrains.kotlin</groupId>
  <artifactId>kotlin-metadata-jvm</artifactId>
  <version>2.2.0</version>
</dependency>

    Gradle (Kotlin DSL):

    implementation("org.jetbrains.kotlin:kotlin-metadata-jvm:2.2.0")

    Gradle (Groovy DSL):

    implementation 'org.jetbrains.kotlin:kotlin-metadata-jvm:2.2.0'

Core Imports

import kotlin.metadata.jvm.KotlinClassMetadata
import kotlin.metadata.jvm.KotlinModuleMetadata
import kotlin.metadata.jvm.JvmMetadataVersion
import kotlin.metadata.jvm.JvmMemberSignature

Basic Usage

import kotlin.metadata.jvm.KotlinClassMetadata

// Read class metadata
val metadata = KotlinClassMetadata.readStrict(metadataAnnotation)
when (metadata) {
    is KotlinClassMetadata.Class -> {
        val klass = metadata.kmClass
        println("Functions: ${klass.functions.map { it.name }}")
    }
    is KotlinClassMetadata.FileFacade -> {
        val pkg = metadata.kmPackage
        println("Top-level functions: ${pkg.functions.map { it.name }}")
    }
}

// Read module metadata
val moduleBytes = File("META-INF/main.kotlin_module").readBytes()
val moduleMetadata = KotlinModuleMetadata.read(moduleBytes)
println("Package parts: ${moduleMetadata.kmModule.packageParts.keys}")

Architecture

Kotlin Metadata JVM is built around several key components:

  • Class Metadata Reading: KotlinClassMetadata for reading and writing Kotlin class metadata from .class files
  • Module Metadata Handling: KotlinModuleMetadata for processing .kotlin_module files
  • Version Management: JvmMetadataVersion for handling metadata version compatibility
  • Member Signatures: JvmMemberSignature for representing JVM method and field signatures
  • Core Metadata Types: Integration with kotlinx-metadata-core (KmClass, KmFunction, KmType) for structured metadata representation

Capabilities

Class Metadata Operations

Core functionality for reading, writing, and transforming Kotlin class metadata from .class files. Supports strict and lenient reading modes for version compatibility.

sealed class KotlinClassMetadata {
    abstract fun write(): Metadata
    abstract val version: JvmMetadataVersion
    abstract val flags: Int
    
    companion object {
        fun readStrict(annotationData: Metadata): KotlinClassMetadata?
        fun readLenient(annotationData: Metadata): KotlinClassMetadata?
        fun transform(metadata: Metadata, transformer: (KotlinClassMetadata) -> Unit): Metadata
    }
}

Class Metadata

Module Metadata Operations

Functionality for reading and writing .kotlin_module files that contain package structure information and compilation metadata.

class KotlinModuleMetadata(
    var kmModule: KmModule, 
    var version: JvmMetadataVersion
) {
    fun write(): ByteArray
    
    companion object {
        @JvmStatic
        fun read(bytes: ByteArray): KotlinModuleMetadata
    }
}

Module Metadata

Version Management

Version handling system for ensuring compatibility between different Kotlin compiler versions and metadata formats.

class JvmMetadataVersion(
    val major: Int, 
    val minor: Int, 
    val patch: Int = 0
) : Comparable<JvmMetadataVersion> {
    companion object {
        val LATEST_STABLE_SUPPORTED: JvmMetadataVersion
        val HIGHEST_ALLOWED_TO_WRITE: JvmMetadataVersion
    }
}

Version Management

JVM Member Signatures

System for representing JVM method and field signatures used in metadata processing and reflection operations.

sealed class JvmMemberSignature {
    abstract val name: String
    abstract val descriptor: String
}

data class JvmMethodSignature(
    override val name: String, 
    override val descriptor: String
) : JvmMemberSignature()

data class JvmFieldSignature(
    override val name: String, 
    override val descriptor: String
) : JvmMemberSignature()

Member Signatures

Utility APIs

Additional utility classes and functions for specialized metadata operations.

// JVM-specific attribute handling utilities
object JvmAttributes

// Extension functions for JVM metadata processing  
object JvmExtensions

// Utility functions for JVM metadata operations
object JvmMetadataUtil

// Java representation of Kotlin class header information
class KotlinClassHeader

// Annotation marking unstable metadata APIs
@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY)
@Retention(AnnotationRetention.BINARY)
annotation class UnstableMetadataApi(val message: String = "")

These utilities provide additional functionality for metadata processing but are considered internal implementation details and may change in future versions.

Core Types

// Metadata annotation type (from Kotlin stdlib)
annotation class Metadata(
    val kind: Int = 1,
    val metadataVersion: IntArray = [],
    val data1: Array<String> = [],
    val data2: Array<String> = [],
    val extraString: String = "",
    val packageName: String = "",
    val extraInt: Int = 0
)

// Module structure types (kotlin-metadata-jvm specific)
class KmModule {
    val packageParts: MutableMap<String, KmPackageParts>
    val optionalAnnotationClasses: MutableList<KmClass>
}

class KmPackageParts(
    val fileFacades: MutableList<String>,
    val multiFileClassParts: MutableMap<String, String>
)

// Core metadata types (from kotlinx-metadata-core dependency)
// These types are used by kotlin-metadata-jvm but defined in the core library
interface KmClass {
    val name: String
    val functions: List<KmFunction>
    val properties: List<KmProperty> 
    val constructors: List<KmConstructor>
}

interface KmFunction {
    val name: String
    val valueParameters: List<KmValueParameter>
    val returnType: KmType
}

interface KmProperty {
    val name: String
    val returnType: KmType
}

interface KmPackage {
    val functions: List<KmFunction>
    val properties: List<KmProperty>
}

interface KmLambda {
    val function: KmFunction?
}

interface KmType {
    // Type representation
}

interface KmConstructor {
    val valueParameters: List<KmValueParameter>
}

interface KmValueParameter {
    val name: String?
    val type: KmType
}