appc-common/src/main/java/org/openecomp/appc/configuration/package.html

   1 <!--
   2   ============LICENSE_START=======================================================
   3   ONAP : APPC
   4   ================================================================================
   5   Copyright (C) 2017 AT&T Intellectual Property. All rights reserved.
   6   ================================================================================
   7   Copyright (C) 2017 Amdocs
   8   =============================================================================
   9   Licensed under the Apache License, Version 2.0 (the "License");
  10   you may not use this file except in compliance with the License.
  11   You may obtain a copy of the License at
  12
  13        http://www.apache.org/licenses/LICENSE-2.0
  14
  15   Unless required by applicable law or agreed to in writing, software
  16   distributed under the License is distributed on an "AS IS" BASIS,
  17   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  18   See the License for the specific language governing permissions and
  19   limitations under the License.
  20
  21   ECOMP is a trademark and service mark of AT&T Intellectual Property.
  22   ============LICENSE_END=========================================================
  23   -->
  24
  25 <html>
  26 <head>
  27 <title>Configuration</title>
  28 </head>
  29
  30 <body>
  31   <p style="margin-left: 30.0px;">
  32     CDP Configuration support is provided by a common framework to load
  33     and manage configuration properties from multiple sources. The basic
  34     concept is to load a set of default properties from a known resource
  35     file located on the class path, and then override these defaults
  36     with optional settings that can be provided by a user through either
  37     additional property files or via the command line (as VM arguments).
  38     The loading of defaults from a resource property file (named <strong>com/att/cdp/default.properties</strong>)
  39     ensures that values are defined for properties the application needs
  40     in order to operate.
  41   </p>
  42   <p style="margin-left: 30.0px;">
  43     One of these default values that can be set is the name of the
  44     property file that allows the user to supply settings, as well as
  45     the path where the file can be found. In general, the default name
  46     of the property file will be &quot;<strong>cdp.properties</strong>&quot;,
  47     and the path that will be searched is &quot;<strong>${user.home};etc;../etc</strong>&quot;.
  48     However, these values can be changed through the use of the
  49     default.properties resource file. The property that specifies the
  50     property file name is named <strong>com.att.cdp.bootstrap.file</strong>,
  51     while the property named <strong>com.att.cdp.bootstrap.path</strong>
  52     specifies the search path.
  53   </p>
  54   <p style="margin-left: 30.0px;">
  55     After the default.properties are loaded, but prior to searching for
  56     the application configuration file, the configuration factory checks
  57     for properties <strong>com.att.cdp.bootstrap.path</strong> and <strong>com.att.cdp.bootstrap.file
  58     </strong>in the System properties object (meaning they were set by the
  59     command line). If these values are defined in the system properties
  60     object, they are used. If not, these values are obtained from the
  61     default properties just loaded. This allows the specification of
  62     either the file name or path, or both, to be overridden during start
  63     up by using command-line arguments.
  64   </p>
  65   <p style="margin-left: 30.0px;">The search path is scanned for the
  66     first occurrence of the specified property file. The first
  67     occurrence is loaded and scanning is stopped at that point. The
  68     configuration factory does not load all occurrences it finds, only
  69     the first occurrence it finds.</p>
  70   <p style="margin-left: 30.0px;">The configuration properties are
  71     loaded and processed according to a defined precedence order, such
  72     that properties defined with a higher precedence override the same
  73     property at a lower precedence. The precedence order is defined as
  74     follows:</p>
  75   <h2>Precedence Order</h2>
  76   <ol>
  77     <li>Default properties are initially loaded into the
  78       configuration. These default properties are the lowest level
  79       precedence, and will be overridden by any properties specified at
  80       higher levels. These are loaded from resources that are packaged
  81       as part of the various application components. Each component
  82       (Server, Coordinator, EPM, or CLI) may have different default
  83       properties. The default properties are loaded from a resource
  84       named <strong>com/att/cdp/default.properties</strong>. The default
  85       properties can specify the name of the application property file
  86       to be used to configure the application, as well as the path to
  87       search. Additionally, these properties can be supplied via the
  88       command line to override the default settings if needed.<br /> <br />
  89     </li>
  90     <li>The configuration factory allows for the application to
  91       supply an initial properties object to initialize the
  92       configuration. This properties object could be loaded or created
  93       in any way necessary for the application. This is totally up to
  94       the application to define, if it is needed. If no
  95       application-specific property object is supplied, this step is
  96       skipped. If a property object is supplied, it is used to replace
  97       or set any properties that may have been defined by the defaults.<br />
  98       <br />
  99     </li>
 100     <li>The configuration factory will then search for a bootstrap
 101       file on a bootstrap path. The actual bootstrap file name and path
 102       can be specified as properties on the command line, or will
 103       default to a file name of <strong>cdp.properties</strong> and a
 104       path of <strong>${user.home};etc;../etc</strong>. If desired, the
 105       user can specify the exact name of the property file to be loaded
 106       as well as the path using <strong>-Dcom.att.cdp.bootstrap.file=&lt;filename&gt;</strong>
 107       and <strong>-Dcom.att.cdp.bootstrap.path=&lt;path&gt;</strong>.
 108       These properties are set to default values by the default
 109       properties loaded in step #1 above. The first occurrence of a
 110       property file is the file loaded and used. Any other occurrences
 111       are not processed.<br /> <br />
 112     </li>
 113     <li>The System properties are then merged into the
 114       configuration. This allows the highest level of precedence,
 115       command-line VM arguments (-D<strong>name=value</strong>) to be
 116       merged into the configuration property object. These settings
 117       override all lower level settings of the same name, as well as
 118       merge all system properties into the configuration object.
 119     </li>
 120   </ol>
 121   <h2>Variables</h2>
 122   <p style="margin-left: 30.0px;">
 123     The configuration support allows for variables to be inserted into
 124     any property that is defined. Variables are named using the format <strong>${name}</strong>,
 125     where the &quot;name&quot; is the name of a property that is defined
 126     in the configuration, or a system property (such as <strong>user.home</strong>).
 127     Variables can nest, such that a variable can be replaced with
 128     another variable, which is then reevaluated to obtain the value.
 129     This allows for indirection as well as variable substitution, if
 130     needed.
 131   </p>
 132   <h2>Using the Configuration Support</h2>
 133   <p style="margin-left: 30.0px;">
 134     The configuration support was designed to be easy to use. The
 135     configuration implementation is abstracted away from the application
 136     so that it could be changed easily in the future if needed, or if we
 137     needed to load different implementations for different reasons. This
 138     means that the application always accesses the configuration through
 139     an interface, named <strong>Configuration</strong>. The
 140     implementation of that configuration interface is obtained by a
 141     static method on the <strong>ConfigurationFactory</strong> class.
 142     The configuration factory will both create the configuration if not
 143     already created on the first access, as well as return the current
 144     configuration if already created. Additionally, the
 145     ConfigurationFactory provides mechanisms to recreate the
 146     configuration after the application is initialized should the need
 147     arise to update its configuration.
 148   </p>
 149   <p style="margin-left: 30.0px;">An example of the code needed to
 150     obtain access to the configuration is:</p>
 151   <pre style="margin-left: 30.0px;">Configuration config = ConfigurationFactory.getConfiguration();</pre>
 152   <p style="margin-left: 30.0px;">Please refer to the javadoc or the
 153     source code in cdp-common for other ways that the configuration and
 154     configuration factory can be used.</p>
 155   <h2>Reloading Properties</h2>
 156   <p style="margin-left: 30.0px;">The configuration support allows
 157     for properties to be re-loaded and re-evaluated after the
 158     application is running. This is designed to allow a configuration to
 159     be refreshed should the need arise. This could allow on-demand
 160     refresh (via a command, for example), or automatically based on
 161     sensing a change in the configuration file.</p>
 162   <p style="margin-left: 30.0px;">
 163     When the <strong>ConfigurationFactory</strong> method <strong>getConfiguration(Propert</strong><strong>ies)</strong>
 164     is called, the current configuration is cleared and rebuilt using
 165     the process defined above. The supplied property object is used in
 166     step #2 of the process. While the properties are being re-built, no
 167     access to the properties are allowed. Any attempt to access
 168     properties while the re-build operation is in effect will block the
 169     caller until completed. This is accomplished using read and write
 170     shared locks.
 171   </p>
 172 </body>
 173 </html>
 174 >>>>>>> app-controller/master:appc-common/src/main/java/org/openecomp/appc/configuration/package.html