Class AutoValueExtension
- java.lang.Object
-
- com.google.auto.value.extension.AutoValueExtension
-
- Direct Known Subclasses:
MemoizeExtension
public abstract class AutoValueExtension extends java.lang.Object
An AutoValueExtension allows for extra functionality to be created during the generation of an AutoValue class.Extensions are discovered at compile time using the
ServiceLoader
APIs, allowing them to run without any additional annotations. To be found byServiceLoader
, an extension class must be public with a public no-arg constructor, and its fully-qualified name must appear in a file calledMETA-INF/services/com.google.auto.value.extension.AutoValueExtension
in a jar that is on the compiler's-classpath
or-processorpath
.An Extension can extend the AutoValue implementation by generating a subclass of the AutoValue generated class. It is not guaranteed that an Extension's generated class will be the final class in the inheritance hierarchy, unless its
mustBeFinal(Context)
method returns true. Only one Extension can return true for a given context. Only generated classes that will be the final class in the inheritance hierarchy can be declared final. All others should be declared abstract.Each Extension must also be sure to generate a constructor with arguments corresponding to all properties in
AutoValueExtension.Context.properties()
, in order, and to call the superclass constructor with the same arguments. This constructor must have at least package visibility.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static interface
AutoValueExtension.Context
The context of the generation cycle.
-
Constructor Summary
Constructors Constructor Description AutoValueExtension()
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description boolean
applicable(AutoValueExtension.Context context)
Determines whether this Extension applies to the given context.java.util.Set<javax.lang.model.element.ExecutableElement>
consumeMethods(AutoValueExtension.Context context)
Returns a possible empty set of abstract methods that this Extension intends to implement.java.util.Set<java.lang.String>
consumeProperties(AutoValueExtension.Context context)
Returns a possibly empty set of property names that this Extension intends to implement.abstract java.lang.String
generateClass(AutoValueExtension.Context context, java.lang.String className, java.lang.String classToExtend, boolean isFinal)
Returns the generated source code of the class namedclassName
to extendclassToExtend
, ornull
if this extension does not generate a class in the hierarchy.boolean
mustBeFinal(AutoValueExtension.Context context)
Denotes that the class generated by this Extension must be the final class in the inheritance hierarchy.
-
-
-
Method Detail
-
applicable
public boolean applicable(AutoValueExtension.Context context)
Determines whether this Extension applies to the given context.- Parameters:
context
- The Context of the code generation for this class.- Returns:
- true if this Extension should be applied in the given context. If an Extension returns false for a given class, it will not be called again during the processing of that class.
-
mustBeFinal
public boolean mustBeFinal(AutoValueExtension.Context context)
Denotes that the class generated by this Extension must be the final class in the inheritance hierarchy. Only one Extension may be the final class, so this should be used sparingly.- Parameters:
context
- the Context of the code generation for this class.
-
consumeProperties
public java.util.Set<java.lang.String> consumeProperties(AutoValueExtension.Context context)
Returns a possibly empty set of property names that this Extension intends to implement. This will prevent AutoValue from generating an implementation, and remove the supplied properties from builders, constructors,toString
,equals
, andhashCode
. The default set returned by this method is empty.Each returned string must be one of the property names in
AutoValueExtension.Context.properties()
.Returning a property name from this method is equivalent to returning the property's getter method from
consumeMethods(com.google.auto.value.extension.AutoValueExtension.Context)
.For example, Android's
Parcelable
interface includes a methodint describeContents()
. Since this is an abstract method with no parameters, by default AutoValue will consider that it defines anint
property calleddescribeContents
. If an@AutoValue
class implementsParcelable
and does not provide an implementation of this method, by default its implementation will includedescribeContents
in builders, constructors, and so on. But anAutoValueExtension
that understandsParcelable
can instead provide a useful implementation and return a set containing"describeContents"
. ThendescribeContents
will be omitted from builders and the rest.- Parameters:
context
- the Context of the code generation for this class.
-
consumeMethods
public java.util.Set<javax.lang.model.element.ExecutableElement> consumeMethods(AutoValueExtension.Context context)
Returns a possible empty set of abstract methods that this Extension intends to implement. This will prevent AutoValue from generating an implementation, in cases where it would have, and it will also avoid warnings about abstract methods that AutoValue doesn't expect. The default set returned by this method is empty.Each returned method must be one of the abstract methods in
AutoValueExtension.Context.abstractMethods()
.For example, Android's
Parcelable
interface includes a methodvoid writeToParcel(Parcel, int)
. Normally AutoValue would not know what to do with that abstract method. But anAutoValueExtension
that understandsParcelable
can provide a useful implementation and return thewriteToParcel
method here. That will prevent a warning about the method from AutoValue.- Parameters:
context
- the Context of the code generation for this class.
-
generateClass
public abstract java.lang.String generateClass(AutoValueExtension.Context context, java.lang.String className, java.lang.String classToExtend, boolean isFinal)
Returns the generated source code of the class namedclassName
to extendclassToExtend
, ornull
if this extension does not generate a class in the hierarchy. If there is a generated class, it should be final ifisFinal
is true; otherwise it should be abstract. The returned string should be a complete Java class definition of the classclassName
in the packagecontext.packageName()
.The returned string will typically look like this:
package <package>; ... <finalOrAbstract> class <className> extends <classToExtend> {...}
Here,
<package>
isAutoValueExtension.Context.packageName()
;<finalOrAbstract>
is the keywordfinal
ifisFinal
is true orabstract
otherwise; and<className>
and<classToExtend>
are the values of this method's parameters of the same name.- Parameters:
context
- TheAutoValueExtension.Context
of the code generation for this class.className
- The simple name of the resulting class. The returned code will be written to a file named accordingly.classToExtend
- The simple name of the direct parent of the generated class. This could be the AutoValue generated class, or a class generated as the result of another Extension.isFinal
- True if this class is the last class in the chain, meaning it should be marked as final. Otherwise it should be marked as abstract.- Returns:
- The source code of the generated class, or
null
if this extension does not generate a class in the hierarchy.
-
-