Package org.sosy_lab.common.configuration.converters

Interface TypeConverter

All Known Implementing Classes:

BaseTypeConverter, ClassTypeConverter, FileTypeConverter, IntegerTypeConverter, TimeSpanTypeConverter

public interface TypeConverter

TypeConverters are used to parse Strings into instances of specific types during configuration option injection as performed by Configuration.inject(Object). Each type converter may handle one or more types.

TypeConverters need not to be thread safe as long as no injection is performed in parallel, however, they should have no mutable state anyway.

Primitive types will be converted into their corresponding wrapper type before any type converter is called, so they do not need to care at all about primitive types.

Method Summary

Modifier and Type	Method	Description
@Nullable Object	convert(String optionName, String value, TypeToken<?> type, @Nullable Annotation secondaryOption, @Nullable Path source, LogManager logger)	Convert a String given by the user to an instance of a given type.
default <T> @Nullable T	convertDefaultValue(String optionName, @Nullable T value, TypeToken<T> type, @Nullable Annotation secondaryOption)	Optionally convert the default value for an option that was given in the source code.
default <T> @Nullable T	convertDefaultValueFromOtherInstance(String optionName, @Nullable T value, TypeToken<T> type, @Nullable Annotation secondaryOption)	Like convertDefaultValue(String, Object, TypeToken, Annotation), but called if the default value was not taken from the fresh instance, but from a different instance (cf.
default TypeConverter	getInstanceForNewConfiguration(Configuration newConfiguration)	Return a (possibly) new instance of this converter that has new configuration values applied.

Method Detail

convert

@Nullable Object convert(String optionName,
                         String value,
                         TypeToken<?> type,
                         @Nullable Annotation secondaryOption,
                         @Nullable Path source,
                         LogManager logger)
                  throws InvalidConfigurationException

Convert a String given by the user to an instance of a given type.

Although the signature of this method does not enforce it, the class of the returned value needs to be assignable to "type" as defined by TypeToken.isSupertypeOf(java.lang.reflect.Type).

Before this method is called, the caller ensures that all requirements for the option defined with the Option annotation are met.

Parameters:

optionName - The name of the option (should only be used for nice error messages).

value - The string to parse.

type - The target type.

secondaryOption - An optional second annotation for the option (this is one of the annotations marked with OptionDetailAnnotation).

source - The file where the configuration option was read from. May contain a dummy value or null if the option was given somehow else.

logger - A logger for warnings etc.

Returns:

An instance of the target type produced from the string representation-

Throws:

UnsupportedOperationException - If the option specification in the source code is invalid (e.g., a missing annotation).

InvalidConfigurationException - If the user specified an invalid value.

convertDefaultValue

default <T> @Nullable T convertDefaultValue(String optionName,
                                            @Nullable T value,
                                            TypeToken<T> type,
                                            @Nullable Annotation secondaryOption)
                                     throws InvalidConfigurationException

Optionally convert the default value for an option that was given in the source code. This method is called if the user gave no explicit value.

Parameters:

optionName - The name of the option (should only be used for nice error messages).

value - The default value (may be null).

type - The target type.

secondaryOption - An optional second annotation for the option

Returns:

An instance of the target type.

Throws:

InvalidConfigurationException - If the default value is invalid for this option.

UnsupportedOperationException - If the option specification in the source code is invalid (e.g., a missing annotation).

convertDefaultValueFromOtherInstance

default <T> @Nullable T convertDefaultValueFromOtherInstance(String optionName,
                                                             @Nullable T value,
                                                             TypeToken<T> type,
                                                             @Nullable Annotation secondaryOption)
                                                      throws InvalidConfigurationException

Like convertDefaultValue(String, Object, TypeToken, Annotation), but called if the default value was not taken from the fresh instance, but from a different instance (cf. Configuration.injectWithDefaults(Object, Class, Object).

Override this method if convertDefaultValue(String, Object, TypeToken, Annotation) changes values and this should not be done twice if the value is injected again into another instance.

Throws:

InvalidConfigurationException

getInstanceForNewConfiguration

default TypeConverter getInstanceForNewConfiguration(Configuration newConfiguration)
                                              throws InvalidConfigurationException

Return a (possibly) new instance of this converter that has new configuration values applied.

If this converter has configuration options itself, it may be desired to use new values for these options if the converter instance is used together with a new Configuration instance. This method is called whenever an existing converter instance will be used by a new Configuration instance, e.g., by ConfigurationBuilder.copyFrom(Configuration) or if the converter instance is taken from Configuration.getDefaultConverters(). It can return a new converter instance according to the options in the new Configuration instance, or return the current converter instance. Note that this method should not change the existing instance.

Parameters:

newConfiguration - The new configuration instance which will use the returned converter

Returns:

A new instance of the same converter, or this

Throws:

InvalidConfigurationException - If applying the new configuration fails