0
# protobuf-kotlin
1
2
The protobuf-kotlin library provides idiomatic Kotlin language bindings and extensions for Google Protocol Buffers. It offers type-safe extension functions, DSL builders, enhanced collection types, and seamless interoperability with Java protobuf code while providing Kotlin-specific features like nullable types and enhanced type safety.
3
4
## Package Information
5
6
- **Package Name**: com.google.protobuf:protobuf-kotlin
7
- **Package Type**: maven
8
- **Language**: Kotlin
9
- **Installation**: Add to your Maven dependencies or Gradle build file:
10
11
```xml
12
<dependency>
13
<groupId>com.google.protobuf</groupId>
14
<artifactId>protobuf-kotlin</artifactId>
15
<version>4.31.1</version>
16
</dependency>
17
```
18
19
```kotlin
20
implementation("com.google.protobuf:protobuf-kotlin:4.31.1")
21
```
22
23
## Core Imports
24
25
```kotlin
26
import com.google.protobuf.kotlin.*
27
```
28
29
For specific functionality:
30
31
```kotlin
32
// ByteString extensions
33
import com.google.protobuf.kotlin.toByteStringUtf8
34
import com.google.protobuf.kotlin.plus
35
import com.google.protobuf.kotlin.isNotEmpty
36
37
// Any message operations
38
import com.google.protobuf.kotlin.isA
39
import com.google.protobuf.kotlin.unpack
40
41
// Extension field operations
42
import com.google.protobuf.kotlin.get
43
import com.google.protobuf.kotlin.set
44
import com.google.protobuf.kotlin.contains
45
```
46
47
## Basic Usage
48
49
```kotlin
50
import com.google.protobuf.kotlin.*
51
import com.google.protobuf.ByteString
52
import com.google.protobuf.Any as ProtoAny
53
54
// ByteString operations
55
val message = "Hello, Protocol Buffers!"
56
val byteString = message.toByteStringUtf8()
57
val combined = byteString + " From Kotlin!".toByteStringUtf8()
58
val isEmpty = byteString.isNotEmpty() // true
59
60
// Any message type checking and unpacking
61
val packedMessage: ProtoAny = // ... some packed message
62
if (packedMessage.isA<MyMessageType>()) {
63
val unpacked = packedMessage.unpack<MyMessageType>()
64
// Use unpacked message
65
}
66
67
// Extension field access (with generated message builders)
68
val builder = MyExtendableMessage.newBuilder()
69
builder[myExtensionField] = "extension value"
70
val hasExtension = builder.contains(myExtensionField)
71
val extensionValue = builder[myExtensionField]
72
```
73
74
## Architecture
75
76
The protobuf-kotlin library is built around several key design patterns:
77
78
- **Extension Functions**: Kotlin extension functions add idiomatic APIs to existing Java protobuf types
79
- **Type Safety**: Heavy use of generics and reified types for compile-time type checking
80
- **Immutable Collections**: All collection wrappers provide unmodifiable views for safety
81
- **Java Interoperability**: Designed to work seamlessly across Kotlin/Java boundaries
82
- **Generated Code Support**: Many APIs are optimized for use by protoc-generated Kotlin code
83
- **DSL Infrastructure**: Provides foundation for type-safe DSL builders in generated code
84
85
## Capabilities
86
87
### ByteString Extensions
88
89
Kotlin idiomatic extensions for ByteString operations including conversion from strings and byte arrays, concatenation, indexing, and utility functions.
90
91
```kotlin { .api }
92
fun String.toByteStringUtf8(): ByteString
93
operator fun ByteString.plus(other: ByteString): ByteString
94
operator fun ByteString.get(index: Int): Byte
95
fun ByteString.isNotEmpty(): Boolean
96
fun ByteArray.toByteString(): ByteString
97
fun ByteBuffer.toByteString(): ByteString
98
```
99
100
[ByteString Extensions](./bytestring-extensions.md)
101
102
### Any Message Operations
103
104
Type-safe operations for protocol buffer Any messages, allowing runtime type checking and unpacking with compile-time type safety through reified generics.
105
106
```kotlin { .api }
107
inline fun <reified T : Message> ProtoAny.isA(): Boolean
108
inline fun <reified T : Message> ProtoAny.unpack(): T
109
```
110
111
[Any Message Operations](./any-message-operations.md)
112
113
### Extension Field Access
114
115
Operator overloads for intuitive extension field access on extendable messages and builders, providing get, set, and contains operations with full type safety.
116
117
```kotlin { .api }
118
operator fun <M : GeneratedMessage.ExtendableMessage<M>, B : GeneratedMessage.ExtendableBuilder<M, B>, T : Any>
119
B.set(extension: ExtensionLite<M, T>, value: T)
120
121
operator fun <M : GeneratedMessage.ExtendableMessage<M>, MorBT : GeneratedMessage.ExtendableMessageOrBuilder<M>, T : Any>
122
MorBT.get(extension: ExtensionLite<M, T>): T
123
124
operator fun <M : GeneratedMessage.ExtendableMessage<M>, MorBT : GeneratedMessage.ExtendableMessageOrBuilder<M>>
125
MorBT.contains(extension: ExtensionLite<M, *>): Boolean
126
```
127
128
[Extension Field Access](./extension-field-access.md)
129
130
### DSL Infrastructure
131
132
Core infrastructure for generated protobuf DSL including collection wrappers, proxy types, and annotations for type-safe message building.
133
134
```kotlin { .api }
135
@ProtoDslMarker
136
@OnlyForUseByGeneratedProtoCode
137
annotation class ProtoDslMarker
138
139
class DslList<E, P : DslProxy>
140
class DslMap<K, V, P : DslProxy>
141
abstract class DslProxy
142
143
class ExtensionList<E, M : MessageLite>
144
```
145
146
[DSL Infrastructure](./dsl-infrastructure.md)
147
148
## Types
149
150
### Core Annotations
151
152
```kotlin { .api }
153
@ProtoDslMarker
154
annotation class ProtoDslMarker
155
156
@RequiresOptIn(
157
message = "This API is only intended for use by generated protobuf code",
158
level = RequiresOptIn.Level.ERROR
159
)
160
annotation class OnlyForUseByGeneratedProtoCode
161
```
162
163
### Extension Types
164
165
```kotlin { .api }
166
// From Java protobuf library (imported)
167
import com.google.protobuf.ExtensionLite
168
import com.google.protobuf.GeneratedMessage
169
import com.google.protobuf.Message
170
import com.google.protobuf.MessageLite
171
import com.google.protobuf.ByteString
172
import com.google.protobuf.Any as ProtoAny
173
import java.nio.ByteBuffer
174
```