Code generation to track which properties have been set in a builder.

Every property in an @AutoValue or @AutoBuilder builder must be set before the build() method is called, with a few exceptions like @Nullable and Optional properties. That means we must keep track of which ones have in fact been set. We do that in two ways: for reference (non-primitive) types, we use null to indicate that the value has not been set, while for primitive types we use a bitmask where each bit indicates whether a certain primitive property has been set.

Additionally, for Kotlin constructors with default parameters, we track exactly which properties have been set so we can invoke the constructor thas has a bitmask indicating the properties to be defaulted.

The public methods in this class are accessed reflectively from the builder.vm template. In that template, $builderRequiredProperties references an instance of this class corresponding to the builder being generated. A reference like $builderRequiredProperties.markAsSet($p) calls the method markAsSet with the given parameter. A reference like $builderRequiredProperties.requiredProperties is shorthand for $builderRequiredProperties.getProperties().

Nested and Inner Type Summary

Modifier and Type	Class and Description
private static class	BuilderRequiredProperties.BitmaskField Represents a field in which we will record which tracked properties from a certain set have been given a value.
private static class	BuilderRequiredProperties.NoDefaults Subclass for when there are no Kotlin default properties.
private static class	BuilderRequiredProperties.WithDefaults Subclass for when there are Kotlin default properties.

Modifier and Type	Field and Description
pack-priv final ImmutableList<BuilderRequiredProperties.BitmaskField>	bitmaskFields The integer fields that store the bitmask.
pack-priv static final BuilderRequiredProperties	EMPTY
pack-priv final ImmutableSet<AutoValueishProcessor.Property>	requiredProperties All required properties.
pack-priv final ImmutableMap<AutoValueishProcessor.Property, Integer>	trackedPropertyToIndex The bit index for each tracked property.

Constructor Summary

Access	Constructor and Description
private	BuilderRequiredProperties(ImmutableSet<AutoValueishProcessor.Property> requiredProperties, ImmutableList<AutoValueishProcessor.Property> trackedProperties)

Method Summary

Modifier and Type	Method and Description
pack-priv abstract String	allRequiredBitmask(ImmutableList<AutoValueishProcessor.Property> trackedProperties, int bitBase, int remainingBits)
private static String	cast(Class<?> type, String number)
private static Class<?>	classForBits(int bits) The smallest primitive integer type that has at least this many bits, or `int` if the number of bits is more than 32.
public abstract String	getAnyMissing() Returns an expression that is true if any required properties have not been set.
public abstract String	getDefaultedBitmaskParameters() Returns additional constructor parameters to indicate what properties have been defaulted, or an empty string if there are none.
public ImmutableList<String>	getFieldDeclarations() Returns code to declare any fields needed to track which properties have been set.
public ImmutableList<String>	getInitToAllSet() Returns code to indicate that all tracked properties have received a value.
public ImmutableSet<AutoValueishProcessor.Property>	getRequiredProperties()
pack-priv static String	hex(int number)
public String	markAsSet(AutoValueishProcessor.Property p) Returns code to indicate that the given property has been set, if assigning to the property field is not enough.
public String	missingRequiredProperty(AutoValueishProcessor.Property p) Returns an expression that is true if the given property is required but has not been set.
public String	noValueToGet(AutoValueishProcessor.Property p) Returns an expression that is true if the given property has not been given a value.
pack-priv static BuilderRequiredProperties	of(ImmutableSet<AutoValueishProcessor.Property> allProperties, ImmutableSet<AutoValueishProcessor.Property> requiredProperties)
private String	propertyNotSet(AutoValueishProcessor.Property p)

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

bitmaskFields back to summary

bitmaskFields	back to summary
pack-priv final ImmutableList<BuilderRequiredProperties.BitmaskField> bitmaskFields The integer fields that store the bitmask. In the usual case, where there are ≤32 tracked properties, we can pack the bitmask into one integer field. Its type is the smallest one that fits the required number of bits, for example `byte` if there are ≤8 tracked properties. If there are >32 tracked properties, we will pack them into as few integer fields as possible. For example if there are 75 tracked properties (this can happen) then we will put numbers 0 to 31 in an `int`, 32 to 63 in a second `int`, and 64 to 75 in a `short`. When there are >32 tracked properties, we could potentially pack them better if we used `long`. But sometimes AutoValue code gets translated into JavaScript, which doesn't handle long values natively. By the time you have that many properties you are probably not going to notice the difference between 5 ints or 2 longs plus an int.

