AndHow (AndHow Annotation Processor 1.5.0 API)

java.lang.Object
- org.yarnandtail.andhow.AndHow

All Implemented Interfaces:

PropertyConfiguration, ValidatedValues
```
public class AndHow
extends Object
implements PropertyConfiguration, ValidatedValues
```
Central AndHow singleton class. This class is not directly constructed. The primary way to configure an instance is indirectly by creating a subclass of org.yarnandtail.andhow.AndHowInit. At startup, AndHow discovers your AndHowInit implementation and uses it to configure a single instance. For cases where the application needs to accept command line arguments or augment the configuration with fixed values, the configuration can have those parameters added like this:
```
 AndHow.findConfig().setCmdLineArgs(myCmdLineArgs).build();
 
```
findConfig() finds the AndHowConfiguration that would be used if AndHow.instance() was called. build() then causes the AndHow instance to be built with that modified configuration. The code above (or any method of AndHow initiation) can only be executed once during the life of the application.

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class AndHow.Initialization
Encapsulate when and where AndHow was initialized.

Nested Classes
Modifier and Type	Class and Description
`static class`	`AndHow.Initialization` Encapsulate when and where AndHow was initialized.

Field Summary

Fields
Modifier and Type Field and Description

static String ANDHOW_INLINE_NAME

static String ANDHOW_NAME

static String ANDHOW_TAG_LINE

static String ANDHOW_URL

Fields
Modifier and Type	Field and Description
`static String`	`ANDHOW_INLINE_NAME`
`static String`	`ANDHOW_NAME`
`static String`	`ANDHOW_TAG_LINE`
`static String`	`ANDHOW_URL`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Stream<PropertyExport>`	`export(Class<?>... exportClasses)` Export Property's to a collection for use with frameworks that take configuration as key-value maps or similar.
`static AndHowConfiguration<? extends AndHowConfiguration>`	`findConfig()` Prior to AndHow initialization, this method finds the configuration that will be used.
`List<EffectiveName>`	`getAliases(Property<?> property)` All the effective 'in' & 'out' aliases for this property, not including the canonical name.
`String`	`getCanonicalName(Property<?> prop)` The canonical name of a `Property`.
`<T> T`	`getExplicitValue(Property<T> prop)` The value found and loaded for this value by a Loader.
`static StackTraceElement[]`	`getInitializationTrace()` Get the stacktrace of where AndHow was initialized.
`NamingStrategy`	`getNamingStrategy()` Defines how names are created for Properties.
`<T> T`	`getValue(Property<T> prop)` The effective value, similar to Property.getValue, but specifically for the context of this ValueMap.
`static AndHow`	`instance()` Returns the singleton instance of AndHow, initializing a new instance if one doesn't exist.
`boolean`	`isExplicitlySet(Property<?> prop)` True if the Property's value is explicitly set to a non-null value via one of the loaders.
`static boolean`	`isInitialized()` Determine if AndHow is initialized or not w/out forcing AndHow to load.
`static void`	`setConfig(AndHowConfiguration<? extends AndHowConfiguration> config)` Prior to AndHow initialization, this method explicitly sets the configuration to be used.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - ANDHOW_INLINE_NAME
```
public static final String ANDHOW_INLINE_NAME
```
    See Also:
    
    Constant Field Values
  - ANDHOW_NAME
```
public static final String ANDHOW_NAME
```
    See Also:
    
    Constant Field Values
  - ANDHOW_URL
```
public static final String ANDHOW_URL
```
    See Also:
    
    Constant Field Values
  - ANDHOW_TAG_LINE
```
public static final String ANDHOW_TAG_LINE
```
    See Also:
    
    Constant Field Values
- Method Detail
  - findConfig
```
public static AndHowConfiguration<? extends AndHowConfiguration> findConfig()
                                                                     throws AppFatalException
```
    Prior to AndHow initialization, this method finds the configuration that will be used. On the first call to this method, a new AndHowConfiguration instance will be created. Later calls to this method prior to AndHow initialization will return that same instance. After AndHow is initialized this method will throw a fatal exception, since no modification to the configuration can be made after AndHow has initialized.
    The new AndHowConfiguration is created in one of two ways:
    1. If there is a class implementing the AndHowInit interface on the classpath, it will be discovered and that class' AndHowInit.getConfiguration() method will be called to construct the instance. This is an easy configuration point to configure AndHow for production or test.
    2. Otherwise, a default implementation of AndHowConfiguration is created and returned.
    This method provides a way to 'grab' the configuration before AndHow initialization and make additions or customizations. Common reasons for doing this would be:
    - In the main(String[] args) method to add the command line arguments to AndHow (see code example below)
    - To provide different configuration or modify the list Loaders based on the entry point of the application.
    - In a test class to add 'fixed' configuration values needed for a specific test (See test examples in the simulated app tests)
    Example usage in a main method:
```
 public static void main(String[] args) {
   AndHow.findConfig().setCmdLineArgs(myCmdLineArgs);
   //Do other stuff - AndHow initializes as soon as the first Property access happens.
   //...
   //AndHow.instance();	//Forces initialization, but isn't required
 }
 
