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. 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. 55 * 56 * <p>An attribute list includes only attributes that have been 57 * specified or defaulted: #IMPLIED attributes will not be included. 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: 62 * 63 * <pre>{@code 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: 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 @Deprecated(since="1.5") 97 public interface AttributeList { 98 99 100 //////////////////////////////////////////////////////////////////// 101 // Iteration methods. 102 //////////////////////////////////////////////////////////////////// 103 104 105 /** 106 * Return the number of attributes in this list. 107 * 108 * <p>The SAX parser may provide attributes in any 109 * arbitrary order, regardless of the order in which they were 110 * declared or specified. The number of attributes may be 111 * zero. 112 * 113 * @return The number of attributes in the list. 114 */ getLength()115 public abstract int getLength (); 116 117 118 /** 119 * Return the name of an attribute in this list (by position). 120 * 121 * <p>The names must be unique: the SAX parser shall not include the 122 * same attribute twice. Attributes without values (those declared 123 * #IMPLIED without a value specified in the start tag) will be 124 * omitted from the list. 125 * 126 * <p>If the attribute name has a namespace prefix, the prefix 127 * will still be attached. 128 * 129 * @param i The index of the attribute in the list (starting at 0). 130 * @return The name of the indexed attribute, or null 131 * if the index is out of range. 132 * @see #getLength 133 */ getName(int i)134 public abstract String getName (int i); 135 136 137 /** 138 * Return the type of an attribute in the list (by position). 139 * 140 * <p>The attribute type is one of the strings "CDATA", "ID", 141 * "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES", 142 * or "NOTATION" (always in upper case). 143 * 144 * <p>If the parser has not read a declaration for the attribute, 145 * or if the parser does not report attribute types, then it must 146 * return the value "CDATA" as stated in the XML 1.0 Recommentation 147 * (clause 3.3.3, "Attribute-Value Normalization"). 148 * 149 * <p>For an enumerated attribute that is not a notation, the 150 * parser will report the type as "NMTOKEN". 151 * 152 * @param i The index of the attribute in the list (starting at 0). 153 * @return The attribute type as a string, or 154 * null if the index is out of range. 155 * @see #getLength 156 * @see #getType(java.lang.String) 157 */ getType(int i)158 public abstract String getType (int i); 159 160 161 /** 162 * Return the value of an attribute in the list (by position). 163 * 164 * <p>If the attribute value is a list of tokens (IDREFS, 165 * ENTITIES, or NMTOKENS), the tokens will be concatenated 166 * into a single string separated by whitespace. 167 * 168 * @param i The index of the attribute in the list (starting at 0). 169 * @return The attribute value as a string, or 170 * null if the index is out of range. 171 * @see #getLength 172 * @see #getValue(java.lang.String) 173 */ getValue(int i)174 public abstract String getValue (int i); 175 176 177 178 //////////////////////////////////////////////////////////////////// 179 // Lookup methods. 180 //////////////////////////////////////////////////////////////////// 181 182 183 /** 184 * Return the type of an attribute in the list (by name). 185 * 186 * <p>The return value is the same as the return value for 187 * getType(int). 188 * 189 * <p>If the attribute name has a namespace prefix in the document, 190 * the application must include the prefix here. 191 * 192 * @param name The name of the attribute. 193 * @return The attribute type as a string, or null if no 194 * such attribute exists. 195 * @see #getType(int) 196 */ getType(String name)197 public abstract String getType (String name); 198 199 200 /** 201 * Return the value of an attribute in the list (by name). 202 * 203 * <p>The return value is the same as the return value for 204 * getValue(int). 205 * 206 * <p>If the attribute name has a namespace prefix in the document, 207 * the application must include the prefix here. 208 * 209 * @param name the name of the attribute to return 210 * @return The attribute value as a string, or null if 211 * no such attribute exists. 212 * @see #getValue(int) 213 */ getValue(String name)214 public abstract String getValue (String name); 215 216 } 217 218 // end of AttributeList.java 219