core/core-engine/src/main/java/org/onap/policy/apex/core/engine/executor/Executor.java

   1 /*-
   2  * ============LICENSE_START=======================================================
   3  *  Copyright (C) 2016-2018 Ericsson. All rights reserved.
   4  *  Modifications Copyright (C) 2019 Nordix Foundation.
   5  * ================================================================================
   6  * Licensed under the Apache License, Version 2.0 (the "License");
   7  * you may not use this file except in compliance with the License.
   8  * You may obtain a copy of the License at
   9  *
  10  *      http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an "AS IS" BASIS,
  14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  *
  18  * SPDX-License-Identifier: Apache-2.0
  19  * ============LICENSE_END=========================================================
  20  */
  21
  22 package org.onap.policy.apex.core.engine.executor;
  23
  24 import java.util.Properties;
  25
  26 import org.onap.policy.apex.core.engine.ExecutorParameters;
  27 import org.onap.policy.apex.core.engine.executor.exception.StateMachineException;
  28 import org.onap.policy.apex.model.basicmodel.concepts.ApexException;
  29 import org.onap.policy.apex.model.basicmodel.concepts.AxConcept;
  30
  31 /**
  32  * This interface defines what operations must be provided by an executing entity in Apex. It is
  33  * implemented by classes that execute logic in a state machine. Each executor has an incoming
  34  * entity {@code IN} that triggers execution, an outgoing entity {@code OUT} that is produced by
  35  * execution, a subject {@code SUBJECT} that is being executed, and a context {@code CONTEXT} in
  36  * which execution is being carried out. An executor can be part of a chain of executors and the
  37  * {@code setNext} method is used to set the next executor to be executed after this executor has
  38  * completed.
  39  *
  40  * @author Sven van der Meer (sven.van.der.meer@ericsson.com)
  41  * @author Liam Fallon (liam.fallon@ericsson.com)
  42  *
  43  * @param <I> type of the incoming entity
  44  * @param <O> type of the outgoing entity
  45  * @param <S> type that is the subject of execution
  46  * @param <C> context holding the context of execution
  47  */
  48
  49 public interface Executor<I, O, S, C> {
  50     /**
  51      * Save the subject and context of the executor.
  52      *
  53      * @param parent the parent executor of this executor or null if this executor is the top
  54      *        executor
  55      * @param executorSubject the executor subject, the subject of execution
  56      * @param executorContext the executor context, the context in which execution takes place
  57      */
  58     void setContext(Executor<?, ?, ?, ?> parent, S executorSubject, C executorContext);
  59
  60     /**
  61      * Prepares the processing.
  62      *
  63      * @throws StateMachineException thrown when a state machine execution error occurs
  64      */
  65     void prepare() throws StateMachineException;
  66
  67     /**
  68      * Executes the executor, running through its context in its natural order.
  69      *
  70      * @param executionId the execution ID of the current APEX execution policy thread
  71      * @param executionProperties the execution properties to set
  72      * @param incomingEntity the incoming entity that triggers execution
  73      * @return The outgoing entity that is the result of execution
  74      * @throws ApexException on an execution error
  75      */
  76     O execute(long executionId, Properties executionProperties, I incomingEntity) throws ApexException;
  77
  78     /**
  79      * Carry out the preparatory work for execution.
  80      *
  81      * @param executionId the execution ID of the current APEX execution policy thread
  82      * @param executionProperties the execution properties to set
  83      * @param incomingEntity the incoming entity that triggers execution
  84      * @throws ApexException on an execution error
  85      */
  86     void executePre(long executionId, Properties executionProperties, I incomingEntity) throws ApexException;
  87
  88     /**
  89      * Carry out the post work for execution, the returning entity should be set by the child
  90      * execution object.
  91      *
  92      * @param returnValue the return value indicates whether the execution was successful and, if it
  93      *        failed, how it failed
  94      * @throws ApexException on an execution error
  95      */
  96     void executePost(boolean returnValue) throws ApexException;
  97
  98     /**
  99      * Cleans up after processing.
 100      *
 101      * @throws StateMachineException thrown when a state machine execution error occurs
 102      */
 103     void cleanUp() throws StateMachineException;
 104
 105     /**
 106      * Get the key associated with the executor.
 107      *
 108      * @return The key associated with the executor
 109      */
 110     AxConcept getKey();
 111
 112     /**
 113      * Get the parent executor of the executor.
 114      *
 115      * @return The parent executor of this executor
 116      */
 117     @SuppressWarnings("rawtypes")
 118     Executor getParent();
 119
 120     /**
 121      * Get the subject of the executor.
 122      *
 123      * @return The subject for the executor
 124      */
 125     S getSubject();
 126
 127     /**
 128      * Get the context of the executor.
 129      *
 130      * @return The context for the executor
 131      */
 132     C getContext();
 133
 134     /**
 135      * Get the incoming object of the executor.
 136      *
 137      * @return The incoming object for the executor
 138      */
 139     I getIncoming();
 140
 141     /**
 142      * Get the outgoing object of the executor.
 143      *
 144      * @return The outgoing object for the executor
 145      */
 146     O getOutgoing();
 147
 148     /**
 149      * Save the next executor for this executor.
 150      *
 151      * @param nextExecutor the next executor
 152      */
 153     void setNext(Executor<I, O, S, C> nextExecutor);
 154
 155     /**
 156      * Get the next executor to be run after this executor completes its execution.
 157      *
 158      * @return The next executor
 159      */
 160     Executor<I, O, S, C> getNext();
 161
 162     /**
 163      * Set parameters for this executor, overloaded by executors that use parameters.
 164      *
 165      * @param parameters executor parameters
 166      */
 167     void setParameters(ExecutorParameters parameters);
 168 }