pack-priv final ImmutableList<BuilderRequiredProperties.BitmaskField> bitmaskFields

The integer fields that store the bitmask. In the usual case, where there are ≤32 tracked properties, we can pack the bitmask into one integer field. Its type is the smallest one that fits the required number of bits, for example byte if there are ≤8 tracked properties.

If there are >32 tracked properties, we will pack them into as few integer fields as possible. For example if there are 75 tracked properties (this can happen) then we will put numbers 0 to 31 in an int, 32 to 63 in a second int, and 64 to 75 in a short.

When there are >32 tracked properties, we could potentially pack them better if we used long. But sometimes AutoValue code gets translated into JavaScript, which doesn't handle long values natively. By the time you have that many properties you are probably not going to notice the difference between 5 ints or 2 longs plus an int.

EMPTY	back to summary
pack-priv static final BuilderRequiredProperties EMPTY

requiredProperties	back to summary
pack-priv final ImmutableSet<AutoValueishProcessor.Property> requiredProperties All required properties.

trackedPropertyToIndex	back to summary
pack-priv final ImmutableMap<AutoValueishProcessor.Property, Integer> trackedPropertyToIndex The bit index for each tracked property. Properties are tracked if they are primitive, or if this is a Kotlin constructor with default parameters. Non-tracked properties do not appear in this map.

Constructor Detail

BuilderRequiredProperties	back to summary
private BuilderRequiredProperties(ImmutableSet<AutoValueishProcessor.Property> requiredProperties, ImmutableList<AutoValueishProcessor.Property> trackedProperties)

Method Detail

allRequiredBitmask	back to summary
pack-priv abstract String allRequiredBitmask(ImmutableList<AutoValueishProcessor.Property> trackedProperties, int bitBase, int remainingBits)

cast	back to summary
private static String cast(Class<?> type, String number)

classForBits	back to summary
private static Class<?> classForBits(int bits) The smallest primitive integer type that has at least this many bits, or `int` if the number of bits is more than 32.

getAnyMissing	back to summary
public abstract String getAnyMissing() Returns an expression that is true if any required properties have not been set. Should not be called if there are no required properties.

getDefaultedBitmaskParameters	back to summary
public abstract String getDefaultedBitmaskParameters() Returns additional constructor parameters to indicate what properties have been defaulted, or an empty string if there are none.

getFieldDeclarations	back to summary
public ImmutableList<String> getFieldDeclarations() Returns code to declare any fields needed to track which properties have been set. Each line in the returned list should appear on a line of its own.

getInitToAllSet	back to summary
public ImmutableList<String> getInitToAllSet() Returns code to indicate that all tracked properties have received a value. This is needed in the `toBuilder()` constructor, since it assigns to the corresponding fields directly without going through their setters.

getRequiredProperties	back to summary
public ImmutableSet<AutoValueishProcessor.Property> getRequiredProperties()

hex	back to summary
pack-priv static String hex(int number) Annotations @VisibleForTesting

markAsSet	back to summary
public String markAsSet(AutoValueishProcessor.Property p) Returns code to indicate that the given property has been set, if assigning to the property field is not enough. For reference (non-primitive) properties, assignment is enough, but for primitive properties we also need to set a bit in the bitmask.

missingRequiredProperty	back to summary
public String missingRequiredProperty(AutoValueishProcessor.Property p) Returns an expression that is true if the given property is required but has not been set. Returns null if the property is not required.

noValueToGet back to summary

noValueToGet	back to summary
public String noValueToGet(AutoValueishProcessor.Property p) Returns an expression that is true if the given property has not been given a value. That's only different from `missingRequiredProperty` if the property has a Kotlin default. If so, we don't require it to be set at build time (because Kotlin will supply the default), but we do require it to be set if it is accessed with a getter on the builder. We don't have access to Kotlin parameter defaults so we can't arrange for the builder field to have the same default value. Rather than returning a bogus zero value we say the value is unset.

public String noValueToGet(AutoValueishProcessor.Property p)

