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