1   /*
2    * SPDX-FileCopyrightText: none
3    * SPDX-License-Identifier: CC0-1.0
4    */
5   
6   package gov.nist.secauto.metaschema.core.metapath;
7   
8   import gov.nist.secauto.metaschema.core.metapath.item.node.IDocumentNodeItem;
9   import gov.nist.secauto.metaschema.core.model.IResourceResolver;
10  import gov.nist.secauto.metaschema.core.model.IUriResolver;
11  import gov.nist.secauto.metaschema.core.util.ObjectUtils;
12  
13  import java.io.File;
14  import java.io.IOException;
15  import java.net.URI;
16  import java.net.URISyntaxException;
17  import java.net.URL;
18  import java.nio.file.Path;
19  
20  import edu.umd.cs.findbugs.annotations.NonNull;
21  
22  /**
23   * Supports loading documents referenced in Metapath expressions.
24   */
25  public interface IDocumentLoader extends IResourceResolver {
26    /**
27     * Allows setting an {@link IUriResolver}, which will be used to map URIs prior
28     * to loading the resource.
29     *
30     * @param resolver
31     *          the resolver to set
32     */
33    void setUriResolver(@NonNull IUriResolver resolver);
34  
35    /**
36     * Load a Metaschema-based document from a file resource.
37     *
38     * @param file
39     *          the file to load
40     * @return a document item representing the contents of the document.
41     * @throws IOException
42     *           if an error occurred while parsing the file
43     */
44    @NonNull
45    default IDocumentNodeItem loadAsNodeItem(@NonNull File file) throws IOException {
46      return loadAsNodeItem(ObjectUtils.notNull(file.toPath()));
47    }
48  
49    /**
50     * Load a Metaschema-based document from a file resource identified by a path.
51     *
52     * @param path
53     *          the file to load
54     * @return a document item representing the contents of the document.
55     * @throws IOException
56     *           if an error occurred while parsing the file
57     */
58    @NonNull
59    default IDocumentNodeItem loadAsNodeItem(@NonNull Path path) throws IOException {
60      return loadAsNodeItem(ObjectUtils.notNull(path.toUri()));
61    }
62  
63    /**
64     * Load a Metaschema-based document from a URL resource.
65     *
66     * @param url
67     *          the resource to load
68     * @return a document item representing the contents of the document.
69     * @throws IOException
70     *           if an error occurred while parsing the resource
71     * @throws URISyntaxException
72     *           if the URL is not a valid URI
73     */
74    @NonNull
75    default IDocumentNodeItem loadAsNodeItem(@NonNull URL url) throws IOException, URISyntaxException {
76      return loadAsNodeItem(ObjectUtils.notNull(url.toURI()));
77    }
78  
79    /**
80     * Load a Metaschema-based document from a URI resource.
81     * <p>
82     * This is the expected, primary entry point for implementations.
83     *
84     * @param uri
85     *          the resource to load
86     * @return a document item representing the contents of the document.
87     * @throws IOException
88     *           if an error occurred while parsing the resource
89     */
90    @NonNull
91    IDocumentNodeItem loadAsNodeItem(@NonNull URI uri) throws IOException;
92  }