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