A configuration/metadata generator for java.util.ServiceLoader-style service providers

Java annotation processors and other systems use java.util.ServiceLoader 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.

Say you have:

package foo.bar;

import com.google.auto.service.AutoService;
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.

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:

<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>

Previous versions of these instructions suggested an alternative configuration, where the com.google.auto.service:auto-service dependency itself was an optional dependency. We no longer recommend that configuration. (It may pull unnecessary classes into your runtime classpath, and it may produce warnings or errors under recent versions of Java.)

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.