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 */ TypeInfoProvider()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 */ getElementTypeInfo()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 */ getAttributeTypeInfo(int index)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 */ isIdAttribute(int index)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 */ isSpecified(int index)196 public abstract boolean isSpecified(int index); 197 } 198