001/*
002 * SPDX-FileCopyrightText: none
003 * SPDX-License-Identifier: CC0-1.0
004 */
005
006package dev.metaschema.core.metapath;
007
008import java.io.File;
009import java.io.IOException;
010import java.net.URI;
011import java.net.URISyntaxException;
012import java.net.URL;
013import java.nio.file.Path;
014
015import dev.metaschema.core.metapath.item.node.IDocumentNodeItem;
016import dev.metaschema.core.model.IResourceResolver;
017import dev.metaschema.core.model.IUriResolver;
018import dev.metaschema.core.util.ObjectUtils;
019import edu.umd.cs.findbugs.annotations.NonNull;
020
021/**
022 * Supports loading documents referenced in Metapath expressions.
023 */
024public interface IDocumentLoader extends IResourceResolver {
025  /**
026   * Allows setting an {@link IUriResolver}, which will be used to map URIs prior
027   * to loading the resource.
028   *
029   * @param resolver
030   *          the resolver to set
031   */
032  void setUriResolver(@NonNull IUriResolver resolver);
033
034  /**
035   * Load a Metaschema-based document from a file resource.
036   *
037   * @param file
038   *          the file to load
039   * @return a document item representing the contents of the document.
040   * @throws IOException
041   *           if an error occurred while parsing the file
042   */
043  @NonNull
044  default IDocumentNodeItem loadAsNodeItem(@NonNull File file) throws IOException {
045    return loadAsNodeItem(ObjectUtils.notNull(file.toPath()));
046  }
047
048  /**
049   * Load a Metaschema-based document from a file resource identified by a path.
050   *
051   * @param path
052   *          the file to load
053   * @return a document item representing the contents of the document.
054   * @throws IOException
055   *           if an error occurred while parsing the file
056   */
057  @NonNull
058  default IDocumentNodeItem loadAsNodeItem(@NonNull Path path) throws IOException {
059    return loadAsNodeItem(ObjectUtils.notNull(path.toUri()));
060  }
061
062  /**
063   * Load a Metaschema-based document from a URL resource.
064   *
065   * @param url
066   *          the resource to load
067   * @return a document item representing the contents of the document.
068   * @throws IOException
069   *           if an error occurred while parsing the resource
070   * @throws URISyntaxException
071   *           if the URL is not a valid URI
072   */
073  @NonNull
074  default IDocumentNodeItem loadAsNodeItem(@NonNull URL url) throws IOException, URISyntaxException {
075    return loadAsNodeItem(ObjectUtils.notNull(url.toURI()));
076  }
077
078  /**
079   * Load a Metaschema-based document from a URI resource.
080   * <p>
081   * This is the expected, primary entry point for implementations.
082   *
083   * @param uri
084   *          the resource to load
085   * @return a document item representing the contents of the document.
086   * @throws IOException
087   *           if an error occurred while parsing the resource
088   */
089  @NonNull
090  IDocumentNodeItem loadAsNodeItem(@NonNull URI uri) throws IOException;
091}