Interface PropertySpec

All Known Subinterfaces:

SpecialPropertySpec

All Known Implementing Classes:

CharsetProperty, ClockProperty, LocaleProperty, MessagePrefixProperty, ProcessIdProperty, PropertySpecImpl, RandomProperty, ResourceBundleProperty, SessionKeyProperty, SpecialPropertySpecBase, TimeZoneProperty

@ClassVersion(sourceVersion="$Id: PropertySpec.java 1258 2026-06-04 18:33:06Z tquadrat $")
@API(status=MAINTAINED,
     since="0.1.0")
public interface PropertySpec

The specification for a property of a configuration bean.

Author:

Thomas Thrien (thomas.thrien@tquadrat.org)

Version:

$Id: PropertySpec.java 1258 2026-06-04 18:33:06Z tquadrat $

Since:

0.1.0

UML Diagram

⁠

UML Diagram for "org.tquadrat.foundation.config.ap.PropertySpec"

⁠

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static enum	PropertySpec.PropertyFlag	The flags for a property.

Method Summary

Modifier and Type	Method	Description
Optional<MethodSpec>	createAddMethod(CodeBuilder codeBuilder)	Creates the specification of the 'add' method for this property.
Optional<CodeBlock>	createConstructorFragment(CodeBuilder codeBuilder)	Creates a code block that is a fragment for the constructor of the new configuration bean and that initialises this property.
Optional<FieldSpec>	createField(CodeBuilder codeBuilder)	Creates the field specification for this property.
Optional<MethodSpec>	createGetter(CodeBuilder codeBuilder)	Creates the specification of the getter for this property.
Optional<MethodSpec>	createSetter(CodeBuilder codeBuilder)	Creates the specification of the setter for this property.
Name	getAddMethodArgumentName()	Returns the name of the 'add' method's argument.
Optional<Name>	getAddMethodName()	Returns the name of the 'add' method for this property.
OptionalInt	getCLIArgumentIndex()	Returns the index for an argument on the command line.
Optional<String>	getCLIFormat()	Returns the special CLI format.
Optional<String>	getCLIMetaVar()	Returns the name of the CLI meta variable for this property.
Optional<List<String>>	getCLIOptionNames()	Returns the CLI option names.
Optional<String>	getCLIUsage()	Returns the CLI usage text for this property.
Optional<String>	getCLIUsageKey()	Returns the CLI usage key for this property.
Optional<TypeName>	getCLIValueHandlerClass()	Returns the CLI value handler class for this property.
CollectionKind	getCollectionKind()	Returns the kind of collection for this property.
default Optional<TypeName>	getElementType()	If the property is a collection (either Set or List, this method returns the element type of that collection.
Optional<String>	getEnvironmentDefaultValue()	Returns the default value for an environment variable or a system property.
Optional<String>	getEnvironmentVariableName()	Returns the name of the environment variable that is used to initialise this property.
default String	getFieldName()	Returns the name of the field for the property.
Optional<MethodSpec.Builder>	getGetterBuilder()	Returns a builder for the getter for this property.
Optional<Name>	getGetterMethodName()	Returns the name of the getter method name.
TypeName	getGetterReturnType()	Returns the return type of the getter.
Optional<String>	getINIComment()	Returns the comment for this property in the INI file.
Optional<String>	getINIGroup()	Returns the group for this property in the INI file.
Optional<String>	getINIKey()	Returns the key for this property in the INI file.
Optional<TypeName>	getPrefsAccessorClass()	Returns the Preferences accessor class.
Optional<String>	getPrefsKey()	Returns the Preferences key for this property.
String	getPropertyName()	Returns the name of the configuration property.
TypeName	getPropertyType()	Returns the property type.
Name	getSetterArgumentName()	Returns the name of the setter's argument.
Optional<MethodSpec.Builder>	getSetterBuilder()	Returns a builder for the setter for this property.
Optional<Name>	getSetterMethodName()	Returns the name of the setter method name.
Optional<SpecialPropertyType>	getSpecialPropertyType()	Return the 'speciality' type for this property.
Optional<TypeName>	getStringConverterClass()	Returns the class that implements the String converter for the type of this property.
Optional<String>	getSystemPrefsPath()	Returns the path to the SYSTEM Preferences node that holds the data for the initialisation of this property.
Optional<String>	getSystemPropertyName()	Returns the name of the system property that is used to initialise this property.
boolean	hasFlag(PropertySpec.PropertyFlag flag)	Checks whether the given flag is set for this property.
default boolean	isCollection()	Checks whether this property is a collection of some kind.
boolean	isEnum()	Returns the flag that indicates whether the property is an enum type.
default boolean	isOnCLI()	Checks whether this property is exposed to the CLI.
PropertySpec	merge()	'Merges' the attributes from a special property with the attributes retrieved from the configuration bean specification and returns a new instance of PropertySpec.

Method Details

createAddMethod

Optional<MethodSpec> createAddMethod(CodeBuilder codeBuilder)

Creates the specification of the 'add' method for this property.

Parameters:

codeBuilder - The factory for the code generation.

Returns:

An instance of Optional that holds the method specification.

createConstructorFragment

Optional<CodeBlock> createConstructorFragment(CodeBuilder codeBuilder)

Creates a code block that is a fragment for the constructor of the new configuration bean and that initialises this property.

Parameters:

codeBuilder - The factory for the code generation.

Returns:

An instance of Optional that holds the code block.

createField

Optional<FieldSpec> createField(CodeBuilder codeBuilder)

Creates the field specification for this property.

Parameters:

codeBuilder - The factory for the code generation.

Returns:

An instance of Optional that holds the field specification.

createGetter

Optional<MethodSpec> createGetter(CodeBuilder codeBuilder)

Creates the specification of the getter for this property.

Parameters:

codeBuilder - The factory for the code generation.

Returns:

An instance of Optional that holds the method specification.

createSetter

Optional<MethodSpec> createSetter(CodeBuilder codeBuilder)

Creates the specification of the setter for this property.

Parameters:

codeBuilder - The factory for the code generation.

Returns:

An instance of Optional that holds the method specification.

getAddMethodArgumentName

Name getAddMethodArgumentName()

Returns the name of the 'add' method's argument.

Returns:

The argument name; is probable null when getAddMethodName() returns Optional.empty().

getAddMethodName

Optional<Name> getAddMethodName()

Returns the name of the 'add' method for this property.

Returns:

An instance of Optional that holds the name of the add method.

getCLIArgumentIndex

OptionalInt getCLIArgumentIndex()

Returns the index for an argument on the command line.

The return value will be empty if the property is not a CLI argument.

Returns:

An instance of OptionalInt that holds the index.

See Also:

• Argument.index()

getCLIFormat

Optional<String> getCLIFormat()

Returns the special CLI format.

Returns:

An instance of Optional that holds the format.

See Also:

• Argument.format()
• Option.format()

getCLIMetaVar

Optional<String> getCLIMetaVar()

Returns the name of the CLI meta variable for this property.

Returns:

An instance of Optional that holds the name of the meta variable.

See Also:

• Argument.metaVar()
• Option.metaVar()

getCLIOptionNames

Optional<List<String>> getCLIOptionNames()

Returns the CLI option names. The mandatory first name in the list is the primary name, the optional others are the aliases.

The return value will be empty if the property is not a CLI option.

Returns:

An instance of Optional that holds the option names.

See Also:

• Option.name()
• Option.aliases()

getCLIUsage

Optional<String> getCLIUsage()

Returns the CLI usage text for this property. This text will not be localised.

Returns:

An instance of Optional that holds the usage text.

See Also:

• Argument.usage()
• Option.usage()

getCLIUsageKey

Optional<String> getCLIUsageKey()

Returns the CLI usage key for this property. This key is used to retrieve a localised usage text.

Returns:

An instance of Optional that holds the usage key.

See Also:

• Argument.usageKey()
• Option.usageKey()

getCLIValueHandlerClass

Optional<TypeName> getCLIValueHandlerClass()

Returns the CLI value handler class for this property.

Returns:

An instance of Optional that holds the TypeName for the handler class.

See Also:

• Argument.handler()
• Option.handler()

getCollectionKind

CollectionKind getCollectionKind()

Returns the kind of collection for this property.

Returns:

The collection kind.

getElementType

default Optional<TypeName> getElementType()

If the property is a collection (either Set or List, this method returns the element type of that collection.

Returns:

An instance of Optional that holds the element type.

getEnvironmentDefaultValue

Optional<String> getEnvironmentDefaultValue()

Returns the default value for an environment variable or a system property. This is used to initialise this property when it has the annotation @EnvironmentVariable or @EnvironmentVariable, but no value is provided.

A default value is mandatory when the annotated property has a primitive type.

Returns:

An instance of Optional that holds the default value.

getEnvironmentVariableName

Optional<String> getEnvironmentVariableName()

Returns the name of the environment variable that is used to initialise this property.

Returns:

An instance of Optional that holds the environment variable name.

See Also:

• EnvironmentVariable

getFieldName

default String getFieldName()

Returns the name of the field for the property.

Returns:

The field name.

getGetterBuilder

Optional<MethodSpec.Builder> getGetterBuilder()

Returns a builder for the getter for this property.

Returns:

An instance of Optional that holds the builder.

getGetterMethodName

Optional<Name> getGetterMethodName()

Returns the name of the getter method name. If there is no name for the method, it will not be generated.

Returns:

An instance of Optional that holds the name of the getter method.

getGetterReturnType

TypeName getGetterReturnType()

Returns the return type of the getter. This is not necessarily the same as the property type.

Returns:

The getter's return type.

getINIComment

Optional<String> getINIComment()

Returns the comment for this property in the INI file.

Returns:

An instance of Optional that holds the comment.

getINIGroup

Optional<String> getINIGroup()

Returns the group for this property in the INI file.

Returns:

An instance of Optional that holds the group name.

getINIKey

Optional<String> getINIKey()

Returns the key for this property in the INI file.

Returns:

An instance of Optional that holds the key.

getPrefsAccessorClass

Optional<TypeName> getPrefsAccessorClass()

Returns the Preferences accessor class.

This is used when this property is linked to a preference, but also to initialise it from a SYSTEM preference.

Returns:

An instance of Optional that holds the TypeName for the accessor class.

See Also:

• PreferencesBeanSpec
• Preference.accessor()
• SystemPreference.accessor()

getPrefsKey

Optional<String> getPrefsKey()

Returns the Preferences key for this property.

This is used when this property is linked to a preference, but also to initialise it from a SYSTEM preference. In first case, the name is defaulted to the property name, while it is mandatory otherwise.

Returns:

An instance of Optional that holds the preferences key for this property.

See Also:

• PreferencesBeanSpec
• Preference.key()
• SystemPreference.key()

getPropertyName

String getPropertyName()

Returns the name of the configuration property.

Returns:

The name.

getPropertyType

TypeName getPropertyType()

Returns the property type.

Returns:

The property type.

getSetterArgumentName

Name getSetterArgumentName()

Returns the name of the setter's argument.

Returns:

The argument name; is probably null when getSetterMethodName() returns Optional.empty().

getSetterBuilder

Optional<MethodSpec.Builder> getSetterBuilder()

Returns a builder for the setter for this property.

Returns:

An instance of Optional that holds the builder.

getSetterMethodName

Optional<Name> getSetterMethodName()

Returns the name of the setter method name. If there is no name for the method, it will not be generated.

Returns:

An instance of Optional that holds the name of the setter method.

getSpecialPropertyType

Optional<SpecialPropertyType> getSpecialPropertyType()

Return the 'speciality' type for this property.

Returns:

An instance of Optional that holds the speciality type.

getStringConverterClass

Optional<TypeName> getStringConverterClass()

Returns the class that implements the String converter for the type of this property.

Returns:

An instance of Optional that holds the implementation class for StringConverter.

getSystemPrefsPath

Optional<String> getSystemPrefsPath()

Returns the path to the SYSTEM Preferences node that holds the data for the initialisation of this property.

Returns:

An instance of Optional that holds the path.

See Also:

• SystemPreference.path()

getSystemPropertyName

Optional<String> getSystemPropertyName()

Returns the name of the system property that is used to initialise this property.

Returns:

An instance of Optional that holds the system property name.

See Also:

• SystemProperty

hasFlag

boolean hasFlag(PropertySpec.PropertyFlag flag)

Checks whether the given flag is set for this property.

Parameters:

flag - The flag to test for.

Returns:

true if the flag is set, false otherwise.

isCollection

default boolean isCollection()

Checks whether this property is a collection of some kind.

Returns:

true if this property is a collection, false otherwise.

isEnum

boolean isEnum()

Returns the flag that indicates whether the property is an enum type.

Returns:

true if the property type is an enum, false otherwise.

isOnCLI

default boolean isOnCLI()

Checks whether this property is exposed to the CLI. This means that it has either the flag PropertySpec.PropertyFlag.PROPERTY_IS_ARGUMENT or the PropertySpec.PropertyFlag.PROPERTY_IS_OPTION set to it.

Returns:

true if the property is exposed to the CLI, false otherwise.

merge

PropertySpec merge()

'Merges' the attributes from a special property with the attributes retrieved from the configuration bean specification and returns a new instance of PropertySpec. The original instance remains unchanged.

If the property is not a special property (the flag PropertySpec.PropertyFlag.PROPERTY_IS_SPECIAL is not set), this instance will be returned.

Returns:

The effective property specification.