org.yarnandtail.andhow

Interface AndHowConfiguration<C extends AndHowConfiguration>

All Known Implementing Classes:

BaseConfig, StdConfig.StdConfigAbstract, StdConfig.StdConfigImpl

public interface AndHowConfiguration<C extends AndHowConfiguration>

Author:

ericeverman

Method Summary

Modifier and Type	Method and Description
<T> C	addFixedValue(Property<T> property, T value) Sets a fixed, non-configurable value for a Property.
C	addFixedValue(String name, Object value) Sets a fixed, non-configurable value for a named Property.
List<Loader>	buildLoaders()
C	classpathPropertiesNotRequired() Sets the properties file on the classpath to be optional, the default.
C	classpathPropertiesRequired() If called to set this to 'required', a classpath properties file must exist and be readable.
C	filesystemPropFileNotRequired() Sets the properties file on the filesystem to be optional, the default.
C	filesystemPropFileRequired() If called to set this to 'required', a non-null configured value for the filesystem properties file must point to an existing, readable properties file.
List<Class<? extends StandardLoader>>	getDefaultLoaderList() The default list of standard loaders, as a list of Classes that implement StandardLoader
LoaderEnvironment	getLoaderEnvironment() The environment for Loaders when they load values.
NamingStrategy	getNamingStrategy() Return the naming strategy used to form Property names, match them to values and display them.
List<GroupProxy>	getRegisteredGroups() Return a custom list of 'Groups' (classes or interfaces containing AndHow Properties) to use instead of allowing the auto-discovery to find the Groups.
C	insertLoaderAfter(Class<? extends StandardLoader> insertAfterThisLoader, Loader loaderToInsert)
C	insertLoaderBefore(Class<? extends StandardLoader> insertBeforeThisLoader, Loader loaderToInsert)
C	removeFixedValue(Property<?> property) Removes a Property value set only via addFixedValue(Property, T value) from the list of fixed values.
C	removeFixedValue(String propertyNameOrAlias) Removes a Property value set only via addFixedValue(String name, Object value) from the list of fixed values.
C	setClasspathPropFilePath(String classpathPropFilePathString) Sets the classpath path to a properties file for the StdPropFileOnClasspathLoader to read and load from.
C	setClasspathPropFilePath(StrProp classpathPropFilePathProperty) Sets the classpath path via a StrProp (a Property of String type) to a properties file for the StdPropFileOnClasspathLoader to read and load from.
C	setCmdLineArgs(String[] commandLineArgs) Sets the command line arguments, removing any previously set commandline args.
C	setFilesystemPropFilePath(StrProp filesystemPropFilePath) Sets the filesystem path via a StrProp (a Property of String type) to a properties file for the StdPropFileOnFilesystemLoader to load.
C	setStandardLoaders(Class<? extends StandardLoader>... newStandardLoaders)
C	setStandardLoaders(List<Class<? extends StandardLoader>> newStandardLoaders)

Method Detail

buildLoaders

List<Loader> buildLoaders()

getRegisteredGroups

List<GroupProxy> getRegisteredGroups()

Return a custom list of 'Groups' (classes or interfaces containing AndHow Properties) to use instead of allowing the auto-discovery to find the Groups. AndHow will use a ServiceLoader to discover all classes containing AndHow Properties in conjunction with a generated manifest of those classes created at compile time. Each class containing at least one AndHow Property is called a Group and is represented by a GroupProxy object.

If this method returns non-null, then AndHow does not use this auto-discovery mechanism and just uses the returned list of GroupProxies. This is primarily for testing, where it is useful to test on only a small set of Groups and Properties.

Returning an empty list from this method would result in AndHow initializing with no registered Groups.

Returns:

A list of GroupProxies to use instead of the auto-discovery process. May return null (and normally does) to allow the normal auto-discovery to happen.

getNamingStrategy

NamingStrategy getNamingStrategy()

Return the naming strategy used to form Property names, match them to values and display them. Currently only CaseInsensitiveNaming is implemented.

