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 19 package javax.xml.validation; 20 21 import 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 (at) 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 */ 42 public 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
