model/basic-model/src/main/java/org/onap/policy/apex/model/basicmodel/concepts/AxReferenceKey.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.basicmodel.concepts;
  23
  24 import java.util.ArrayList;
  25 import java.util.List;
  26 import javax.persistence.Column;
  27 import javax.persistence.Embeddable;
  28 import javax.xml.bind.annotation.XmlAccessType;
  29 import javax.xml.bind.annotation.XmlAccessorType;
  30 import javax.xml.bind.annotation.XmlElement;
  31 import javax.xml.bind.annotation.XmlRootElement;
  32 import javax.xml.bind.annotation.XmlType;
  33 import org.onap.policy.apex.model.basicmodel.concepts.AxValidationResult.ValidationResult;
  34 import org.onap.policy.common.utils.validation.Assertions;
  35
  36 /**
  37  * A reference key identifies entities in the system that are contained in other entities. Every contained concept in
  38  * the system must have an {@link AxReferenceKey} to identify it. Non-contained first order concepts are identified
  39  * using an {@link AxArtifactKey} key.
  40  *
  41  * <p>An {@link AxReferenceKey} contains an {@link AxArtifactKey} key reference to the first order entity that contains
  42  * it. The local name of the reference key must uniquely identify the referenced concept among those concepts contained
  43  * in the reference key's parent. In other words, if a parent concept has more than one child, the local name in the key
  44  * of all its children must be unique.
  45  *
  46  * <p>If a reference key's parent is itself a reference key, then the parent's local name must be set in the reference
  47  * key. If the parent is a first order concept, then the parent's local name in the key will be set to NULL.
  48  *
  49  * <p>Key validation checks that the parent name and parent version fields match the NAME_REGEXP and
  50  * VERSION_REGEXP regular expressions respectively and that the local name fields match the
  51  * LOCAL_NAME_REGEXP regular expression.
  52  */
  53 @Embeddable
  54 @XmlAccessorType(XmlAccessType.FIELD)
  55 @XmlRootElement(name = "apexReferenceKey", namespace = "http://www.onap.org/policy/apex-pdp")
  56 @XmlType(name = "AxReferenceKey", namespace = "http://www.onap.org/policy/apex-pdp", propOrder = { "parentKeyName",
  57                 "parentKeyVersion", "parentLocalName", "localName" })
  58
  59 public class AxReferenceKey extends AxKey {
  60     private static final String PARENT_KEY_NAME = "parentKeyName";
  61     private static final String PARENT_KEY_VERSION = "parentKeyVersion";
  62     private static final String PARENT_LOCAL_NAME = "parentLocalName";
  63     private static final String LOCAL_NAME = "localName";
  64
  65     private static final long serialVersionUID = 8932717618579392561L;
  66
  67     /** Regular expression to specify the structure of local names in reference keys. */
  68     public static final String LOCAL_NAME_REGEXP = "[A-Za-z0-9\\-_\\.]+|^$";
  69
  70     /** Regular expression to specify the structure of IDs in reference keys. */
  71     public static final String REFERENCE_KEY_ID_REGEXP =
  72                     "[A-Za-z0-9\\-_]+:[0-9].[0-9].[0-9]:[A-Za-z0-9\\-_]+:[A-Za-z0-9\\-_]+";
  73
  74     private static final int PARENT_NAME_FIELD = 0;
  75     private static final int PARENT_VERSION_FIELD = 1;
  76     private static final int PARENT_LOCAL_NAME_FIELD = 2;
  77     private static final int LOCAL_NAME_FIELD = 3;
  78
  79     @Column(name = PARENT_KEY_NAME)
  80     @XmlElement(required = true)
  81     private String parentKeyName;
  82
  83     @Column(name = PARENT_KEY_VERSION)
  84     @XmlElement(required = true)
  85     private String parentKeyVersion;
  86
  87     @Column(name = PARENT_LOCAL_NAME)
  88     @XmlElement(required = true)
  89     private String parentLocalName;
  90
  91     @Column(name = LOCAL_NAME)
  92     @XmlElement(required = true)
  93     private String localName;
  94
  95     /**
  96      * The default constructor creates a null reference key.
  97      */
  98     public AxReferenceKey() {
  99         this(NULL_KEY_NAME, NULL_KEY_VERSION, NULL_KEY_NAME, NULL_KEY_NAME);
 100     }
 101
 102     /**
 103      * The Copy Constructor creates a key by copying another key.
 104      *
 105      * @param referenceKey
 106      *        the reference key to copy from
 107      */
 108     public AxReferenceKey(final AxReferenceKey referenceKey) {
 109         this(referenceKey.getParentKeyName(), referenceKey.getParentKeyVersion(), referenceKey.getParentLocalName(),
 110                         referenceKey.getLocalName());
 111     }
 112
 113     /**
 114      * Constructor to create a null reference key for the specified parent artifact key.
 115      *
 116      * @param axArtifactKey
 117      *        the parent artifact key of this reference key
 118      */
 119     public AxReferenceKey(final AxArtifactKey axArtifactKey) {
 120         this(axArtifactKey.getName(), axArtifactKey.getVersion(), NULL_KEY_NAME, NULL_KEY_NAME);
 121     }
 122
 123     /**
 124      * Constructor to create a reference key for the given parent artifact key with the given local name.
 125      *
 126      * @param axArtifactKey
 127      *        the parent artifact key of this reference key
 128      * @param localName
 129      *        the local name of this reference key
 130      */
 131     public AxReferenceKey(final AxArtifactKey axArtifactKey, final String localName) {
 132         this(axArtifactKey, NULL_KEY_NAME, localName);
 133     }
 134
 135     /**
 136      * Constructor to create a reference key for the given parent reference key with the given local name.
 137      *
 138      * @param parentReferenceKey
 139      *        the parent reference key of this reference key
 140      * @param localName
 141      *        the local name of this reference key
 142      */
 143     public AxReferenceKey(final AxReferenceKey parentReferenceKey, final String localName) {
 144         this(parentReferenceKey.getParentArtifactKey(), parentReferenceKey.getLocalName(), localName);
 145     }
 146
 147     /**
 148      * Constructor to create a reference key for the given parent reference key (specified by the parent reference key's
 149      * artifact key and local name) with the given local name.
 150      *
 151      * @param axArtifactKey
 152      *        the artifact key of the parent reference key of this reference key
 153      * @param parentLocalName
 154      *        the local name of the parent reference key of this reference key
 155      * @param localName
 156      *        the local name of this reference key
 157      */
 158     public AxReferenceKey(final AxArtifactKey axArtifactKey, final String parentLocalName, final String localName) {
 159         this(axArtifactKey.getName(), axArtifactKey.getVersion(), parentLocalName, localName);
 160     }
 161
 162     /**
 163      * Constructor to create a reference key for the given parent artifact key (specified by the parent artifact key's
 164      * name and version) with the given local name.
 165      *
 166      * @param parentKeyName
 167      *        the name of the parent artifact key of this reference key
 168      * @param parentKeyVersion
 169      *        the version of the parent artifact key of this reference key
 170      * @param localName
 171      *        the local name of this reference key
 172      */
 173     public AxReferenceKey(final String parentKeyName, final String parentKeyVersion, final String localName) {
 174         this(parentKeyName, parentKeyVersion, NULL_KEY_NAME, localName);
 175     }
 176
 177     /**
 178      * Constructor to create a reference key for the given parent key (specified by the parent key's name, version nad
 179      * local name) with the given local name.
 180      *
 181      * @param parentKeyName
 182      *        the parent key name of this reference key
 183      * @param parentKeyVersion
 184      *        the parent key version of this reference key
 185      * @param parentLocalName
 186      *        the parent local name of this reference key
 187      * @param localName
 188      *        the local name of this reference key
 189      */
 190     public AxReferenceKey(final String parentKeyName, final String parentKeyVersion, final String parentLocalName,
 191                     final String localName) {
 192         super();
 193         this.parentKeyName = Assertions.validateStringParameter(PARENT_KEY_NAME, parentKeyName, NAME_REGEXP);
 194         this.parentKeyVersion = Assertions.validateStringParameter(PARENT_KEY_VERSION, parentKeyVersion,
 195                         VERSION_REGEXP);
 196         this.parentLocalName = Assertions.validateStringParameter(PARENT_LOCAL_NAME, parentLocalName,
 197                         LOCAL_NAME_REGEXP);
 198         this.localName = Assertions.validateStringParameter(LOCAL_NAME, localName, LOCAL_NAME_REGEXP);
 199     }
 200
 201     /**
 202      * Constructor to create a key from the specified key ID.
 203      *
 204      * @param id
 205      *        the key ID in a format that respects the KEY_ID_REGEXP
 206      */
 207     public AxReferenceKey(final String id) {
 208         final String conditionedId = Assertions.validateStringParameter("id", id, REFERENCE_KEY_ID_REGEXP);
 209
 210         // Split on colon, if the id passes the regular expression test above
 211         // it'll have just three colons separating the parent name,
 212         // parent version, parent local name, and and local name
 213         // No need for range checks or size checks on the array
 214         final String[] nameVersionNameArray = conditionedId.split(":");
 215
 216         // Initiate the new key
 217         parentKeyName = Assertions.validateStringParameter(PARENT_KEY_NAME, nameVersionNameArray[PARENT_NAME_FIELD],
 218                         NAME_REGEXP);
 219         parentKeyVersion = Assertions.validateStringParameter(PARENT_KEY_VERSION,
 220                         nameVersionNameArray[PARENT_VERSION_FIELD], VERSION_REGEXP);
 221         parentLocalName = Assertions.validateStringParameter(PARENT_LOCAL_NAME,
 222                         nameVersionNameArray[PARENT_LOCAL_NAME_FIELD], LOCAL_NAME_REGEXP);
 223         localName = Assertions.validateStringParameter(LOCAL_NAME, nameVersionNameArray[LOCAL_NAME_FIELD],
 224                         LOCAL_NAME_REGEXP);
 225     }
 226
 227     /**
 228      * Get a null reference key.
 229      *
 230      * @return a null reference key
 231      */
 232     public static AxReferenceKey getNullKey() {
 233         return new AxReferenceKey(AxKey.NULL_KEY_NAME, AxKey.NULL_KEY_VERSION, AxKey.NULL_KEY_NAME,
 234                         AxKey.NULL_KEY_NAME);
 235     }
 236
 237     /**
 238      * {@inheritDoc}.
 239      */
 240     @Override
 241     public AxReferenceKey getKey() {
 242         return this;
 243     }
 244
 245     /**
 246      * {@inheritDoc}.
 247      */
 248     @Override
 249     public List<AxKey> getKeys() {
 250         final List<AxKey> keyList = new ArrayList<>();
 251         keyList.add(getKey());
 252         return keyList;
 253     }
 254
 255     /**
 256      * {@inheritDoc}.
 257      */
 258     @Override
 259     public String getId() {
 260         return parentKeyName + ':' + parentKeyVersion + ':' + parentLocalName + ':' + localName;
 261     }
 262
 263     /**
 264      * Gets the parent artifact key of this reference key.
 265      *
 266      * @return the parent artifact key of this reference key
 267      */
 268     public AxArtifactKey getParentArtifactKey() {
 269         return new AxArtifactKey(parentKeyName, parentKeyVersion);
 270     }
 271
 272     /**
 273      * Gets the parent reference key of this reference key.
 274      *
 275      * @return the parent reference key of this reference key
 276      */
 277     public AxReferenceKey getParentReferenceKey() {
 278         return new AxReferenceKey(parentKeyName, parentKeyVersion, parentLocalName);
 279     }
 280
 281     /**
 282      * Sets the parent artifact key of this reference key.
 283      *
 284      * @param parentKey
 285      *        the parent artifact key of this reference key
 286      */
 287     public void setParentArtifactKey(final AxArtifactKey parentKey) {
 288         Assertions.argumentNotNull(parentKey, "parentKey may not be null");
 289
 290         parentKeyName = parentKey.getName();
 291         parentKeyVersion = parentKey.getVersion();
 292         parentLocalName = NULL_KEY_NAME;
 293     }
 294
 295     /**
 296      * Sets the parent reference key of this reference key.
 297      *
 298      * @param parentKey
 299      *        the parent reference key of this reference key
 300      */
 301     public void setParentReferenceKey(final AxReferenceKey parentKey) {
 302         Assertions.argumentNotNull(parentKey, "parentKey may not be null");
 303
 304         parentKeyName = parentKey.getParentKeyName();
 305         parentKeyVersion = parentKey.getParentKeyVersion();
 306         parentLocalName = parentKey.getLocalName();
 307     }
 308
 309     /**
 310      * Gets the parent key name of this reference key.
 311      *
 312      * @return the parent key name of this reference key
 313      */
 314     public String getParentKeyName() {
 315         return parentKeyName;
 316     }
 317
 318     /**
 319      * Sets the parent key name of this reference key.
 320      *
 321      * @param parentKeyName
 322      *        the parent key name of this reference key
 323      */
 324     public void setParentKeyName(final String parentKeyName) {
 325         this.parentKeyName = Assertions.validateStringParameter(PARENT_KEY_NAME, parentKeyName, NAME_REGEXP);
 326     }
 327
 328     /**
 329      * Gets the parent key version of this reference key.
 330      *
 331      * @return the parent key version of this reference key
 332      */
 333     public String getParentKeyVersion() {
 334         return parentKeyVersion;
 335     }
 336
 337     /**
 338      * Sets the parent key version of this reference key.
 339      *
 340      * @param parentKeyVersion
 341      *        the parent key version of this reference key
 342      */
 343     public void setParentKeyVersion(final String parentKeyVersion) {
 344         this.parentKeyVersion = Assertions.validateStringParameter(PARENT_KEY_VERSION, parentKeyVersion,
 345                         VERSION_REGEXP);
 346     }
 347
 348     /**
 349      * Gets the parent local name of this reference key.
 350      *
 351      * @return the parent local name of this reference key
 352      */
 353     public String getParentLocalName() {
 354         return parentLocalName;
 355     }
 356
 357     /**
 358      * Sets the parent local name of this reference key.
 359      *
 360      * @param parentLocalName
 361      *        the parent local name of this reference key
 362      */
 363     public void setParentLocalName(final String parentLocalName) {
 364         this.parentLocalName = Assertions.validateStringParameter(PARENT_LOCAL_NAME, parentLocalName,
 365                         LOCAL_NAME_REGEXP);
 366     }
 367
 368     /**
 369      * Gets the local name of this reference key.
 370      *
 371      * @return the local name of this reference key
 372      */
 373     public String getLocalName() {
 374         return localName;
 375     }
 376
 377     /**
 378      * Sets the local name of this reference key.
 379      *
 380      * @param localName
 381      *        the local name of this reference key
 382      */
 383     public void setLocalName(final String localName) {
 384         this.localName = Assertions.validateStringParameter(LOCAL_NAME, localName, LOCAL_NAME_REGEXP);
 385     }
 386
 387     /**
 388      * {@inheritDoc}.
 389      */
 390     @Override
 391     public AxKey.Compatibility getCompatibility(final AxKey otherKey) {
 392         if (!(otherKey instanceof AxReferenceKey)) {
 393             return Compatibility.DIFFERENT;
 394         }
 395         final AxReferenceKey otherReferenceKey = (AxReferenceKey) otherKey;
 396
 397         return this.getParentArtifactKey().getCompatibility(otherReferenceKey.getParentArtifactKey());
 398     }
 399
 400     /**
 401      * {@inheritDoc}.
 402      */
 403     @Override
 404     public boolean isCompatible(final AxKey otherKey) {
 405         if (!(otherKey instanceof AxReferenceKey)) {
 406             return false;
 407         }
 408         final AxReferenceKey otherReferenceKey = (AxReferenceKey) otherKey;
 409
 410         return this.getParentArtifactKey().isCompatible(otherReferenceKey.getParentArtifactKey());
 411     }
 412
 413     /**
 414      * {@inheritDoc}.
 415      */
 416     @Override
 417     public AxValidationResult validate(final AxValidationResult result) {
 418         final String parentNameValidationErrorMessage = Assertions.getStringParameterValidationMessage(PARENT_KEY_NAME,
 419                         parentKeyName, NAME_REGEXP);
 420         if (parentNameValidationErrorMessage != null) {
 421             result.addValidationMessage(new AxValidationMessage(this, this.getClass(), ValidationResult.INVALID,
 422                             "parentKeyName invalid-" + parentNameValidationErrorMessage));
 423         }
 424
 425         final String parentKeyVersionValidationErrorMessage = Assertions
 426                         .getStringParameterValidationMessage(PARENT_KEY_VERSION, parentKeyVersion, VERSION_REGEXP);
 427         if (parentKeyVersionValidationErrorMessage != null) {
 428             result.addValidationMessage(new AxValidationMessage(this, this.getClass(), ValidationResult.INVALID,
 429                             "parentKeyVersion invalid-" + parentKeyVersionValidationErrorMessage));
 430         }
 431
 432         final String parentLocalNameValidationErrorMessage = Assertions
 433                         .getStringParameterValidationMessage(PARENT_LOCAL_NAME, parentLocalName, LOCAL_NAME_REGEXP);
 434         if (parentLocalNameValidationErrorMessage != null) {
 435             result.addValidationMessage(new AxValidationMessage(this, this.getClass(), ValidationResult.INVALID,
 436                             "parentLocalName invalid-" + parentLocalNameValidationErrorMessage));
 437         }
 438
 439         final String localNameValidationErrorMessage = Assertions.getStringParameterValidationMessage(LOCAL_NAME,
 440                         localName, LOCAL_NAME_REGEXP);
 441         if (localNameValidationErrorMessage != null) {
 442             result.addValidationMessage(new AxValidationMessage(this, this.getClass(), ValidationResult.INVALID,
 443                             "localName invalid-" + localNameValidationErrorMessage));
 444         }
 445
 446         return result;
 447     }
 448
 449     /**
 450      * {@inheritDoc}.
 451      */
 452     @Override
 453     public void clean() {
 454         parentKeyName = Assertions.validateStringParameter(PARENT_KEY_NAME, parentKeyName, NAME_REGEXP);
 455         parentKeyVersion = Assertions.validateStringParameter(PARENT_KEY_VERSION, parentKeyVersion, VERSION_REGEXP);
 456         parentLocalName = Assertions.validateStringParameter(PARENT_LOCAL_NAME, parentLocalName, LOCAL_NAME_REGEXP);
 457         localName = Assertions.validateStringParameter(LOCAL_NAME, localName, LOCAL_NAME_REGEXP);
 458     }
 459
 460     /**
 461      * {@inheritDoc}.
 462      */
 463     @Override
 464     public String toString() {
 465         final StringBuilder builder = new StringBuilder();
 466         builder.append(this.getClass().getSimpleName());
 467         builder.append(":(");
 468         builder.append("parentKeyName=");
 469         builder.append(parentKeyName);
 470         builder.append(",parentKeyVersion=");
 471         builder.append(parentKeyVersion);
 472         builder.append(",parentLocalName=");
 473         builder.append(parentLocalName);
 474         builder.append(",localName=");
 475         builder.append(localName);
 476         builder.append(")");
 477         return builder.toString();
 478     }
 479
 480     /**
 481      * {@inheritDoc}.
 482      */
 483     @Override
 484     public AxConcept copyTo(final AxConcept target) {
 485         Assertions.argumentNotNull(target, "target may not be null");
 486
 487         final Object copyObject = target;
 488         Assertions.instanceOf(copyObject, AxReferenceKey.class);
 489
 490         final AxReferenceKey copy = ((AxReferenceKey) copyObject);
 491         copy.setParentKeyName(parentKeyName);
 492         copy.setParentKeyVersion(parentKeyVersion);
 493         copy.setLocalName(localName);
 494         copy.setParentLocalName(parentLocalName);
 495
 496         return copy;
 497     }
 498
 499     /**
 500      * {@inheritDoc}.
 501      */
 502     @Override
 503     public int hashCode() {
 504         final int prime = 31;
 505         int result = 1;
 506         result = prime * result + parentKeyName.hashCode();
 507         result = prime * result + parentKeyVersion.hashCode();
 508         result = prime * result + parentLocalName.hashCode();
 509         result = prime * result + localName.hashCode();
 510         return result;
 511     }
 512
 513     /**
 514      * {@inheritDoc}.
 515      */
 516     @Override
 517     public boolean equals(final Object obj) {
 518         if (obj == null) {
 519             throw new IllegalArgumentException("comparison object may not be null");
 520         }
 521
 522         if (this == obj) {
 523             return true;
 524         }
 525
 526         if (getClass() != obj.getClass()) {
 527             return false;
 528         }
 529
 530         final AxReferenceKey other = (AxReferenceKey) obj;
 531
 532         if (!parentKeyName.equals(other.parentKeyName)) {
 533             return false;
 534         }
 535         if (!parentKeyVersion.equals(other.parentKeyVersion)) {
 536             return false;
 537         }
 538         if (!parentLocalName.equals(other.parentLocalName)) {
 539             return false;
 540         }
 541         return localName.equals(other.localName);
 542     }
 543
 544     /**
 545      * {@inheritDoc}.
 546      */
 547     @Override
 548     public int compareTo(final AxConcept otherObj) {
 549         Assertions.argumentNotNull(otherObj, "comparison object may not be null");
 550
 551         if (this == otherObj) {
 552             return 0;
 553         }
 554         if (getClass() != otherObj.getClass()) {
 555             return this.hashCode() - otherObj.hashCode();
 556         }
 557
 558         final AxReferenceKey other = (AxReferenceKey) otherObj;
 559         if (!parentKeyName.equals(other.parentKeyName)) {
 560             return parentKeyName.compareTo(other.parentKeyName);
 561         }
 562         if (!parentKeyVersion.equals(other.parentKeyVersion)) {
 563             return parentKeyVersion.compareTo(other.parentKeyVersion);
 564         }
 565         if (!parentLocalName.equals(other.parentLocalName)) {
 566             return parentLocalName.compareTo(other.parentLocalName);
 567         }
 568         return localName.compareTo(other.localName);
 569     }
 570 }