## File: README.md
# Auto
[](https://github.com/google/auto/actions/workflows/ci.yml)
A collection of source code generators for [Java][java].
## Overview
[Java][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
[](https://mvnrepository.com/artifact/com.google.auto.factory/auto-factory)
* [AutoService] - Provider-configuration files for [`ServiceLoader`]
[](https://mvnrepository.com/artifact/com.google.auto.service/auto-service)
* [AutoValue] - Immutable [value-type] code generation for Java 8+.
[](https://mvnrepository.com/artifact/com.google.auto.value/auto-value)
* [Common] - Helper utilities for writing annotation processors.
[](https://mvnrepository.com/artifact/com.google.auto/auto-common)
## 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.
[AutoFactory]: https://github.com/google/auto/tree/main/factory
[AutoService]: https://github.com/google/auto/tree/main/service
[AutoValue]: https://github.com/google/auto/tree/main/value
[Common]: https://github.com/google/auto/tree/main/common
[java]: https://en.wikipedia.org/wiki/Java_(programming_language)
[value-type]: http://en.wikipedia.org/wiki/Value_object
[`ServiceLoader`]: https://docs.oracle.com/en/java/javase/23/docs/api/java.base/java/util/ServiceLoader.html
---
## 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 `Element`s' 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](http://maven.apache.org) setup
which can also be used from Gradle, Ivy, Ant, or other systems which consume
binary artifacts from the central Maven binary artifact repositories.
```xml
com.google.auto
auto-common
1.0-SNAPSHOT
```
---
## File: factory/README.md
AutoFactory
======
A source code generator for JSR-330-compatible factories.
AutoWhat‽
-------------
[Java][java] is full of [factories](https://en.wikipedia.org/wiki/Factory_method_pattern). 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](https://jcp.org/en/jsr/detail?id=330)-compatible [dependency injectors](https://en.wikipedia.org/wiki/Dependency_injection) 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](https://dagger.dev/) users: Dagger's own
[assisted injection](https://dagger.dev/dev-guide/assisted-injection) is
now usually preferred to AutoFactory.
Example
-------
Say you have:
```java
@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:
```java
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 providedDepAProvider;
@Inject SomeClassFactory(
@AQualifier Provider 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 setting
`allowSubclasses = true`, as follows:
```java
@AutoFactory(allowSubclasses = true)
final class SomeClass {
// …
}
```
Download
--------
In order to activate code generation, you will need to include
`auto-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`:
```xml
com.google.auto.factory
auto-factory
${auto-factory.version}
true
...
maven-compiler-plugin
com.google.auto.factory
auto-factory
${auto-factory.version}
```
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][JDK-8321319] 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.
[JDK-8321319]: https://bugs.openjdk.org/browse/JDK-8321319
[java]: https://en.wikipedia.org/wiki/Java_(programming_language)
---
## File: service/README.md
# 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 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.
## 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
com.google.auto.service
auto-service-annotations
${auto-service.version}
...
maven-compiler-plugin
com.google.auto.service
auto-service
${auto-service.version}
```
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][JDK-8321319] under recent versions of Java.)
[JDK-8321319]: https://bugs.openjdk.org/browse/JDK-8321319
## 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
---
## 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](https://kotlinlang.org/docs/data-classes.html) 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.
[detailed documentation]: userguide/index.md
[records]: userguide/records.md
[AutoBuilder]: userguide/autobuilder.md