org.yarnandtail.andhow.property

Class FlagProp

java.lang.Object

org.yarnandtail.andhow.property.PropertyBase<Boolean>

org.yarnandtail.andhow.property.FlagProp

All Implemented Interfaces:

Property<Boolean>

public class FlagProp
extends PropertyBase<Boolean>

A True/False switch that is never null and behaves similarly to a 'nix cmd line switch when used on command line.

Use a FlagProp when you want a configuration parameter that is always true or false, such as toggling a feature on or off. It can also be used when a configuration parameter should work like a 'nix command line switch, which is 'on' just by being present, e.g.:
java MyClass enableAwesomeMode
If enableAwesomeMode is the name or alias of a FlagProp, that FlagProp will set True simply by having its name as an argument. You can also explicitly set its value, e.g. enableAwesomeMode=true or enableAwesomeMode=false. When set to a value, a FlagProp behaves exactly like a BolProp.

Note: A FlagProp has it's special present == true behavior only for the command line loader (i.e. StdMainStringArgsLoader. (see note below)

A FlagProp is similar to a BolProp, but with these differences:

• A Flag is never null - FlagProp.getValue() always return true or false. Thus, A FlagProp will never throw a RequirementProblem error during configuration because it always has a value.
• FlagProp.getDefaultValue() never returns null and defaults to false. Via the constructor or builder, it is possible to set the default to be true. In that case a loader would need to find it explicitly set to false to change its value, e.g. propertyName=false.

The technical details

If no name is found by any loader that refers to the FlagProp, it defaults to false (unless the default is set to true). If a name referring to a FlagProp is found in any loader other than the command line loader, the value is parsed and handled exactly as if it were a BolProp. If a name referring to a FlagProp is found on command line loader:

• If the argument is of the form key=value and the value contains any non-whitespace, the value is handled just as a BolProp would handle the value.
• If the value is all whitespace or there is no '=' delimiter, the presence of the key without a value sets the FlagProp to True.

NOTE: The behavior of the FlagProp changed in release 0.5.0
Prior to 0.5.0, FlagProps' special present == true behavior applied to all loaders, so a properties file that included the name of a FlagProp with no value would set it True. This non-desirable behavior was fixed for the 0.5.0 release.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	FlagProp.FlagBuilder

Constructor Summary

Constructors

Constructor and Description
FlagProp(Boolean defaultValue, String shortDesc, List<Name> aliases, PropertyType paramType, ValueType<Boolean> valueType, Trimmer trimmer, String helpText)

Method Summary

Modifier and Type	Method and Description
static FlagProp.FlagBuilder	builder() A chainable builder for this property that should terminate with build()
Boolean	getValue() Returns the effective value of this property.

Methods inherited from class org.yarnandtail.andhow.property.PropertyBase

getDefaultValue, getDescription, getExplicitValue, getHelpText, getPropertyType, getRequestedAliases, getTrimmer, getValidators, getValueType, isNonNullRequired

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.yarnandtail.andhow.api.Property

getCanonicalName, getInAliases, getOutAliases, getValueAsString, isExplicitlySet

Constructor Detail

FlagProp

public FlagProp(Boolean defaultValue,
                String shortDesc,
                List<Name> aliases,
                PropertyType paramType,
                ValueType<Boolean> valueType,
                Trimmer trimmer,
                String helpText)

Method Detail

getValue

public Boolean getValue()

Description copied from interface: Property

Returns the effective value of this property. The effective value is the explicitly configured value, or if that is null, the default value. Explicitly setting a property to null is not possible because it will just be ignored and the default used instead.

Specified by:

getValue in interface Property<Boolean>

Overrides:

getValue in class PropertyBase<Boolean>

Returns:

May be null, unless the property is marked as required.

builder

public static FlagProp.FlagBuilder builder()

A chainable builder for this property that should terminate with build()

Use as FlagProp.builder()...series of builder methods...build();

Returns:

The builder instance that can be chained