--- /dev/null
+<!--
+ ============LICENSE_START=======================================================
+ ONAP : APPC
+ ================================================================================
+ Copyright (C) 2017 AT&T Intellectual Property. All rights reserved.
+ ================================================================================
+ Copyright (C) 2017 Amdocs
+ =============================================================================
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+ ECOMP is a trademark and service mark of AT&T Intellectual Property.
+ ============LICENSE_END=========================================================
+ -->
+
+<html>
+<head>
+<title>Configuration</title>
+</head>
+
+<body>
+ <p style="margin-left: 30.0px;">
+ CDP Configuration support is provided by a common framework to load
+ and manage configuration properties from multiple sources. The basic
+ concept is to load a set of default properties from a known resource
+ file located on the class path, and then override these defaults
+ with optional settings that can be provided by a user through either
+ additional property files or via the command line (as VM arguments).
+ The loading of defaults from a resource property file (named <strong>com/att/cdp/default.properties</strong>)
+ ensures that values are defined for properties the application needs
+ in order to operate.
+ </p>
+ <p style="margin-left: 30.0px;">
+ One of these default values that can be set is the name of the
+ property file that allows the user to supply settings, as well as
+ the path where the file can be found. In general, the default name
+ of the property file will be "<strong>cdp.properties</strong>",
+ and the path that will be searched is "<strong>${user.home};etc;../etc</strong>".
+ However, these values can be changed through the use of the
+ default.properties resource file. The property that specifies the
+ property file name is named <strong>com.att.cdp.bootstrap.file</strong>,
+ while the property named <strong>com.att.cdp.bootstrap.path</strong>
+ specifies the search path.
+ </p>
+ <p style="margin-left: 30.0px;">
+ After the default.properties are loaded, but prior to searching for
+ the application configuration file, the configuration factory checks
+ for properties <strong>com.att.cdp.bootstrap.path</strong> and <strong>com.att.cdp.bootstrap.file
+ </strong>in the System properties object (meaning they were set by the
+ command line). If these values are defined in the system properties
+ object, they are used. If not, these values are obtained from the
+ default properties just loaded. This allows the specification of
+ either the file name or path, or both, to be overridden during start
+ up by using command-line arguments.
+ </p>
+ <p style="margin-left: 30.0px;">The search path is scanned for the
+ first occurrence of the specified property file. The first
+ occurrence is loaded and scanning is stopped at that point. The
+ configuration factory does not load all occurrences it finds, only
+ the first occurrence it finds.</p>
+ <p style="margin-left: 30.0px;">The configuration properties are
+ loaded and processed according to a defined precedence order, such
+ that properties defined with a higher precedence override the same
+ property at a lower precedence. The precedence order is defined as
+ follows:</p>
+ <h2>Precedence Order</h2>
+ <ol>
+ <li>Default properties are initially loaded into the
+ configuration. These default properties are the lowest level
+ precedence, and will be overridden by any properties specified at
+ higher levels. These are loaded from resources that are packaged
+ as part of the various application components. Each component
+ (Server, Coordinator, EPM, or CLI) may have different default
+ properties. The default properties are loaded from a resource
+ named <strong>com/att/cdp/default.properties</strong>. The default
+ properties can specify the name of the application property file
+ to be used to configure the application, as well as the path to
+ search. Additionally, these properties can be supplied via the
+ command line to override the default settings if needed.<br /> <br />
+ </li>
+ <li>The configuration factory allows for the application to
+ supply an initial properties object to initialize the
+ configuration. This properties object could be loaded or created
+ in any way necessary for the application. This is totally up to
+ the application to define, if it is needed. If no
+ application-specific property object is supplied, this step is
+ skipped. If a property object is supplied, it is used to replace
+ or set any properties that may have been defined by the defaults.<br />
+ <br />
+ </li>
+ <li>The configuration factory will then search for a bootstrap
+ file on a bootstrap path. The actual bootstrap file name and path
+ can be specified as properties on the command line, or will
+ default to a file name of <strong>cdp.properties</strong> and a
+ path of <strong>${user.home};etc;../etc</strong>. If desired, the
+ user can specify the exact name of the property file to be loaded
+ as well as the path using <strong>-Dcom.att.cdp.bootstrap.file=<filename></strong>
+ and <strong>-Dcom.att.cdp.bootstrap.path=<path></strong>.
+ These properties are set to default values by the default
+ properties loaded in step #1 above. The first occurrence of a
+ property file is the file loaded and used. Any other occurrences
+ are not processed.<br /> <br />
+ </li>
+ <li>The System properties are then merged into the
+ configuration. This allows the highest level of precedence,
+ command-line VM arguments (-D<strong>name=value</strong>) to be
+ merged into the configuration property object. These settings
+ override all lower level settings of the same name, as well as
+ merge all system properties into the configuration object.
+ </li>
+ </ol>
+ <h2>Variables</h2>
+ <p style="margin-left: 30.0px;">
+ The configuration support allows for variables to be inserted into
+ any property that is defined. Variables are named using the format <strong>${name}</strong>,
+ where the "name" is the name of a property that is defined
+ in the configuration, or a system property (such as <strong>user.home</strong>).
+ Variables can nest, such that a variable can be replaced with
+ another variable, which is then reevaluated to obtain the value.
+ This allows for indirection as well as variable substitution, if
+ needed.
+ </p>
+ <h2>Using the Configuration Support</h2>
+ <p style="margin-left: 30.0px;">
+ The configuration support was designed to be easy to use. The
+ configuration implementation is abstracted away from the application
+ so that it could be changed easily in the future if needed, or if we
+ needed to load different implementations for different reasons. This
+ means that the application always accesses the configuration through
+ an interface, named <strong>Configuration</strong>. The
+ implementation of that configuration interface is obtained by a
+ static method on the <strong>ConfigurationFactory</strong> class.
+ The configuration factory will both create the configuration if not
+ already created on the first access, as well as return the current
+ configuration if already created. Additionally, the
+ ConfigurationFactory provides mechanisms to recreate the
+ configuration after the application is initialized should the need
+ arise to update its configuration.
+ </p>
+ <p style="margin-left: 30.0px;">An example of the code needed to
+ obtain access to the configuration is:</p>
+ <pre style="margin-left: 30.0px;">Configuration config = ConfigurationFactory.getConfiguration();</pre>
+ <p style="margin-left: 30.0px;">Please refer to the javadoc or the
+ source code in cdp-common for other ways that the configuration and
+ configuration factory can be used.</p>
+ <h2>Reloading Properties</h2>
+ <p style="margin-left: 30.0px;">The configuration support allows
+ for properties to be re-loaded and re-evaluated after the
+ application is running. This is designed to allow a configuration to
+ be refreshed should the need arise. This could allow on-demand
+ refresh (via a command, for example), or automatically based on
+ sensing a change in the configuration file.</p>
+ <p style="margin-left: 30.0px;">
+ When the <strong>ConfigurationFactory</strong> method <strong>getConfiguration(Propert</strong><strong>ies)</strong>
+ is called, the current configuration is cleared and rebuilt using
+ the process defined above. The supplied property object is used in
+ step #2 of the process. While the properties are being re-built, no
+ access to the properties are allowed. Any attempt to access
+ properties while the re-build operation is in effect will block the
+ caller until completed. This is accomplished using read and write
+ shared locks.
+ </p>
+</body>
+</html>
+>>>>>>> app-controller/master:appc-common/src/main/java/org/onap/appc/configuration/package.html
Code Review / appc.git / blobdiff