```
    In the above example, AndHow will initialize itself as soon as the first Property value is accessed, e.g. MyProperty.getValue(). In nearly all cases this is acceptable. If, however, you are worried your application has thread contention at startup or the application doesn't access property values until some later event happens, you can force initialization by calling AndHow.instance(). Initialization will force validation of all property values and will block other attempts to initialize AndHow, perhaps helping to pinpoint startup contention.
    Note: There was a behaviour change from v1.4.1 to v1.4.2: Beginning with v1.4.2, this method returns the same instance each time until initialization, then it throws a fatal exception. In v1.4.1 and earlier, a newly created instance was returned for each call. This is a large behaviour change, but its really blocking an unsafe application operation or an unexpected application 'no-op' where the caller might expect to keep working on the same configuration and actually be starting over.
    Returns:
    
    The AndHowConfiguration with continuity between calls
    
    Throws:
    
    AppFatalException - A fatal exception if called after AndHow has initialized.
  - setConfig
```
public static void setConfig(AndHowConfiguration<? extends AndHowConfiguration> config)
                      throws AppFatalException
```
    Prior to AndHow initialization, this method explicitly sets the configuration to be used. After AndHow is initialized this method will throw a fatal exception since no modification to configuration is possible after initialization.
    It is easier and safer to use findConfig(), which will a auto-discover configuration, however, during testing or some advanced use cases, it can be useful to ignore the normal configuration discovery mechanism.
    If this method is used, configuration created by AndHowInit.getConfiguration() and possibly later modified by calls to findConfig() up to this point will be replaced by the configuration set here. Later calls to findConfig() will return this new value.
    
    Parameters:
    
    config - The new configuration which must not be null.
    
    Throws:
    
    AppFatalException - If AndHow is already initialized or the passed config is null.
  - instance
```
public static AndHow instance()
                       throws AppFatalException
```
    Returns the singleton instance of AndHow, initializing a new instance if one doesn't exist. If AndHow is not yet initialized, a new instance is created by initializing AndHow using configuration found via findConfig(). AndHow initialization configures AndHow, loads Property values from all sources (such as env. vars., System Props, etc.), then validates all values.
    In production, use of this method is optional at startup. See findConfig() for an example of how to access and modify configuration, and initialize AndHow.
    
    Returns:
    
    The singleton AndHow instance - the same instance for the life of the app.
    
    Throws:
    
    AppFatalException - If AndHow is mis-configured
  - isInitialized
```
public static boolean isInitialized()
```
    Determine if AndHow is initialized or not w/out forcing AndHow to load.
    
    Returns:
  - getInitializationTrace
```
public static StackTraceElement[] getInitializationTrace()
```
    Get the stacktrace of where AndHow was initialized. This can be useful for debugging InitiationLoopException errors or errors caused by trying to initialize AndHow when it is already initialized. This stacktrace identifies the point in code that caused the initial AndHow initialization, prior to the error. The reported exception will point to the place where AndHow entered a loop during its construction or application code attempted to re-initialize AndHow.
    
    Returns:
    
    A stacktrace if it is available (some JVMs may not provide one) or an empty stacktrace array if it is not available or AndHow is not yet initialized.
  - export
```
public Stream<PropertyExport> export(Class<?>... exportClasses)
                              throws IllegalAccessException
```
    Export Property's to a collection for use with frameworks that take configuration as key-value maps or similar.
    Simple example usage that results in a Map<String, String> of names and values:
```
 //UI_CONFIG & SERVICE_CONFIG contain AndHow Properties
 Map<String, String> export =
   AndHow.instance().export(UI_CONFIG.class, SERVICE_CONFIG.class)
   .collect(ExportCollector.stringMap());
 
```
    Property export is not allowed by default and is enabled by annotating a class containing Properties with ManualExportAllowed.
    ExportCollector can collect to Maps or Properties, as well as exporting String or Object values. Many variations are possible: e.g. export object values (instead of Strings) and prepend 'aaa_' to each export name:
```
 Map<String, Object> export =
  AndHow.instance().export(SERVICE_CONFIG.class)
   .map(p -> p.mapNames(
     p.getExportNames().stream().map(n -> "aaa_" + n).collect(Collectors.toList())
   ))
   .collect(ExportCollector.objectMap());
 
