com.google.auto.value.extension

Class AutoValueExtension

java.lang.Object

com.google.auto.value.extension.AutoValueExtension

public abstract class AutoValueExtension
extends Object

This API is not final and WILL CHANGE in a future release. 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.

Extensions can extend the AutoValue implementation by generating subclasses 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. This constructor must have at least package visibility.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	AutoValueExtension.Context The context of the generation cycle.

Constructor Summary

Constructors

Constructor and Description
AutoValueExtension()

Method Summary

Modifier and Type	Method and Description
boolean	applicable(AutoValueExtension.Context context) Determines whether this extension applies to the given context.
Set<String>	consumeProperties(AutoValueExtension.Context context) Returns a non-null set of property names from AutoValueExtension.Context.properties() that this extension intends to implement.
abstract String	generateClass(AutoValueExtension.Context context, String className, String classToExtend, boolean isFinal) Generates the source code of the class named className to extend classToExtend, with the original annotated class of classToImplement.
boolean	mustBeFinal(AutoValueExtension.Context context) Denotes that the class generated by this Extension must be the final class in the inheritance hierarchy.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AutoValueExtension

public AutoValueExtension()

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.

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.

Returns:

True if the resulting class must be the final class in the inheritance hierarchy.

consumeProperties

public Set<String> consumeProperties(AutoValueExtension.Context context)

Returns a non-null set of property names from AutoValueExtension.Context.properties() that this extension intends to implement. This will prevent AutoValue from generating an implementation, and remove the supplied properties from builders, constructors, toString, equals, and hashCode. The default set returned by this method is empty.

For example, Android's Parcelable interface includes a method int describeContents(). Since this is an abstract method with no parameters, by default AutoValue will consider that it defines an int property called describeContents. If an @AutoValue class implements Parcelable and does not provide an implementation of this method, by default its implementation will include describeContents in builders, constructors, and so on. But an AutoValueExtension that understands Parcelable can instead provide a useful implementation and return a set containing "describeContents". Then describeContents will be omitted from builders and the rest.

Parameters:

context - The Context of the code generation for this class.

Returns:

A collection of property names that this extension intends to implement.

generateClass

public abstract String generateClass(AutoValueExtension.Context context,
                                     String className,
                                     String classToExtend,
                                     boolean isFinal)

Generates the source code of the class named className to extend classToExtend, with the original annotated class of classToImplement. The generated class should be final if isFinal is true; otherwise it should be abstract.

Parameters:

context - The AutoValueExtension.Context of the code generation for this class.

className - The name of the resulting class. The returned code will be written to a file named accordingly.

classToExtend - The direct parent of the generated class. 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