org.yarnandtail.andhow.load.std

Class StdJndiLoader

java.lang.Object

org.yarnandtail.andhow.load.BaseLoader

org.yarnandtail.andhow.load.std.StdJndiLoader

All Implemented Interfaces:

Loader, LookupLoader, StandardLoader

public class StdJndiLoader
extends BaseLoader
implements LookupLoader, StandardLoader

Attempts to look up the name of each known Property in the JNDI environment and loads the value for any that are found.

Position in Standard Loading Order, first to last

• StdFixedValueLoader
• StdMainStringArgsLoader
• StdSysPropLoader
• StdEnvVarLoader
• StdJndiLoader <-- This loader
• StdPropFileOnFilesystemLoader
• StdPropFileOnClasspathLoader

Typical Use Case

A web or service application runs in an application container such as Tomcat. Application containers provide a JNDI environment which can be used to configure applications running in their environment.

Basic Behaviors

• Pre-trims String values: No (Individual Properties may still trim values)
• Complains about unrecognized properties: No
• Complains about missing JNDI environment: No (by default)
• Default behavior: Always attempts to look up each Property in the JNDI environment
• Is case sensitive: Yes (This is one of the only loaders that is case sensitive)

Loader Details and Configuration

While most other loaders are case insensitive, the JNDI loader is case sensitive because the JNDI API is case sensitive. Also, while most other loaders consume a configuration resource (e.g. a properties file) and read all the names and values, the JNDI loader works the other way: It goes through the list of known Properties looks up each property name in the JNDI context. This because its not possible to somehow read the entire JNDI environment.
JNDI implementations vary in how they name properties, so the loader will try several common name forms, for example, the JNDI loader will attempt to look up the following JNDI names for a property named org.foo.My_Prop:

• java:comp/env/org/foo/My_Prop
• java:comp/env/org.foo.My_Prop
• java:org/foo/My_Prop
• java:org.foo.My_Prop
• org/foo/My_Prop
• org.foo.My_Prop

This list has two different styles of property names: dot separated 'AndHow style' and slash separated JNDI style. Additionally, AndHow looks for three different roots (the part that comes before the variable name): java:comp/env/ is used by Tomcat and several other application servers, java: is used by some non-container environments and at least one application server (Glassfish) uses no root at all. In all, AndHow will search for each property under six different names (2 X 3). AndHow will throw an error at startup if it finds multiple names in the JNDI context that refer to the same property.
Specifying JNDI environment variables varies by environment, but here is an example of specifying some properties in a Tomcat context.xml file:

 <Context>
 . . .
   <Environment name="org/simple/GettingStarted/COUNT_DOWN_START" value="3" type="java.lang.Integer" override="false"/>
   <Environment name="org/simple/GettingStarted/LAUNCH_CMD" value="GoGoGo!" type="java.lang.String" override="false"/>
 . . .
 </Context>
 

In the example above, Tomcat will automatically prepend java:comp/env/ to the name it associates with each value. As the example shows, JNDI values can be typed. If AndHow finds the value to already be the type it expects (e.g. an Integer), great! If AndHow finds a String and needs a different type, AndHow will do the conversion. Any other type of conversion (e.g. from a Short to an Integer) will result in an exception.
If your JNDI environment uses a non-default different root, it can be added using one of the built-in Properties for the JNDI loader. Those property values would need to be loaded prior to the JNDI loader, so using system properties, for example, would work. Here is an example of adding the custom JNDI root java:xyz/ as a system property on command line:

 java -Dorg.yarnandtail.andhow.load.std.StdJndiLoader.CONFIG.ADDED_JNDI_ROOTS=java:xyz/ -jar MyJarName.jar
 

This is a Standard Loader

Like all StandardLoader's, this loader is intended to be auto-created by AndHow. The set of standard loaders and their order can bet set via the AndHowConfiguration.setStandardLoaders() methods. Other loaders which don't implement the StandardLoader interface can be inserted into the load order via the AndHowConfiguration.insertLoaderBefore/After().

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	StdJndiLoader.CONFIG

Field Summary

Fields

Modifier and Type	Field and Description
protected static AndHowLog	log

Constructor Summary

Constructors

Constructor and Description
StdJndiLoader() There is no reason to use the constructor in production application code because AndHow creates a single instance on demand at runtime.

Method Summary

