README.md
1AutoFactory
2======
3
4A source code generator for JSR-330-compatible factories.
5
6AutoWhat‽
7-------------
8
9[Java][java] is full of [factories](http://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!_
10
11AutoFactory generates factories that can be used on their own or with [JSR-330](http://jcp.org/en/jsr/detail?id=330)-compatible [dependency injectors](http://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.
12
13[Dagger](https://dagger.dev/) users: Dagger's own
14[assisted injection](https://dagger.dev/dev-guide/assisted-injection.html) is
15now usually preferred to AutoFactory.
16
17Example
18-------
19
20Say you have:
21
22```java
23@AutoFactory
24final class SomeClass {
25 private final String providedDepA;
26 private final String depB;
27
28 SomeClass(@Provided @AQualifier String providedDepA, String depB) {
29 this.providedDepA = providedDepA;
30 this.depB = depB;
31 }
32
33 // …
34}
35```
36
37AutoFactory will generate:
38
39```java
40import javax.annotation.Generated;
41import javax.inject.Inject;
42import javax.inject.Provider;
43
44@Generated(value = "com.google.auto.factory.processor.AutoFactoryProcessor")
45final class SomeClassFactory {
46 private final Provider<String> providedDepAProvider;
47
48 @Inject SomeClassFactory(
49 @AQualifier Provider<String> providedDepAProvider) {
50 this.providedDepAProvider = providedDepAProvider;
51 }
52
53 SomeClass create(String depB) {
54 return new SomeClass(providedDepAProvider.get(), depB);
55 }
56}
57```
58
59> NOTE: AutoFactory only supports JSR-330 @Qualifier annotations. Older,
60> framework-specific annotations from Guice, Spring, etc are not
61> supported (though these all support JSR-330)
62
63Mocking
64-------
65
66By default, the factory class generated by AutoFactory is final, and thus cannot
67be mocked. The generated factory class can be made mockable by setting
68`allowSubclasses = true`, as follows:
69
70```java
71@AutoFactory(allowSubclasses = true)
72final class SomeClass {
73 // …
74}
75```
76
77Download
78--------
79
80In order to activate code generation you will need to
81include `auto-factory-${version}.jar` in your build at
82compile time.
83
84In a Maven project, one would include the `auto-factory`
85artifact as an "optional" dependency:
86
87```xml
88<dependencies>
89 <dependency>
90 <groupId>com.google.auto.factory</groupId>
91 <artifactId>auto-factory</artifactId>
92 <version>${version}</version>
93 <optional>true</optional>
94 </dependency>
95</dependencies>
96```
97
98
99License
100-------
101
102 Copyright 2013 Google LLC
103
104 Licensed under the Apache License, Version 2.0 (the "License");
105 you may not use this file except in compliance with the License.
106 You may obtain a copy of the License at
107
108 http://www.apache.org/licenses/LICENSE-2.0
109
110 Unless required by applicable law or agreed to in writing, software
111 distributed under the License is distributed on an "AS IS" BASIS,
112 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
113 See the License for the specific language governing permissions and
114 limitations under the License.
115
116[java]: https://en.wikipedia.org/wiki/Java_(programming_language)
117
118