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