policy-management/src/main/java/org/onap/policy/drools/system/PolicyEngine.java

   1 /*
   2  * ============LICENSE_START=======================================================
   3  * policy-management
   4  * ================================================================================
   5  * Copyright (C) 2017-2019 AT&T Intellectual Property. All rights reserved.
   6  * ================================================================================
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  *      http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  * ============LICENSE_END=========================================================
  19  */
  20
  21 package org.onap.policy.drools.system;
  22
  23 import java.util.List;
  24 import java.util.Properties;
  25 import org.onap.policy.common.capabilities.Lockable;
  26 import org.onap.policy.common.capabilities.Startable;
  27 import org.onap.policy.common.endpoints.event.comm.Topic.CommInfrastructure;
  28 import org.onap.policy.common.endpoints.event.comm.TopicListener;
  29 import org.onap.policy.common.endpoints.event.comm.TopicSink;
  30 import org.onap.policy.common.endpoints.event.comm.TopicSource;
  31 import org.onap.policy.common.endpoints.http.server.HttpServletServer;
  32 import org.onap.policy.drools.features.PolicyEngineFeatureApi;
  33 import org.onap.policy.drools.protocol.configuration.ControllerConfiguration;
  34 import org.onap.policy.drools.protocol.configuration.PdpdConfiguration;
  35
  36 /**
  37  * Policy Engine, the top abstraction for the Drools PDP Policy Engine. It abstracts away a Drools
  38  * PDP Engine from management purposes. This is the best place to looking at the code from a top
  39  * down approach. Other managed entities can be obtained from the PolicyEngine, hierarchically. <br>
  40  * PolicyEngine 1 --- * PolicyController 1 --- 1 DroolsController 1 --- 1 PolicyContainer 1 --- *
  41  * PolicySession <br> PolicyEngine 1 --- 1 TopicEndpointManager 1 -- * TopicReader 1 --- 1
  42  * UebTopicReader <br> PolicyEngine 1 --- 1 TopicEndpointManager 1 -- * TopicReader 1 --- 1
  43  * DmaapTopicReader <br> PolicyEngine 1 --- 1 TopicEndpointManager 1 -- * TopicWriter 1 --- 1
  44  * DmaapTopicWriter <br> PolicyEngine 1 --- 1 TopicEndpointManager 1 -- * TopicReader 1 --- 1
  45  * RestTopicReader <br> PolicyEngine 1 --- 1 TopicEndpointManager 1 -- * TopicWriter 1 --- 1
  46  * RestTopicWriter <br> PolicyEngine 1 --- 1 ManagementServer
  47  */
  48 public interface PolicyEngine extends Startable, Lockable, TopicListener {
  49     /**
  50      * Policy Engine Manager.
  51      */
  52     PolicyEngine manager = new PolicyEngineManager();
  53
  54     /**
  55      * Default Telemetry Server Port.
  56      */
  57     int TELEMETRY_SERVER_DEFAULT_PORT = 9696;
  58
  59     /**
  60      * Default Telemetry Server Hostname.
  61      */
  62     String TELEMETRY_SERVER_DEFAULT_HOST = "localhost";
  63
  64     /**
  65      * Default Telemetry Server Name.
  66      */
  67     String TELEMETRY_SERVER_DEFAULT_NAME = "TELEMETRY";
  68
  69     /**
  70      * Boot the engine.
  71      *
  72      * @param cliArgs command line arguments
  73      */
  74     void boot(String[] cliArgs);
  75
  76     /**
  77      * configure the policy engine according to the given properties.
  78      *
  79      * @param properties Policy Engine properties
  80      * @throws IllegalArgumentException when invalid or insufficient properties are provided
  81      */
  82     void configure(Properties properties);
  83
  84     /**
  85      * updates the Policy Engine with the given configuration.
  86      *
  87      * @param configuration the configuration
  88      * @return success or failure
  89      * @throws IllegalArgumentException if invalid argument provided
  90      * @throws IllegalStateException    if the system is in an invalid state
  91      */
  92     boolean configure(PdpdConfiguration configuration);
  93
  94     /**
  95      * configure the engine's environment. General lab installation configuration is made available
  96      * to the Engine. Typically, custom lab installation that may be needed by arbitrary drools
  97      * applications are made available, for example network component and database host addresses.
  98      * Multiple environments can be passed in and tracked by the engine.
  99      *
 100      * @param properties an environment properties
 101      */
 102     void setEnvironment(Properties properties);
 103
 104     /**
 105      * gets the engine's environment.
 106      *
 107      * @return properties object
 108      */
 109     Properties getEnvironment();
 110
 111     /**
 112      * gets an environment's value, by 1) first from the engine's environment, and 2) from the OS
 113      * environment.
 114      *
 115      * @param key environment key
 116      * @return environment value or null if absent
 117      */
 118     String getEnvironmentProperty(String key);
 119
 120     /**
 121      * sets an engine's environment property.
 122      *
 123      * @param key key
 124      * @param value value
 125      * @return property string
 126      */
 127     String setEnvironmentProperty(String key, String value);
 128
 129     /**
 130      * registers a new Policy Controller with the Policy Engine initialized per properties.
 131      *
 132      * @param properties properties to initialize the Policy Controller
 133      * @return the newly instantiated Policy Controller
 134      * @throws IllegalArgumentException when invalid or insufficient properties are provided
 135      * @throws IllegalStateException    when the engine is in a state where this operation is not
 136      *                                  permitted.
 137      */
 138     PolicyController createPolicyController(String name, Properties properties);
 139
 140     /**
 141      * updates a set of Policy Controllers with configuration information.
 142      *
 143      * @param configuration list of configurations
 144      * @return list of controllers
 145      * @throws IllegalArgumentException exception
 146      * @throws IllegalStateException exception
 147      */
 148     List<PolicyController> updatePolicyControllers(List<ControllerConfiguration> configuration);
 149
 150     /**
 151      * updates an already existing Policy Controller with configuration information.
 152      *
 153      * @param configuration configuration
 154      * @return the updated Policy Controller
 155      * @throws IllegalArgumentException in the configuration is invalid
 156      * @throws IllegalStateException    if the controller is in a bad state
 157      * @throws Exception                any other reason
 158      */
 159     PolicyController updatePolicyController(ControllerConfiguration configuration);
 160
 161     /**
 162      * removes the Policy Controller identified by its name from the Policy Engine.
 163      *
 164      * @param name name of the Policy Controller
 165      */
 166     void removePolicyController(String name);
 167
 168     /**
 169      * removes a Policy Controller from the Policy Engine.
 170      *
 171      * @param controller the Policy Controller to remove from the Policy Engine
 172      */
 173     void removePolicyController(PolicyController controller);
 174
 175     /**
 176      * returns a list of the available Policy Controllers.
 177      *
 178      * @return list of Policy Controllers
 179      */
 180     List<PolicyController> getPolicyControllers();
 181
 182
 183     /**
 184      * get policy controller names.
 185      *
 186      * @return list of controller names
 187      */
 188     List<String> getPolicyControllerIds();
 189
 190     /**
 191      * get unmanaged sources.
 192      *
 193      * @return unmanaged sources
 194      */
 195     List<TopicSource> getSources();
 196
 197     /**
 198      * get unmanaged sinks.
 199      *
 200      * @return unmanaged sinks
 201      */
 202     List<TopicSink> getSinks();
 203
 204     /**
 205      * get unmmanaged http servers list.
 206      *
 207      * @return http servers
 208      */
 209     List<HttpServletServer> getHttpServers();
 210
 211     /**
 212      * get properties configuration.
 213      *
 214      * @return properties objects
 215      */
 216     Properties getProperties();
 217
 218     /**
 219      * get features attached to the Policy Engine.
 220      *
 221      * @return list of features
 222      */
 223     List<PolicyEngineFeatureApi> getFeatureProviders();
 224
 225     /**
 226      * get named feature attached to the Policy Engine.
 227      *
 228      * @return the feature
 229      */
 230     PolicyEngineFeatureApi getFeatureProvider(String featureName);
 231
 232     /**
 233      * get features attached to the Policy Engine.
 234      *
 235      * @return list of features
 236      */
 237     List<String> getFeatures();
 238
 239     /**
 240      * Attempts the dispatching of an "event" object.
 241      *
 242      * @param topic topic
 243      * @param event the event object to send
 244      * @return true if successful, false if a failure has occurred.
 245      * @throws IllegalArgumentException when invalid or insufficient properties are provided
 246      * @throws IllegalStateException    when the engine is in a state where this operation is not
 247      *                                  permitted (ie. locked or stopped).
 248      */
 249     boolean deliver(String topic, Object event);
 250
 251     /**
 252      * Attempts the dispatching of an "event" object over communication infrastructure "busType".
 253      *
 254      * @param topic topic
 255      * @param event the event object to send
 256      * @return true if successful, false if a failure has occurred.
 257      * @throws IllegalArgumentException      when invalid or insufficient properties are provided
 258      * @throws IllegalStateException         when the engine is in a state where this operation is not
 259      *                                       permitted (ie. locked or stopped).
 260      * @throws UnsupportedOperationException when the engine cannot deliver due to the functionality
 261      *                                       missing (ie. communication infrastructure not supported.
 262      */
 263     boolean deliver(String busType, String topic, Object event);
 264
 265     /**
 266      * Attempts the dispatching of an "event" object over communication infrastructure "busType".
 267      *
 268      * @param topic topic
 269      * @param event the event object to send
 270      * @return true if successful, false if a failure has occurred.
 271      * @throws IllegalArgumentException      when invalid or insufficient properties are provided
 272      * @throws IllegalStateException         when the engine is in a state where this operation is not
 273      *                                       permitted (ie. locked or stopped).
 274      * @throws UnsupportedOperationException when the engine cannot deliver due to the functionality
 275      *                                       missing (ie. communication infrastructure not supported.
 276      */
 277     boolean deliver(CommInfrastructure busType, String topic, Object event);
 278
 279     /**
 280      * Attempts delivering of an String over communication infrastructure "busType".
 281      *
 282      * @param topic topic
 283      * @param event the event object to send
 284      * @return true if successful, false if a failure has occurred.
 285      * @throws IllegalArgumentException      when invalid or insufficient properties are provided
 286      * @throws IllegalStateException         when the engine is in a state where this operation is not
 287      *                                       permitted (ie. locked or stopped).
 288      * @throws UnsupportedOperationException when the engine cannot deliver due to the functionality
 289      *                                       missing (ie. communication infrastructure not supported.
 290      */
 291     boolean deliver(CommInfrastructure busType, String topic, String event);
 292
 293     /**
 294      * Invoked when the host goes into the active state.
 295      */
 296     void activate();
 297
 298     /**
 299      * Invoked when the host goes into the standby state.
 300      */
 301     void deactivate();
 302
 303     /**
 304      * produces a default telemetry configuration.
 305      *
 306      * @return policy engine configuration
 307      */
 308     Properties defaultTelemetryConfig();
 309 }