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.metapath.StaticContext;
9   import gov.nist.secauto.metaschema.core.model.constraint.impl.InternalModelSource;
10  import gov.nist.secauto.metaschema.core.model.constraint.impl.StaticContextSource;
11  
12  import java.net.URI;
13  
14  import edu.umd.cs.findbugs.annotations.NonNull;
15  import edu.umd.cs.findbugs.annotations.Nullable;
16  
17  /**
18   * A descriptor that identifies where a given constraint was defined.
19   */
20  public interface ISource {
21    /**
22     * The relative location of the source.
23     */
24    enum SourceLocation {
25      /**
26       * A constraint embedded in a model.
27       */
28      MODEL,
29      /**
30       * A constraint defined externally from a model.
31       */
32      EXTERNAL;
33    }
34  
35    /**
36     * Get the descriptor for a
37     * {@link gov.nist.secauto.metaschema.core.model.ISource.SourceLocation#MODEL}
38     * source with as associated resource.
39     *
40     * @param module
41     *          the Metaschema module the constraint was defined in
42     * @return the source descriptor
43     * @since 2.0.0
44     */
45    @NonNull
46    static ISource moduleSource(@NonNull IModule module) {
47      return InternalModelSource.instance(module);
48    }
49  
50    /**
51     * Get the descriptor for a
52     * {@link gov.nist.secauto.metaschema.core.model.ISource.SourceLocation#EXTERNAL}
53     * source for the provided resource.
54     *
55     * @param location
56     *          the resource used as the source
57     *
58     * @return the source descriptor
59     */
60    @NonNull
61    static ISource externalSource(@NonNull URI location) {
62      return StaticContextSource.instance(
63          StaticContext.builder()
64              .baseUri(location)
65              .build());
66    }
67  
68    /**
69     * Get the descriptor for a
70     * {@link gov.nist.secauto.metaschema.core.model.ISource.SourceLocation#EXTERNAL}
71     * source with as associated resource.
72     * <p>
73     * The provided static context idenfies the location of this source based on the
74     * {@link StaticContext#getBaseUri()} method.
75     *
76     * @param staticContext
77     *          the static Metapath context to use for compiling Metapath
78     *          expressions in this source
79     *
80     * @return the source descriptor
81     */
82    @NonNull
83    static ISource externalSource(@NonNull StaticContext staticContext) {
84      if (staticContext.getBaseUri() == null) {
85        throw new IllegalArgumentException("The static content must define a baseUri identifing the source resource.");
86      }
87      return StaticContextSource.instance(staticContext);
88    }
89  
90    /**
91     * Get the type of source.
92     *
93     * @return the type
94     */
95    @NonNull
96    ISource.SourceLocation getSourceType();
97  
98    /**
99     * Get the resource where the constraint was defined, if known.
100    *
101    * @return the resource or {@code null} if the resource is not known
102    */
103   @Nullable
104   URI getSource();
105 
106   /**
107    * Get a hint about where the source is location.
108    * <p>
109    * This value will typically be a URI or class name.
110    *
111    * @return the hint
112    */
113   @NonNull
114   String getLocationHint();
115 
116   /**
117    * Get the static Metapath context to use when compiling Metapath expressions.
118    *
119    * @return the static Metapath context
120    */
121   @NonNull
122   StaticContext getStaticContext();
123 }