Returns an expression that is true if the given property has not been given a value. That's only different from missingRequiredProperty if the property has a Kotlin default. If so, we don't require it to be set at build time (because Kotlin will supply the default), but we do require it to be set if it is accessed with a getter on the builder. We don't have access to Kotlin parameter defaults so we can't arrange for the builder field to have the same default value. Rather than returning a bogus zero value we say the value is unset.

of	back to summary
pack-priv static BuilderRequiredProperties of(ImmutableSet<AutoValueishProcessor.Property> allProperties, ImmutableSet<AutoValueishProcessor.Property> requiredProperties)

propertyNotSet	back to summary
private String propertyNotSet(AutoValueishProcessor.Property p)

com.google.auto.value.processor back to summary

private Class BuilderRequiredProperties.BitmaskField

Class Inheritance

extends Object

java.lang.Object
com.google.auto.value.processor.BuilderRequiredProperties.BitmaskField

Represents a field in which we will record which tracked properties from a certain set have been given a value.

Field Summary

Modifier and Type	Field and Description
pack-priv final String	allRequiredBitmask The source representation of the value this field has when all required properties have been given a value.
pack-priv final String	allSetBitmask The source representation of the value this field has when all properties have been given a value.
pack-priv final String	name
pack-priv final Class<?>	type

Constructor Summary

Access	Constructor and Description
pack-priv	BitmaskField(Class<?> type, String name, String allSetBitmask, String allRequiredBitmask)

Method Summary

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

allRequiredBitmask	back to summary
pack-priv final String allRequiredBitmask The source representation of the value this field has when all required properties have been given a value.

allSetBitmask	back to summary
pack-priv final String allSetBitmask The source representation of the value this field has when all properties have been given a value.

name	back to summary
pack-priv final String name

type	back to summary
pack-priv final Class<?> type

Constructor Detail

BitmaskField	back to summary
pack-priv BitmaskField(Class<?> type, String name, String allSetBitmask, String allRequiredBitmask)

com.google.auto.value.processor back to summary

private final Class BuilderRequiredProperties.NoDefaults

Class Inheritance

extends BuilderRequiredProperties

java.lang.Object
com.google.auto.value.processor.BuilderRequiredProperties
com.google.auto.value.processor.BuilderRequiredProperties.NoDefaults

Subclass for when there are no Kotlin default properties.

Field Summary

Inherited from com.google.auto.value.processor.BuilderRequiredProperties:: bitmaskFields EMPTY requiredProperties trackedPropertyToIndex

Constructor Summary

Access	Constructor and Description
pack-priv	NoDefaults(ImmutableSet<AutoValueishProcessor.Property> requiredProperties)

Method Summary

Modifier and Type	Method and Description
pack-priv String	allRequiredBitmask(ImmutableList<AutoValueishProcessor.Property> trackedProperties, int bitBase, int remainingBits) Implements abstract com.google.auto.value.processor.BuilderRequiredProperties.allRequiredBitmask.
public String	getAnyMissing() Implements abstract com.google.auto.value.processor.BuilderRequiredProperties.getAnyMissing. Returns an expression that is true if any required properties have not been set.
public String	getDefaultedBitmaskParameters() Implements abstract com.google.auto.value.processor.BuilderRequiredProperties.getDefaultedBitmaskParameters. Returns additional constructor parameters to indicate what properties have been defaulted, or an empty string if there are none.
private static ImmutableList<AutoValueishProcessor.Property>	primitivePropertiesIn(ImmutableSet<AutoValueishProcessor.Property> properties)

Inherited from com.google.auto.value.processor.BuilderRequiredProperties:: getFieldDeclarations getInitToAllSet getRequiredProperties hex markAsSet missingRequiredProperty noValueToGet of

Constructor Detail

NoDefaults	back to summary
pack-priv NoDefaults(ImmutableSet<AutoValueishProcessor.Property> requiredProperties)

Method Detail

allRequiredBitmask	back to summary
pack-priv String allRequiredBitmask(ImmutableList<AutoValueishProcessor.Property> trackedProperties, int bitBase, int remainingBits) Implements abstract com.google.auto.value.processor.BuilderRequiredProperties.allRequiredBitmask. Annotations @Override

allRequiredBitmask

back to summary

pack-priv String allRequiredBitmask(ImmutableList<AutoValueishProcessor.Property> trackedProperties, int bitBase, int remainingBits)