Returns:

The strategy to use. Must not be null.

setCmdLineArgs

C setCmdLineArgs(String[] commandLineArgs)

Sets the command line arguments, removing any previously set commandline args. Setting empty or null results in removing all previously set command line arguments

Parameters:

commandLineArgs -

Returns:

addFixedValue

<T> C addFixedValue(Property<T> property,
                    T value)

Sets a fixed, non-configurable value for a Property. Property values set in this way use the FixedValueLoader to load values prior to any other loader. Since the first loaded value for a Property 'wins', this effectively fixes the value and makes it non-configurable. Values specified by the two addFixedValue methods will through a DuplicatePropertyLoaderProblem if they refer to the same Property.

Type Parameters:

T - The type of Property and value

Parameters:

property - The property to set a value for

value - The value to set.

Returns:

removeFixedValue

C removeFixedValue(Property<?> property)

Removes a Property value set only via addFixedValue(Property, T value) from the list of fixed values. It is not an error to attempt to remove a property that is not in this fixed value list.

Parameters:

property - A non-null property.

Returns:

addFixedValue

C addFixedValue(String name,
                Object value)

Sets a fixed, non-configurable value for a named Property. Property values set in this way use the FixedValueLoader to load values prior to any other loader. Since the first loaded value for a Property 'wins', this effectively fixes the value and makes it non-configurable. Values specified by the two addFixedValue methods will through a DuplicatePropertyLoaderProblem if they refer to the same Property.

Parameters:

name - The canonical or alias name of Property, which is trimmed to null.

value - The Object value to set, which must match the type of the Property.

Returns:

removeFixedValue

C removeFixedValue(String propertyNameOrAlias)

Removes a Property value set only via addFixedValue(String name, Object value) from the list of fixed values. Note that to successfully remove a fixed value from this list, the name must exactly match the name used to set the property via addFixedValue(String, Object). Since Properties can have aliases, you must know the exact name to set the property. It is not an error to attempt to remove a property that is not in this fixed value list, or to attempt to remove a property value that does not exist - these are just no-ops.

Parameters:

propertyNameOrAlias - The name or alias of a property.

Returns:

setClasspathPropFilePath

C setClasspathPropFilePath(String classpathPropFilePathString)

Sets the classpath path to a properties file for the StdPropFileOnClasspathLoader to read and load from. If no path is specified via one of the two setClasspathPropFilePath methods, the default classpath of '/andhow.properties' is used.

As per Java convention, a path on the classpath can use dots or slashes to separate packages. However, if the file name itself contains dots, then the path must start with a slash and use slashes to separate packages.

Valid Examples:

• /andhow.property - The default. The file is at the root and the name contains a dot
• /org/ngo/config.props - Similar to above, but in the org.ngo package, the file name is 'config.props'
• org.ngo.props - The package is org.ngo, the file name is 'props'. There are no dots in the file name, so its OK to use dots to separate the packages

Parameters:

classpathPropFilePathString -

Returns:

setClasspathPropFilePath

C setClasspathPropFilePath(StrProp classpathPropFilePathProperty)

Sets the classpath path via a StrProp (a Property of String type) to a properties file for the StdPropFileOnClasspathLoader to read and load from. If no path is specified via one of the two setClasspathPropFilePath methods, the default classpath of '/andhow.properties' is used.

As per Java convention, a path on the classpath can use dots or slashes to separate packages. However, if the file name itself contains dots, then the path must start with a slash and use slashes to separate packages. Its common to have a '.properties' extension on the properties file, so its good practice to add a validation rule to the StrProp used here to ensure it mustStartWith("/").

Valid Examples of configured values:

• /andhow.property - The default. The file is at the root and the name contains a dot
• /org/ngo/config.props - Similar to above, but in the org.ngo package, the file name is 'config.props'
• org.ngo.props - The package is org.ngo, the file name is 'props'. There are no dots in the file name, so its OK to use dots to separate the packages

Parameters:

classpathPropFilePathProperty -

