Skip to content

android-support.md

Latest commit

 

History

History
122 lines (95 loc) · 4.63 KB

android-support.md

File metadata and controls

122 lines (95 loc) · 4.63 KB
title Android Support
sidebar_position 6
id android_support
license Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Apache Fory Kotlin supports Kotlin/JVM and Android. Android support is built on the existing Fory Java runtime plus Kotlin runtime serializers from fory-kotlin. Kotlin schema serializers are generated by fory-kotlin-ksp at build time.

Use this page for Android setup and release-build constraints. Use Static Generated Serializers for the Kotlin KSP serializer model itself. If your Android project also contains Java @ForyStruct classes, use the Java annotation processor documented in Java Static Generated Serializers.

Dependencies

Add fory-kotlin to the Android module that uses Fory. Add fory-kotlin-ksp to the module that compiles Kotlin @ForyStruct model classes.

plugins {
  id("com.android.application")
  id("org.jetbrains.kotlin.android")
  id("com.google.devtools.ksp")
}

dependencies {
  implementation("org.apache.fory:fory-kotlin:<fory-version>")
  ksp("org.apache.fory:fory-kotlin-ksp:<fory-version>")
}

For Android library modules, apply KSP in the library module that owns the annotated Kotlin classes. The generated serializers and generated consumer R8 rules must be packaged with that library artifact.

Runtime Setup

Create the runtime with ForyKotlin.builder().withXlang(true), then register application classes through the Kotlin register<T> extension or the normal Fory Java registration APIs.

import org.apache.fory.kotlin.ForyKotlin
import org.apache.fory.kotlin.register

val fory = ForyKotlin.builder()
    .withXlang(true)
    .requireClassRegistration(true)
    .build()

fory.register<User>("example", "User")

Do not reference generated serializer classes from application code. The runtime resolves generated serializers from the registered target class.

Xlang Schema Mode

Android Kotlin structs that participate in Fory cross-language schema serialization should use KSP generated serializers. Generated serializers avoid using runtime reflection as the source of Kotlin schema metadata and call the same Fory Java runtime infrastructure used by other generated serializers.

Kotlin KSP generated serializers are xlang/schema serializers only. They do not replace Java native object serializers and do not preserve concrete JVM collection implementation identity. For example, a Kotlin List<String> field is schema list<string>; deserialization only guarantees a value assignable to the declared field type.

Minified Release Builds

Validate Fory Android behavior with a minified release build. Debug builds do not prove that generated serializers, generated constructor entry points, or Kotlin metadata survive R8.

KSP emits generated consumer R8/ProGuard rules under META-INF/proguard/ for the generated serializer constructors and Kotlin metadata required by Fory. Android apps should not need broad user-written keep rules for generated Kotlin serializers. If a custom packaging setup drops generated META-INF/proguard/ resources, fix that packaging path instead of adding broad keep rules for every generated serializer.

The Apache Fory repository validates this path with integration_tests/android_tests, including release-minified instrumented tests.

Java Models In Android Apps

Kotlin KSP only processes Kotlin source. If your Android app contains Java classes annotated with @ForyStruct, configure the Java fory-annotation-processor for those Java sources.

Static generated Java serializers are also important on Android when Java model classes use Fory type-use annotations on nested types, such as List<@UInt8Type Integer>. See Java Static Generated Serializers for that path.

Unsupported Targets

fory-kotlin and fory-kotlin-ksp target Kotlin/JVM and Android only. Kotlin/Native and Kotlin/JS are not supported.