com.isomorphic.base

## Class Config

- java.lang.Object
- - org.apache.commons.collections4.map.AbstractIterableMap
  - - com.isomorphic.collections.DataTypeMap
    - - com.isomorphic.base.Config

- All Implemented Interfaces:
    java.util.Map, org.apache.commons.collections4.Get, org.apache.commons.collections4.IterableGet, org.apache.commons.collections4.IterableMap, org.apache.commons.collections4.Put

      public class Config
      extends DataTypeMap

  This class provides config parameters to all the Java classes in the SmartClient Framework by reading a series of .properties files including server.properties.

  If running in a servlets environment, you must use the "Init" servlet and use <load-on-startup> to ensure it initializes before any calls are made to this class.

  Then the Config class can be used to read settings as follows: ``

       Config config = Config.getGlobal();
       String propertyValue = (String)config.getProperty("propertyName");

  If running outside of a servlet environment, the following call should be made from the startup thread of the application before any Config APIs are called:

  ``

       Config.initGlobalConfig();

- - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static Config` | `getGlobal()` Returns the global Config object, initializing it if it has not yet been set up.
    `static Config` | `getGlobal(boolean initIfNull)` Returns the global Config object, optionally initializing it if it has not yet been set up.
    `static java.lang.Object` | `getProperty(java.lang.String propertyName)` Returns a property extracted from the SmartClient global configuration file, server.properties.
    `static Config` | `initGlobalConfig()` Initializes the global Config using the default Isomorphic ConfigLoader and ConfigParser, which read `.properties` files with variable interpolation.
    `java.lang.Object` | `put(java.lang.Object key, java.lang.Object value)` Programmatically inject a value into the global config.
    `void` | `putAll(java.util.Map map)` Programmatically inject a set of values in a Map into the global config.

- - ### Method Detail

    - #### getGlobal

          public static Config getGlobal(boolean initIfNull)

      Returns the global Config object, optionally initializing it if it has not yet been set up.

      In a servlet environment, the Init servlet handles initialization automatically. In a non-servlet environment, call `Config.initGlobalConfig()` from the startup thread before calling this method.

      Parameters:
        `initIfNull` - if true, automatically calls `Config.initGlobalConfig()` when the global config has not yet been initialized
      Returns:
        the global Config instance, or null if `initIfNull` is false and the config has not been initialized

    - #### getGlobal

          public static Config getGlobal()

      Returns the global Config object, initializing it if it has not yet been set up. Equivalent to calling `getGlobal(true)`.

      See the `class overview` for usage examples.

      Returns:
        the global Config instance

    - #### getProperty

          public static java.lang.Object getProperty(java.lang.String propertyName)

      Returns a property extracted from the SmartClient global configuration file, server.properties. Note that the Init servlet must be used if you wish to make use of this API.
      Parameters:
        `propertyName` - The name of the property to retrieve
      Returns:
        The property value, or null if it was not found

    - #### initGlobalConfig

          public static Config initGlobalConfig()
                                         throws java.lang.Exception

      Initializes the global Config using the default Isomorphic ConfigLoader and ConfigParser, which read `.properties` files with variable interpolation.

      In a servlet environment, the Init servlet calls this automatically. In a non-servlet environment, call this from the startup thread before any Config APIs are used, as shown in the `class overview`.

      Returns:
        the initialized global Config instance
      Throws:
        `java.lang.Exception` - if the configuration cannot be loaded

    - #### put

          public java.lang.Object put(java.lang.Object key,
                                      java.lang.Object value)

      Programmatically inject a value into the global config. Note, the timing of this is key. Your programmatic overrides or additions must take place after the core config has loaded from the framework's various `.properties` files, but before anything else in the system.

      The simplest way to achieve this is to have your programmatic changes to config invoked from a servlet which is configured in `web.xml` with a `load-on-startup` parameter of 2, like this:

           <servlet>
               <servlet-name>MyConfigChanges</servlet-name>
               <servlet-class>com.company.servlet.MyConfigChanges</servlet-class>
               <load-on-startup>2</load-on-startup>
           </servlet>

      The setting of "2" is important, because your code needs to run after the SmartClient `Init` servlet, but before anything else.

      If running outside of a servlet environment, you should invoke your config override code from the startup thread of the application, after the call to `Config.initGlobalConfig()` described in the class overview docs, but before any Config APIs are called.

      Overrides:
        `put` in class `DataTypeMap`
      Parameters:
        `key` - The key of the property to set
        `value` - The new value for the property
      Returns:
        The property's old value, or null if it was not previously set

    - #### putAll

          public void putAll(java.util.Map map)

      Programmatically inject a set of values in a Map into the global config. See `Config.put(Object, Object)` for important information about timing issues associated with this API.
      Overrides:
        `putAll` in class `DataTypeMap`
      Parameters:
        `map` - A Map of property values to apply to the config