aboutsummaryrefslogtreecommitdiff
path: root/value/userguide/extensions.md
blob: ec6c4675410e8aab24fbe2388df6446be45c79e6 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
# Extensions


AutoValue can be extended to implement new features for classes annotated with
`@AutoValue`.

## Using extensions

Each extension is a class. If that class is on the `processorpath` when you
compile your `@AutoValue` class, the extension can run.


Some extensions are triggered by their own annotations, which you add to your
class; others may be triggered in other ways. Consult the extension's
documentation for usage instructions.

## Writing an extension

To add a feature, write a class that extends [`AutoValueExtension`], and put
that class on the `processorpath` along with `AutoValueProcessor`.

`AutoValueExtension` uses the [`ServiceLoader`] mechanism, which means:

*   Your class must be public and have a public no-argument constructor.
*   Its fully-qualified name must appear in a file called
    `META-INF/services/com.google.auto.value.extension.AutoValueExtension` in a
    JAR that is on the compiler's `classpath` or `processorpath`.

You can use [AutoService] to make implementing the `ServiceLoader` pattern easy.

Without extensions, AutoValue generates a subclass of the `@AutoValue` class.
Extensions can work by generating a chain of subclasses, each of which alters
behavior by overriding or implementing new methods.

## TODO

*   How to distribute extensions.
*   List of known extensions.

[AutoService]: https://github.com/google/auto/tree/master/service
[`AutoValueExtension`]: https://github.com/google/auto/blob/master/value/src/main/java/com/google/auto/value/extension/AutoValueExtension.java
[`ServiceLoader`]: http://docs.oracle.com/javase/7/docs/api/java/util/ServiceLoader.html