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 import org.onap.policy.apex.core.engine.ExecutorParameters;
  26 import org.onap.policy.apex.core.engine.executor.exception.StateMachineException;
  27 import org.onap.policy.apex.model.basicmodel.concepts.ApexException;
  28 import org.onap.policy.apex.model.basicmodel.concepts.AxConcept;
  29
  30 /**
  31  * This interface defines what operations must be provided by an executing entity in Apex. It is
  32  * implemented by classes that execute logic in a state machine. Each executor has an incoming
  33  * entity {@code IN} that triggers execution, an outgoing entity {@code OUT} that is produced by
  34  * execution, a subject {@code SUBJECT} that is being executed, and a context {@code CONTEXT} in
  35  * which execution is being carried out. An executor can be part of a chain of executors and the
  36  * {@code setNext} method is used to set the next executor to be executed after this executor has
  37  * completed.
  38  *
  39  * @author Sven van der Meer (sven.van.der.meer@ericsson.com)
  40  * @author Liam Fallon (liam.fallon@ericsson.com)
  41  *
  42  * @param <I> type of the incoming entity
  43  * @param <O> type of the outgoing entity
  44  * @param <S> type that is the subject of execution
  45  * @param <C> context holding the context of execution
  46  */
  47
  48 public interface Executor<I, O, S, C> {
  49     /**
  50      * Save the subject and context of the executor.
  51      *
  52      * @param parent the parent executor of this executor or null if this executor is the top
  53      *        executor
  54      * @param executorSubject the executor subject, the subject of execution
  55      * @param executorContext the executor context, the context in which execution takes place
  56      */
  57     void setContext(Executor<?, ?, ?, ?> parent, S executorSubject, C executorContext);
  58
  59     /**
  60      * Prepares the processing.
  61      *
  62      * @throws StateMachineException thrown when a state machine execution error occurs
  63      */
  64     void prepare() throws StateMachineException;
  65
  66     /**
  67      * Executes the executor, running through its context in its natural order.
  68      *
  69      * @param executionId the execution ID of the current APEX execution policy thread
  70      * @param executionProperties the execution properties to set
  71      * @param incomingEntity the incoming entity that triggers execution
  72      * @return The outgoing entity that is the result of execution
  73      * @throws ApexException on an execution error
  74      */
  75     O execute(long executionId, Properties executionProperties, I incomingEntity) throws ApexException;
  76
  77     /**
  78      * Carry out the preparatory work for execution.
  79      *
  80      * @param executionId the execution ID of the current APEX execution policy thread
  81      * @param executionProperties the execution properties to set
  82      * @param incomingEntity the incoming entity that triggers execution
  83      * @throws ApexException on an execution error
  84      */
  85     void executePre(long executionId, Properties executionProperties, I incomingEntity) throws ApexException;
  86
  87     /**
  88      * Carry out the post work for execution, the returning entity should be set by the child
  89      * execution object.
  90      *
  91      * @param returnValue the return value indicates whether the execution was successful and, if it
  92      *        failed, how it failed
  93      * @throws ApexException on an execution error
  94      */
  95     void executePost(boolean returnValue) throws ApexException;
  96
  97     /**
  98      * Cleans up after processing.
  99      *
 100      * @throws StateMachineException thrown when a state machine execution error occurs
 101      */
 102     void cleanUp() throws StateMachineException;
 103
 104     /**
 105      * Get the key associated with the executor.
 106      *
 107      * @return The key associated with the executor
 108      */
 109     AxConcept getKey();
 110
 111     /**
 112      * Get the parent executor of the executor.
 113      *
 114      * @return The parent executor of this executor
 115      */
 116     @SuppressWarnings("rawtypes")
 117     Executor getParent();
 118
 119     /**
 120      * Get the subject of the executor.
 121      *
 122      * @return The subject for the executor
 123      */
 124     S getSubject();
 125
 126     /**
 127      * Get the context of the executor.
 128      *
 129      * @return The context for the executor
 130      */
 131     C getContext();
 132
 133     /**
 134      * Get the incoming object of the executor.
 135      *
 136      * @return The incoming object for the executor
 137      */
 138     I getIncoming();
 139
 140     /**
 141      * Get the outgoing object of the executor.
 142      *
 143      * @return The outgoing object for the executor
 144      */
 145     O getOutgoing();
 146
 147     /**
 148      * Save the next executor for this executor.
 149      *
 150      * @param nextExecutor the next executor
 151      */
 152     void setNext(Executor<I, O, S, C> nextExecutor);
 153
 154     /**
 155      * Get the next executor to be run after this executor completes its execution.
 156      *
 157      * @return The next executor
 158      */
 159     Executor<I, O, S, C> getNext();
 160
 161     /**
 162      * Set parameters for this executor, overloaded by executors that use parameters.
 163      *
 164      * @param parameters executor parameters
 165      */
 166     void setParameters(ExecutorParameters parameters);
 167 }