/*
 * Copyright (c) 2017 XMLmind Software. All rights reserved.
 *
 * Author: Hussein Shafie
 *
 * This file is part of the XMLmind Assembly Processor project.
 * For conditions of distribution and use, see the accompanying legal.txt file.
 */
package com.xmlmind.domutil;

import java.io.IOException;
import java.io.InputStream;
import java.net.URL;
import org.xml.sax.EntityResolver;
import org.w3c.dom.Document;
import com.xmlmind.util.Console;

/**
 * A W3C DOM document loader service.
 */
public interface Loader {
    /**
     * Specifies the console on which messages issued during document loading
     * are to be displayed. 
     * 
     * @param c the console; may be <code>null</code>, in which case messages
     * are displayed on <code>System.err</code> and <code>System.out</code>
     *
     * @see #getConsole
     */
    void setConsole(Console c);

    /**
     * Returns the console on which messages issued during document loading
     * are to be displayed.
     * 
     * @see #setConsole
     */
    Console getConsole();

    /**
     * Specifies which entity resolver to use when loading an XML document.
     * 
     * @param resolver which resolver to use. May be <code>null</code>.
     * @see #getEntityResolver
     */
    void setEntityResolver(EntityResolver resolver);

    /**
     * Returns the entity resolver being used when loading an XML document. 
     * May return <code>null</code>.
     *
     * @see #setEntityResolver
     */
    EntityResolver getEntityResolver();

    /**
     * Load document from specified input stream.
     * <p><b>Note:</b> <code>xi:include</code> elements (XInclude) 
     * are expected to have been processed in the loaded document.
     *
     * @param in input stream allowing to load the document
     * @param url URL of the document to be loaded if known; 
     * <code>null</code> otherwise
     * @return loaded document
     * @exception IOException if, for any reason, an I/O exception is
     * raised during the processing. 
     * Note that XML parse exception and XInclude exception are reported 
     * as <code>IOException</code>s.
     */
    Document load(InputStream in, URL url) throws IOException;
}