Implements abstract com.google.auto.value.processor.BuilderRequiredProperties.allRequiredBitmask.

Annotations

@Override

getAnyMissing	back to summary
public String getAnyMissing() Implements abstract com.google.auto.value.processor.BuilderRequiredProperties.getAnyMissing. Doc from com.google.auto.value.processor.BuilderRequiredProperties.getAnyMissing. Returns an expression that is true if any required properties have not been set. Should not be called if there are no required properties. We check the bitmask for primitive properties, and null checks for non-primitive ones. Annotations @Override

getAnyMissing

back to summary

public String getAnyMissing()

Implements abstract com.google.auto.value.processor.BuilderRequiredProperties.getAnyMissing.

Doc from com.google.auto.value.processor.BuilderRequiredProperties.getAnyMissing.

Returns an expression that is true if any required properties have not been set. Should not be called if there are no required properties.

We check the bitmask for primitive properties, and null checks for non-primitive ones.

Annotations

@Override

getDefaultedBitmaskParameters	back to summary
public String getDefaultedBitmaskParameters() Implements abstract com.google.auto.value.processor.BuilderRequiredProperties.getDefaultedBitmaskParameters. Doc from com.google.auto.value.processor.BuilderRequiredProperties.getDefaultedBitmaskParameters. Returns additional constructor parameters to indicate what properties have been defaulted, or an empty string if there are none. Annotations @Override

getDefaultedBitmaskParameters

back to summary

public String getDefaultedBitmaskParameters()

Implements abstract com.google.auto.value.processor.BuilderRequiredProperties.getDefaultedBitmaskParameters.

Doc from com.google.auto.value.processor.BuilderRequiredProperties.getDefaultedBitmaskParameters.

Returns additional constructor parameters to indicate what properties have been defaulted, or an empty string if there are none.

Annotations

@Override

primitivePropertiesIn	back to summary
private static ImmutableList<AutoValueishProcessor.Property> primitivePropertiesIn(ImmutableSet<AutoValueishProcessor.Property> properties)

com.google.auto.value.processor back to summary

private final Class BuilderRequiredProperties.WithDefaults

Class Inheritance

extends BuilderRequiredProperties

java.lang.Object
com.google.auto.value.processor.BuilderRequiredProperties
com.google.auto.value.processor.BuilderRequiredProperties.WithDefaults

Subclass for when there are Kotlin default properties.

Field Summary

Modifier and Type	Field and Description
private final ImmutableList<AutoValueishProcessor.Property>	allProperties

Inherited from com.google.auto.value.processor.BuilderRequiredProperties:: bitmaskFields EMPTY requiredProperties trackedPropertyToIndex

Constructor Summary

Access	Constructor and Description
pack-priv	WithDefaults(ImmutableSet<AutoValueishProcessor.Property> allProperties, ImmutableSet<AutoValueishProcessor.Property> requiredProperties)

Method Summary

Modifier and Type	Method and Description
pack-priv String	allRequiredBitmask(ImmutableList<AutoValueishProcessor.Property> trackedProperties, int bitBase, int remainingBits) Implements abstract com.google.auto.value.processor.BuilderRequiredProperties.allRequiredBitmask.
public String	getAnyMissing() Implements abstract com.google.auto.value.processor.BuilderRequiredProperties.getAnyMissing. Returns an expression that is true if any required properties have not been set.
public String	getDefaultedBitmaskParameters() Implements abstract com.google.auto.value.processor.BuilderRequiredProperties.getDefaultedBitmaskParameters. Returns additional constructor parameters to indicate what properties have been defaulted, or an empty string if there are none.

Inherited from com.google.auto.value.processor.BuilderRequiredProperties:: getFieldDeclarations getInitToAllSet getRequiredProperties hex markAsSet missingRequiredProperty noValueToGet of

Field Detail

allProperties	back to summary
private final ImmutableList<AutoValueishProcessor.Property> allProperties

Constructor Detail

WithDefaults	back to summary
pack-priv WithDefaults(ImmutableSet<AutoValueishProcessor.Property> allProperties, ImmutableSet<AutoValueishProcessor.Property> requiredProperties)

Method Detail

