docs/development/actors/overview.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2
   3 .. _actors-overview-label:
   4
   5 #####################
   6 Actor Design Overview
   7 #####################
   8
   9 .. contents::
  10
  11 Intro
  12 #####
  13
  14 An actor/operation is any ONAP component that an Operational Policy can use to control
  15 a VNF/VM/etc. during execution of a control loop operational policy when a Control Loop
  16 Event is triggered.
  17
  18 .. image:: topview.png
  19
  20 An Actor Service object contains one or more Actor objects, which are found and created
  21 using *ServiceLoader*.  Each Actor object, in turn, creates one or more Operator objects.
  22 All of these components, the Actor Service, the Actor, and the Operator are typically
  23 singletons that are created once, at start-up (or on the first request).
  24 The Actor Service includes several methods, *configure()*, *start()*, and *stop()*,
  25 which are cascaded to the Actors and then to the Operators.
  26
  27 Operation objects, on the other hand, are not singletons; a new Operation object is
  28 created for each operation that an application wishes to perform. For instance, if an
  29 application wishes to use the "SO" Actor to add two new modules, then two separate
  30 Operation objects would be created, one for each module.
  31
  32 Actors are configured by invoking the Actor Service *configure()* method, passing it
  33 a set of properties.  The *configure()* method extracts the properties that are relevant
  34 to each Actor and passes them to the Actor's *configure()* method.  Similarly, the
  35 Actor's *configure()* method extracts the properties that are relevant
  36 to each Operator and passes them to the Operator's *configure()* method.  Note:
  37 Actors typically extract "default" properties from their respective property sets
  38 and include those when invoking each Operator's *configure()* method.
  39
  40 Once the Actor Service has been configured, it can be started via *start()*.  It will
  41 then continue to run until no longer needed, at which point *stop()* can be invoked.
  42
  43 Note: it is possible to create separate instances of an Actor Service, each with its
  44 own set of properties.  In that case, each Actor Service will get its own instances of
  45 Actors and Operators.
  46
  47 Components
  48 ##########
  49
  50 This section describes things to consider when creating a new Actor/Operator.
  51
  52 Actor
  53 *****
  54
  55 - The constructor should use addOperator() to add operators
  56 - By convention, the name of the actor is specified by a static field, "NAME"
  57 - An actor is registered via the Java ServiceLoader by including its jar on the
  58   classpath and adding its class name to this file, typically contained within the jar:
  59
  60       onap.policy.controlloop.actorServiceProvider.spi
  61
  62 - Actor loading is ordered, so that those having a lower (i.e., earlier) sequence number
  63   are loaded first.  If a later actor has the same name as one that has already been
  64   loaded, a warning will be generated and the later actor discarded.  This makes it
  65   possible for an organization to override an actor implementation
  66
  67 Operator
  68 ********
  69
  70 - Typically, developers don’t have to implement any Operator classes; they just use
  71   *HttpOperator* or *BidirectionalTopicOperator*
  72
  73 Operation
  74 *********
  75
  76 - Most operations require guard checks to be performed first. Thus, at a minimum, they
  77   should override *startPreprocessorAsync()* and have it invoke *startGuardAsync()*
  78 - In addition, if the operation depends on data being previously gathered and placed
  79   into the context, then it should override *startPreprocessorAsync()* and have it
  80   invoke *obtain()*. Note: *obtain()*
  81   and the guard can be performed in parallel by using the *allOf()* method.  If the
  82   guard
  83   happens to depend on the same data, then it will block until the data is available,
  84   and then continue; the invoker need not deal with the dependency
  85 - Subclasses will typically derive from *HttpOperation* or *BidirectionalTopicOperation*,
  86   though if neither of those suffice, then they can extend *OperationPartial*, or
  87   even just implement a raw *Operation*
  88 - Operation subclasses should be written in a way so-as to avoid any blocking I/O
  89 - Operations return a "future" when *start()* is invoked.  Typically, if the "future" is
  90   canceled, then any outstanding operation should be canceled.  For instance, HTTP
  91   connections should be closed without waiting for a response
  92 - If an operation sets the outcome to "FAILURE", it will be automatically retried; other
  93   failure types are not retried
  94
  95 ControlLoopParams
  96 *****************
  97
  98 - Identifies the operation to be performed
  99 - Includes timeout and retry information, though the actors typically provide default
 100   values if they are not specified in the parameters
 101 - Includes the event "context"
 102 - Includes “Policy” fields (e.g., "actor" and "operation")
 103
 104 Context (aka, Event Context)
 105 ****************************
 106
 107 - Includes:
 108
 109     - the original onset event
 110     - enrichment data associated with the event
 111     - results of A&AI queries
 112
 113 XxxParams and XxxConfig
 114 ***********************
 115
 116 - XxxParams objects are POJOs into which the property Maps are decoded when configuring
 117   actors or operators
 118 - XxxConfig objects contain a single Operator's (or Actor's) configuration information,
 119   based on what was in the XxxParams.  For instance, the HttpConfig contains a reference
 120   to the HttpClient that is used to perform HTTP
 121   operations, while the associated HttpParams just contains the name of the HttpClient.
 122   XxxConfig objects are
 123   shared by all operations created by a single Operator.  As a result, it should not
 124   contain any data associated with an individual operation; such data should be stored
 125   within the Operation object, itself
 126
 127 Junit tests
 128 ***********
 129
 130 - Operation Tests may choose to subclass from *BasicHttpOperation*, which provides some
 131   supporting utilities and mock objects
 132 - Should include a test to verify that the Actor, and possibly each Operator, can be
 133   retrieved via an Actor Service
 134 - Tests with an actual REST server are performed within *HttpOperationTest*, so need not
 135   be repeated in subclasses. Instead, they can catch the callback to the *get()*,
 136   *post()*, etc., methods and pass the rawResponse to it there.  That being said, a
 137   number of actors spin up a simulator to verify end-to-end request/response processing
 138
 139 Clients (e.g., drools-applications)
 140 ***********************************
 141
 142 - When using callbacks, a client may want to use the *isFor()* method to verify that the
 143   outcome is for the desired operation, as callbacks are invoked with the outcome of all
 144   operations performed, including any preprocessor steps
 145
 146 Flow of operation
 147 #################
 148
 149 - PDP:
 150
 151   - Populates a *ControlLoopParams* using *ControlLoopParams.builder()*
 152   - Invokes *start()* on the *ControlLoopParams*
 153
 154 - ControlLoopParams:
 155
 156   - Finds the actor/operator
 157   - Uses it to invoke *buildOperation()*
 158   - Invokes *start()* on the Operation
 159
 160 - Operation:
 161
 162   - *start()* invokes *startPreprocessorAsync()* and then *startOperationAsync()*
 163   - Exceptions that occur while **constructing** the operation pipeline propagate back
 164     to the client that invoked *start()*
 165   - Exceptions that occur while **executing** the operation pipeline are caught and
 166     turned into an *OperationOutcome* whose result is FAILURE_EXCEPTION.  In addition,
 167     the "start" callback (i.e., specified via the *ControlLoopParams*) will be invoked,
 168     if it hasn't been invoked yet, and then the "complete" callback will be invoked
 169   - By default, *startPreprocessorAsync()* does nothing, thus most subclasses will override it to:
 170
 171     - Do any A&AI query that is needed (beyond enrichment, which is already available in
 172       the *Context*)
 173     - Use *Context obtain()* to request the data asynchronously
 174     - Invoke *startGuardAsync()*
 175
 176   - By default, *startGuardAsync()* will simply perform a guard check, passing it the
 177     "standard" payload
 178   - Subclasses may override *makeGuardPayload()* to add extra fields to the payload
 179     (e.g., some SO operations add the VF count)
 180   - If any preprocessing step fails, then the "start" and "complete" callbacks will be
 181     invoked to indicate a failure of the operation as a whole. Otherwise, the flow will
 182     continue on to *startOperationAsync()*, after the "start" callback is invoked
 183   - *StartOperationAsync()* will perform whatever needs to be done to start the operation
 184   - Once it completes, the "complete" callback will be invoked with the outcome of the
 185     operation.  *StartOperationAsync()* should not invoke the callback, as that is
 186     handled automatically by *OperationPartial*, which is the superclass of most
 187     Operations