docs/APPC Client Library Guide/APPC Client Library Guide.rst

   1 NAP Application Controller (APPC) Client Library Guide
   2
   3 +-----------------+------------------+
   4 +-----------------+------------------+
   5 | Revision        | Version 1.0.0    |
   6 +-----------------+------------------+
   7 | Revision Date   | 22 August 2017   |
   8 +-----------------+------------------+
   9
  10 +--------------+------------+---------------+--------------------------------------------------+
  11 | Date         | Revision   | Author        | Changes                                          |
  12 +--------------+------------+---------------+--------------------------------------------------+
  13 | 2017-08-22   | 1.0.0      | Paul Miller   | First draft consistent with AT&T Release 17.10   |
  14 +--------------+------------+---------------+--------------------------------------------------+
  15 +--------------+------------+---------------+--------------------------------------------------+
  16
  17 |
  18
  19
  20 1. .. rubric:: Introduction
  21       :name: introduction
  22
  23    1. .. rubric:: Target Audience
  24          :name: target-audience
  25
  26     This document is for an advanced technical audience, which includes
  27     engineers and technicians. Document revisions occur with the release
  28     of new software versions.
  29
  30 Related Documentation
  31 ---------------------
  32
  33     For additional information, see the ONAP Application Controller
  34     (APPC) API Guide.
  35
  36     The following sections describe the conventions this document uses,
  37     including notices, text conventions, and command-line conventions.
  38
  39 Command-line Conventions
  40 ========================
  41
  42 The following table lists possible elements in a command-line path.
  43
  44 +------------------+--------------------------------------------------------------------------------------------------------+
  45 | **Convention**   | **Description**                                                                                        |
  46 +==================+========================================================================================================+
  47 | Brackets [ ]     | This is used for optional items.                                                                       |
  48 +------------------+--------------------------------------------------------------------------------------------------------+
  49 | Braces { }       | This indicates choices separated by pipe (\|) for sets from which only one is selected. For example:   |
  50 |                  |                                                                                                        |
  51 |                  | {even\|odd}                                                                                            |
  52 +------------------+--------------------------------------------------------------------------------------------------------+
  53 | Blue text        | This indicates a link in this document online.                                                         |
  54 +------------------+--------------------------------------------------------------------------------------------------------+
  55
  56 Text Conventions
  57 ~~~~~~~~~~~~~~~~
  58
  59     The following table lists text conventions in this document.
  60
  61 +------------------------------------+----------------------------------------------------------------------------+
  62 | **Convention**                     | **Description**                                                            |
  63 +====================================+============================================================================+
  64 | Monospace font with blue shading   | This font indicates sample codes, screenshots, or elements. For example:   |
  65 |                                    |                                                                            |
  66 |                                    | contact": {                                                                |
  67 |                                    |                                                                            |
  68 |                                    |             "contactType": "USER",                                         |
  69 |                                    |             "source": "appl",                                              |
  70 |                                    |                                                                            |
  71 |                                    |             }                                                              |
  72 +------------------------------------+----------------------------------------------------------------------------+
  73 | *Italics*                          | Emphasizes a point or denotes new terms defined in the text.               |
  74 |                                    |                                                                            |
  75 |                                    | Indicates an external book title reference.                                |
  76 +------------------------------------+----------------------------------------------------------------------------+
  77 | Numeric                            | A number composed of digits 0 through 9.                                   |
  78 +------------------------------------+----------------------------------------------------------------------------+
  79 | Text                               | Any combination of alphanumeric characters.                                |
  80 |                                    |                                                                            |
  81 |                                    | New items in RED                                                           |
  82 +------------------------------------+----------------------------------------------------------------------------+
  83
  84 Authors and Contributors
  85 ------------------------
  86
  87     The following table lists the persons who are authors and
  88     contributors to this document.
  89
  90 +--------------------+----------------------+
  91 | **Contributors**   |                      |
  92 +====================+======================+
  93 | Borislav Glozman   | Margrethe Fossberg   |
  94 +--------------------+----------------------+
  95 | Paul Mellor        | John Buja            |
  96 +--------------------+----------------------+
  97 +--------------------+----------------------+
  98
  99 Terms and Acronyms
 100 ------------------
 101
 102 The following table defines terms and acronyms used in this document.
 103
 104 +-----------------------+--------------------------------------------------------------+
 105 | **Term or Acronym**   | **Definition**                                               |
 106 +=======================+==============================================================+
 107 | AAI                   | Active and Available Inventory                               |
 108 +-----------------------+--------------------------------------------------------------+
 109 | AAF                   | Authentication & Authorization Framework                     |
 110 +-----------------------+--------------------------------------------------------------+
 111 | AJSC                  | AT&T Java Service Container                                  |
 112 +-----------------------+--------------------------------------------------------------+
 113 | API                   | Application Programming Interface                            |
 114 +-----------------------+--------------------------------------------------------------+
 115 | APPC                  | Application Controller                                       |
 116 +-----------------------+--------------------------------------------------------------+
 117 | SDC                   | Service Design and Creation                                  |
 118 +-----------------------+--------------------------------------------------------------+
 119 | DCAE                  | Data Collection Analytics and Events                         |
 120 +-----------------------+--------------------------------------------------------------+
 121 | DG                    | Directed Graph                                               |
 122 +-----------------------+--------------------------------------------------------------+
 123 | DNS                   | Domain Name System                                           |
 124 +-----------------------+--------------------------------------------------------------+
 125 | EELF                  | Event and Error Logging Framework                            |
 126 +-----------------------+--------------------------------------------------------------+
 127 | HDFS                  | Hadoop Distributed File System                               |
 128 +-----------------------+--------------------------------------------------------------+
 129 | HTTP                  | Hypertext Transfer Protocol                                  |
 130 +-----------------------+--------------------------------------------------------------+
 131 | IAAS                  | Infrastructure As A Service                                  |
 132 +-----------------------+--------------------------------------------------------------+
 133 | I/O                   | Input/Output                                                 |
 134 +-----------------------+--------------------------------------------------------------+
 135 | JMS                   | Java Messaging Service                                       |
 136 +-----------------------+--------------------------------------------------------------+
 137 | JSON                  | JavaScript Object Notation                                   |
 138 +-----------------------+--------------------------------------------------------------+
 139 | LAN                   | Local Area Network                                           |
 140 +-----------------------+--------------------------------------------------------------+
 141 | LRM                   | Local Resource Monitor                                       |
 142 +-----------------------+--------------------------------------------------------------+
 143 | SO                    | Service Orchestrator                                         |
 144 +-----------------------+--------------------------------------------------------------+
 145 | NOD                   | Network on Demand                                            |
 146 +-----------------------+--------------------------------------------------------------+
 147 | ODL                   | OpenDaylight                                                 |
 148 +-----------------------+--------------------------------------------------------------+
 149 | ONAP                  | Open Network Application Platform                            |
 150 +-----------------------+--------------------------------------------------------------+
 151 | OS                    | Operating System                                             |
 152 +-----------------------+--------------------------------------------------------------+
 153 | PO                    | Platform Orchestrator                                        |
 154 +-----------------------+--------------------------------------------------------------+
 155 | RCT                   | Reference Connection Tool                                    |
 156 +-----------------------+--------------------------------------------------------------+
 157 | RO                    | Resource Orchestrator                                        |
 158 +-----------------------+--------------------------------------------------------------+
 159 | SDN-C                 | Software Defined Network - Controller                        |
 160 +-----------------------+--------------------------------------------------------------+
 161 | SDN-GP                | Software Defined Network -  Global Platform                  |
 162 +-----------------------+--------------------------------------------------------------+
 163 | SME                   | Subject Matter Expert                                        |
 164 +-----------------------+--------------------------------------------------------------+
 165 | SNMP                  | Simple Network Management Protocol                           |
 166 +-----------------------+--------------------------------------------------------------+
 167 | SMTP                  | Simple Mail Transfer Protocol                                |
 168 +-----------------------+--------------------------------------------------------------+
 169 | SOT                   | Source Of Truth (ext. system where data object originates)   |
 170 +-----------------------+--------------------------------------------------------------+
 171 | SSH                   | Secure Shell                                                 |
 172 +-----------------------+--------------------------------------------------------------+
 173 | TCP                   | Transmission Control Protocol                                |
 174 +-----------------------+--------------------------------------------------------------+
 175 | TPS                   | Transactions per Second                                      |
 176 +-----------------------+--------------------------------------------------------------+
 177 | UEB                   | Universal Event Broker                                       |
 178 +-----------------------+--------------------------------------------------------------+
 179 | vCE                   | virtual CE (Customer Edge) router                            |
 180 +-----------------------+--------------------------------------------------------------+
 181 | vPE                   | virtual PE (Provider Edge) router                            |
 182 +-----------------------+--------------------------------------------------------------+
 183 | VLAN                  | Virtual Local Area Network                                   |
 184 +-----------------------+--------------------------------------------------------------+
 185 | VM                    | Virtual Machine                                              |
 186 +-----------------------+--------------------------------------------------------------+
 187 | VNF                   | Virtual Network Function                                     |
 188 +-----------------------+--------------------------------------------------------------+
 189 | VNFC                  | Virtual Network Function Component                           |
 190 +-----------------------+--------------------------------------------------------------+
 191 | vSCP                  | Virtualized Service Control Point                            |
 192 +-----------------------+--------------------------------------------------------------+
 193 | WAN                   | Wide Area Network                                            |
 194 +-----------------------+--------------------------------------------------------------+
 195 | WUI                   | Web User Interface                                           |
 196 +-----------------------+--------------------------------------------------------------+
 197 | XML                   | Extensible Markup Language                                   |
 198 +-----------------------+--------------------------------------------------------------+
 199 | YAML                  | YAML Ain't Markup Language                                   |
 200 +-----------------------+--------------------------------------------------------------+
 201
 202 Client Library Background
 203 -------------------------
 204
 205     This guide discusses the Application Controller (APPC) Client
 206     Library and how to use it.
 207
 208 About the Client Library
 209 ------------------------
 210
 211     The APPC client library provides consumers of APPC capabilities with
 212     a strongly-typed Java interface and encapsulates the actual
 213     interaction with the APPC component over an asynchronous messaging
 214     channel such as UEB.
 215
 216 Consumer Logic
 217 --------------
 218
 219     The client application that consumes APPC's capability for VNF
 220     lifecycle management (the APPC client library) can be implemented
 221     against the lightweight and strongly-typed Java API exposed by the
 222     APPC client library. The library does not try to impose
 223     architectural constraints upon clients, but instead provides support
 224     for different options and styles of API. It is the responsibility of
 225     the client application to select the most suitable paradigm to use;
 226     for example, a client may choose to use blocking calls as opposed to
 227     asynchronous notifications.
 228
 229 VNF Lifecycle Management API
 230 ----------------------------
 231
 232     The API represents a relatively thin layer that consists mainly of
 233     business interfaces with strongly-typed APIs and a data object model
 234     created for the convenience of the consumer application.Â
 235
 236     The original YANG schema used by the APPC component and the
 237     underlying MD-SAL layer on the server-side generates these
 238     artifacts.
 239
 240 APP-C Client Library Flow
 241 -------------------------
 242
 243     |image0|
 244
 245 Asynchronous Flow
 246 -----------------
 247
 248 -  The APPC Client Library is called using an asynchronous API using a
 249    full command object, which is mapped to a JSON representation.
 250
 251 -  The APPC client calls the UEB client and sends the JSON command to a
 252    configured topic.
 253
 254 -  The APPC client pulls response messages from the configured topic.
 255
 256 -  On receiving the response for the command, the APPC client runs the
 257    relevant callback method of the consumer ResponseHandler.
 258
 259    1. .. rubric:: Synchronous Flow
 260          :name: synchronous-flow
 261
 262 -  The APPC Client Library is called using a synchronous API using a
 263    full command object, which is mapped to a JSON representation.
 264
 265 -  The APPC client calls the UEB client and sends the JSON command to a
 266    configured topic.
 267
 268 -  The APPC client pulls response messages from the configured topic.
 269
 270 -  On receiving the **final** response for the command, the APPC client
 271    returns the response object with a final status.
 272
 273 1. .. rubric:: Client Library Usage
 274       :name: client-library-usage
 275
 276    1. .. rubric::  Jar Files
 277          :name: jar-files
 278
 279     The Java application that runs the APPC client kit uses the
 280     following jar files:
 281
 282 -  com.att.appc.client.client-kit
 283
 284 -  com.att.appc.client.client-lib
 285
 286     The client library JAR files are located in the repository under
 287     /gerrit.onap.org/r/p/appc.git/appc-client.
 288
 289 Initialization
 290 --------------
 291
 292     Initialize the client by calling the following method:
 293
 294     AppcClientServiceFactoryProvider.getFactory(AppcLifeCycleManagerServiceFactory.class).createLifeCycleManagerStateful()
 295
 296     Specify the following configuration properties as method parameters:
 297
 298 -  "topic.read"
 299
 300 -  "topic.read.timeout"
 301
 302 -  "topic.write"
 303
 304 -  "client.key"
 305
 306 -  "client.secret"
 307
 308 -  "client.name"
 309
 310 -  "client.name.id"
 311
 312 -  "poolMembers"
 313
 314 -  "client.response.timeout"
 315
 316 -  "client.graceful.shutdown.timeout"
 317
 318 Shutdown
 319 --------
 320
 321 Shutdown the client by calling the following method:
 322
 323 void shutdownLifeCycleManager(boolean isForceShutdown)
 324
 325 If the isForceShutdown flag is set to false, the client shuts down as
 326 soon as all responses for pending requests are received, or upon
 327 configurable timeout. (client.graceful.shutdown.timeout).
 328
 329 If the isForceShutdown flag is set to true, the client shuts down
 330 immediately.
 331
 332 Invoking LCM Commands
 333 ---------------------
 334
 335 Invoke the LCM commands by:
 336
 337 -  Creating input objects, such as AuditInput, LiveUpgradeInput, with
 338    relevant command information.
 339
 340 -  Executing commands asynchronously, for example:
 341
 342 void liveUpgrade(LiveUpgradeInput liveUpgradeInput,
 343 ResponseHandler<LiveUpgradeOutput> listener) throws
 344 AppcClientException;)
 345
 346 In this case, client should implement the ResponseHandler<T> interface.
 347
 348 -  Executing commands synchronously, for example:
 349
 350 LiveUpgradeOutput liveUpgrade(LiveUpgradeInput liveUpgradeInput) throws
 351 AppcClientException;)
 352
 353 Client API
 354 ----------
 355
 356     After initializing the client, a returned Object of type
 357     LifeCycleManagerStateful defines all the Life Cycle Management APIs
 358     supported by APPC.
 359
 360     The interface contains two definitions for each RPC: one for
 361     Asynchronous call mode, and one for Synchronous.
 362
 363     In Asynchronous mode, client consumer should provide a callback
 364     function of type:
 365
 366     ResponseHandler<RPC-NAMEOutput>
 367
 368     where RPC-NAME is the command name, such as Audit or Snapshot.
 369
 370     There may be multiple calls to the ResponseHandler for each response
 371     returned by APPC. For example, first 100 'accept' is returned, then
 372     400 'success'.
 373
 374 LifeCycleManagerStateful Interface
 375 ----------------------------------
 376
 377     Generated from the APPC Yang model, this interface defines the
 378     services and request/response requirements for the ECOMP APPC
 379     component. For example, for LCM Command Audit, the following is
 380     defined:
 381
 382     @RPC(name="audit", outputType=AuditOutput.class)
 383
 384     AuditOutput audit(AuditInput auditInput) throws AppcClientException;
 385
 386     For a Synchronous call to Audit, the consumer thread is blocked
 387     until a response is received or a timeout exception is thrown.
 388
 389     @RPC(name="audit", outputType=AuditOutput.class)
 390
 391     void audit(AuditInput auditInput, ResponseHandler<AuditOutput>
 392     listener) throws AppcClientException;
 393
 394     For an Asynchronous call to Audit, a callback should be provided so
 395     that when a response is received the listener is called.
 396
 397 API documentation
 398 -----------------
 399
 400     The API documentation is also available as a swagger page generated
 401     from files at /client-kit/target/resources.
 402
 403 appc-provider-lcm
 404 -----------------
 405
 406 This defines the services and request/response requirements for the APPC
 407 component.
 408
 409 Methods
 410 --------
 411
 412 The methods should match the actions described in the LCM API Guide. For
 413 each method:
 414
 415 **Consumes**
 416
 417 This API call consumes the following media types using the
 418 **Content-Type** request header:
 419
 420 -  application/json
 421
 422 **Request body**
 423
 424 The request body is the action name followed by Input (e.g., AuditInput)
 425
 426 **Return type**
 427
 428 The return type is the action name followed by Output (e.g.,
 429 OutputInput)
 430
 431 **Produces**
 432
 433 This API call produces the following media types according to the
 434 **Accept** request header; the **Content-Type** response header conveys
 435 the media type.
 436
 437 -  application/json
 438
 439 **Responses**
 440
 441 200 Successful operation
 442
 443 401 Unauthorized
 444
 445 500 Internal server error
 446
 447 .. |image0| image:: image2.png
 448    :width: 5.60495in
 449    :height: 4.55272in
 450
 451