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