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

   1 .. _appc_client_library:
   2
   3 ==================================================
   4 Application Controller (APPC) Client Library Guide
   5 ==================================================
   6
   7
   8 Revision History
   9 ----------------
  10
  11 +--------------+------------+---------------+--------------------------------------------------+
  12 | Date         | Revision   | Author        | Changes                                          |
  13 +--------------+------------+---------------+--------------------------------------------------+
  14 | 2017-08-22   | 1.0.0      | Paul Miller   | First draft                                      |
  15 +--------------+------------+---------------+--------------------------------------------------+
  16 +--------------+------------+---------------+--------------------------------------------------+
  17
  18 Introduction
  19 ============
  20
  21 Target Audience
  22 ---------------
  23
  24 This document is for an advanced technical audience, which includes engineers and technicians. Document revisions occur with the release of new software versions.
  25
  26 Related Documentation
  27 ---------------------
  28
  29 For additional information, see the ONAP Application Controller (APPC) API Guide.
  30
  31
  32 Client Library Background
  33 =========================
  34
  35 This guide discusses the Application Controller (APPC) Client Library and how to use it.
  36
  37 About the Client Library
  38 ------------------------
  39
  40 The APPC client library provides consumers of APPC capabilities with a strongly-typed Java interface and encapsulates the actual interaction with the APPC component over an asynchronous messaging channel such as UEB.
  41
  42 Consumer Logic
  43 --------------
  44
  45 The client application that consumes APPC’s capability for VNF lifecycle management (the APPC client library) can be implemented against the lightweight and strongly-typed Java API exposed by the APPC client library. The library does not try to impose architectural constraints upon clients, but instead provides support for different options and styles of API. It is the responsibility of the client application to select the most suitable paradigm to use; for example, a client may choose to use blocking calls as opposed to asynchronous notifications.
  46
  47 VNF Lifecycle Management API
  48 ----------------------------
  49
  50 The API represents a relatively thin layer that consists mainly of business interfaces with strongly-typed APIs and a data object model created for the convenience of the consumer application. The original YANG schema used by the APPC component and the  underlying MD-SAL layer on the server-side generates these artifacts.
  51
  52 APP-C Client Library Flow
  53 -------------------------
  54
  55     |image0|
  56
  57 **Asynchronous Flow**
  58
  59 -  The APPC Client Library is called using an asynchronous API using a full command object, which is mapped to a JSON representation.
  60 -  The APPC client calls the UEB client and sends the JSON command to a configured topic.
  61 -  The APPC client pulls response messages from the configured topic.
  62 -  On receiving the response for the command, the APPC client runs the relevant callback method of the consumer ResponseHandler.
  63
  64 **Synchronous Flow**
  65
  66 -  The APPC Client Library is called using a synchronous API using a full command object, which is mapped to a JSON representation.
  67 -  The APPC client calls the UEB client and sends the JSON command to a configured topic.
  68 -  The APPC client pulls response messages from the configured topic.
  69 -  On receiving the **final** response for the command, the APPC client returns the response object with a final status.
  70
  71 Client Library Usage
  72 ====================
  73
  74 Jar Files
  75 ---------
  76
  77 The Java application that runs the APPC client kit uses the following jar files:
  78
  79     -  com.att.appc.client.client-kit
  80     -  com.att.appc.client.client-lib
  81
  82 The client library JAR files are located in the repository under ``com\\att\\appc\\client``.
  83
  84 Initialization
  85 --------------
  86
  87 Initialize the client by calling the following method:
  88
  89 ``AppcClientServiceFactoryProvider.getFactory(AppcLifeCycleManagerServiceFactory.class).createLifeCycleManagerStateful()``
  90
  91 Specify the following configuration properties as method parameters:
  92
  93     -  "topic.read"
  94     -  "topic.read.timeout"
  95     -  "topic.write"
  96     -  "client.key"
  97     -  "client.secret"
  98     -  "client.name"
  99     -  "client.name.id"
 100     -  "poolMembers"
 101     -  “client.response.timeout”
 102     -  “client.graceful.shutdown.timeout”
 103
 104 Shutdown
 105 --------
 106
 107 Shutdown the client by calling the following method:
 108
 109 ``void shutdownLifeCycleManager(boolean isForceShutdown)``
 110
 111 If the ``isForceShutdown`` flag is set to false, the client shuts down as soon as all responses for pending requests are received, or upon configurable timeout. (``client.graceful.shutdown.timeout``).
 112
 113 If the ``isForceShutdown`` flag is set to true, the client shuts down immediately.
 114
 115 Invoking LCM Commands
 116 ---------------------
 117
 118 Invoke the LCM commands by:
 119
 120     -  Creating input objects, such as AuditInput, LiveUpgradeInput, with relevant command information.
 121     -  Executing commands asynchronously, for example:
 122
 123 ``void liveUpgrade(LiveUpgradeInput liveUpgradeInput, ResponseHandler<LiveUpgradeOutput> listener) throws AppcClientException;)``
 124
 125 In this case, client should implement the ResponseHandler<T> interface.
 126
 127     -  Executing commands synchronously, for example:
 128
 129 ``LiveUpgradeOutput liveUpgrade(LiveUpgradeInput liveUpgradeInput) throws AppcClientException;)``
 130
 131
 132 Client API
 133 ==========
 134
 135 After initializing the client, a returned Object of type LifeCycleManagerStateful defines all the Life Cycle Management APIs
 136  supported by APPC.
 137
 138 The interface contains two definitions for each RPC: one for Asynchronous call mode, and one for Synchronous.
 139
 140 In Asynchronous mode, client consumer should provide a callback function of type:
 141
 142     ``ResponseHandler<RPC-NAMEOutput>``
 143
 144 where ``RPC-NAME`` is the command name, such as Audit or Snapshot.
 145
 146 There may be multiple calls to the ResponseHandler for each response returned by APPC. For example, first 100 ‘accept’ is returned, then 400 ‘success’.
 147
 148 LifeCycleManagerStateful Interface
 149 ----------------------------------
 150
 151 Generated from the APPC Yang model, this interface defines the services and request/response requirements for the ECOMP APPC component. For example, for LCM Command Audit, the following is defined:
 152
 153 ``@RPC(name="audit", outputType=AuditOutput.class)``
 154
 155 ``AuditOutput audit(AuditInput auditInput) throws AppcClientException;``
 156
 157 For a Synchronous call to Audit, the consumer thread is blocked until a response is received or a timeout exception is thrown.
 158
 159 ``@RPC(name="audit", outputType=AuditOutput.class)``
 160
 161 ``void audit(AuditInput auditInput, ResponseHandler<AuditOutput> listener) throws AppcClientException;``
 162
 163 For an Asynchronous call to Audit, a callback should be provided so that when a response is received the listener is called.
 164
 165 API documentation
 166 -----------------
 167
 168 The API documentation is also available as a swagger page generated from files at /client-kit/target/resources.
 169
 170 appc-provider-lcm
 171 -----------------
 172
 173 This defines the services and request/response requirements for the APPC component.
 174
 175 Methods
 176 --------
 177
 178 The methods should match the actions described in the LCM API Guide. For each method:
 179
 180 **Consumes**
 181
 182 This API call consumes the following media types using the**Content-Type** request header:
 183
 184     -  ``application/json``
 185
 186 **Request body**
 187
 188 The request body is the action name followed by Input (e.g., AuditInput)
 189
 190 **Return type**
 191
 192 The return type is the action name followed by Output (e.g., OutputInput)
 193
 194 **Produces**
 195
 196 This API call produces the following media types according to the **Accept** request header; the **Content-Type** response header conveys the media type.
 197
 198     -  ``application/json``
 199
 200 **Responses**
 201
 202 200 Successful operation
 203
 204 401 Unauthorized
 205
 206 500 Internal server error
 207
 208 .. |image0| image:: image2.png
 209    :width: 5.60495in
 210    :height: 4.55272in