doc/src/user/config.im

   1 .** vim: sw=4 ts=4 et :
   2 .if false
   3 ==================================================================================
   4     Copyright (c) 2020 Nokia
   5     Copyright (c) 2020 AT&T Intellectual Property.
   6
   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
  10
  11        http://www.apache.org/licenses/LICENSE-2.0
  12
  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 ==================================================================================
  19 .fi
  20
  21
  22 .if false
  23         This imbed file contains the portion of the document that describes the
  24     configuration file and config notification update interface.
  25 .fi
  26
  27
  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.
  36
  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.
  42 &space
  43
  44
  45 .ca start conf_const.ca
  46 &ex_start
  47     #include <ricxfcpp/config.hpp>
  48
  49     auto cfg = new xapp::Config( );
  50     auto cfg = new xapp::Config( "/var/myapp/config.json"  );
  51 &ex_end
  52 &export_fig(conf_const_fig)
  53 &fig_cen(Creating a configuration instance.)
  54 &space
  55 .ca end
  56 .gv remain
  57 &ifroom( 1.5 : conf_const.ca )
  58
  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
  61 it needs.
  62
  63 &h2( Available Functions )
  64 Once a configuration has been created the following capabilities are
  65 available:
  66 &space
  67
  68 &indent
  69 &beg_list( &lic1 )
  70 &li Get a control value (numeric, string, or boolean)
  71 &half_space
  72 &li Get the RMR port for the container with the supplied name
  73 &half_space
  74 &li Set a notification callback function
  75 &half_space
  76 &li Get the raw contents of the file
  77 &end_list
  78 &uindent
  79
  80 &h3(Control Values)
  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.
  88
  89 &space
  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.
  94
  95
  96 .ca start conf_proto1.ca
  97 &ex_start
  98   bool Get_control_bool( std::string name, bool defval );
  99   bool Get_control_bool( std::string name );
 100
 101   std::string Get_control_str( std::string name, std::string defval );
 102   std::string Get_control_str( std::string name );
 103
 104   double Get_control_value( std::string name, double defval );
 105   double Get_control_value( std::string name );
 106 &ex_end
 107 &export_fig(config_proto1_fig)
 108 &fig_cen(The various controls section get functions.)
 109 &space
 110 .ca end
 111 .gv remain
 112 &ifroom( 1.5 : conf_proto1.ca )
 113
 114
 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.
 118
 119
 120 &h3(The RMR Port)
 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
 123 given container.
 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.
 126 &space
 127
 128 .ca start git_port.ca
 129 &ex_start
 130   std::string Get_port( std::string name );
 131 &ex_end
 132 &export_fig(get_port_fig)
 133 &fig_cen(The get port prototype.)
 134 &space
 135 .ca end
 136 .gv remain
 137 &ifroom( 0.5 : git_port.ca )
 138
 139
 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.
 146
 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
 153 necessary.
 154 The prototype for the xAPP callback function is described in figure &callback_proto_fig.
 155 &space
 156
 157
 158
 159 .ca start callbac_proto.ca
 160 &ex_start
 161    void cb_name( xapp::Config& c, void* data )
 162 &ex_end
 163 &export_fig(callback_proto_fig)
 164 &fig_cen(The prototype which the xAPP configuration notify callback must use.)
 165 &space
 166 .ca end
 167 .gv remain
 168 &ifroom( 0.75 : callbac_proto.ca )
 169
 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
 176 changes.
 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
 180 callback.
 181 &space
 182
 183 .ca start callback.ca
 184 &ex_start
 185
 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
 189
 190    ctx = (app_ctx *) vdata;
 191    ctx->vlevel = c->Get_value( "verbose_level", ctx->vlevel );
 192   }
 193 &ex_end
 194 &export_fig(callback_fig)
 195 &fig_cen(Small notification callback function allowing on the fly verbose level change.)
 196 &space
 197 .ca end
 198 .gv remain
 199 &ifroom( 1.75 : callback.ca )
 200
 201 &space
 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.
 204
 205 .ca start set_callback.ca
 206 &ex_start
 207
 208    auto conf = new xapp::Config();
 209    conf->Set_callback( config_chg );
 210 &ex_end
 211 &export_fig(config_set_cb_fig)
 212 &fig_cen(Setting the notification callback and and activating notifications.)
 213 &mult_space( 2.5 )
 214 .ca end
 215 .gv remain
 216 &ifroom( 0.75 : set_callback.ca )
 217
 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.
 224
 225 &h3(The RMR Section)
 226 There is a deprecated section within the xAPP descriptor which has the title
 227 &ital(rmr.)
 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
 235 &ital(rmr) section.
 236