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
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
|
# AutoService
A configuration/metadata generator for java.util.ServiceLoader-style service
providers
## AutoWhat‽
[Java][java] annotation processors and other systems use
[java.util.ServiceLoader][sl] to register implementations of well-known types
using META-INF metadata. However, it is easy for a developer to forget to update
or correctly specify the service descriptors. \
AutoService generates this metadata for the developer, for any class annotated
with `@AutoService`, avoiding typos, providing resistance to errors from
refactoring, etc.
## Example
Say you have:
```java
package foo.bar;
import javax.annotation.processing.Processor;
@AutoService(Processor.class)
final class MyProcessor implements Processor {
// …
}
```
AutoService will generate the file
`META-INF/services/javax.annotation.processing.Processor` in the output classes
folder. The file will contain:
```
foo.bar.MyProcessor
```
In the case of javax.annotation.processing.Processor, if this metadata file is
included in a jar, and that jar is on javac's classpath, then `javac` will
automatically load it, and include it in its normal annotation processing
environment. Other users of java.util.ServiceLoader may use the infrastructure
to different ends, but this metadata will provide auto-loading appropriately.
## Getting Started
You will need `auto-service-annotations-${version}.jar` in your compile-time
classpath, and you will need `auto-service-${version}.jar` in your
annotation-processor classpath.
In Maven, you can write:
```xml
<dependencies>
<dependency>
<groupId>com.google.auto.service</groupId>
<artifactId>auto-service-annotations</artifactId>
<version>${auto-service.version}</version>
</dependency>
</dependencies>
...
<plugins>
<plugin>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<annotationProcessorPaths>
<path>
<groupId>com.google.auto.service</groupId>
<artifactId>auto-service</artifactId>
<version>${auto-service.version}</version>
</path>
</annotationProcessorPaths>
</configuration>
</plugin>
</plugins>
```
Alternatively, you can include the processor itself (which transitively depends
on the annotation) in your compile-time classpath. (However, note that doing so
may pull unnecessary classes into your runtime classpath.)
```xml
<dependencies>
<dependency>
<groupId>com.google.auto.service</groupId>
<artifactId>auto-service</artifactId>
<version>${version}</version>
<optional>true</optional>
</dependency>
</dependencies>
```
## License
Copyright 2013 Google LLC
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
[java]: https://en.wikipedia.org/wiki/Java_(programming_language)
[sl]: http://docs.oracle.com/javase/6/docs/api/java/util/ServiceLoader.html
|
