java/fory-annotation-processor/README.md

# Fory Annotation Processor

`fory-annotation-processor` generates static serializers for Java classes annotated with
`@ForyStruct`. For Fory JSON it processes direct `@JsonType` models and
`@JsonMixin(target = ...)` declarations. Direct models receive their existing type-owned JSON
companion when required. A non-empty Mixin receives exact platform configuration and a
pair-specific companion when generated target operations are available. Runtime codec resolution,
including registered and built-in codecs, still decides whether those operations are used. The
generated rules retain the complete effective annotation surface, matched target declarations,
generic endpoints, subtype and unwrapped models, and selected codec constructors. An empty Mixin
produces no output. All outputs are generated by javac during the application build.

Use this processor for:

- Android applications.
- ordinary JVM applications using `ForyJsonBuilder#withCodegen(false)`.
- Android model classes that use Fory type-use annotations such as `@Ref`, `@UInt8Type`, or
  `@Float16Type`.
- Fory JSON object models that need direct member access, Android Record support, GraalVM metadata,
  or automatic R8 rules.

For GraalVM native images, use the processor for every reachable `@JsonType` JSON model and
`@JsonMixin` source, and use Fory's native-image build-time serializer generation for ordinary Fory
serialization.

## Ownership

The processor is an opt-in build tool. Applications add it to their annotation-processor path. The
processor has no production dependency on `fory-core` or `fory-json`; generated sources compile
against the corresponding runtime artifact already used by the application.

A Mixin source declares exactly one target. The processor may generate pair artifacts for multiple
sources that name the same target because they are alternative runtime configurations. One
`ForyJsonBuilder` enables one source per exact target, and a later registration replaces an earlier
one before `build()` snapshots the mapping. The processor never merges multiple sources and never
changes the direct companion path without a Mixin. A source must be named, must not be local or anonymous,
and must not extend another source or implement interfaces, so there is no second
annotation-precedence hierarchy.

`JsonMixin` supports the Fory JSON mapping annotations. `JsonType` remains a direct
build-time marker and cannot be added or removed through a Mixin. The processor does not duplicate
the runtime's built-in codec selection.

For ordinary Fory JSON object models on Android, `@JsonType` is optional. A model without it can use
application-authored exact R8 rules and reflection. Android builds that need desugared Java Record
construction require processor-generated operations from either a direct `@JsonType` declaration
or a compiled exact `@JsonMixin` pair, because generated code calls the canonical constructor and
component accessors directly. This includes a Record using a String `JsonValue` representation and
an annotated canonical constructor. `@JsonCodec` uses ordinary type, field, method, and parameter
annotations, so every supported codec member remains available through reflection with equivalent
rules. See
[`docs/guide/java/android-support.md`](../../docs/guide/java/android-support.md).

For the full user-facing guides, see
[`docs/guide/java/static-generated-serializers.md`](../../docs/guide/java/static-generated-serializers.md)
and [`docs/guide/java/json-support.md`](../../docs/guide/java/json-support.md).