1/*
2 * Copyright (c) 2003, 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.validation;
27
28import org.w3c.dom.TypeInfo;
29
30/**
31 * This class provides access to the type information determined
32 * by {@link ValidatorHandler}.
33 *
34 * <p>
35 * Some schema languages, such as W3C XML Schema, encourages a validator
36 * to report the "type" it assigns to each attribute/element.
37 * Those applications who wish to access this type information can invoke
38 * methods defined on this "interface" to access such type information.
39 *
40 * <p>
41 * Implementation of this "interface" can be obtained through the
42 * {@link ValidatorHandler#getTypeInfoProvider()} method.
43 *
44 * @author  <a href="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a>
45 * @see org.w3c.dom.TypeInfo
46 * @since 1.5
47 */
48public abstract class TypeInfoProvider {
49
50    /**
51     * Constructor for the derived class.
52     *
53     * <p>
54     * The constructor does nothing.
55     */
56    protected TypeInfoProvider() {
57    }
58
59    /**
60     * <p>Returns the immutable {@link TypeInfo} object for the current
61     * element.</p>
62     *
63     * <p>The method may only be called by the startElement event
64     * or the endElement event
65     * of the {@link org.xml.sax.ContentHandler} that the application sets to
66     * the {@link ValidatorHandler}.</p>
67     *
68     * <p>When W3C XML Schema validation is being performed, in the
69     * case where an element has a union type, the {@link TypeInfo}
70     * returned by a call to <code>getElementTypeInfo()</code> from the
71     * startElement
72     * event will be the union type. The <code>TypeInfo</code>
73     * returned by a call
74     * from the endElement event will be the actual member type used
75     * to validate the element.</p>
76     *
77     * @throws IllegalStateException
78     *      If this method is called from other {@link org.xml.sax.ContentHandler}
79     *      methods.
80     * @return
81     *      An immutable {@link TypeInfo} object that represents the
82     *      type of the current element.
83     *      Note that the caller can keep references to the obtained
84     *      {@link TypeInfo} longer than the callback scope.
85     *
86     *      Otherwise, this method returns
87     *      null if the validator is unable to
88     *      determine the type of the current element for some reason
89     *      (for example, if the validator is recovering from
90     *      an earlier error.)
91     *
92     */
93    public abstract TypeInfo getElementTypeInfo();
94
95    /**
96     * Returns the immutable {@link TypeInfo} object for the specified
97     * attribute of the current element.
98     *
99     * <p>
100     * The method may only be called by the startElement event of
101     * the {@link org.xml.sax.ContentHandler} that the application sets to the
102     * {@link ValidatorHandler}.</p>
103     *
104     * @param index
105     *      The index of the attribute. The same index for
106     *      the {@link org.xml.sax.Attributes} object passed to the
107     *      <code>startElement</code> callback.
108     *
109     * @throws IndexOutOfBoundsException
110     *      If the index is invalid.
111     * @throws IllegalStateException
112     *      If this method is called from other {@link org.xml.sax.ContentHandler}
113     *      methods.
114     *
115     * @return
116     *      An immutable {@link TypeInfo} object that represents the
117     *      type of the specified attribute.
118     *      Note that the caller can keep references to the obtained
119     *      {@link TypeInfo} longer than the callback scope.
120     *
121     *      Otherwise, this method returns
122     *      null if the validator is unable to
123     *      determine the type.
124     */
125    public abstract TypeInfo getAttributeTypeInfo(int index);
126
127    /**
128     * Returns <code>true</code> if the specified attribute is determined
129     * to be ID.
130     *
131     * <p>
132     * Exacly how an attribute is "determined to be ID" is up to the
133     * schema language. In case of W3C XML Schema, this means
134     * that the actual type of the attribute is the built-in ID type
135     * or its derived type.
136     *
137     * <p>
138     * A {@link javax.xml.parsers.DocumentBuilder} uses this information
139     * to properly implement {@link org.w3c.dom.Attr#isId()}.
140     *
141     * <p>
142     * The method may only be called by the startElement event of
143     * the {@link org.xml.sax.ContentHandler} that the application sets to the
144     * {@link ValidatorHandler}.
145     *
146     * @param index
147     *      The index of the attribute. The same index for
148     *      the {@link org.xml.sax.Attributes} object passed to the
149     *      <code>startElement</code> callback.
150     *
151     * @throws IndexOutOfBoundsException
152     *      If the index is invalid.
153     * @throws IllegalStateException
154     *      If this method is called from other {@link org.xml.sax.ContentHandler}
155     *      methods.
156     *
157     * @return true
158     *      if the type of the specified attribute is ID.
159     */
160    public abstract boolean isIdAttribute(int index);
161
162    /**
163     * Returns <code>false</code> if the attribute was added by the validator.
164     *
165     * <p>
166     * This method provides information necessary for
167     * a {@link javax.xml.parsers.DocumentBuilder} to determine what
168     * the DOM tree should return from the {@link org.w3c.dom.Attr#getSpecified()} method.
169     *
170     * <p>
171     * The method may only be called by the startElement event of
172     * the {@link org.xml.sax.ContentHandler} that the application sets to the
173     * {@link ValidatorHandler}.
174     *
175     * <p>
176     * A general guideline for validators is to return true if
177     * the attribute was originally present in the pipeline, and
178     * false if it was added by the validator.
179     *
180     * @param index
181     *      The index of the attribute. The same index for
182     *      the {@link org.xml.sax.Attributes} object passed to the
183     *      <code>startElement</code> callback.
184     *
185     * @throws IndexOutOfBoundsException
186     *      If the index is invalid.
187     * @throws IllegalStateException
188     *      If this method is called from other {@link org.xml.sax.ContentHandler}
189     *      methods.
190     *
191     * @return
192     *      <code>true</code> if the attribute was present before the validator
193     *      processes input. <code>false</code> if the attribute was added
194     *      by the validator.
195     */
196    public abstract boolean isSpecified(int index);
197}
198