001/* 002 * Portions of this software was developed by employees of the National Institute 003 * of Standards and Technology (NIST), an agency of the Federal Government and is 004 * being made available as a public service. Pursuant to title 17 United States 005 * Code Section 105, works of NIST employees are not subject to copyright 006 * protection in the United States. This software may be subject to foreign 007 * copyright. Permission in the United States and in foreign countries, to the 008 * extent that NIST may hold copyright, to use, copy, modify, create derivative 009 * works, and distribute this software and its documentation without fee is hereby 010 * granted on a non-exclusive basis, provided that this notice and disclaimer 011 * of warranty appears in all copies. 012 * 013 * THE SOFTWARE IS PROVIDED 'AS IS' WITHOUT ANY WARRANTY OF ANY KIND, EITHER 014 * EXPRESSED, IMPLIED, OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, ANY WARRANTY 015 * THAT THE SOFTWARE WILL CONFORM TO SPECIFICATIONS, ANY IMPLIED WARRANTIES OF 016 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND FREEDOM FROM 017 * INFRINGEMENT, AND ANY WARRANTY THAT THE DOCUMENTATION WILL CONFORM TO THE 018 * SOFTWARE, OR ANY WARRANTY THAT THE SOFTWARE WILL BE ERROR FREE. IN NO EVENT 019 * SHALL NIST BE LIABLE FOR ANY DAMAGES, INCLUDING, BUT NOT LIMITED TO, DIRECT, 020 * INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES, ARISING OUT OF, RESULTING FROM, 021 * OR IN ANY WAY CONNECTED WITH THIS SOFTWARE, WHETHER OR NOT BASED UPON WARRANTY, 022 * CONTRACT, TORT, OR OTHERWISE, WHETHER OR NOT INJURY WAS SUSTAINED BY PERSONS OR 023 * PROPERTY OR OTHERWISE, AND WHETHER OR NOT LOSS WAS SUSTAINED FROM, OR AROSE OUT 024 * OF THE RESULTS OF, OR USE OF, THE SOFTWARE OR SERVICES PROVIDED HEREUNDER. 025 */ 026 027package gov.nist.secauto.metaschema.core.model; 028 029import gov.nist.secauto.metaschema.core.datatype.markup.MarkupLine; 030 031import javax.xml.namespace.QName; 032 033import edu.umd.cs.findbugs.annotations.NonNull; 034 035/** 036 * This marker interface indicates that the instance has a flag, field, or 037 * assembly name associated with it which will be used in JSON/YAML or XML to 038 * identify the data. 039 * 040 */ 041public interface INamedInstance extends IInstance, INamedModelElement { 042 043 /** 044 * Retrieve the definition of this instance. 045 * 046 * @return the corresponding definition 047 */ 048 @NonNull 049 IDefinition getDefinition(); 050 051 /** 052 * Get the XML qualified name to use in XML. 053 * 054 * @return the XML qualified name, or {@code null} if there isn't one 055 */ 056 default QName getXmlQName() { 057 return new QName(getXmlNamespace(), getEffectiveName()); 058 } 059 060 /** 061 * Retrieve the XML namespace for this instance. 062 * 063 * @return the XML namespace or {@code null} if no namespace is defined 064 */ 065 default String getXmlNamespace() { 066 return getContainingModule().getXmlNamespace().toASCIIString(); 067 } 068 069 /** 070 * Get the current value from the provided {@code parentInstance} object. The 071 * provided object must be of the type associated with the definition containing 072 * this property. 073 * 074 * @param parentInstance 075 * the object associated with the definition containing this property 076 * @return the value if available, or {@code null} otherwise 077 */ 078 Object getValue(@NonNull Object parentInstance); 079 080 /** 081 * Generates a "coordinate" string for the provided information element 082 * instance. 083 * 084 * A coordinate consists of the element's: 085 * <ul> 086 * <li>containing Metaschema module's short name</li> 087 * <li>model type</li> 088 * <li>name</li> 089 * <li>hash code</li> 090 * <li>the hash code of the definition</li> 091 * </ul> 092 * 093 * @return the coordinate 094 */ 095 @SuppressWarnings("null") 096 @Override 097 default String toCoordinates() { 098 IDefinition definition = getDefinition(); 099 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}