1   /*
2    * SPDX-FileCopyrightText: none
3    * SPDX-License-Identifier: CC0-1.0
4    */
5   
6   package gov.nist.secauto.metaschema.core.model;
7   
8   import gov.nist.secauto.metaschema.core.datatype.markup.MarkupLine;
9   import gov.nist.secauto.metaschema.core.datatype.markup.MarkupMultiline;
10  import gov.nist.secauto.metaschema.core.metapath.StaticContext;
11  import gov.nist.secauto.metaschema.core.qname.IEnhancedQName;
12  
13  import java.net.URI;
14  import java.util.Collection;
15  import java.util.List;
16  import java.util.Map;
17  
18  import edu.umd.cs.findbugs.annotations.NonNull;
19  import edu.umd.cs.findbugs.annotations.Nullable;
20  
21  /**
22   * Represents a Metaschema module.
23   */
24  public interface IModule {
25    /**
26     * Retrieves the location where the Metaschema module was loaded from.
27     *
28     * @return the location, or {@code null} if this information is not available
29     */
30    URI getLocation();
31  
32    /**
33     * Get a hint about where the source is location.
34     * <p>
35     * This value will typically be a URI or class name.
36     *
37     * @return the hint
38     */
39    @NonNull
40    String getLocationHint();
41  
42    /**
43     * Get the source information for the module.
44     *
45     * @return the source information
46     */
47    @NonNull
48    ISource getSource();
49  
50    /**
51     * Get the long name for the Metaschema module.
52     *
53     * @return the name
54     */
55    @NonNull
56    MarkupLine getName();
57  
58    /**
59     * Get the revision of the Metaschema module.
60     *
61     * @return the revision
62     */
63    @NonNull
64    String getVersion();
65  
66    /**
67     * Retrieve the remarks associated with this Metaschema module, if any.
68     *
69     * @return the remarks or {@code null} if no remarks are defined
70     */
71    @Nullable
72    MarkupMultiline getRemarks();
73  
74    /**
75     * Retrieves the unique short name for the Metaschema module, which provides a
76     * textual identifier for the Metaschema module.
77     *
78     * @return the short name
79     */
80    @NonNull
81    String getShortName();
82  
83    /**
84     * Retrieves the XML namespace associated with the Metaschema module.
85     *
86     * @return a namespace
87     */
88    @NonNull
89    URI getXmlNamespace();
90  
91    /**
92     * Retrieve the JSON schema base URI associated with the Metaschema module.
93     *
94     * @return the base URI
95     */
96    @NonNull
97    URI getJsonBaseUri();
98  
99    /**
100    * Get the qualified name associated with the Metaschema module.
101    *
102    * @return the qualified name
103    */
104   @NonNull
105   IEnhancedQName getQName();
106 
107   /**
108    * Retrieves all Metaschema modules imported by this Metaschema module.
109    *
110    * @return a list of imported Metaschema modules
111    */
112   @NonNull
113   List<? extends IModule> getImportedModules();
114 
115   /**
116    * Retrieve the imported Metaschema module with the specified name, if it
117    * exists.
118    *
119    * @param name
120    *          the short name of the Metschema module to retrieve
121    * @return the imported Metaschema module or {@code null} if it doesn't exist
122    */
123   @Nullable
124   IModule getImportedModuleByShortName(String name);
125 
126   /**
127    * Retrieves the top-level assembly definitions in this Metaschema module.
128    *
129    * @return the collection of assembly definitions
130    */
131   @NonNull
132   Collection<? extends IAssemblyDefinition> getAssemblyDefinitions();
133 
134   /**
135    * Retrieves the top-level assembly definition in this Metaschema module with
136    * the matching name, if it exists.
137    *
138    * @param name
139    *          the definition name
140    *
141    * @return the matching assembly definition, or {@code null} if none match
142    */
143   @Nullable
144   IAssemblyDefinition getAssemblyDefinitionByName(@NonNull Integer name);
145 
146   /**
147    * Retrieves the top-level field definitions in this Metaschema module.
148    *
149    * @return the collection of field definitions
150    */
151   @NonNull
152   Collection<? extends IFieldDefinition> getFieldDefinitions();
153 
154   /**
155    * Retrieves the top-level field definition in this Metaschema module with the
156    * matching name, if it exists.
157    *
158    * @param name
159    *          the definition name
160    *
161    * @return the matching field definition, or {@code null} if none match
162    */
163   @Nullable
164   IFieldDefinition getFieldDefinitionByName(@NonNull Integer name);
165 
166   /**
167    * Retrieves the top-level assembly and field definitions in this Metaschema
168    * module.
169    *
170    * @return a listing of assembly and field definitions
171    */
172   @NonNull
173   List<? extends IModelDefinition> getAssemblyAndFieldDefinitions();
174 
175   /**
176    * Retrieves the top-level flag definitions in this Metaschema module.
177    *
178    * @return the collection of flag definitions
179    */
180   @NonNull
181   Collection<? extends IFlagDefinition> getFlagDefinitions();
182 
183   /**
184    * Retrieves the top-level flag definition in this Metaschema module with the
185    * matching name, if it exists.
186    *
187    * @param name
188    *          the definition name
189    *
190    * @return the matching flag definition, or {@code null} if none match
191    */
192   @Nullable
193   IFlagDefinition getFlagDefinitionByName(@NonNull IEnhancedQName name);
194 
195   /**
196    * Retrieves the assembly definition with a matching name from either: 1) the
197    * top-level assembly definitions from this Metaschema module, or 2) global
198    * assembly definitions from each imported Metaschema module in reverse order of
199    * import.
200    *
201    * @param name
202    *          the name of the assembly to find
203    * @return the assembly definition
204    */
205   @Nullable
206   IAssemblyDefinition getScopedAssemblyDefinitionByName(@NonNull Integer name);
207 
208   /**
209    * Retrieves the field definition with a matching name from either: 1) the
210    * top-level field definitions from this Metaschema module, or 2) global field
211    * definitions from each imported Metaschema module in reverse order of import.
212    *
213    * @param name
214    *          the name of the field definition to find
215    * @return the field definition
216    */
217   @Nullable
218   IFieldDefinition getScopedFieldDefinitionByName(@NonNull Integer name);
219 
220   /**
221    * Retrieves the flag definition with a matching name from either: 1) the
222    * top-level flag definitions from this Metaschema module, or 2) global flag
223    * definitions from each imported Metaschema module in reverse order of import.
224    *
225    * @param name
226    *          the name of the flag definition to find
227    * @return the flag definition
228    */
229   @Nullable
230   IFlagDefinition getScopedFlagDefinitionByName(@NonNull IEnhancedQName name);
231 
232   /**
233    * Retrieves the top-level assembly definitions that are marked as roots from
234    * the current Metaschema module.
235    *
236    * @return a listing of assembly definitions marked as root
237    */
238   @NonNull
239   Collection<? extends IAssemblyDefinition> getRootAssemblyDefinitions();
240 
241   /**
242    * Retrieve the top-level flag definitions that are marked global in this
243    * Metaschema module or in any imported Metaschema modules. The resulting
244    * collection is built by adding global definitions from each imported
245    * Metaschema module in order of import, then adding global definitions from the
246    * current Metaschema module. Such a map is built in this way for each imported
247    * Metaschema module in the chain. Values for clashing keys will be replaced in
248    * this order, giving preference to the "closest" definition.
249    *
250    * @return the collection of exported flag definitions
251    */
252   @NonNull
253   Collection<? extends IFlagDefinition> getExportedFlagDefinitions();
254 
255   /**
256    * Retrieves the exported named flag definition, if it exists.
257    * <p>
258    * For information about how flag definitions are exported see
259    * {@link #getExportedFlagDefinitions()}.
260    *
261    * @param name
262    *          the definition name
263    * @return the flag definition, or {@code null} if it doesn't exist.
264    */
265   @Nullable
266   IFlagDefinition getExportedFlagDefinitionByName(@NonNull IEnhancedQName name);
267 
268   /**
269    * Retrieve the top-level field definitions that are marked global in this
270    * Metaschema module or in any imported Metaschema module. The resulting
271    * collection is built by adding global definitions from each imported
272    * Metaschema module in order of import, then adding global definitions from the
273    * current Metaschema module. Such a map is built in this way for each imported
274    * Metaschema module in the chain. Values for clashing keys will be replaced in
275    * this order, giving preference to the "closest" definition
276    *
277    * @return the collection of exported field definitions
278    */
279   @NonNull
280   Collection<? extends IFieldDefinition> getExportedFieldDefinitions();
281 
282   /**
283    * Retrieves the exported named field definition, if it exists.
284    * <p>
285    * For information about how field definitions are exported see
286    * {@link #getExportedFieldDefinitions()}.
287    *
288    * @param name
289    *          the definition name
290    * @return the field definition, or {@code null} if it doesn't exist.
291    */
292   @Nullable
293   IFieldDefinition getExportedFieldDefinitionByName(@NonNull Integer name);
294 
295   /**
296    * Retrieve the top-level assembly definitions that are marked global in this
297    * Metaschema module or in any imported Metaschema module. The resulting
298    * collection is built by adding global definitions from each imported
299    * Metaschema module in order of import, then adding global definitions from the
300    * current Metaschema module. This collection is built in this way for each
301    * imported Metaschema module in the chain. Items with duplicate names will be
302    * replaced in this order, giving preference to the "closest" definition
303    *
304    * @return the collection of exported assembly definitions
305    */
306   @NonNull
307   Collection<? extends IAssemblyDefinition> getExportedAssemblyDefinitions();
308 
309   /**
310    * Retrieves the exported named assembly definition, if it exists.
311    * <p>
312    * For information about how assembly definitions are exported see
313    * {@link #getExportedAssemblyDefinitions()}.
314    *
315    * @param name
316    *          the definition name
317    * @return the assembly definition, or {@code null} if it doesn't exist.
318    */
319   @Nullable
320   IAssemblyDefinition getExportedAssemblyDefinitionByName(@NonNull Integer name);
321 
322   /**
323    * Retrieves the top-level assembly definitions that are marked as roots from
324    * the current Metaschema module and any imported Metaschema modules.
325    *
326    * @return a listing of assembly definitions marked as root
327    */
328   @NonNull
329   Collection<? extends IAssemblyDefinition> getExportedRootAssemblyDefinitions();
330 
331   /**
332    * Retrieves the exported named root assembly definition, if it exists.
333    * <p>
334    * For information about how assembly definitions are exported see
335    * {@link #getExportedAssemblyDefinitions()}.
336    *
337    * @param name
338    *          the root name
339    * @return the assembly definition, or {@code null} if it doesn't exist.
340    */
341   @Nullable
342   IAssemblyDefinition getExportedRootAssemblyDefinitionByName(Integer name);
343 
344   /**
345    * Get the mapping of prefix to namespace URI for use in resolving the namespace
346    * of lexical qualified named in Metapath.
347    *
348    * @return the mapping
349    */
350   @NonNull
351   Map<String, String> getNamespaceBindings();
352 
353   /**
354    * Get the Metapath static context for compiling Metapath expressions that query
355    * instances of this model.
356    *
357    * @return the static context
358    */
359   @NonNull
360   StaticContext getModuleStaticContext();
361 }