This module (room-compiler-processing) provides an abstraction over Java Annotation Processing (JavaAP) and Kotlin Symbol Processing (KSP) for Room's annotation processor.
If you are an annotation processor author and want to add KSP support to your project (while still supporting Java AP), this library might be useful to get ideas or even directly use it in your project.
DISCLAIMER This is NOT a public Jetpack library and it will NOT have any of the API guarantees that Jetpack Libraries provide (e.g. no semantic versioning). That being said, if it is useful for your use case, feel free to use it. If you include it in your project, please jarjar it to avoid classpath conflicts with Room. This library is still expected to be a production quality abstraction because Room relies on it.
This is not a general purpose abstraction over JavaAP(JSR 269) and KSP. Instead, it is designed to support what Room needs (and only what Room needs). Despite this goal, it ended up covering most use cases hence the library can be used as a general purpose abstraction and it also includes a testing artifact (room-compiler-processing-testing).
If this abstraction turns out to be useful to enough people, we are open to unbundling it from Room as an independent library.
As long as it does not break Room, we are happy to expand the library to cover your use case. If you would like a change:
The entry API is the XProcessingEnv which has the necessary API's to access types etc.
To find annotated elements, you need to subclass the XProcessingStep. It is very similar to the BasicAnnotationProcessor API in Google Auto and you can find Room's implementation here.
To initialize your XProcessingStep implementation, you still need to create your own AnnotationProcessor (JavaAP) or SymbolProcessor (KSP) implementations and tie it to the XProcessingStep.
For everything else, the API docs in the library should be sufficient and if not, feel free to file bugs for more explanations.
This is analogous to JavaAP‘s TypeElement or KSP’s KSClassDeclaration. It can be used to get methods, fields etc declared in a class declaration.
This is analogous to JavaAP‘s TypeMirror or KSP’s KSType. For convenience, each XType has a typeName property that convert it to JavaPoet's TypeName. For types that do not match 1-1 between Kotlin and Java (e.g. Kotlin Int maps to java.lang.Integer or primitive int ), Room will do a best effort conversion based on the information avaiable from the use site.
Represents a field in Java. Might be driven from a kotlin property. You can obtain them via XTypeElement.
Represents a Java method or Kotlin function. They can be obtained from XTypeElement.
Similar to XMethodElement but only represents constructor functions.
Represents an XMethodElement as member of an XType. Notice that when a method is resolved as a member of an XType, all available type arguments will be resolved based on the type declaration.
XProcessing assumes it is being used to generate Java code and tries to optimize for that. Chances are, if you are converting a Java AP to support KSP, your annotation processor expects what XProcessing does. Caveats listed here are subject to change if/when Room supports generating Kotlin code but it is very likely that we'll make it an argument to XProcessing.
For suspend methods, it will synthesize an additional Continuation parameter.
XProcessing will synthesize getter/setter methods for Kotlin properties.
When checking if a method overrides another, XProcessing checks its JVM declaration as well , which may not be what you see in Kotlin sources but this is exactly what an Annotation Processor would see when used via KAPT.
When an internal modifier is used in Kotlin code, its binary representation has a mangled name. XProcessing automatically checks for it and the name property of a method/property will include that conversion.