1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
3 .. _actors-overview-label:
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
18 .. image:: topview.png
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.
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.
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.
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.
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
50 This section describes things to consider when creating a new Actor/Operator.
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:
60 onap.policy.controlloop.actorServiceProvider.spi
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 - An implementation for a specific Actor will typically be derived from
67 *HttpActor* or *BidirectionalTopicActor*, depending whether it is HTTP/REST-based
68 or DMaaP-topic-based. These super classes provide most of the functionality needed
69 to configure the operators, extracting operator-specific properties and adding
70 default, actor-level properties
75 - Typically, developers don’t have to implement any Operator classes; they just use
76 *HttpOperator* or *BidirectionalTopicOperator*
81 - Most operations require guard checks to be performed first. Thus, at a minimum, they
82 should override *startPreprocessorAsync()* and have it invoke *startGuardAsync()*
83 - In addition, if the operation depends on data being previously gathered and placed
84 into the context, then it should override *startPreprocessorAsync()* and have it
85 invoke *obtain()*. Note: *obtain()*
86 and the guard can be performed in parallel by using the *allOf()* method. If the
88 happens to depend on the same data, then it will block until the data is available,
89 and then continue; the invoker need not deal with the dependency
90 - Subclasses will typically derive from *HttpOperation* or *BidirectionalTopicOperation*,
91 though if neither of those suffice, then they can extend *OperationPartial*, or
92 even just implement a raw *Operation*. *OperationPartial* is the super class of
93 *HttpOperation* and *BidirectionalTopicOperation* and provides most of the methods
94 used by the Operation subclasses, including a number of utility methods (e.g.,
96 - Operation subclasses should be written in a way so-as to avoid any blocking I/O. If
97 this proves too difficult, then the implementation should override *doOperation()*
98 instead of *startOperationAsync()*
99 - Operations return a "future" when *start()* is invoked. Typically, if the "future" is
100 canceled, then any outstanding operation should be canceled. For instance, HTTP
101 connections should be closed without waiting for a response
102 - If an operation sets the outcome to "FAILURE", it will be automatically retried; other
103 failure types are not retried
108 - Identifies the operation to be performed
109 - Includes timeout and retry information, though the actors typically provide default
110 values if they are not specified in the parameters
111 - Includes the event "context"
112 - Includes “Policy” fields (e.g., "actor" and "operation")
114 Context (aka, Event Context)
115 ****************************
119 - the original onset event
120 - enrichment data associated with the event
121 - results of A&AI queries
123 XxxParams and XxxConfig
124 ***********************
126 - XxxParams objects are POJOs into which the property Maps are decoded when configuring
128 - XxxConfig objects contain a single Operator's (or Actor's) configuration information,
129 based on what was in the XxxParams. For instance, the HttpConfig contains a reference
130 to the HttpClient that is used to perform HTTP
131 operations, while the associated HttpParams just contains the name of the HttpClient.
132 XxxConfig objects are
133 shared by all operations created by a single Operator. As a result, it should not
134 contain any data associated with an individual operation; such data should be stored
135 within the Operation object, itself
140 - Operation Tests may choose to subclass from *BasicHttpOperation*, which provides some
141 supporting utilities and mock objects
142 - Should include a test to verify that the Actor, and possibly each Operator, can be
143 retrieved via an Actor Service
144 - Tests with an actual REST server are performed within *HttpOperationTest*, so need not
145 be repeated in subclasses. Instead, they can catch the callback to the *get()*,
146 *post()*, etc., methods and pass the rawResponse to it there. That being said, a
147 number of actors spin up a simulator to verify end-to-end request/response processing
149 Clients (e.g., drools-applications)
150 ***********************************
152 - When using callbacks, a client may want to use the *isFor()* method to verify that the
153 outcome is for the desired operation, as callbacks are invoked with the outcome of all
154 operations performed, including any preprocessor steps
161 - Populates a *ControlLoopParams* using *ControlLoopParams.builder()*
162 - Invokes *start()* on the *ControlLoopParams*
166 - Finds the actor/operator
167 - Uses it to invoke *buildOperation()*
168 - Invokes *start()* on the Operation
172 - *start()* invokes *startPreprocessorAsync()* and then *startOperationAsync()*
173 - Exceptions that occur while **constructing** the operation pipeline propagate back
174 to the client that invoked *start()*
175 - Exceptions that occur while **executing** the operation pipeline are caught and
176 turned into an *OperationOutcome* whose result is FAILURE_EXCEPTION. In addition,
177 the "start" callback (i.e., specified via the *ControlLoopParams*) will be invoked,
178 if it hasn't been invoked yet, and then the "complete" callback will be invoked
179 - By default, *startPreprocessorAsync()* does nothing, thus most subclasses will override it to:
181 - Do any A&AI query that is needed (beyond enrichment, which is already available in
183 - Use *Context obtain()* to request the data asynchronously
184 - Invoke *startGuardAsync()*
186 - By default, *startGuardAsync()* will simply perform a guard check, passing it the
188 - Subclasses may override *makeGuardPayload()* to add extra fields to the payload
189 (e.g., some SO operations add the VF count)
190 - If any preprocessing step fails, then the "start" and "complete" callbacks will be
191 invoked to indicate a failure of the operation as a whole. Otherwise, the flow will
192 continue on to *startOperationAsync()*, after the "start" callback is invoked
193 - *StartOperationAsync()* will perform whatever needs to be done to start the operation
194 - Once it completes, the "complete" callback will be invoked with the outcome of the
195 operation. *StartOperationAsync()* should not invoke the callback, as that is
196 handled automatically by *OperationPartial*, which is the superclass of most