static-generated-serializers.md

title	Static Generated Serializers
sidebar_position	15
id	static_generated_serializers
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.

Static generated serializers are Java serializers generated by javac during your application build. They are useful when runtime code generation is disabled or unavailable.

Use them when:

• you run on Android.
• you run an ordinary JVM with ForyBuilder#withCodegen(false) and want generated serializers.
• your Android model classes use Fory type-use annotations such as @Ref, @UInt8Type, or @Float16Type.

For GraalVM native images, follow GraalVM Support instead.

Install The Annotation Processor

Add fory-annotation-processor to the annotation processor path of the module that compiles your serializable classes:

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-compiler-plugin</artifactId>
      <configuration>
        <annotationProcessorPaths>
          <path>
            <groupId>org.apache.fory</groupId>
            <artifactId>fory-annotation-processor</artifactId>
            <version>${fory.version}</version>
          </path>
        </annotationProcessorPaths>
      </configuration>
    </plugin>
  </plugins>
</build>

The generated serializers depend on fory-core at runtime. Applications opt in by adding the annotation processor; fory-core does not depend on it.

Annotate Classes

Annotate each serializable class with @ForyStruct:

import org.apache.fory.annotation.ForyStruct;

@ForyStruct
public class Order {
  public long id;
  public String note;

  public Order() {}
}

The processor generates serializer classes in the same Java package as the annotated class. For Order, the generated classes are:

• Order_ForySerializer for cross-language mode.
• Order_ForyNativeSerializer for Java native mode.

For a static nested type such as Outer.Inner, the generated top-level classes are Outer_Inner_ForySerializer and Outer_Inner_ForyNativeSerializer.

Field Debug Tracing

Add @ForyDebug next to @ForyStruct when you need generated serializers to include field-level debug tracing hooks. The generated code prints those traces only when ENABLE_FORY_DEBUG_OUTPUT=1.

import org.apache.fory.annotation.ForyDebug;
import org.apache.fory.annotation.ForyStruct;

@ForyStruct
@ForyDebug
public class DebugOrder {
  public long id;
  public String note;

  public DebugOrder() {}
}

Runtime Use

Fory uses static generated serializers when they are available on:

• Android.
• ordinary JVMs with ForyBuilder#withCodegen(false).
• compatible-mode reads when the target struct has a generated serializer.

On an ordinary JVM with codegen=true, Fory continues to prefer runtime-generated serializers.

The runtime resolves generated serializers from the registered target class name. Application code should not reference generated serializer classes directly.

Field Access Rules

Generated serializers must be able to access serialized fields or their accessors at compile time.

• Public, protected, and package-private fields can be accessed directly when Java package access allows same-package generated serializers to use them.
• Private serialized fields must have accessible non-private getter and setter methods, or be excluded with transient or Fory @Ignore.
• Public, protected, and package-private getter/setter methods are accepted when they are accessible from the generated serializer package.
• Final fields are not supported for normal mutable classes because generated read and copy methods must assign fields. Use records for constructor-based immutable values.

For records, generated serializers use public record accessors and construct values through the canonical record constructor. Ignored record components are skipped by serialization and copy, and their constructor arguments use Java default values during generated read/copy.

Type-Use Annotations On Android

On Android, static generated serializers are required when a class uses Fory type-use annotations on nested types:

import java.util.List;
import org.apache.fory.annotation.ForyStruct;
import org.apache.fory.annotation.UInt8Type;

@ForyStruct
public class ImageBlock {
  public List<@UInt8Type Integer> pixels;
}

Without the generated serializer metadata, Android may not expose enough nested type information for Fory to preserve annotations such as @Ref, @Int8Type, @UInt8Type, @Float16Type, or @BFloat16Type.

The annotation processor emits generated consumer R8/ProGuard rules under META-INF/proguard/ for the exact serializer constructors used by Fory. Android applications should not add broad generated serializer keep rules by hand.

Compatible Reads

Static generated serializers support both normal serialization and compatible-mode reads. Compatible reads match remote fields to local fields, skip fields that no longer exist locally, and keep Java default values for fields that are missing from the remote payload.