A protoc compiler plugin that generates useful extension code for Kotlin.
- Generate
*OrNullextension properties for optional field- In protoc-gen-kotlin, this extension properties is only provided for message types. We provide it for scalar types as well.
- protocolbuffers/protobuf#12935
- Generate factory functions that resemble data class constructors
- We do not generate our own code, so we can take advantage of the official ecosystem
- It only generates additional useful code.
Let's assume we have the following proto file.
message Person {
string first_name = 1;
string last_name = 2;
optional string middle_name = 3;
Gender gender = 4;
optional string nickname = 5;
Address primary_address = 6;
}
enum Gender {
GENDER_UNSPECIFIED = 0;
MALE = 1;
FEMALE = 2;
OTHERS = 3;
}
message Address {
string country = 1;
string state = 2;
string city = 3;
string address_line_1 = 4;
optional string address_line_2 = 5;
}Using the generated code, you can write the following:
fun main() {
// You can use factory functions that resemble data class constructors
val person = Person(
firstName = "Ryosuke",
lastName = "Hasebe",
middleName = null, // Optional fields become nullable
gender = Gender.MALE,
nickname = null, // Optional fields become nullable
primaryAddress = Address(
country = "JP",
state = "Tokyo",
city = "blah blah blah",
addressLine1 = "blah blah blah",
addressLine2 = null, // Optional fields become nullable
),
)
// You can use `*OrNull` extension properties for optional field
println(person.middleNameOrNull)
println(person.nicknameOrNull)
println(person.primaryAddress.addressLine2OrNull)
println(person.primaryAddressOrNull)
}When used with protoc-gen-kotlin:
protobuf {
protoc {
artifact = "com.google.protobuf:protoc:<version>"
}
plugins {
id("kotlin-ext") {
artifact = "dev.hsbrysk:protoc-gen-kotlin-ext:<version>:jdk8@jar"
}
}
generateProtoTasks {
all().forEach { task ->
task.plugins {
id("kotlin-ext") {
outputSubDir = "kotlin"
}
}
task.builtins {
id("kotlin")
}
}
}
}When used standalone:
protobuf {
protoc {
artifact = "com.google.protobuf:protoc:<version>"
}
plugins {
id("kotlin-ext") {
artifact = "dev.hsbrysk:protoc-gen-kotlin-ext:<version>:jdk8@jar"
}
}
generateProtoTasks {
all().forEach { task ->
task.plugins {
id("kotlin-ext") {
outputSubDir = "kotlin"
// This option is explained later in the document
option("messageOrNullGetter+")
}
}
}
}
}Since the plugin is created using the same mechanism as protoc-gen-grpc-kotlin, please refer to this document.
From protobuf 3.12, the long-awaited optional field (Field Presence) has been reintroduced. This allows the representation of null (as in java/kotlin).
message Sample {
optional string hoge = 2;
optional int32 bar = 3;
}However, this optional feature is somewhat tricky. When you retrieve a value with a getter, it returns the default
value (e.g., "" for strings, 0 for int32). This means that for strings, you cannot distinguish whether the value has
been explicitly set to "" or not set at all. Instead, optional fields provide a has* method to check if the value
has been set, which you should use to determine if it is null.
If you are unaware of this specification, you might mistakenly treat an "" or 0 as a valid value, potentially
causing bugs.
Sample.newBuilder().build().also {
println("[1] hoge: ${it.hoge}")
println("[1] hasHoge: ${it.hasHoge()}")
println("[1] bar: ${it.bar}")
println("[1] hasBar: ${it.hasBar()}")
}
Sample.newBuilder().setHoge("hoge").setBar(1).build().also {
println("[2] hoge: ${it.hoge}")
println("[2] hasHoge: ${it.hasHoge()}")
println("[2] bar: ${it.bar}")
println("[2] hasBar: ${it.hasBar()}")
}[1] hoge:
[1] hasHoge: false
[1] bar: 0
[1] hasBar: false
[2] hoge: hoge
[2] hasHoge: true
[2] bar: 1
[2] hasBar: true
Even knowing this specification correctly would result in a large amount of boilerplate code, such as the following:
// 😭
val hoge = if (sample.hasHoge()) {
sample.hoge
} else {
null
}To address this for Kotlin, we will auto-generate *OrNull extension properties. When implementing,
seeing *OrNull
through autocompletion should help avoid some issues. Additionally, this allows the use of the Elvis operator, resulting
in smoother code.
val BlahBlah.hogeOrNull: kotlin.String?
get() = if (hasHoge()) hoge else nullInterestingly, for message types, using protoc-gen-kotlin already generates similar extension properties.
https://github.com/protocolbuffers/protobuf/blob/b30f3de12f946b6d610c21bc605726bf56ea889f/src/google/protobuf/compiler/java/message.cc#L1352C33-L1370
I have raised an issue requesting the addition of optional
scalar types, but it is not planned to be supported by protoc-gen-kotlin.
Protobuf uses builders to set values. Since this code is written in Java, there is no non-null/nullable type checking. When used from Kotlin, it is often misunderstood that it is okay to set null for optional fields, which results in passing null and encountering NPEs (NullPointerExceptions).
Sample.newBuilder()
.setHoge(null) // This code raises NPE 😭
.setBar(1)
.build();When using protoc-gen-kotlin, the following DSL is generated for Kotlin. This is beneficial because it includes non-null/nullable type checking. Great!
sample {
hoge = null // This code results in a compile error 😀
bar = 1
}However, in Kotlin, it feels more natural to write using constructors with named arguments, like data classes.
Additionally, just like the builder, the DSL does not result in a compile error when a field is added later. This can lead to cases where values are forgotten to be set. However, opinions may differ on whether this is seen as a disadvantage or an advantage.
If it is code provided by libraries or similar, it is better not to do it as it may break compatibility.
If it is code used within your own application, I think it is convenient. If you prioritize a more robust programming style, it is preferable to have a compile error indicating that a value has been forgotten.
Therefore, we will auto-generate the following factory function. Note that this Sample(...) is not a constructor but a
function.
It can be written similarly to a data class, and when a field is added later, it will result in a compile error,
indicating that a value might be forgotten to be set. Since it is defined in Kotlin, nullable type checking is also
enabled.
// similar to a data class 😀
Sample(
hoge = "hoge",
bar = 1
)
// Of course, when it is optional, it becomes a nullable type
Sample(
hoge = null, // This code results in a compile error 😀
bar = 1
)
public fun Sample(hoge: String?, bar: Int?): Sample {
val _builder = Sample.newBuilder().apply {
hoge?.let { setHoge(it) }
bar?.let { setBar(it) }
}
return _builder.build()
}We considered adding factory functions with default arguments, but we decided not to create them at this time. If there are default arguments, adding a field later would not result in a compile error. If you want to use default values, you can use java builder or kotlin DSL.
Perhaps you only want the *OrNull extension property and do not need the factory function. (and vice versa).
This can be achieved by setting the compile options.
// Here, we will use Gradle as an example.
protobuf {
// ...
generateProtoTasks {
all().forEach { task ->
task.plugins {
id("kotlin-ext") {
// ...
// HERE
option("messageOrNullGetter+")
}
}
}
}
}The following options are available. Appending + to the end of an option enables it, while appending - disables it.
factory- Whether to generate a factory (default: on)
orNullGetter- Whether to generate
orNullextension functions for optional scalar fields (default: on)
- Whether to generate
messageOrNullGetter- Whether to generate
orNullextension functions for optional message fields (default: off) - Not needed when using protobuf-kotlin.
- Whether to generate
When specifying multiple options, please separate them with commas. For
example, factory-, orNullGetter+, messageOrNullGetter+