0
# Kotlin Metadata JVM
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: org.jetbrains.kotlin:kotlin-metadata-jvm
7
- **Package Type**: Maven
8
- **Language**: Kotlin
9
- **Installation**: 
10
  
11
  Maven:
12
  ```xml
13
  <dependency>
14
    <groupId>org.jetbrains.kotlin</groupId>
15
    <artifactId>kotlin-metadata-jvm</artifactId>
16
    <version>2.2.0</version>
17
  </dependency>
18
  ```
19
  
20
  Gradle (Kotlin DSL):
21
  ```kotlin
22
  implementation("org.jetbrains.kotlin:kotlin-metadata-jvm:2.2.0")
23
  ```
24
  
25
  Gradle (Groovy DSL):
26
  ```groovy
27
  implementation 'org.jetbrains.kotlin:kotlin-metadata-jvm:2.2.0'
28
  ```
29

30
## Core Imports
31

32
```kotlin
33
import kotlin.metadata.jvm.KotlinClassMetadata
34
import kotlin.metadata.jvm.KotlinModuleMetadata
35
import kotlin.metadata.jvm.JvmMetadataVersion
36
import kotlin.metadata.jvm.JvmMemberSignature
37
```
38

39
## Basic Usage
40

41
```kotlin
42
import kotlin.metadata.jvm.KotlinClassMetadata
43

44
// Read class metadata
45
val metadata = KotlinClassMetadata.readStrict(metadataAnnotation)
46
when (metadata) {
47
    is KotlinClassMetadata.Class -> {
48
        val klass = metadata.kmClass
49
        println("Functions: ${klass.functions.map { it.name }}")
50
    }
51
    is KotlinClassMetadata.FileFacade -> {
52
        val pkg = metadata.kmPackage
53
        println("Top-level functions: ${pkg.functions.map { it.name }}")
54
    }
55
}
56

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

63
## Architecture
64

65
Kotlin Metadata JVM is built around several key components:
66

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

73
## Capabilities
74

75
### Class Metadata Operations
76

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

79
```kotlin { .api }
80
sealed class KotlinClassMetadata {
81
    abstract fun write(): Metadata
82
    abstract val version: JvmMetadataVersion
83
    abstract val flags: Int
84
    
85
    companion object {
86
        fun readStrict(annotationData: Metadata): KotlinClassMetadata?
87
        fun readLenient(annotationData: Metadata): KotlinClassMetadata?
88
        fun transform(metadata: Metadata, transformer: (KotlinClassMetadata) -> Unit): Metadata
89
    }
90
}
91
```
92

93
[Class Metadata](./class-metadata.md)
94

95
### Module Metadata Operations
96

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

99
```kotlin { .api }
100
class KotlinModuleMetadata(
101
    var kmModule: KmModule, 
102
    var version: JvmMetadataVersion
103
) {
104
    fun write(): ByteArray
105
    
106
    companion object {
107
        @JvmStatic
108
        fun read(bytes: ByteArray): KotlinModuleMetadata
109
    }
110
}
111
```
112

113
[Module Metadata](./module-metadata.md)
114

115
### Version Management
116

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

119
```kotlin { .api }
120
class JvmMetadataVersion(
121
    val major: Int, 
122
    val minor: Int, 
123
    val patch: Int = 0
124
) : Comparable<JvmMetadataVersion> {
125
    companion object {
126
        val LATEST_STABLE_SUPPORTED: JvmMetadataVersion
127
        val HIGHEST_ALLOWED_TO_WRITE: JvmMetadataVersion
128
    }
129
}
130
```
131

132
[Version Management](./version-management.md)
133

134
### JVM Member Signatures
135

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

138
```kotlin { .api }
139
sealed class JvmMemberSignature {
140
    abstract val name: String
141
    abstract val descriptor: String
142
}
143

144
data class JvmMethodSignature(
145
    override val name: String, 
146
    override val descriptor: String
147
) : JvmMemberSignature()
148

149
data class JvmFieldSignature(
150
    override val name: String, 
151
    override val descriptor: String
152
) : JvmMemberSignature()
153
```
154

155
[Member Signatures](./member-signatures.md)
156

157
### Utility APIs
158

159
Additional utility classes and functions for specialized metadata operations.
160

161
```kotlin { .api }
162
// JVM-specific attribute handling utilities
163
object JvmAttributes
164

165
// Extension functions for JVM metadata processing  
166
object JvmExtensions
167

168
// Utility functions for JVM metadata operations
169
object JvmMetadataUtil
170

171
// Java representation of Kotlin class header information
172
class KotlinClassHeader
173

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

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

182
## Core Types
183

184
```kotlin { .api }
185
// Metadata annotation type (from Kotlin stdlib)
186
annotation class Metadata(
187
    val kind: Int = 1,
188
    val metadataVersion: IntArray = [],
189
    val data1: Array<String> = [],
190
    val data2: Array<String> = [],
191
    val extraString: String = "",
192
    val packageName: String = "",
193
    val extraInt: Int = 0
194
)
195

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

202
class KmPackageParts(
203
    val fileFacades: MutableList<String>,
204
    val multiFileClassParts: MutableMap<String, String>
205
)
206

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

216
interface KmFunction {
217
    val name: String
218
    val valueParameters: List<KmValueParameter>
219
    val returnType: KmType
220
}
221

222
interface KmProperty {
223
    val name: String
224
    val returnType: KmType
225
}
226

227
interface KmPackage {
228
    val functions: List<KmFunction>
229
    val properties: List<KmProperty>
230
}
231

232
interface KmLambda {
233
    val function: KmFunction?
234
}
235

236
interface KmType {
237
    // Type representation
238
}
239

240
interface KmConstructor {
241
    val valueParameters: List<KmValueParameter>
242
}
243

244
interface KmValueParameter {
245
    val name: String?
246
    val type: KmType
247
}
248
```