allRequiredBitmask	back to summary
pack-priv String allRequiredBitmask(ImmutableList<AutoValueishProcessor.Property> trackedProperties, int bitBase, int remainingBits) Implements abstract com.google.auto.value.processor.BuilderRequiredProperties.allRequiredBitmask. Annotations @Override

allRequiredBitmask

back to summary

pack-priv String allRequiredBitmask(ImmutableList<AutoValueishProcessor.Property> trackedProperties, int bitBase, int remainingBits)

Implements abstract com.google.auto.value.processor.BuilderRequiredProperties.allRequiredBitmask.

Annotations

@Override

getAnyMissing	back to summary
public String getAnyMissing() Implements abstract com.google.auto.value.processor.BuilderRequiredProperties.getAnyMissing. Doc from com.google.auto.value.processor.BuilderRequiredProperties.getAnyMissing. Returns an expression that is true if any required properties have not been set. Should not be called if there are no required properties. Everything can be checked with bitmask operations. If bit i represents a required property then it must be 1 in the bitmask field. So if we invert it we must get 0, and if we do that for the field as a whole and AND with a bitmask selecting only required properties we should get 0. Annotations @Override

getAnyMissing

back to summary

public String getAnyMissing()

Implements abstract com.google.auto.value.processor.BuilderRequiredProperties.getAnyMissing.

Doc from com.google.auto.value.processor.BuilderRequiredProperties.getAnyMissing.

Returns an expression that is true if any required properties have not been set. Should not be called if there are no required properties.

Everything can be checked with bitmask operations. If bit i represents a required property then it must be 1 in the bitmask field. So if we invert it we must get 0, and if we do that for the field as a whole and AND with a bitmask selecting only required properties we should get 0.

Annotations

@Override

getDefaultedBitmaskParameters back to summary

getDefaultedBitmaskParameters	back to summary
public String getDefaultedBitmaskParameters() Implements abstract com.google.auto.value.processor.BuilderRequiredProperties.getDefaultedBitmaskParameters. Doc from com.google.auto.value.processor.BuilderRequiredProperties.getDefaultedBitmaskParameters. Returns additional constructor parameters to indicate what properties have been defaulted, or an empty string if there are none. When there are default parameters, we're calling the special constructor that has one or more bitmask parameters at the end. Bit i is set if parameter i (zero-origin) has its default value, and then the actual value passed for that parameter is ignored. Our bitmask field has a 1 for any parameter that has been set, meaning it has a 0 for any parameter that has been defaulted. So we need to invert it, and we also want to AND it with a bitmask that selects just the bits for parameters with defaults. (The AND probably isn't strictly necessary, since the constructor code doesn't actually look at those other bits, but it seems cleaner.) If the bitmask for parameters with defaults is 0 then we can just use 0 for that bitmask, and if it is ~0 (all 1 bits) then we can skip the AND. That special constructor has an additional dummy parameter of type `DefaultConstructorMarker`. We just pass `null` to that parameter. Annotations @Override

public String getDefaultedBitmaskParameters()

Implements abstract com.google.auto.value.processor.BuilderRequiredProperties.getDefaultedBitmaskParameters.

Doc from com.google.auto.value.processor.BuilderRequiredProperties.getDefaultedBitmaskParameters.

Returns additional constructor parameters to indicate what properties have been defaulted, or an empty string if there are none.

When there are default parameters, we're calling the special constructor that has one or more bitmask parameters at the end. Bit i is set if parameter i (zero-origin) has its default value, and then the actual value passed for that parameter is ignored. Our bitmask field has a 1 for any parameter that has been set, meaning it has a 0 for any parameter that has been defaulted. So we need to invert it, and we also want to AND it with a bitmask that selects just the bits for parameters with defaults. (The AND probably isn't strictly necessary, since the constructor code doesn't actually look at those other bits, but it seems cleaner.) If the bitmask for parameters with defaults is 0 then we can just use 0 for that bitmask, and if it is ~0 (all 1 bits) then we can skip the AND.

That special constructor has an additional dummy parameter of type DefaultConstructorMarker. We just pass null to that parameter.

Annotations

@Override

public abstract Class BuilderRequiredProperties

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private Class BuilderRequiredProperties.BitmaskField

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

private final Class BuilderRequiredProperties.NoDefaults

Field Summary

Constructor Summary

Method Summary

Constructor Detail

Method Detail

private final Class BuilderRequiredProperties.WithDefaults

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail