1 /* 2 * Portions of this software was developed by employees of the National Institute 3 * of Standards and Technology (NIST), an agency of the Federal Government and is 4 * being made available as a public service. Pursuant to title 17 United States 5 * Code Section 105, works of NIST employees are not subject to copyright 6 * protection in the United States. This software may be subject to foreign 7 * copyright. Permission in the United States and in foreign countries, to the 8 * extent that NIST may hold copyright, to use, copy, modify, create derivative 9 * works, and distribute this software and its documentation without fee is hereby 10 * granted on a non-exclusive basis, provided that this notice and disclaimer 11 * of warranty appears in all copies. 12 * 13 * THE SOFTWARE IS PROVIDED 'AS IS' WITHOUT ANY WARRANTY OF ANY KIND, EITHER 14 * EXPRESSED, IMPLIED, OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, ANY WARRANTY 15 * THAT THE SOFTWARE WILL CONFORM TO SPECIFICATIONS, ANY IMPLIED WARRANTIES OF 16 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND FREEDOM FROM 17 * INFRINGEMENT, AND ANY WARRANTY THAT THE DOCUMENTATION WILL CONFORM TO THE 18 * SOFTWARE, OR ANY WARRANTY THAT THE SOFTWARE WILL BE ERROR FREE. IN NO EVENT 19 * SHALL NIST BE LIABLE FOR ANY DAMAGES, INCLUDING, BUT NOT LIMITED TO, DIRECT, 20 * INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES, ARISING OUT OF, RESULTING FROM, 21 * OR IN ANY WAY CONNECTED WITH THIS SOFTWARE, WHETHER OR NOT BASED UPON WARRANTY, 22 * CONTRACT, TORT, OR OTHERWISE, WHETHER OR NOT INJURY WAS SUSTAINED BY PERSONS OR 23 * PROPERTY OR OTHERWISE, AND WHETHER OR NOT LOSS WAS SUSTAINED FROM, OR AROSE OUT 24 * OF THE RESULTS OF, OR USE OF, THE SOFTWARE OR SERVICES PROVIDED HEREUNDER. 25 */ 26 27 package gov.nist.secauto.metaschema.core.model; 28 29 import gov.nist.secauto.metaschema.core.datatype.markup.MarkupLine; 30 31 import javax.xml.namespace.QName; 32 33 import edu.umd.cs.findbugs.annotations.NonNull; 34 35 /** 36 * This marker interface indicates that the instance has a flag, field, or 37 * assembly name associated with it which will be used in JSON/YAML or XML to 38 * identify the data. 39 * 40 */ 41 public interface INamedInstance extends IInstance, INamedModelElement { 42 43 /** 44 * Retrieve the definition of this instance. 45 * 46 * @return the corresponding definition 47 */ 48 @NonNull 49 IDefinition getDefinition(); 50 51 /** 52 * Get the XML qualified name to use in XML. 53 * 54 * @return the XML qualified name, or {@code null} if there isn't one 55 */ 56 default QName getXmlQName() { 57 return new QName(getXmlNamespace(), getEffectiveName()); 58 } 59 60 /** 61 * Retrieve the XML namespace for this instance. 62 * 63 * @return the XML namespace or {@code null} if no namespace is defined 64 */ 65 default String getXmlNamespace() { 66 return getContainingModule().getXmlNamespace().toASCIIString(); 67 } 68 69 /** 70 * Get the current value from the provided {@code parentInstance} object. The 71 * provided object must be of the type associated with the definition containing 72 * this property. 73 * 74 * @param parentInstance 75 * the object associated with the definition containing this property 76 * @return the value if available, or {@code null} otherwise 77 */ 78 Object getValue(@NonNull Object parentInstance); 79 80 /** 81 * Generates a "coordinate" string for the provided information element 82 * instance. 83 * 84 * A coordinate consists of the element's: 85 * <ul> 86 * <li>containing Metaschema module's short name</li> 87 * <li>model type</li> 88 * <li>name</li> 89 * <li>hash code</li> 90 * <li>the hash code of the definition</li> 91 * </ul> 92 * 93 * @return the coordinate 94 */ 95 @SuppressWarnings("null") 96 @Override 97 default String toCoordinates() { 98 IDefinition definition = getDefinition(); 99 return String.format("%s:%s:%s@%d(%d)", 100 getContainingDefinition().getContainingModule().getShortName(), 101 getModelType(), 102 definition.getName(), 103 hashCode(), 104 definition.isInline() ? 0 : definition.hashCode()); 105 } 106 107 @Override 108 @NonNull 109 default String getEffectiveName() { 110 String result = getUseName(); 111 if (result == null) { 112 // fall back to the definition 113 IDefinition def = getDefinition(); 114 result = def.getEffectiveName(); 115 } 116 return result; 117 } 118 119 @Override 120 default String getEffectiveFormalName() { 121 String result = getFormalName(); 122 return result == null ? getDefinition().getEffectiveFormalName() : result; 123 } 124 125 @Override 126 default MarkupLine getEffectiveDescription() { 127 MarkupLine result = getDescription(); 128 return result == null ? getDefinition().getEffectiveDescription() : result; 129 } 130 }