Returns:

classpathPropertiesRequired

C classpathPropertiesRequired()

If called to set this to 'required', a classpath properties file must exist and be readable. This flag is used by the StdPropFileOnClasspathLoader. Since the StdPropFileOnClasspathLoader has a default property file name, /andhow.properties, setting this to 'required' means that either that default file name or another that you configure instead must exist.

Returns:

See Also:

methods for details on using a non-default classpath properties file. A RuntimeException will be thrown if this is set to 'required' and there is no classpath properties file that can be read.
This is NOT set by default, allowing the properties file to be optional.

classpathPropertiesNotRequired

C classpathPropertiesNotRequired()

Sets the properties file on the classpath to be optional, the default.

Returns:

See Also:

classpathPropertiesRequired()

setFilesystemPropFilePath

C setFilesystemPropFilePath(StrProp filesystemPropFilePath)

Sets the filesystem path via a StrProp (a Property of String type) to a properties file for the StdPropFileOnFilesystemLoader to load. If no property is set to specify a path, or a property is set by has no value, this loader won't be used. If the property is specified but the specified file is missing, an error will be thrown based on the filesystemPropFileRequired flag. Paths should generally be absolute and correctly formed for the host environment.

Parameters:

filesystemPropFilePath -

Returns:

filesystemPropFileRequired

C filesystemPropFileRequired()

If called to set this to 'required', a non-null configured value for the filesystem properties file must point to an existing, readable properties file. This flag is used by the StdPropFileOnFilesystemLoader. A RuntimeException will be thrown if this is set to 'required' and there is a path specified which points to a file that does not exist. Configuring a filesystem path is a two step process:

• First, a StrProp Property must be specified for this configuration via the setFilesystemPropFilePath method
• Then, a value must be configured for in an any way that AndHow reads and loads values, such as environment vars, system properties, etc..

If and non-null value is configured, its doesn't point to a readable properties file, AND this required flag is set, a RuntimeException will be thrown at startup.
This is NOT set by default, allowing the properties file to be optional.

Returns:

filesystemPropFileNotRequired

C filesystemPropFileNotRequired()

Sets the properties file on the filesystem to be optional, the default.

Returns:

See Also:

setFilesystemPropFilePath(org.yarnandtail.andhow.property.StrProp)

getDefaultLoaderList

List<Class<? extends StandardLoader>> getDefaultLoaderList()

The default list of standard loaders, as a list of Classes that implement StandardLoader

The returned list is disconnected from the actual list of loaders - it is intended to be a starting point for applications that want to modify the list, then call setStandardLoaders().

Unlike other methods of this class, it does not fluently return a method to itself, so your code will need a AndHowConfiguration instance reference to use it, eg:

     
 public class MyAppInitiation implements AndHowInit {
     @Override
        public AndHowConfiguration getConfiguration() {
                        AndHowConfiguration config = AndHow.findConfig();
                         List<Class<? extends StandardLoader>> sll = config.getDefaultLoaderList();
                        ...do some rearranging of the list...

                        config.setStandardLoaders(sll) ...and go on to call other methods on config...
                }
 }
     
 

Note: AndHow version up to and including 0.4.1 had this method as a static method.

Returns:

getLoaderEnvironment

LoaderEnvironment getLoaderEnvironment()

The environment for Loaders when they load values.

Though this may be editable in the AndHowConfiguration, the instance returned here should be immutable.

Returns:

An immutable LoaderEnvironment.

setStandardLoaders

C setStandardLoaders(List<Class<? extends StandardLoader>> newStandardLoaders)

setStandardLoaders

C setStandardLoaders(Class<? extends StandardLoader>... newStandardLoaders)

insertLoaderBefore

C insertLoaderBefore(Class<? extends StandardLoader> insertBeforeThisLoader,
                     Loader loaderToInsert)

insertLoaderAfter

C insertLoaderAfter(Class<? extends StandardLoader> insertAfterThisLoader,
                    Loader loaderToInsert)