1 /* 2 * Copyright (c) 2000, 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 // SAX Attribute List Interface. 27 // http://www.saxproject.org 28 // No warranty; no copyright -- use this as you will. 29 // $Id: AttributeList.java,v 1.3 2004/11/03 22:44:51 jsuttor Exp $ 30 31 package org.xml.sax; 32 33 /** 34 * Interface for an element's attribute specifications. 35 * 36 * <blockquote> 37 * <em>This module, both source code and documentation, is in the 38 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em> 39 * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a> 40 * for further information. 41 * </blockquote> 42 * 43 * <p>This is the original SAX1 interface for reporting an element's 44 * attributes. Unlike the new {@link org.xml.sax.Attributes Attributes} 45 * interface, it does not support Namespace-related information.</p> 46 * 47 * <p>When an attribute list is supplied as part of a 48 * {@link org.xml.sax.DocumentHandler#startElement startElement} 49 * event, the list will return valid results only during the 50 * scope of the event; once the event handler returns control 51 * to the parser, the attribute list is invalid. To save a 52 * persistent copy of the attribute list, use the SAX1 53 * {@link org.xml.sax.helpers.AttributeListImpl AttributeListImpl} 54 * helper class.</p> 55 * 56 * <p>An attribute list includes only attributes that have been 57 * specified or defaulted: #IMPLIED attributes will not be included.</p> 58 * 59 * <p>There are two ways for the SAX application to obtain information 60 * from the AttributeList. First, it can iterate through the entire 61 * list:</p> 62 * 63 * <pre> 64 * public void startElement (String name, AttributeList atts) { 65 * for (int i = 0; i < atts.getLength(); i++) { 66 * String name = atts.getName(i); 67 * String type = atts.getType(i); 68 * String value = atts.getValue(i); 69 * [...] 70 * } 71 * } 72 * </pre> 73 * 74 * <p>(Note that the result of getLength() will be zero if there 75 * are no attributes.) 76 * 77 * <p>As an alternative, the application can request the value or 78 * type of specific attributes:</p> 79 * 80 * <pre> 81 * public void startElement (String name, AttributeList atts) { 82 * String identifier = atts.getValue("id"); 83 * String label = atts.getValue("label"); 84 * [...] 85 * } 86 * </pre> 87 * 88 * @deprecated This interface has been replaced by the SAX2 89 * {@link org.xml.sax.Attributes Attributes} 90 * interface, which includes Namespace support. 91 * @since 1.4, SAX 1.0 92 * @author David Megginson 93 * @see org.xml.sax.DocumentHandler#startElement startElement 94 * @see org.xml.sax.helpers.AttributeListImpl AttributeListImpl 95 */ 96 public interface AttributeList { 97 98 99 //////////////////////////////////////////////////////////////////// 100 // Iteration methods. 101 //////////////////////////////////////////////////////////////////// 102 103 104 /** 105 * Return the number of attributes in this list. 106 * 107 * <p>The SAX parser may provide attributes in any 108 * arbitrary order, regardless of the order in which they were 109 * declared or specified. The number of attributes may be 110 * zero.</p> 111 * 112 * @return The number of attributes in the list. 113 */ 114 public abstract int getLength (); 115 116 117 /** 118 * Return the name of an attribute in this list (by position). 119 * 120 * <p>The names must be unique: the SAX parser shall not include the 121 * same attribute twice. Attributes without values (those declared 122 * #IMPLIED without a value specified in the start tag) will be 123 * omitted from the list.</p> 124 * 125 * <p>If the attribute name has a namespace prefix, the prefix 126 * will still be attached.</p> 127 * 128 * @param i The index of the attribute in the list (starting at 0). 129 * @return The name of the indexed attribute, or null 130 * if the index is out of range. 131 * @see #getLength 132 */ 133 public abstract String getName (int i); 134 135 136 /** 137 * Return the type of an attribute in the list (by position). 138 * 139 * <p>The attribute type is one of the strings "CDATA", "ID", 140 * "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES", 141 * or "NOTATION" (always in upper case).</p> 142 * 143 * <p>If the parser has not read a declaration for the attribute, 144 * or if the parser does not report attribute types, then it must 145 * return the value "CDATA" as stated in the XML 1.0 Recommentation 146 * (clause 3.3.3, "Attribute-Value Normalization").</p> 147 * 148 * <p>For an enumerated attribute that is not a notation, the 149 * parser will report the type as "NMTOKEN".</p> 150 * 151 * @param i The index of the attribute in the list (starting at 0). 152 * @return The attribute type as a string, or 153 * null if the index is out of range. 154 * @see #getLength 155 * @see #getType(java.lang.String) 156 */ 157 public abstract String getType (int i); 158 159 160 /** 161 * Return the value of an attribute in the list (by position). 162 * 163 * <p>If the attribute value is a list of tokens (IDREFS, 164 * ENTITIES, or NMTOKENS), the tokens will be concatenated 165 * into a single string separated by whitespace.</p> 166 * 167 * @param i The index of the attribute in the list (starting at 0). 168 * @return The attribute value as a string, or 169 * null if the index is out of range. 170 * @see #getLength 171 * @see #getValue(java.lang.String) 172 */ 173 public abstract String getValue (int i); 174 175 176 177 //////////////////////////////////////////////////////////////////// 178 // Lookup methods. 179 //////////////////////////////////////////////////////////////////// 180 181 182 /** 183 * Return the type of an attribute in the list (by name). 184 * 185 * <p>The return value is the same as the return value for 186 * getType(int).</p> 187 * 188 * <p>If the attribute name has a namespace prefix in the document, 189 * the application must include the prefix here.</p> 190 * 191 * @param name The name of the attribute. 192 * @return The attribute type as a string, or null if no 193 * such attribute exists. 194 * @see #getType(int) 195 */ 196 public abstract String getType (String name); 197 198 199 /** 200 * Return the value of an attribute in the list (by name). 201 * 202 * <p>The return value is the same as the return value for 203 * getValue(int).</p> 204 * 205 * <p>If the attribute name has a namespace prefix in the document, 206 * the application must include the prefix here.</p> 207 * 208 * @param name the name of the attribute to return 209 * @return The attribute value as a string, or null if 210 * no such attribute exists. 211 * @see #getValue(int) 212 */ 213 public abstract String getValue (String name); 214 215 } 216 217 // end of AttributeList.java