1*1c2bbba8SAndroid Build Coastguard Worker# Extensions 2*1c2bbba8SAndroid Build Coastguard Worker 3*1c2bbba8SAndroid Build Coastguard Worker 4*1c2bbba8SAndroid Build Coastguard WorkerAutoValue can be extended to implement new features for classes annotated with 5*1c2bbba8SAndroid Build Coastguard Worker`@AutoValue`. 6*1c2bbba8SAndroid Build Coastguard Worker 7*1c2bbba8SAndroid Build Coastguard Worker## Using extensions 8*1c2bbba8SAndroid Build Coastguard Worker 9*1c2bbba8SAndroid Build Coastguard WorkerEach extension is a class. If that class is on the `processorpath` when you 10*1c2bbba8SAndroid Build Coastguard Workercompile your `@AutoValue` class, the extension can run. 11*1c2bbba8SAndroid Build Coastguard Worker 12*1c2bbba8SAndroid Build Coastguard WorkerSome extensions are triggered by their own annotations, which you add to your 13*1c2bbba8SAndroid Build Coastguard Workerclass; others may be triggered in other ways. Consult the extension's 14*1c2bbba8SAndroid Build Coastguard Workerdocumentation for usage instructions. 15*1c2bbba8SAndroid Build Coastguard Worker 16*1c2bbba8SAndroid Build Coastguard Worker## Writing an extension 17*1c2bbba8SAndroid Build Coastguard Worker 18*1c2bbba8SAndroid Build Coastguard WorkerTo add a feature, write a class that extends [`AutoValueExtension`], and put 19*1c2bbba8SAndroid Build Coastguard Workerthat class on the `processorpath` along with `AutoValueProcessor`. 20*1c2bbba8SAndroid Build Coastguard Worker 21*1c2bbba8SAndroid Build Coastguard Worker`AutoValueExtension` uses the [`ServiceLoader`] mechanism, which means: 22*1c2bbba8SAndroid Build Coastguard Worker 23*1c2bbba8SAndroid Build Coastguard Worker* Your class must be public and have a public no-argument constructor. 24*1c2bbba8SAndroid Build Coastguard Worker* Its fully-qualified name must appear in a file called 25*1c2bbba8SAndroid Build Coastguard Worker `META-INF/services/com.google.auto.value.extension.AutoValueExtension` in a 26*1c2bbba8SAndroid Build Coastguard Worker JAR that is on the compiler's `classpath` or `processorpath`. 27*1c2bbba8SAndroid Build Coastguard Worker 28*1c2bbba8SAndroid Build Coastguard WorkerYou can use [AutoService] to make implementing the `ServiceLoader` pattern easy. 29*1c2bbba8SAndroid Build Coastguard Worker 30*1c2bbba8SAndroid Build Coastguard WorkerWithout extensions, AutoValue generates a subclass of the `@AutoValue` class. 31*1c2bbba8SAndroid Build Coastguard WorkerExtensions can work by generating a chain of subclasses, each of which alters 32*1c2bbba8SAndroid Build Coastguard Workerbehavior by overriding or implementing new methods. 33*1c2bbba8SAndroid Build Coastguard Worker 34*1c2bbba8SAndroid Build Coastguard Worker## TODO 35*1c2bbba8SAndroid Build Coastguard Worker 36*1c2bbba8SAndroid Build Coastguard Worker* How to distribute extensions. 37*1c2bbba8SAndroid Build Coastguard Worker* List of known extensions. 38*1c2bbba8SAndroid Build Coastguard Worker 39*1c2bbba8SAndroid Build Coastguard Worker[AutoService]: https://github.com/google/auto/tree/main/service 40*1c2bbba8SAndroid Build Coastguard Worker[`AutoValueExtension`]: https://github.com/google/auto/blob/main/value/src/main/java/com/google/auto/value/extension/AutoValueExtension.java 41*1c2bbba8SAndroid Build Coastguard Worker[`ServiceLoader`]: http://docs.oracle.com/javase/7/docs/api/java/util/ServiceLoader.html 42