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.metapath.item.node; 028 029import gov.nist.secauto.metaschema.core.metapath.MetapathExpression; 030import gov.nist.secauto.metaschema.core.model.IAssemblyDefinition; 031import gov.nist.secauto.metaschema.core.model.IAssemblyInstance; 032import gov.nist.secauto.metaschema.core.model.IFieldDefinition; 033import gov.nist.secauto.metaschema.core.model.IFieldInstance; 034import gov.nist.secauto.metaschema.core.model.IFlagDefinition; 035import gov.nist.secauto.metaschema.core.model.IFlagInstance; 036import gov.nist.secauto.metaschema.core.model.IModule; 037 038import java.net.URI; 039 040import edu.umd.cs.findbugs.annotations.NonNull; 041import edu.umd.cs.findbugs.annotations.Nullable; 042 043/** 044 * This factory interface is used to create {@link INodeItem} objects of various 045 * types. 046 * <p> 047 * A singleton instance of this factory can be acquired using the 048 * {@link #instance()} method. 049 */ 050public interface INodeItemFactory { 051 052 /** 053 * Get the singleton instance of the default node factory. 054 * 055 * @return the node factory instance 056 */ 057 @NonNull 058 static INodeItemFactory instance() { 059 return DefaultNodeItemFactory.instance(); 060 } 061 062 /** 063 * Create a new document node item for the provided {@code definition}. 064 * 065 * @param definition 066 * the root assembly definition to create the document item for. 067 * @param documentUri 068 * the uniform resource identifier of the document 069 * @param value 070 * the root item's associated data 071 * @return the new node item 072 */ 073 @NonNull 074 IDocumentNodeItem newDocumentNodeItem( 075 @NonNull IAssemblyDefinition definition, 076 @NonNull URI documentUri, 077 @NonNull Object value); 078 079 /** 080 * Create a new Metaschema node item for the provided {@code metaschema}. 081 * 082 * @param module 083 * the Metaschema to create the item for. 084 * @return the new node item 085 */ 086 @NonNull 087 IModuleNodeItem newModuleNodeItem(@NonNull IModule module); 088 089 /** 090 * Create a new {@link IFlagNodeItem}, with no associated value, based on the 091 * provided flag definition. 092 * 093 * @param definition 094 * the flag definition 095 * @param parent 096 * the item for the Metaschema containing the definition 097 * @return the new flag node item 098 */ 099 @NonNull 100 default IFlagNodeItem newFlagNodeItem( 101 @NonNull IFlagDefinition definition, 102 @NonNull IModuleNodeItem parent) { 103 return new FlagDefinitionNodeItemImpl(definition, parent); 104 } 105 106 /** 107 * Create a new {@link IFlagNodeItem} based on the provided flag instance. 108 * 109 * @param instance 110 * the flag instance 111 * @param parent 112 * the node item containing the flag 113 * @return the new flag node item 114 */ 115 @NonNull 116 default IFlagNodeItem newFlagNodeItem( 117 @NonNull IFlagInstance instance, 118 @NonNull IModelNodeItem<?, ?> parent) { 119 return new FlagInstanceNoValueNodeItemImpl(instance, parent); 120 } 121 122 /** 123 * Create a new {@link IFlagNodeItem} based on the provided flag instance. 124 * 125 * @param instance 126 * the flag instance 127 * @param parent 128 * the node item containing the flag 129 * @param value 130 * the item's associated data 131 * @return the new flag node item 132 */ 133 @NonNull 134 default IFlagNodeItem newFlagNodeItem( 135 @NonNull IFlagInstance instance, 136 @NonNull IModelNodeItem<?, ?> parent, 137 @NonNull Object value) { 138 return new FlagInstanceNodeItemImpl(instance, parent, value); 139 } 140 141 /** 142 * Create a new {@link IFieldNodeItem} based on the provided definition, which 143 * is expected to be a global definition within the provided Metaschema. 144 * 145 * @param definition 146 * the global definition 147 * @param metaschema 148 * the Metaschema containing the definition 149 * @return the new field node item 150 */ 151 @NonNull 152 IFieldNodeItem newFieldNodeItem( 153 @NonNull IFieldDefinition definition, 154 @NonNull IModuleNodeItem metaschema); 155 156 /** 157 * Create a new {@link IFieldNodeItem} that is detached from a Metaschema. 158 * 159 * @param definition 160 * the global definition 161 * @param baseUri 162 * the base URI to use for this node item when evaluating a 163 * {@link MetapathExpression} 164 * @return the new field node item 165 */ 166 @NonNull 167 IFieldNodeItem newFieldNodeItem( 168 @NonNull IFieldDefinition definition, 169 @Nullable URI baseUri); 170 171 /** 172 * Create a new {@link IFieldNodeItem} that is based on a Metaschema instance. 173 * <p> 174 * A single instance of this item is expected to represent the possibility in a 175 * metaschema of a series of instance values. 176 * 177 * @param instance 178 * the Metaschema field instance 179 * @param parent 180 * the parent node item 181 * @return the new field node item 182 */ 183 @NonNull 184 IFieldNodeItem newFieldNodeItem( 185 @NonNull IFieldInstance instance, 186 @NonNull IAssemblyNodeItem parent); 187 188 /** 189 * Create a new {@link IFieldNodeItem} that is based on a Metaschema instance 190 * with associated data. 191 * 192 * @param instance 193 * the Metaschema field instance 194 * @param parent 195 * the parent node item 196 * @param position 197 * the data item's position in the sequence of data items for the 198 * instance 199 * @param value 200 * the item's associated data 201 * @return the new field node item 202 */ 203 @NonNull 204 IFieldNodeItem newFieldNodeItem( 205 @NonNull IFieldInstance instance, 206 @NonNull IAssemblyNodeItem parent, 207 int position, 208 @NonNull Object value); 209 210 /** 211 * Create a new {@link IAssemblyNodeItem} that is detached from a Metaschema. 212 * 213 * @param definition 214 * the global definition 215 * @return the new assembly node item 216 */ 217 @NonNull 218 default IAssemblyNodeItem newAssemblyNodeItem( 219 @NonNull IAssemblyDefinition definition) { 220 return newAssemblyNodeItem(definition, (URI) null); 221 } 222 223 /** 224 * Create a new {@link IAssemblyNodeItem} based on the provided definition, 225 * which is expected to be a global definition within the provided Metaschema. 226 * 227 * @param definition 228 * the global definition 229 * @param metaschema 230 * the Metaschema containing the definition 231 * @return the new assembly node item 232 */ 233 @NonNull 234 IAssemblyNodeItem newAssemblyNodeItem( 235 @NonNull IAssemblyDefinition definition, 236 @NonNull IModuleNodeItem metaschema); 237 238 /** 239 * Create a new {@link IAssemblyNodeItem} that is detached from a Metaschema. 240 * 241 * @param definition 242 * the global definition 243 * @param baseUri 244 * the base URI to use for this node item when evaluating a 245 * {@link MetapathExpression} 246 * @return the new assembly node item 247 */ 248 @NonNull 249 IAssemblyNodeItem newAssemblyNodeItem( 250 @NonNull IAssemblyDefinition definition, 251 @Nullable URI baseUri); 252 253 /** 254 * Create a new {@link IAssemblyNodeItem} that is detached from a Metaschema, 255 * with associated data. 256 * 257 * @param definition 258 * the global definition 259 * @param baseUri 260 * the base URI to use for this node item when evaluating a 261 * {@link MetapathExpression} 262 * @param value 263 * the associated data 264 * @return the new assembly node item 265 */ 266 @NonNull 267 IAssemblyNodeItem newAssemblyNodeItem( 268 @NonNull IAssemblyDefinition definition, 269 @Nullable URI baseUri, 270 @NonNull Object value); 271 272 /** 273 * Create a new {@link IAssemblyNodeItem} that is based on a Metaschema 274 * instance. 275 * <p> 276 * A single instance of this item is expected to represent the possibility in a 277 * metaschema of a series of instance values. 278 * 279 * @param instance 280 * the Metaschema assembly instance 281 * @param parent 282 * the parent node item 283 * @return the new assembly node item 284 */ 285 @NonNull 286 IAssemblyNodeItem newAssemblyNodeItem( 287 @NonNull IAssemblyInstance instance, 288 @NonNull IAssemblyNodeItem parent); 289 290 /** 291 * Create a new {@link IAssemblyNodeItem} that is based on a Metaschema instance 292 * with associated data. 293 * 294 * @param instance 295 * the Metaschema assembly instance 296 * @param parent 297 * the parent node item 298 * @param position 299 * the data item's position in the sequence of data items for the 300 * instance 301 * @param value 302 * the data item's value 303 * @return the new assembly node item 304 */ 305 @NonNull 306 IAssemblyNodeItem newAssemblyNodeItem( 307 @NonNull IAssemblyInstance instance, 308 @NonNull IAssemblyNodeItem parent, 309 int position, 310 @NonNull Object value); 311}