/*

 * Copyright (c) 2000, 2005, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed 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.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package javax.xml.transform;

/**

 * This interface is primarily for the purposes of reporting where

 * an error occurred in the XML source or transformation instructions.

 *

 * @since 1.4

 */

public interface SourceLocator {

    /**

     * Return the public identifier for the current document event.

     *

     * <p>The return value is the public identifier of the document

     * entity or of the external parsed entity in which the markup that

     * triggered the event appears.</p>

     *

     * @return A string containing the public identifier, or

     *         null if none is available.

     * @see #getSystemId

     */

    public String getPublicId();

    /**

     * Return the system identifier for the current document event.

     *

     * <p>The return value is the system identifier of the document

     * entity or of the external parsed entity in which the markup that

     * triggered the event appears.</p>

     *

     * <p>If the system identifier is a URL, the parser must resolve it

     * fully before passing it to the application.</p>

     *

     * @return A string containing the system identifier, or null

     *         if none is available.

     * @see #getPublicId

     */

    public String getSystemId();

    /**

     * Return the line number where the current document event ends.

     *

     * <p><strong>Warning:</strong> The return value from the method

     * is intended only as an approximation for the sake of error

     * reporting; it is not intended to provide sufficient information

     * to edit the character content of the original XML document.</p>

     *

     * <p>The return value is an approximation of the line number

     * in the document entity or external parsed entity where the

     * markup that triggered the event appears.</p>

     *

     * @return The line number, or -1 if none is available.

     * @see #getColumnNumber

     */

    public int getLineNumber();

    /**

     * Return the character position where the current document event ends.

     *

     * <p><strong>Warning:</strong> The return value from the method

     * is intended only as an approximation for the sake of error

     * reporting; it is not intended to provide sufficient information

     * to edit the character content of the original XML document.</p>

     *

     * <p>The return value is an approximation of the column number

     * in the document entity or external parsed entity where the

     * markup that triggered the event appears.</p>

     *

     * @return The column number, or -1 if none is available.

     * @see #getLineNumber

     */

    public int getColumnNumber();

}