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

   1 .. ============LICENSE_START==========================================
   2 .. ===================================================================
   3 .. Copyright © 2017 AT&T Intellectual Property. All rights reserved.
   4 .. ===================================================================
   5 .. Licensed under the Creative Commons License, Attribution 4.0 Intl.  (the "License");
   6 .. you may not use this documentation except in compliance with the License.
   7 .. You may obtain a copy of the License at
   8 ..
   9 ..  https://creativecommons.org/licenses/by/4.0/
  10 ..
  11 .. Unless required by applicable law or agreed to in writing, software
  12 .. distributed under the License is distributed on an "AS IS" BASIS,
  13 .. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 .. See the License for the specific language governing permissions and
  15 .. limitations under the License.
  16 .. ============LICENSE_END============================================
  17 .. ECOMP is a trademark and service mark of AT&T Intellectual Property.
  18
  19 .. _appc_client_library:
  20
  21 ==================================================
  22 Application Controller (APPC) Client Library Guide
  23 ==================================================
  24
  25
  26 Introduction
  27 ============
  28
  29 Target Audience
  30 ---------------
  31
  32 This document is for an advanced technical audience, which includes engineers and technicians. Document revisions occur with the release of new software versions.
  33
  34 Related Documentation
  35 ---------------------
  36
  37 For additional information, see
  38
  39         :ref:`appc_api_guide`
  40
  41
  42 Client Library Background
  43 =========================
  44
  45 This guide discusses the Application Controller (APPC) Client Library and how to use it.
  46
  47 About the Client Library
  48 ------------------------
  49
  50 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.
  51
  52 Consumer Logic
  53 --------------
  54
  55 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.
  56
  57 VNF Lifecycle Management API
  58 ----------------------------
  59
  60 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.
  61
  62 APP-C Client Library Flow
  63 -------------------------
  64
  65     |image0|
  66
  67 Asynchronous Flow
  68 ^^^^^^^^^^^^^^^^^
  69
  70 -  The APPC Client Library is called using an asynchronous API using a full command object, which is mapped to a JSON representation.
  71 -  The APPC client calls the UEB client and sends the JSON command to a configured topic.
  72 -  The APPC client pulls response messages from the configured topic.
  73 -  On receiving the response for the command, the APPC client runs the relevant callback method of the consumer ResponseHandler.
  74
  75 Synchronous Flow
  76 ^^^^^^^^^^^^^^^^
  77
  78 -  The APPC Client Library is called using a synchronous API using a full command object, which is mapped to a JSON representation.
  79 -  The APPC client calls the UEB client and sends the JSON command to a configured topic.
  80 -  The APPC client pulls response messages from the configured topic.
  81 -  On receiving the **final** response for the command, the APPC client returns the response object with a final status.
  82
  83 Client Library Usage
  84 ====================
  85
  86 Jar Files
  87 ---------
  88
  89 The Java application that runs the APPC client kit uses the following jar files:
  90
  91     -  com.att.appc.client.client-kit
  92     -  com.att.appc.client.client-lib
  93
  94 The client library JAR files are located in the repository under ``com\\att\\appc\\client``.
  95
  96 Initialization
  97 --------------
  98
  99 Initialize the client by calling the following method:
 100
 101 ``AppcClientServiceFactoryProvider.getFactory(AppcLifeCycleManagerServiceFactory.class).createLifeCycleManagerStateful()``
 102
 103 Specify the following configuration properties as method parameters:
 104
 105     -  "topic.read"
 106     -  "topic.read.timeout"
 107     -  "topic.write"
 108     -  "client.key"
 109     -  "client.secret"
 110     -  "client.name"
 111     -  "client.name.id"
 112     -  "poolMembers"
 113     -  “client.response.timeout”
 114     -  “client.graceful.shutdown.timeout”
 115
 116 Shutdown
 117 --------
 118
 119 Shutdown the client by calling the following method:
 120
 121 ``void shutdownLifeCycleManager(boolean isForceShutdown)``
 122
 123 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``).
 124
 125 If the ``isForceShutdown`` flag is set to true, the client shuts down immediately.
 126
 127 Invoking LCM Commands
 128 ---------------------
 129
 130 Invoke the LCM commands by:
 131
 132     -  Creating input objects, such as AuditInput, LiveUpgradeInput, with relevant command information.
 133     -  Executing commands asynchronously, for example:
 134
 135 ``void liveUpgrade(LiveUpgradeInput liveUpgradeInput, ResponseHandler<LiveUpgradeOutput> listener) throws AppcClientException;)``
 136
 137 In this case, client should implement the ResponseHandler<T> interface.
 138
 139     -  Executing commands synchronously, for example:
 140
 141 ``LiveUpgradeOutput liveUpgrade(LiveUpgradeInput liveUpgradeInput) throws AppcClientException;)``
 142
 143
 144 Client API
 145 ==========
 146
 147 After initializing the client, a returned Object of type LifeCycleManagerStateful defines all the Life Cycle Management APIs
 148  supported by APPC.
 149
 150 The interface contains two definitions for each RPC: one for Asynchronous call mode, and one for Synchronous.
 151
 152 In Asynchronous mode, client consumer should provide a callback function of type:
 153
 154     ``ResponseHandler<RPC-NAMEOutput>``
 155
 156 where ``RPC-NAME`` is the command name, such as Audit or Snapshot.
 157
 158 There may be multiple calls to the ResponseHandler for each response returned by APPC. For example, first 100 ‘accept’ is returned, then 400 ‘success’.
 159
 160 LifeCycleManagerStateful Interface
 161 ----------------------------------
 162
 163 Generated from the APPC Yang model, this interface defines the services and request/response requirements for the ONAP APPC component. For example, for LCM Command Audit, the following is defined:
 164
 165 ``@RPC(name="audit", outputType=AuditOutput.class)``
 166
 167 ``AuditOutput audit(AuditInput auditInput) throws AppcClientException;``
 168
 169 For a Synchronous call to Audit, the consumer thread is blocked until a response is received or a timeout exception is thrown.
 170
 171 ``@RPC(name="audit", outputType=AuditOutput.class)``
 172
 173 ``void audit(AuditInput auditInput, ResponseHandler<AuditOutput> listener) throws AppcClientException;``
 174
 175 For an Asynchronous call to Audit, a callback should be provided so that when a response is received the listener is called.
 176
 177 API documentation
 178 -----------------
 179
 180 The API documentation is also available as a swagger page generated from files at /client-kit/target/resources.
 181
 182 appc-provider-lcm
 183 -----------------
 184
 185 This defines the services and request/response requirements for the APPC component.
 186
 187 Methods
 188 -------
 189
 190 The methods should match the actions described in the LCM API Guide. For each method:
 191
 192 **Consumes**
 193
 194 This API call consumes the following media types using the**Content-Type** request header:
 195
 196     -  ``application/json``
 197
 198 **Request body**
 199
 200 The request body is the action name followed by Input (e.g., AuditInput)
 201
 202 **Return type**
 203
 204 The return type is the action name followed by Output (e.g., OutputInput)
 205
 206 **Produces**
 207
 208 This API call produces the following media types according to the **Accept** request header; the **Content-Type** response header conveys the media type.
 209
 210     -  ``application/json``
 211
 212 **Responses**
 213
 214 200 Successful operation
 215
 216 401 Unauthorized
 217
 218 500 Internal server error
 219
 220 .. |image0| image:: image2.png
 221    :width: 5.60495in
 222    :height: 4.55272in