--- /dev/null
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+.. _actors-overview-label:
+
+#####################
+Actor Design Overview
+#####################
+
+.. contents::
+
+Intro
+#####
+
+An actor/operation is any ONAP component that an Operational Policy can use to control
+a VNF/VM/etc. during execution of a control loop operational policy when a Control Loop
+Event is triggered.
+
+.. image:: topview.png
+
+An Actor Service object contains one or more Actor objects, which are found and created
+using *ServiceLoader*. Each Actor object, in turn, creates one or more Operator objects.
+All of these components, the Actor Service, the Actor, and the Operator are typically
+singletons that are created once, at start-up (or on the first request).
+The Actor Service includes several methods, *configure()*, *start()*, and *stop()*,
+which are cascaded to the Actors and then to the Operators.
+
+Operation objects, on the other hand, are not singletons; a new Operation object is
+created for each operation that an application wishes to perform. For instance, if an
+application wishes to use the "SO" Actor to add two new modules, then two separate
+Operation objects would be created, one for each module.
+
+Actors are configured by invoking the Actor Service *configure()* method, passing it
+a set of properties. The *configure()* method extracts the properties that are relevant
+to each Actor and passes them to the Actor's *configure()* method. Similarly, the
+Actor's *configure()* method extracts the properties that are relevant
+to each Operator and passes them to the Operator's *configure()* method. Note:
+Actors typically extract "default" properties from their respective property sets
+and include those when invoking each Operator's *configure()* method.
+
+Once the Actor Service has been configured, it can be started via *start()*. It will
+then continue to run until no longer needed, at which point *stop()* can be invoked.
+
+Note: it is possible to create separate instances of an Actor Service, each with its
+own set of properties. In that case, each Actor Service will get its own instances of
+Actors and Operators.
+
+Components
+##########
+
+This section describes things to consider when creating a new Actor/Operator.
+
+Actor
+*****
+
+- The constructor should use addOperator() to add operators
+- By convention, the name of the actor is specified by a static field, "NAME"
+- An actor is registered via the Java ServiceLoader by including its jar on the
+ classpath and adding its class name to this file, typically contained within the jar:
+
+ onap.policy.controlloop.actorServiceProvider.spi
+
+- Actor loading is ordered, so that those having a lower (i.e., earlier) sequence number
+ are loaded first. If a later actor has the same name as one that has already been
+ loaded, a warning will be generated and the later actor discarded. This makes it
+ possible for an organization to override an actor implementation
+
+Operator
+********
+
+- Typically, developers don’t have to implement any Operator classes; they just use
+ *HttpOperator* or *BidirectionalTopicOperator*
+
+Operation
+*********
+
+- Most operations require guard checks to be performed first. Thus, at a minimum, they
+ should override *startPreprocessorAsync()* and have it invoke *startGuardAsync()*
+- In addition, if the operation depends on data being previously gathered and placed
+ into the context, then it should override *startPreprocessorAsync()* and have it
+ invoke *obtain()*. Note: *obtain()*
+ and the guard can be performed in parallel by using the *allOf()* method. If the
+ guard
+ happens to depend on the same data, then it will block until the data is available,
+ and then continue; the invoker need not deal with the dependency
+- Subclasses will typically derive from *HttpOperation* or *BidirectionalTopicOperation*,
+ though if neither of those suffice, then they can extend *OperationPartial*, or
+ even just implement a raw *Operation*
+- Operation subclasses should be written in a way so-as to avoid any blocking I/O
+- Operations return a "future" when *start()* is invoked. Typically, if the "future" is
+ canceled, then any outstanding operation should be canceled. For instance, HTTP
+ connections should be closed without waiting for a response
+- If an operation sets the outcome to "FAILURE", it will be automatically retried; other
+ failure types are not retried
+
+ControlLoopParams
+*****************
+
+- Identifies the operation to be performed
+- Includes timeout and retry information, though the actors typically provide default
+ values if they are not specified in the parameters
+- Includes the event "context"
+- Includes “Policy” fields (e.g., "actor" and "operation")
+
+Context (aka, Event Context)
+****************************
+
+- Includes:
+
+ - the original onset event
+ - enrichment data associated with the event
+ - results of A&AI queries
+
+XxxParams and XxxConfig
+***********************
+
+- XxxParams objects are POJOs into which the property Maps are decoded when configuring
+ actors or operators
+- XxxConfig objects contain a single Operator's (or Actor's) configuration information,
+ based on what was in the XxxParams. For instance, the HttpConfig contains a reference
+ to the HttpClient that is used to perform HTTP
+ operations, while the associated HttpParams just contains the name of the HttpClient.
+ XxxConfig objects are
+ shared by all operations created by a single Operator. As a result, it should not
+ contain any data associated with an individual operation; such data should be stored
+ within the operation object, itself
+
+Junit tests
+***********
+
+- Operation Tests may choose to subclass from *BasicHttpOperation*, which provides some
+ supporting utilities and mock objects
+- Should include a test to verify that the Actor, and possibly each Operator, can be
+ retrieved via an Actor Service
+- Tests with an actual REST server are performed within *HttpOperationTest*, so need not
+ be repeated in subclasses. Instead, they can catch the callback to the *get()*,
+ *post()*, etc., methods and pass the rawResponse to it there. That being said, a
+ number of actors spin up a simulator to verify end-to-end request/response processing
+
+Clients (e.g., drools-applications)
+***********************************
+
+- When using callbacks, a client may want to use the *isFor()* method to verify that the
+ outcome is for the desired operation, as callbacks are invoked with the outcome of all
+ operations performed, including any preprocessor steps
+
+Flow of operation
+#################
+
+- PDP:
+
+ - Populates a *ControlLoopParams* using *ControlLoopParams.builder()*
+ - Invokes *start()* on the *ControlLoopParams*
+
+- ControlLoopParams:
+
+ - Finds the actor/operator
+ - Uses it to invoke *buildOperation()*
+ - Invokes *start()* on the Operation
+
+- Operation:
+
+ - *start()* invokes *startPreprocessorAsync()* and then *startOperationAsync()*
+ - Exceptions that occur while **constructing** the operation pipeline propagate back
+ to the client that invoked *start()*
+ - Exceptions that occur while **executing** the operation pipeline are caught and
+ turned into an *OperationOutcome* whose result is FAILURE_EXCEPTION. In addition,
+ the "start" callback (i.e., specified via the *ControlLoopParams*) will be invoked,
+ if it hasn't been invoked yet, and then the "complete" callback will be invoked
+ - By default, *startPreprocessorAsync()* does nothing, thus most subclasses will override it to:
+
+ - Do any A&AI query that is needed (beyond enrichment, which is already available in
+ the *Context*)
+ - Use *Context obtain()* to request the data asynchronously
+ - Invoke *startGuardAsync()*
+
+ - By default, *startGuardAsync()* will simply perform a guard check, passing it the
+ "standard" payload
+ - Subclasses may override *makeGuardPayload()* to add extra fields to the payload
+ (e.g., some SO operations add the VF count)
+ - If any preprocessing step fails, then the "start" & "complete" callbacks will be
+ invoked to indicate a failure of the operation as a whole. Otherwise, the flow will
+ continue on to *startOperationAsync()*, after the "start" callback is invoked
+ - *StartOperationAsync()* will perform whatever needs to be done to start the operation
+ - Once it completes, the "complete" callback will be invoked with the outcome of the
+ operation. *StartOperationAsync()* should not invoke the callback, as that is
+ handled automatically by *OperationPartial*, which is the superclass of most
+ Operations
Code Review / policy / parent.git / commitdiff
