room/room-compiler-processing/README.md - platform/frameworks/support - Git at Google

 # X Processing

 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.

 ## Project Goals
 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.

 ### Want to make changes?
 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:

 * File a bug. [example](https://issuetracker.google.com/issues/182195680)
 * Once the bug is acknowledged by the Room team, send a PR.
 [example](https://github.com/androidx/androidx/pull/137)
   * Make sure to add good tests coveraging the change in the PR. Not only it is mandatory for
   AndroidX submissions, but will also help us ensure we don't break it.


 ## How To Use It

 The entry API is the [XProcessingEnv](src/main/java/androidx/room/compiler/processing/XProcessingEnv.kt)
 which has the necessary API's to access types etc.

 To find annotated elements, you need to subclass the
 [XProcessingStep](src/main/java/androidx/room/compiler/processing/XProcessingStep.kt).
 It is very similar to the
 [BasicAnnotationProcessor](https://github.com/google/auto/blob/master/common/src/main/java/com/google/auto/common/BasicAnnotationProcessor.java)
 API in [Google Auto](https://github.com/google/auto) and you can find Room's implementation
 [here](../compiler/src/main/kotlin/androidx/room/DatabaseProcessingStep.kt).

 To initialize your `XProcessingStep` implementation, you still need to create your own
  AnnotationProcessor (JavaAP) or SymbolProcessor (KSP) implementations and tie it to the
  `XProcessingStep`.
 * Room's [KSP processor](../compiler/src/main/kotlin/androidx/room/RoomKspProcessor.kt)
 * Room's [JavaAP processor](../compiler/src/main/kotlin/androidx/room/RoomProcessor.kt)

 For everything else, the API docs in the library should be sufficient and if not, feel free to file
 bugs for more explanations.

 ## Main Classes
 ### XTypeElement
 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.
 ### XType
 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.
 ### XFieldElement
 Represents a field in Java. Might be driven from a kotlin property.
 You can obtain them via `XTypeElement`.
 ### XMethodElement
 Represents a Java method or Kotlin function. They can be obtained from `XTypeElement`.
 ### XConstructorElement
 Similar to `XMethodElement` but only represents constructor functions.
 ### XMethodType
 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.

 ## Known Caveats (a.k.a. hacks)
 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.

 ### Suspend Methods
 For suspend methods, it will synthesize an additional `Continuation` parameter.

 ### Properties
 XProcessing will synthesize `getter`/`setter` methods for Kotlin properties.

 ### Overrides
 When checking if a method overrides another, XProcessing [checks its JVM declaration as well
 ](https://android-review.googlesource.com/c/platform/frameworks/support/+/1564504/11/room/compiler-processing/src/main/java/androidx/room/compiler/processing/ksp/ResolverExt.kt#68),
 which may not be what you see in Kotlin sources but this is exactly what an Annotation Processor
 would see when used via KAPT.

 ### Internal Modifier
 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.
	# X Processing

	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.

	## Project Goals
	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.

	### Want to make changes?
	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:

	* File a bug. [example](https://issuetracker.google.com/issues/182195680)
	* Once the bug is acknowledged by the Room team, send a PR.
	[example](https://github.com/androidx/androidx/pull/137)
	* Make sure to add good tests coveraging the change in the PR. Not only it is mandatory for
	AndroidX submissions, but will also help us ensure we don't break it.


	## How To Use It

	The entry API is the [XProcessingEnv](src/main/java/androidx/room/compiler/processing/XProcessingEnv.kt)
	which has the necessary API's to access types etc.

	To find annotated elements, you need to subclass the
	[XProcessingStep](src/main/java/androidx/room/compiler/processing/XProcessingStep.kt).
	It is very similar to the
	[BasicAnnotationProcessor](https://github.com/google/auto/blob/master/common/src/main/java/com/google/auto/common/BasicAnnotationProcessor.java)
	API in [Google Auto](https://github.com/google/auto) and you can find Room's implementation
	[here](../compiler/src/main/kotlin/androidx/room/DatabaseProcessingStep.kt).

	To initialize your `XProcessingStep` implementation, you still need to create your own
	AnnotationProcessor (JavaAP) or SymbolProcessor (KSP) implementations and tie it to the
	`XProcessingStep`.
	* Room's [KSP processor](../compiler/src/main/kotlin/androidx/room/RoomKspProcessor.kt)
	* Room's [JavaAP processor](../compiler/src/main/kotlin/androidx/room/RoomProcessor.kt)

	For everything else, the API docs in the library should be sufficient and if not, feel free to file
	bugs for more explanations.

	## Main Classes
	### XTypeElement
	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.
	### XType
	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.
	### XFieldElement
	Represents a field in Java. Might be driven from a kotlin property.
	You can obtain them via `XTypeElement`.
	### XMethodElement
	Represents a Java method or Kotlin function. They can be obtained from `XTypeElement`.
	### XConstructorElement
	Similar to `XMethodElement` but only represents constructor functions.
	### XMethodType
	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.

	## Known Caveats (a.k.a. hacks)
	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.

	### Suspend Methods
	For suspend methods, it will synthesize an additional `Continuation` parameter.

	### Properties
	XProcessing will synthesize `getter`/`setter` methods for Kotlin properties.

	### Overrides
	When checking if a method overrides another, XProcessing [checks its JVM declaration as well
	](https://android-review.googlesource.com/c/platform/frameworks/support/+/1564504/11/room/compiler-processing/src/main/java/androidx/room/compiler/processing/ksp/ResolverExt.kt#68),
	which may not be what you see in Kotlin sources but this is exactly what an Annotation Processor
	would see when used via KAPT.

	### Internal Modifier
	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.