Modifier and Type	Method and Description
protected List<String>	buildJndiNames(PropertyConfigurationInternal appConfigDef, List<String> roots, Property prop) Builds a complete list of complete JNDI names to search for a parameter value.
protected List<String>	buildJndiRoots(ValidatedValues values) Combines the values of STANDARD_JNDI_ROOTS and ADDED_JNDI_ROOTS into one list of jndi root contexts to search.
protected LoaderValues	doLoad(PropertyConfigurationInternal appConfigDef, Context ctx, ValidatedValuesWithContext existingValues) The actual loading, called only when there is a non-null Jndi Context.
Class<?>	getClassConfig() Returns a PropertyGroup used to globally configure a class of Loader.
SamplePrinter	getConfigSamplePrinter() Returns a ConfigSamplePrinter, which can be used to print a configuration sample for this Loader.
String	getLoaderDialect() The type dialect of the loader.
String	getLoaderType() The type of the loader, such as JNDI, PropertyFile, SystemProperty, etc..
String	getSpecificLoadDescription() For this particular load, where was info loaded from? This may vary from run to run based on config params.
boolean	isFailedEnvironmentAProblem() If true, then a failure to initiate or connect to the needed environment or external system will result in a failure and it will register a 'Propblem' during load which will cause application initiation to stop.
boolean	isFlaggable() Returns true if this loader supports FlaggableType's.
boolean	isTrimmingRequiredForStringValues() If true, values for string properties are trimmed by the Trimmer of the property they are associated with.
LoaderValues	load(PropertyConfigurationInternal appConfigDef, LoaderEnvironment environment, ValidatedValuesWithContext existingValues) Builds up a list of LoaderValues by loading property values from a configuration source.
void	setFailedEnvironmentAProblem(boolean isAProblem) If true, failing to initialize the environment needed to lookup values is considered a problem/error.
protected List<String>	split(String rootStr) Spits a comma separate list of JNDI roots into individual root strings.

Methods inherited from class org.yarnandtail.andhow.load.BaseLoader

attemptToAdd, attemptToAdd, attemptToAdd, attemptToAddIfNotDuplicate, createValue, findDuplicateProperty, getInstanceConfig, mapNametoProperty, releaseResources

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.Loader

getInstanceConfig, releaseResources

Field Detail

log

protected static AndHowLog log

Constructor Detail

StdJndiLoader

public StdJndiLoader()

There is no reason to use the constructor in production application code because AndHow creates a single instance on demand at runtime.

Method Detail

load

public LoaderValues load(PropertyConfigurationInternal appConfigDef,
                         LoaderEnvironment environment,
                         ValidatedValuesWithContext existingValues)

Description copied from interface: Loader

Builds up a list of LoaderValues by loading property values from a configuration source.

Loaders find and load values and associate them with the correct Property. If there is a problem while doing that, they register one or more LoaderProblems in the returned LoaderValues.

Validation of Property values is not Loader's responsibility and will be handled outside this method.

Specified by:

load in interface Loader

Parameters:

appConfigDef - The definition of all known Properties and naming metadata.

environment - The environment (System Props, Env vars, fixed values) as known to the Loader.

existingValues - The values already set by prior loaders, which may configure the behavior of this loader.

Returns:

The Property values loaded by this loader and/or the problems discovered while attempting to load those Property values.

doLoad

protected LoaderValues doLoad(PropertyConfigurationInternal appConfigDef,
                              Context ctx,
                              ValidatedValuesWithContext existingValues)

The actual loading, called only when there is a non-null Jndi Context.

Parameters:

appConfigDef - The definition of all known Properties and naming metadata.

ctx - The non-null Jndi Context

existingValues - The values already set by prior loaders, which may configure the behavior of this loader.

Returns:

The Property values loaded by this loader and/or the problems discovered while attempting to load those Property values.

isTrimmingRequiredForStringValues

public boolean isTrimmingRequiredForStringValues()

Description copied from interface: Loader

If true, values for string properties are trimmed by the Trimmer of the property they are associated with. If false, no trimming is done. Non-String type property values (like Integer or Date type values) are not affected by this. Loaders that read from text files need to trim values to separate white space and carriage returns from the value. Loaders that read from more tightly defined sources, like reading properties from java.lang.System.getProperties(), can assume that trimming has already happened.

Specified by:

isTrimmingRequiredForStringValues in interface Loader

Returns:

isFlaggable

public boolean isFlaggable()

Description copied from interface: Loader

Returns true if this loader supports FlaggableType's.

Loaders that support FlaggableType give special 'is present' meaning to a property being present without a value, similar to a 'nix command line flag. If a Loader supports flags, it should call FlaggableType.parseFlag(String) instead of ValueType.parse(String) when a Property's ValueType is a FlaggableType. See FlagProp for an example type.

Note: Returning true from this method is only potentially applicable to Loaders that parse strings. Loaders that directly load from rich values do not parse, so the loader logic would ignore the value here.

