org.w3c.dom.ls.DOMImplementationLS Maven / Gradle / Ivy

/*
 * Copyright (c) 2004 World Wide Web Consortium,
 *
 * (Massachusetts Institute of Technology, European Research Consortium for
 * Informatics and Mathematics, Keio University). All Rights Reserved. This
 * work is distributed under the W3C(r) Software License [1] in the hope that
 * it will be useful, but WITHOUT ANY WARRANTY; without even the implied
 * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 *
 * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231
 */

package org.w3c.dom.ls;

import org.w3c.dom.DOMException;

/**
 *  DOMImplementationLS contains the factory methods for creating
 * Load and Save objects.
 *  The expectation is that an instance of the
 * DOMImplementationLS interface can be obtained by using
 * binding-specific casting methods on an instance of the
 * DOMImplementation interface or, if the Document
 * supports the feature "Core" version "3.0"
 * defined in [DOM Level 3 Core]
 * , by using the method DOMImplementation.getFeature with
 * parameter values "LS" (or "LS-Async") and
 * "3.0" (respectively).
 * 
See also the Document Object Model (DOM) Level 3 Load
and Save Specification.
 */
public interface DOMImplementationLS {
    // DOMImplementationLSMode
    /**
     * Create a synchronous LSParser.
     */
    public static final short MODE_SYNCHRONOUS          = 1;
    /**
     * Create an asynchronous LSParser.
     */
    public static final short MODE_ASYNCHRONOUS         = 2;

    /**
     * Create a new LSParser. The newly constructed parser may
     * then be configured by means of its DOMConfiguration
     * object, and used to parse documents by means of its parse
     *  method.
     * @param mode  The mode argument is either
     *   MODE_SYNCHRONOUS or MODE_ASYNCHRONOUS, if
     *   mode is MODE_SYNCHRONOUS then the
     *   LSParser that is created will operate in synchronous
     *   mode, if it's MODE_ASYNCHRONOUS then the
     *   LSParser that is created will operate in asynchronous
     *   mode.
     * @param schemaType  An absolute URI representing the type of the schema
     *   language used during the load of a Document using the
     *   newly created LSParser. Note that no lexical checking
     *   is done on the absolute URI. In order to create a
     *   LSParser for any kind of schema types (i.e. the
     *   LSParser will be free to use any schema found), use the value
     *   null.
     * 
Note:    For W3C XML Schema [XML Schema Part 1]
     *   , applications must use the value
     *   "http://www.w3.org/2001/XMLSchema". For XML DTD [XML 1.0],
     *   applications must use the value
     *   "http://www.w3.org/TR/REC-xml". Other Schema languages
     *   are outside the scope of the W3C and therefore should recommend an
     *   absolute URI in order to use this method.
     * @return  The newly created LSParser object. This
     *   LSParser is either synchronous or asynchronous
     *   depending on the value of the mode argument.
     * 
Note:    By default, the newly created LSParser
     *   does not contain a DOMErrorHandler, i.e. the value of
     *   the "
     *   error-handler" configuration parameter is null. However, implementations
     *   may provide a default error handler at creation time. In that case,
     *   the initial value of the "error-handler" configuration
     *   parameter on the new LSParser object contains a
     *   reference to the default error handler.
     * @exception DOMException
     *    NOT_SUPPORTED_ERR: Raised if the requested mode or schema type is
     *   not supported.
     */
    public LSParser createLSParser(short mode,
                                   String schemaType)
                                   throws DOMException;

    /**
     *  Create a new LSSerializer object.
     * @return The newly created LSSerializer object.
     * Note:    By default, the newly created
     *   LSSerializer has no DOMErrorHandler, i.e.
     *   the value of the "error-handler" configuration
     *   parameter is null. However, implementations may
     *   provide a default error handler at creation time. In that case, the
     *   initial value of the "error-handler" configuration
     *   parameter on the new LSSerializer object contains a
     *   reference to the default error handler.
     */
    public LSSerializer createLSSerializer();

    /**
     *  Create a new empty input source object where
     * LSInput.characterStream, LSInput.byteStream
     * , LSInput.stringData LSInput.systemId,
     * LSInput.publicId, LSInput.baseURI, and
     * LSInput.encoding are null, and
     * LSInput.certifiedText is false.
     * @return  The newly created input object.
     */
    public LSInput createLSInput();

    /**
     *  Create a new empty output destination object where
     * LSOutput.characterStream,
     * LSOutput.byteStream, LSOutput.systemId,
     * LSOutput.encoding are null.
     * @return  The newly created output object.
     */
    public LSOutput createLSOutput();

}