model/policy-model/src/main/java/org/onap/policy/apex/model/policymodel/concepts/AxStateOutput.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.model.policymodel.concepts;
  23
  24 import java.util.List;
  25 import javax.persistence.AttributeOverride;
  26 import javax.persistence.AttributeOverrides;
  27 import javax.persistence.Column;
  28 import javax.persistence.Embedded;
  29 import javax.persistence.EmbeddedId;
  30 import javax.persistence.Entity;
  31 import javax.persistence.Table;
  32 import javax.xml.bind.annotation.XmlAccessType;
  33 import javax.xml.bind.annotation.XmlAccessorType;
  34 import javax.xml.bind.annotation.XmlElement;
  35 import javax.xml.bind.annotation.XmlRootElement;
  36 import javax.xml.bind.annotation.XmlType;
  37 import org.onap.policy.apex.model.basicmodel.concepts.AxArtifactKey;
  38 import org.onap.policy.apex.model.basicmodel.concepts.AxConcept;
  39 import org.onap.policy.apex.model.basicmodel.concepts.AxKey;
  40 import org.onap.policy.apex.model.basicmodel.concepts.AxKeyUse;
  41 import org.onap.policy.apex.model.basicmodel.concepts.AxReferenceKey;
  42 import org.onap.policy.apex.model.basicmodel.concepts.AxValidationMessage;
  43 import org.onap.policy.apex.model.basicmodel.concepts.AxValidationResult;
  44 import org.onap.policy.apex.model.basicmodel.concepts.AxValidationResult.ValidationResult;
  45 import org.onap.policy.common.utils.validation.Assertions;
  46
  47 /**
  48  * This class defines a single output that a state can have. A state can have many outputs with each
  49  * output defined as an instance of this class. Each state output defines the output event that will
  50  * be emitted when this output is selected and optionally the next state that is executed when this
  51  * state output is selected. If no next state is defined (the next state is a null
  52  * {@link AxReferenceKey} key), then this state output outputs its event to an external system and
  53  * is an output state for the full policy.
  54  *
  55  * <p>During validation of a state output, the validation checks listed below are executed:
  56  * <ol>
  57  * <li>The state output key must not be a null key and must be valid, see validation in
  58  * {@link AxReferenceKey}
  59  * <li>The outgoing event key must not be a null key and must be valid, see validation in
  60  * {@link AxArtifactKey}
  61  * <li>The next state key must be valid, see validation in {@link AxReferenceKey}
  62  * </ol>
  63  */
  64
  65 @Entity
  66 @Table(name = "AxStateOutput")
  67
  68 @XmlAccessorType(XmlAccessType.FIELD)
  69 @XmlRootElement(name = "apexStateOutput", namespace = "http://www.onap.org/policy/apex-pdp")
  70 @XmlType(name = "AxStateOutput", namespace = "http://www.onap.org/policy/apex-pdp",
  71         propOrder = {"key", "outgoingEvent", "nextState"})
  72
  73 public class AxStateOutput extends AxConcept {
  74     private static final long serialVersionUID = 8041771382337655535L;
  75
  76     @EmbeddedId
  77     @XmlElement(name = "key", required = true)
  78     private AxReferenceKey key;
  79
  80     // @formatter:off
  81     @Embedded
  82     @AttributeOverrides({@AttributeOverride(name = "name", column = @Column(name = "outgoingEventName")),
  83             @AttributeOverride(name = "version", column = @Column(name = "outgoingEventVersion"))})
  84     @Column(name = "outgoingEvent")
  85     @XmlElement(required = true)
  86     private AxArtifactKey outgoingEvent;
  87
  88     @Embedded
  89     @AttributeOverrides({@AttributeOverride(name = "parentKeyName", column = @Column(name = "nextStateParentKeyName")),
  90             @AttributeOverride(name = "parentKeyVersion", column = @Column(name = "nextStateParentKeyVersion")),
  91             @AttributeOverride(name = "parentLocalName", column = @Column(name = "nextStateParentLocalName")),
  92             @AttributeOverride(name = "localName", column = @Column(name = "nextStateLocalName"))})
  93     @Column(name = "nextState")
  94     @XmlElement(required = true)
  95     private AxReferenceKey nextState;
  96     // @formatter:on
  97
  98     /**
  99      * The Default Constructor creates a state output instance with a null reference key, outgoing
 100      * event key and next state reference key.
 101      */
 102     public AxStateOutput() {
 103         this(new AxReferenceKey());
 104     }
 105
 106     /**
 107      * Copy constructor.
 108      *
 109      * @param copyConcept the concept to copy from
 110      */
 111     public AxStateOutput(final AxStateOutput copyConcept) {
 112         super(copyConcept);
 113     }
 114
 115     /**
 116      * The Keyed Constructor creates a state output instance with the given reference key, outgoing
 117      * event key and next state reference key.
 118      *
 119      * @param key the reference key for the state output
 120      */
 121     public AxStateOutput(final AxReferenceKey key) {
 122         this(key, // Key
 123                 AxArtifactKey.getNullKey(), // Outgoing Event
 124                 AxReferenceKey.getNullKey() // Next State
 125         );
 126     }
 127
 128     /**
 129      * This Constructor creates a state output with a reference key composed of the given parent key
 130      * and with a local name composed from the parent key local name concatenated with the next
 131      * state's local name. The next state and outgoing event of the state output are set as
 132      * specified.
 133      *
 134      * @param parentKey the parent key of the state output
 135      * @param nextState the next state to which execution will pass on use of this state output
 136      * @param outgoingEvent the outgoing event emitted on use of this state output
 137      */
 138     public AxStateOutput(final AxReferenceKey parentKey, final AxReferenceKey nextState,
 139             final AxArtifactKey outgoingEvent) {
 140         this(new AxReferenceKey(parentKey, parentKey.getLocalName() + '_' + nextState.getLocalName()), outgoingEvent,
 141                 nextState);
 142     }
 143
 144     /**
 145      * This Constructor creates a state output with the specified reference key. The next state and
 146      * outgoing event of the state output are set as specified.
 147      *
 148      * @param key the key
 149      * @param nextState the next state to which execution will pass on use of this state output
 150      * @param outgoingEvent the outgoing event emitted on use of this state output
 151      */
 152     public AxStateOutput(final AxReferenceKey key, final AxArtifactKey outgoingEvent, final AxReferenceKey nextState) {
 153         super();
 154         Assertions.argumentNotNull(key, "key may not be null");
 155         Assertions.argumentNotNull(outgoingEvent, "outgoingEvent may not be null");
 156         Assertions.argumentNotNull(nextState, "nextState may not be null");
 157
 158         this.key = key;
 159         this.outgoingEvent = outgoingEvent;
 160         this.nextState = nextState;
 161     }
 162
 163     /**
 164      * {@inheritDoc}.
 165      */
 166     @Override
 167     public AxReferenceKey getKey() {
 168         return key;
 169     }
 170
 171     /**
 172      * {@inheritDoc}.
 173      */
 174     @Override
 175     public List<AxKey> getKeys() {
 176         final List<AxKey> keyList = key.getKeys();
 177         keyList.add(new AxKeyUse(outgoingEvent));
 178
 179         if (!nextState.equals(AxReferenceKey.getNullKey())) {
 180             keyList.add(new AxKeyUse(nextState));
 181         }
 182
 183         return keyList;
 184     }
 185
 186     /**
 187      * Sets the reference key for the state output.
 188      *
 189      * @param key the reference key for the state output
 190      */
 191     public void setKey(final AxReferenceKey key) {
 192         Assertions.argumentNotNull(key, "key may not be null");
 193         this.key = key;
 194     }
 195
 196     /**
 197      * Gets the outgoing event emitted on use of this state output.
 198      *
 199      * @return the outgoing event emitted on use of this state output
 200      */
 201     public AxArtifactKey getOutgingEvent() {
 202         return outgoingEvent;
 203     }
 204
 205     /**
 206      * Sets the outgoing event emitted on use of this state output.
 207      *
 208      * @param outgoingEvent the outgoing event emitted on use of this state output
 209      */
 210     public void setOutgoingEvent(final AxArtifactKey outgoingEvent) {
 211         Assertions.argumentNotNull(outgoingEvent, "outgoingEvent may not be null");
 212         this.outgoingEvent = outgoingEvent;
 213     }
 214
 215     /**
 216      * Gets the next state to which execution will pass on use of this state output.
 217      *
 218      * @return the next state to which execution will pass on use of this state output
 219      */
 220     public AxReferenceKey getNextState() {
 221         return nextState;
 222     }
 223
 224     /**
 225      * Sets the next state to which execution will pass on use of this state output.
 226      *
 227      * @param nextState the next state to which execution will pass on use of this state output
 228      */
 229     public void setNextState(final AxReferenceKey nextState) {
 230         Assertions.argumentNotNull(nextState, "nextState may not be null");
 231         this.nextState = nextState;
 232     }
 233
 234     /**
 235      * {@inheritDoc}.
 236      */
 237     @Override
 238     public AxValidationResult validate(final AxValidationResult resultIn) {
 239         AxValidationResult result = resultIn;
 240
 241         if (key.equals(AxReferenceKey.getNullKey())) {
 242             result.addValidationMessage(
 243                     new AxValidationMessage(key, this.getClass(), ValidationResult.INVALID, "key is a null key"));
 244         }
 245
 246         result = key.validate(result);
 247
 248         if (outgoingEvent.equals(AxArtifactKey.getNullKey())) {
 249             result.addValidationMessage(new AxValidationMessage(key, this.getClass(), ValidationResult.INVALID,
 250                     "outgoingEvent reference is a null key, an outgoing event must be specified"));
 251         }
 252         result = outgoingEvent.validate(result);
 253
 254         // Note: Null keys are allowed on nextState as there may not be a next state
 255         result = nextState.validate(result);
 256
 257         return result;
 258     }
 259
 260     /**
 261      * {@inheritDoc}.
 262      */
 263     @Override
 264     public void clean() {
 265         key.clean();
 266         outgoingEvent.clean();
 267         nextState.clean();
 268     }
 269
 270     /**
 271      * {@inheritDoc}.
 272      */
 273     @Override
 274     public String toString() {
 275         final StringBuilder builder = new StringBuilder();
 276         builder.append(this.getClass().getSimpleName());
 277         builder.append(":(");
 278         builder.append("stateKey=");
 279         builder.append(key);
 280         builder.append(",outgoingEvent=");
 281         builder.append(outgoingEvent);
 282         builder.append(",nextState=");
 283         builder.append(nextState);
 284         builder.append(")");
 285         return builder.toString();
 286     }
 287
 288     /**
 289      * {@inheritDoc}.
 290      */
 291     @Override
 292     public AxConcept copyTo(final AxConcept targetObject) {
 293         Assertions.argumentNotNull(targetObject, "target may not be null");
 294
 295         final Object copyObject = targetObject;
 296         Assertions.instanceOf(copyObject, AxStateOutput.class);
 297
 298         final AxStateOutput copy = ((AxStateOutput) copyObject);
 299         copy.setKey(new AxReferenceKey(key));
 300         copy.setOutgoingEvent(new AxArtifactKey(outgoingEvent));
 301         copy.setNextState(nextState);
 302
 303         return copy;
 304     }
 305
 306     /**
 307      * {@inheritDoc}.
 308      */
 309     @Override
 310     public int hashCode() {
 311         final int prime = 31;
 312         int result = 1;
 313         result = prime * result + key.hashCode();
 314         result = prime * result + outgoingEvent.hashCode();
 315         result = prime * result + nextState.hashCode();
 316         return result;
 317     }
 318
 319     /**
 320      * {@inheritDoc}.
 321      */
 322     @Override
 323     public boolean equals(final Object obj) {
 324         if (obj == null) {
 325             return false;
 326         }
 327         if (this == obj) {
 328             return true;
 329         }
 330         if (getClass() != obj.getClass()) {
 331             return false;
 332         }
 333
 334         final AxStateOutput other = (AxStateOutput) obj;
 335         if (!key.equals(other.key)) {
 336             return false;
 337         }
 338         if (!outgoingEvent.equals(other.outgoingEvent)) {
 339             return false;
 340         }
 341         return nextState.equals(other.nextState);
 342     }
 343
 344     /**
 345      * {@inheritDoc}.
 346      */
 347     @Override
 348     public int compareTo(final AxConcept otherObj) {
 349         if (otherObj == null) {
 350             return -1;
 351         }
 352         if (this == otherObj) {
 353             return 0;
 354         }
 355         if (getClass() != otherObj.getClass()) {
 356             return this.hashCode() - otherObj.hashCode();
 357         }
 358
 359         final AxStateOutput other = (AxStateOutput) otherObj;
 360         if (!key.equals(other.key)) {
 361             return key.compareTo(other.key);
 362         }
 363         if (!outgoingEvent.equals(other.outgoingEvent)) {
 364             return outgoingEvent.compareTo(other.outgoingEvent);
 365         }
 366         return nextState.compareTo(other.nextState);
 367     }
 368 }