```
    export() returns a Stream of PropertyExport's, one PropertyExport per Property. Each PropertyExport has a list of export names for the Property. Names can include the Property's canonical name and any 'out' aliases for the Property. Which names are included is controlled by options on the ManualExportAllowed annotation.
    The export names and the values can be remapped via PropertyExport 'map' methods (see 'mapNames' in example above). See PropertyExport for more mapping examples.
    The ExportCollector creates an entry in the final collection for each name, mapping it to the Property's Object or String value. Thus, the ExportCollector 'flattens' PropertyExports by expanding the name list and collects them into the final collection.
    Exports via the export() method are 'Manual' - the app must invoke them. There are also 'Auto' exports - See the GroupExport annotation.
    Parameters:
    
    exportClasses - The classes to have their contained Properties exported.
    
    Returns:
    
    A Stream of PropertyExport which can be converted into a collection of key-value pairs via one of the ExportCollectors.
    
    Throws:
    
    IllegalAccessException - If any of the exported classes are not annotated to allow export.
  - isExplicitlySet
```
public boolean isExplicitlySet(Property<?> prop)
```
    Description copied from interface: ValidatedValues
    
    True if the Property's value is explicitly set to a non-null value via one of the loaders.
    
    Specified by:
    
    isExplicitlySet in interface ValidatedValues
    
    Parameters:
    
    prop - The property to check
    
    Returns:
    
    True if this value is explicitly set.
  - getExplicitValue
```
public <T> T getExplicitValue(Property<T> prop)
```
    Description copied from interface: ValidatedValues
    
    The value found and loaded for this value by a Loader. If no non-null value was found by a loader for this property, null is returned.
    
    Specified by:
    
    getExplicitValue in interface ValidatedValues
    
    Type Parameters:
    
    T - The return type of the Property.
    
    Parameters:
    
    prop - The property to get the value for
    
    Returns:
    
    The value, if explicitly set, or null if not explicity set.
  - getValue
```
public <T> T getValue(Property<T> prop)
```
    Description copied from interface: ValidatedValues
    
    The effective value, similar to Property.getValue, but specifically for the context of this ValueMap. 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 ValidatedValues
    
    Type Parameters:
    
    T - The return type of the Property.
    
    Parameters:
    
    prop - The property to get the value for.
    
    Returns:
    
    The explicit value or, if no explicit, the default value. Otherwise null.
  - getAliases
```
public List<EffectiveName> getAliases(Property<?> property)
```
    Description copied from interface: PropertyConfiguration
    All the effective 'in' & 'out' aliases for this property, not including the canonical name.
    The returned aliases may differ from the original requested aliases in two ways:
    - NamingStrategy may modify 'In' aliases, e.g. convert them to uppercase for case-insensitive matching. This method returns the modified 'In' aliases.
    - Aliases may be coalesced if: If an 'In' alias matches an 'Out' alias, a single 'InAndOut' alias may be returned.
    Specified by:
    
    getAliases in interface PropertyConfiguration
    
    Parameters:
    
    property - The property to fetch naming information for
    
    Returns:
    
    A non-null, non-modifiable list of alias EffectiveNames for this Property.
    
    See Also:
    
    Property.getInAliases(), Property.getOutAliases(), Property.getRequestedAliases()
  - getCanonicalName
```
public String getCanonicalName(Property<?> prop)
```
    Description copied from interface: PropertyConfiguration
    
    The canonical name of a Property.
    Canonical Property names are the full Java classname of the class containing the Property, plus the Property name, e.g. org.acme.myapp.MyClass.MyProperty. Properties contained in inner classes and interfaces continue the same naming structure, e.g. org.acme.myapp.MyClass.MyInnerClass.MyInnerInterface.MyProperty.
    
    Specified by:
    
    getCanonicalName in interface PropertyConfiguration
    
    Parameters:
    
    prop - The Property to get the canonical name for.
    
    Returns:
    
    The canonical name of the Property.
  - getNamingStrategy
```
public NamingStrategy getNamingStrategy()
```
    Description copied from interface: PropertyConfiguration
    
    Defines how names are created for Properties.
    
    Specified by:
    
    getNamingStrategy in interface PropertyConfiguration
    
    Returns:
    
    The NamingStrategy in use.

Class AndHow

Nested Class Summary

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

ANDHOW_INLINE_NAME

ANDHOW_NAME

ANDHOW_URL

ANDHOW_TAG_LINE

Method Detail

findConfig

setConfig

instance

isInitialized

getInitializationTrace

export

isExplicitlySet

getExplicitValue

getValue

getAliases

getCanonicalName

getNamingStrategy