Examples:
Loading a non-null value from the properties file entry 'name = ' would be unexpected, so a properties file Loader should return 'false' here.
However, a command line loader would be expected to support flags, so should return 'true'.

Specified by:

isFlaggable in interface Loader

Returns:

true if this loader support 'nix style flag semantics for FlaggableType Properties.

getSpecificLoadDescription

public String getSpecificLoadDescription()

Description copied from interface: Loader

For this particular load, where was info loaded from? This may vary from run to run based on config params. For instance, The PropFileLoader will look multiple places to find a properties file. This method should return the actual location it was found. Assume the text is prefixed with "This loader loaded from: ". An example would be "/home/user/config/my-props.properties" No ending punctuation should be used.

Specified by:

getSpecificLoadDescription in interface Loader

Returns:

getClassConfig

public Class<?> getClassConfig()

Description copied from interface: Loader

Returns a PropertyGroup used to globally configure a class of Loader. For loaders that are intended to be single instance and thus have a single set of configuration properties, this method allows them to report their configuration PropertyGroup so it can be included in the list of registered groups. Examples of such loaders would be as system wide naming services like JNDI or a JNDI derivative (like LDAP via JNDI). The Group returned from this method will be registered and included in generated sample config files. Loader classes should provide default Property values so they work w/o configuration if possible. For configuration properties that should vary between instances of the same loader class, the loader class should accept Properties in its constructor. Those properties should then be returned by getInstanceConfig().

Specified by:

getClassConfig in interface Loader

Overrides:

getClassConfig in class BaseLoader

Returns:

A PropertyGroup that defines configuration for this class, or null if there is none.

getConfigSamplePrinter

public SamplePrinter getConfigSamplePrinter()

Description copied from interface: Loader

Returns a ConfigSamplePrinter, which can be used to print a configuration sample for this Loader. This method may return null if there is no sample printer for this loader.

Specified by:

getConfigSamplePrinter in interface Loader

Overrides:

getConfigSamplePrinter in class BaseLoader

Returns:

buildJndiRoots

protected List<String> buildJndiRoots(ValidatedValues values)

Combines the values of STANDARD_JNDI_ROOTS and ADDED_JNDI_ROOTS into one list of jndi root contexts to search. Expected values might look like: java: or java:/comp/env/

Parameters:

values - The configuration state.

Returns:

Never null and never non-empty.

buildJndiNames

protected List<String> buildJndiNames(PropertyConfigurationInternal appConfigDef,
                                      List<String> roots,
                                      Property prop)

Builds a complete list of complete JNDI names to search for a parameter value.

Parameters:

appConfigDef -

roots -

prop -

Returns:

An ordered list of jndi names, with (hopefully) the most likely names first.

split

protected List<String> split(String rootStr)

Spits a comma separate list of JNDI roots into individual root strings. Use double quotes to indicate and preserve and empty or white space string.

Parameters:

rootStr -

Returns:

A list of JNDI root strings

getLoaderType

public String getLoaderType()

Description copied from interface: Loader

The type of the loader, such as JNDI, PropertyFile, SystemProperty, etc.. The actual return value is arbitrary, but should be consistent between loaders of the same type. The values returned by getLoaderType and getLoaderDialect are used to removed duplicate loader types when printing sample files. If two loader instances are of the same type and dialect, only one will print the sample file.

Specified by:

getLoaderType in interface Loader

Returns:

Must never returns null.

getLoaderDialect

public String getLoaderDialect()

Description copied from interface: Loader

The type dialect of the loader. For property files, this might be either KeyValuePair or xml for example. The actual return value is arbitrary, but should be consistent between loaders of the same type and dialect. The values returned by getLoaderType and getLoaderDialect are used to removed duplicate loader types when printing sample files. If two loader instances are of the same type and dialect, only one will print the sample file.

Specified by:

getLoaderDialect in interface Loader

Returns:

May return null if there is no meaningful dialect for this type.

setFailedEnvironmentAProblem

public void setFailedEnvironmentAProblem(boolean isAProblem)

Description copied from interface: LookupLoader

If true, failing to initialize the environment needed to lookup values is considered a problem/error.

Specified by:

setFailedEnvironmentAProblem in interface LookupLoader

isFailedEnvironmentAProblem

public boolean isFailedEnvironmentAProblem()

Description copied from interface: LookupLoader

If true, then a failure to initiate or connect to the needed environment or external system will result in a failure and it will register a 'Propblem' during load which will cause application initiation to stop.

Specified by:

isFailedEnvironmentAProblem in interface LookupLoader

Returns: