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