1 .** vim: sw=4 ts=4 et :
3 ==================================================================================
4 Copyright (c) 2020 Nokia
5 Copyright (c) 2020 AT&T Intellectual Property.
7 Licensed under the Apache License, Version 2.0 (the "License");
8 you may not use this file except in compliance with the License.
9 You may obtain a copy of the License at
11 http://www.apache.org/licenses/LICENSE-2.0
13 Unless required by applicable law or agreed to in writing, software
14 distributed under the License is distributed on an "AS IS" BASIS,
15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 See the License for the specific language governing permissions and
17 limitations under the License.
18 ==================================================================================
23 This imbed file contains the portion of the document that describes the
24 configuration file and config notification update interface.
28 &h1(Configuration Support)
29 The C++ xAPP framework provides the xAPP with an interface to load, parse
30 and receive update notifications on the configuration.
31 The configuration, also known as the xAPP descriptor, is assumed to be a
32 file containing json with a well known structure, with some fields or
33 &ital( objects ) used by an xAPP for configuration purposes.
34 The following paragraphs describe the support that the framework provides
35 to the xAPP with respect to the configuration aspects of the descriptor.
37 &h2( The Config Object )
38 The xAPP must create an instance of the &cw(config) object in order to take
39 advantage of the support.
40 This is accomplished by using one of two constructors illustrated with code
41 samples in figure &conf_const_fig.
45 .ca start conf_const.ca
47 #include <ricxfcpp/config.hpp>
49 auto cfg = new xapp::Config( );
50 auto cfg = new xapp::Config( "/var/myapp/config.json" );
52 &export_fig(conf_const_fig)
53 &fig_cen(Creating a configuration instance.)
57 &ifroom( 1.5 : conf_const.ca )
59 The creation of the object causes the file to be found, loaded, after
60 which the xAPP can use the instance functions to access the information
63 &h2( Available Functions )
64 Once a configuration has been created the following capabilities are
70 &li Get a control value (numeric, string, or boolean)
72 &li Get the RMR port for the container with the supplied name
74 &li Set a notification callback function
76 &li Get the raw contents of the file
81 The &cw(controls) section of the xAPP descriptor is generally used to supply a
82 &ital(flat) namespace of key/value pairs which the xAPP can use for configuration.
83 These pairs are supplied by the xAPP author as a part of development, and thus
84 are specific to each xAPP.
85 The framework provides a general set of functions which allows a key to be searched
86 for in this section and returned to the caller.
87 Data is assumed to be one of three types: numeric (double), string, or boolean.
90 Two methods for each return type are supported with the more specific form
91 allowing the xAPP to supply a default value to be used should the file not
92 contain the requested field.
93 The function prototypes for these are provided in figure &config_proto1_fig.
96 .ca start conf_proto1.ca
98 bool Get_control_bool( std::string name, bool defval );
99 bool Get_control_bool( std::string name );
101 std::string Get_control_str( std::string name, std::string defval );
102 std::string Get_control_str( std::string name );
104 double Get_control_value( std::string name, double defval );
105 double Get_control_value( std::string name );
107 &export_fig(config_proto1_fig)
108 &fig_cen(The various controls section get functions.)
112 &ifroom( 1.5 : conf_proto1.ca )
115 If the more generic form of these functions is used, without a default value,
116 the return values are false, "", and 0.0 in the respective order of the prototypes
117 in figure &config_proto1_fig.
121 The &cw(messaging) section of the xAPP descriptor provides the ability to define
122 one or more RMR &ital(listen ports) that apply to the xAPP(s) started in a
124 The xAPP may read a port value (as a string) using the defined port name via
125 the &cw(Get_port) function whose prototype is illustrated in figure &get_port_fig below.
128 .ca start git_port.ca
130 std::string Get_port( std::string name );
132 &export_fig(get_port_fig)
133 &fig_cen(The get port prototype.)
137 &ifroom( 0.5 : git_port.ca )
140 &h3(Raw File Contents)
141 While it is not anticipated to be necessary, the xAPP might need direct access to the
142 raw contents of the configuration file.
143 As a convenience the framework provides the &cw(Get_contents()) function which
144 reads the entire file into a standard library string and returns that to the calling function.
145 Parsing and interpreting the raw contents is then up to the xAPP.
147 &h2(Notification Of Changes)
148 When desired, the xAPP may register a notification callback function with the framework.
149 This callback will be driven any time a change to the descriptor is detected.
150 When a change is detected, the revised descriptor is read into the existing
151 object (overlaying any previous information), before invoking the callback.
152 The callback may then retrieve the updated values and make any adjustments which are
154 The prototype for the xAPP callback function is described in figure &callback_proto_fig.
159 .ca start callbac_proto.ca
161 void cb_name( xapp::Config& c, void* data )
163 &export_fig(callback_proto_fig)
164 &fig_cen(The prototype which the xAPP configuration notify callback must use.)
168 &ifroom( 0.75 : callbac_proto.ca )
170 &h3(Enabling The Notifications)
171 Notifications are enabled by invoking the &cw(Set_callback()) function.
172 Once enabled, the framework will monitor the configuration source and invoke
173 the callback upon change.
174 This occurs in a separate thread than the main xAPP thread; it is up to the xAPP
175 to guard against any potential data collisions when evaluating configuration
177 If the xAPP does not register a notification function the framework will not
178 monitor the configuration for changes and the object will have static data.
179 Figure &callback_fig illustrates how the xAPP can define and register a notification
183 .ca start callback.ca
186 // notification callback; allows verbose level to change on the fly
187 void config_chg( xapp::Config& c, void* vdata ) {
188 app_ctx* ctx; // application context
190 ctx = (app_ctx *) vdata;
191 ctx->vlevel = c->Get_value( "verbose_level", ctx->vlevel );
194 &export_fig(callback_fig)
195 &fig_cen(Small notification callback function allowing on the fly verbose level change.)
199 &ifroom( 1.75 : callback.ca )
202 The xAPP would register the &cw(config_chg()) function as the notification callback
203 using the call illustrated in figure &config_set_cb_fig.
205 .ca start set_callback.ca
208 auto conf = new xapp::Config();
209 conf->Set_callback( config_chg );
211 &export_fig(config_set_cb_fig)
212 &fig_cen(Setting the notification callback and and activating notifications.)
216 &ifroom( 0.75 : set_callback.ca )
218 &h2(xAPP Descriptor Notes)
219 While it is beyond the scope of this document to describe the complete contents
220 of an xAPP descriptor file, it is prudent to mention several items which
221 are related to the information used from the descriptor file.
222 The following paragraphs discuss things which the xAPP developer should
223 be aware of, and keep in mind when using the configuration class.
226 There is a deprecated section within the xAPP descriptor which has the title
228 The &ital(messaging) section provides more flexibility, and additional information
229 and has been a replacement for the &ital(rmr) section for all applications.
230 The information in the &ital(rmr) section should be kept consistent with the
231 duplicated information in the &ital(messaging) section as long as there are
232 container management and/or platform applications (e.g. Route Manager) which
233 are back level and do not recognise the &ital(messaging) section.
234 The configuration parsing and support provided by the framework will ignore the