2 ============LICENSE_START=======================================================
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
13 http://www.apache.org/licenses/LICENSE-2.0
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.
21 ECOMP is a trademark and service mark of AT&T Intellectual Property.
22 ============LICENSE_END=========================================================
27 <title>Configuration</title>
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
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 "<strong>cdp.properties</strong>",
47 and the path that will be searched is "<strong>${user.home};etc;../etc</strong>".
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.
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.
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
75 <h2>Precedence Order</h2>
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 />
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 />
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=<filename></strong>
107 and <strong>-Dcom.att.cdp.bootstrap.path=<path></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 />
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.
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 "name" 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
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.
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
174 >>>>>>> app-controller/master:appc-common/src/main/java/org/openecomp/appc/configuration/package.html