Gitiles
Code Review Sign In
gerrit.nordix.org / onap / appc / 881d21c2a04c195ad57e7fb14f1fe5cd1b1be413 / . / docs / APPC Client Library Guide / APPC Client Library Guide.rst
blob: 95e45c1b81f8e1958a0fe6efafe2a4becd723a18 [file] [log] [blame]
Scott Seabolt59153e92017-09-08 15:08:33 -0400[diff] [blame]1NAP 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
221. .. 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
32Related 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
41Command-line Conventions
42========================
43
44The 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
58Text 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
86Authors 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
101Terms and Acronyms
102------------------
103
104The 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
204Client Library Background
205-------------------------
206
207 This guide discusses the Application Controller (APPC) Client
208 Library and how to use it.
209
210About 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
218Consumer 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
231VNF 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
242APP-C Client Library Flow
243-------------------------
244
245 |image0|
246
247Asynchronous 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
2751. .. 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
291Initialization
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
320Shutdown
321~~~~~~~~
322
323Shutdown the client by calling the following method:
324
325void shutdownLifeCycleManager(boolean isForceShutdown)
326
327If the isForceShutdown flag is set to false, the client shuts down as
328soon as all responses for pending requests are received, or upon
329configurable timeout. (client.graceful.shutdown.timeout).
330
331If the isForceShutdown flag is set to true, the client shuts down
332immediately.
333
334Invoking LCM Commands
335~~~~~~~~~~~~~~~~~~~~~
336
337Invoke 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
344void liveUpgrade(LiveUpgradeInput liveUpgradeInput,
345ResponseHandler<LiveUpgradeOutput> listener) throws
346AppcClientException;)
347
348In this case, client should implement the ResponseHandler<T> interface.
349
350- Executing commands synchronously, for example:
351
352LiveUpgradeOutput liveUpgrade(LiveUpgradeInput liveUpgradeInput) throws
353AppcClientException;)
354
355Client 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
376LifeCycleManagerStateful 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
399API documentation
400-----------------
401
402 The API documentation is also available as a swagger page generated
403 from files at /client-kit/target/resources.
404
405appc-provider-lcm
406-----------------
407
408This defines the services and request/response requirements for the APPC
409component.
410
411Methods
412--------
413
414The methods should match the actions described in the LCM API Guide. For
415each method:
416
417**Consumes**
418
419This API call consumes the following media types using the
420**Content-Type** request header:
421
422- application/json
423
424**Request body**
425
426The request body is the action name followed by Input (e.g., AuditInput)
427
428**Return type**
429
430The return type is the action name followed by Output (e.g.,
431OutputInput)
432
433**Produces**
434
435This API call produces the following media types according to the
436**Accept** request header; the **Content-Type** response header conveys
437the media type.
438
439- application/json
440
441**Responses**
442
443200 Successful operation
444
445401 Unauthorized
446
447500 Internal server error
448
449.. |image0| image:: image2.png
450 :width: 5.60495in
451 :height: 4.55272in
452
453