1/*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements.  See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License.  You may obtain a copy of the License at
8 *
9 *     http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17// $Id: TypeInfoProvider.java 884939 2009-11-27 18:20:46Z mrglavas $
18
19package javax.xml.validation;
20
21import org.w3c.dom.TypeInfo;
22
23/**
24 * This class provides access to the type information determined
25 * by {@link ValidatorHandler}.
26 *
27 * <p>
28 * Some schema languages, such as W3C XML Schema, encourages a validator
29 * to report the "type" it assigns to each attribute/element.
30 * Those applications who wish to access this type information can invoke
31 * methods defined on this "interface" to access such type information.
32 *
33 * <p>
34 * Implementation of this "interface" can be obtained through the
35 * {@link ValidatorHandler#getTypeInfoProvider()} method.
36 *
37 * @author  <a href="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a>
38 * @version $Revision: 884939 $, $Date: 2009-11-27 10:20:46 -0800 (Fri, 27 Nov 2009) $
39 * @see org.w3c.dom.TypeInfo
40 * @since 1.5
41 */
42public abstract class TypeInfoProvider {
43
44    /**
45     * Constructor for the derived class.
46     *
47     * <p>
48     * The constructor does nothing.
49     */
50    protected TypeInfoProvider() {
51    }
52
53    /**
54     * <p>Returns the immutable {@link TypeInfo} object for the current element.</p>
55     *
56     * <p>
57     * The method may only be called by the startElement and endElement event of
58     * the {@link org.xml.sax.ContentHandler} that the application sets to the
59     * {@link ValidatorHandler}.</p>
60     *
61     * @throws IllegalStateException
62     *      If this method is called from other {@link org.xml.sax.ContentHandler}
63     *      methods.
64     * @return
65     *      An immutable {@link TypeInfo} object that represents the
66     *      type of the current element.
67     *      Note that the caller can keep references to the obtained
68     *      {@link TypeInfo} longer than the callback scope.
69     *
70     *      Otherwise, this method returns
71     *      null if the validator is unable to
72     *      determine the type of the current element for some reason
73     *      (for example, if the validator is recovering from
74     *      an earlier error.)
75     *
76     */
77    public abstract TypeInfo getElementTypeInfo();
78
79    /**
80     * Returns the immutable {@link TypeInfo} object for the specified
81     * attribute of the current element.
82     *
83     * <p>
84     * The method may only be called by the startElement event of
85     * the {@link org.xml.sax.ContentHandler} that the application sets to the
86     * {@link ValidatorHandler}.
87     *
88     * @param index
89     *      The index of the attribute. The same index for
90     *      the {@link org.xml.sax.Attributes} object passed to the
91     *      <tt>startElement</tt> callback.
92     *
93     * @throws IndexOutOfBoundsException
94     *      If the index is invalid.
95     * @throws IllegalStateException
96     *      If this method is called from other {@link org.xml.sax.ContentHandler}
97     *      methods.
98     *
99     * @return
100     *      An immutable {@link TypeInfo} object that represents the
101     *      type of the specified attribute.
102     *      Note that the caller can keep references to the obtained
103     *      {@link TypeInfo} longer than the callback scope.
104     *
105     *      Otherwise, this method returns
106     *      null if the validator is unable to
107     *      determine the type.
108     */
109    public abstract TypeInfo getAttributeTypeInfo(int index);
110
111    /**
112     * Returns <tt>true</tt> if the specified attribute is determined
113     * to be ID.
114     *
115     * <p>
116     * Exactly how an attribute is "determined to be ID" is up to the
117     * schema language. In case of W3C XML Schema, this means
118     * that the actual type of the attribute is the built-in ID type
119     * or its derived type.
120     *
121     * <p>
122     * A {@link javax.xml.parsers.DocumentBuilder} uses this information
123     * to properly implement {@link org.w3c.dom.Attr#isId()}.
124     *
125     * <p>
126     * The method may only be called by the startElement event of
127     * the {@link org.xml.sax.ContentHandler} that the application sets to the
128     * {@link ValidatorHandler}.
129     *
130     * @param index
131     *      The index of the attribute. The same index for
132     *      the {@link org.xml.sax.Attributes} object passed to the
133     *      <tt>startElement</tt> callback.
134     *
135     * @throws IndexOutOfBoundsException
136     *      If the index is invalid.
137     * @throws IllegalStateException
138     *      If this method is called from other {@link org.xml.sax.ContentHandler}
139     *      methods.
140     *
141     * @return true
142     *      if the type of the specified attribute is ID.
143     */
144    public abstract boolean isIdAttribute(int index);
145
146    /**
147     * Returns <tt>false</tt> if the attribute was added by the validator.
148     *
149     * <p>
150     * This method provides information necessary for
151     * a {@link javax.xml.parsers.DocumentBuilder} to determine what
152     * the DOM tree should return from the {@link org.w3c.dom.Attr#getSpecified()} method.
153     *
154     * <p>
155     * The method may only be called by the startElement event of
156     * the {@link org.xml.sax.ContentHandler} that the application sets to the
157     * {@link ValidatorHandler}.
158     *
159     * <p>
160     * A general guideline for validators is to return true if
161     * the attribute was originally present in the pipeline, and
162     * false if it was added by the validator.
163     *
164     * @param index
165     *      The index of the attribute. The same index for
166     *      the {@link org.xml.sax.Attributes} object passed to the
167     *      <tt>startElement</tt> callback.
168     *
169     * @throws IndexOutOfBoundsException
170     *      If the index is invalid.
171     * @throws IllegalStateException
172     *      If this method is called from other {@link org.xml.sax.ContentHandler}
173     *      methods.
174     *
175     * @return
176     *      <tt>true</tt> if the attribute was present before the validator
177     *      processes input. <tt>false</tt> if the attribute was added
178     *      by the validator.
179     */
180    public abstract boolean isSpecified(int index);
181}
182