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
26 package javax.xml.validation;
27
28 import 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 Kohsuke Kawaguchi
45 * @see org.w3c.dom.TypeInfo
46 * @since 1.5
47 */
48 public 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 }