File: README.md
Auto
A collection of source code generators for Java.
Overview
Java is full of code that is mechanical, repetitive, typically untested
and sometimes the source of subtle bugs. Sounds like a job for robots!
The Auto subprojects are a collection of code generators that automate those
types of tasks. They create the code you would have written, but without
the bugs.
Save time. Save code. Save sanity.
Subprojects
AutoFactory - JSR-330-compatible factories
AutoService - Provider-configuration files for
ServiceLoaderAutoValue - Immutable value-type code generation for Java 8+.
Common - Helper utilities for writing annotation processors.
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.File: common/README.md
Auto Common Utilities
Overview
The Auto project has a set of common utilities to help ease use of the
annotation processing environment.
Utility classes of note
MoreTypes
: Utilities and Equivalence wrappers for TypeMirror and related subtypes
MoreElements
: Utilities for Element and related subtypes
SuperficialValidation
: Very simple scanner to ensure an Element is valid and free from distortion
from upstream compilation errors
Visibility
: Utilities for working with Elements' visibility levels (public, protected,
etc.)
BasicAnnotationProcessor/Step
: Simple types that
- implement a validating annotation processor
- defer invalid elements until later
- break processor actions into multiple steps (which may each handle
different annotations)
Usage/Setup
Auto common utilities have a standard Maven setup
which can also be used from Gradle, Ivy, Ant, or other systems which consume
binary artifacts from the central Maven binary artifact repositories.
<dependency>
<groupId>com.google.auto</groupId>
<artifactId>auto-common</artifactId>
<version>1.0-SNAPSHOT</version>
</dependency>File: factory/README.md
AutoFactory
A source code generator for JSR-330-compatible factories.
AutoWhat‽
Java is full of factories. They're mechanical, repetitive, typically untested and sometimes the source of subtle bugs. Sounds like a job for robots!
AutoFactory generates factories that can be used on their own or with JSR-330-compatible dependency injectors from a simple annotation. Any combination of parameters can either be passed through factory methods or provided to the factory at construction time. They can implement interfaces or extend abstract classes. They're what you would have written, but without the bugs.
Dagger users: Dagger's own
assisted injection is
now usually preferred to AutoFactory.
Example
Say you have:
@AutoFactory
final class SomeClass {
private final String providedDepA;
private final String depB;
SomeClass(@Provided @AQualifier String providedDepA, String depB) {
this.providedDepA = providedDepA;
this.depB = depB;
}
// …
}AutoFactory will generate:
import javax.annotation.Generated;
import javax.inject.Inject;
import javax.inject.Provider;
@Generated(value = "com.google.auto.factory.processor.AutoFactoryProcessor")
final class SomeClassFactory {
private final Provider<String> providedDepAProvider;
@Inject SomeClassFactory(
@AQualifier Provider<String> providedDepAProvider) {
this.providedDepAProvider = providedDepAProvider;
}
SomeClass create(String depB) {
return new SomeClass(providedDepAProvider.get(), depB);
}
}NOTE: AutoFactory only supports JSR-330 @Qualifier annotations. Older,
framework-specific annotations from Guice, Spring, etc are not
supported (though these all support JSR-330)
Mocking
By default, the factory class generated by AutoFactory is final, and thus cannot
be mocked. The generated factory class can be made mockable by settingallowSubclasses = true, as follows:
@AutoFactory(allowSubclasses = true)
final class SomeClass {
// …
}Download
In order to activate code generation, you will need to includeauto-factory-${version}.jar in both your classpath and your
annotation-processor path at compile time.
In a Maven project, one would include the auto-factory artifact as an
"optional" dependency and then include it again in annotationProcessorPaths:
<dependencies>
<dependency>
<groupId>com.google.auto.factory</groupId>
<artifactId>auto-factory</artifactId>
<version>${auto-factory.version}</version>
<optional>true</optional>
</dependency>
</dependencies>
...
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<annotationProcessorPaths>
<groupId>com.google.auto.factory</groupId>
<artifactId>auto-factory</artifactId>
<version>${auto-factory.version}</version>
</annotationProcessorPaths>
</configuration>Previous versions of these instructions suggested an alternative configuration
without the annotationProcessorPaths entry. We no longer recommend that
configuration. (It may produce warnings or errors under recent
versions of Java.)
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.File: service/README.md
AutoService
A configuration/metadata generator for java.util.ServiceLoader-style service
providers
AutoWhat‽
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.
Example
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 fileMETA-INF/services/javax.annotation.processing.Processor in the output classes
folder. The file will contain:
foo.bar.MyProcessorIn 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:
<dependencies>
<dependency>
<groupId>com.google.auto.service</groupId>
<artifactId>auto-service-annotations</artifactId>
<version>${auto-service.version}</version>
</dependency>
</dependencies>
...
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<annotationProcessorPaths>
<groupId>com.google.auto.service</groupId>
<artifactId>auto-service</artifactId>
<version>${auto-service.version}</version>
</annotationProcessorPaths>
</configuration>Previous versions of these instructions suggested an alternative configuration,
where the com.google.auto.service:auto-service dependency itself was anoptional 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.)
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.File: value/README.md
AutoValue
Generated immutable value classes for Java 8+
Kevin Bourrillion, Éamonn McManus
Google, Inc.
Value classes are extremely common in Java projects. These are classes for
which you want to treat any two instances with suitably equal field values as
interchangeable. That's right: we're talking about those classes where you wind
up implementing equals, hashCode and toString in a bloated, repetitive,
formulaic yet error-prone fashion.
Writing these methods the first time is not too bad, with the aid of a few
helper methods and IDE templates. But once written they continue to burden
reviewers, editors and future readers. Their wide expanses of boilerplate
sharply decrease the signal-to-noise ratio of your code... and they love to
harbor hard-to-spot bugs.
AutoValue provides an easier way to create immutable value classes, with a lot
less code and less room for error, while not restricting your freedom to
code almost any aspect of your class exactly the way you want it.
For more information, consult the detailed documentation.
Note: If you are using Kotlin then its
data classes are usually more
appropriate than AutoValue. Likewise, if you are using a version of Java that
has records then those are usually more appropriate. You can still
use AutoBuilder to make builders for data classes or records.