1/*
2 * Copyright (c) 2000, 2005, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation.  Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26package javax.xml.transform;
27
28/**
29 * This interface is primarily for the purposes of reporting where
30 * an error occurred in the XML source or transformation instructions.
31 *
32 * @since 1.4
33 */
34public interface SourceLocator {
35
36    /**
37     * Return the public identifier for the current document event.
38     *
39     * <p>The return value is the public identifier of the document
40     * entity or of the external parsed entity in which the markup that
41     * triggered the event appears.</p>
42     *
43     * @return A string containing the public identifier, or
44     *         null if none is available.
45     * @see #getSystemId
46     */
47    public String getPublicId();
48
49    /**
50     * Return the system identifier for the current document event.
51     *
52     * <p>The return value is the system identifier of the document
53     * entity or of the external parsed entity in which the markup that
54     * triggered the event appears.</p>
55     *
56     * <p>If the system identifier is a URL, the parser must resolve it
57     * fully before passing it to the application.</p>
58     *
59     * @return A string containing the system identifier, or null
60     *         if none is available.
61     * @see #getPublicId
62     */
63    public String getSystemId();
64
65    /**
66     * Return the line number where the current document event ends.
67     *
68     * <p><strong>Warning:</strong> The return value from the method
69     * is intended only as an approximation for the sake of error
70     * reporting; it is not intended to provide sufficient information
71     * to edit the character content of the original XML document.</p>
72     *
73     * <p>The return value is an approximation of the line number
74     * in the document entity or external parsed entity where the
75     * markup that triggered the event appears.</p>
76     *
77     * @return The line number, or -1 if none is available.
78     * @see #getColumnNumber
79     */
80    public int getLineNumber();
81
82    /**
83     * Return the character position where the current document event ends.
84     *
85     * <p><strong>Warning:</strong> The return value from the method
86     * is intended only as an approximation for the sake of error
87     * reporting; it is not intended to provide sufficient information
88     * to edit the character content of the original XML document.</p>
89     *
90     * <p>The return value is an approximation of the column number
91     * in the document entity or external parsed entity where the
92     * markup that triggered the event appears.</p>
93     *
94     * @return The column number, or -1 if none is available.
95     * @see #getLineNumber
96     */
97    public int getColumnNumber();
98}
99