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}