001// SAX Attribute List Interface. 002// No warranty; no copyright -- use this as you will. 003// $Id: AttributeList.java,v 1.1 2001/03/05 21:40:05 jstrachan Exp $ 004 005package org.xml.sax; 006 007/** 008 * Interface for an element's attribute specifications. 009 * 010 * <blockquote> 011 * <em>This module, both source code and documentation, is in the 012 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em> 013 * </blockquote> 014 * 015 * <p>This is the original SAX1 interface for reporting an element's 016 * attributes. Unlike the new {@link org.xml.sax.Attributes Attributes} 017 * interface, it does not support Namespace-related information.</p> 018 * 019 * <p>When an attribute list is supplied as part of a 020 * {@link org.xml.sax.DocumentHandler#startElement startElement} 021 * event, the list will return valid results only during the 022 * scope of the event; once the event handler returns control 023 * to the parser, the attribute list is invalid. To save a 024 * persistent copy of the attribute list, use the SAX1 025 * {@link org.xml.sax.helpers.AttributeListImpl AttributeListImpl} 026 * helper class.</p> 027 * 028 * <p>An attribute list includes only attributes that have been 029 * specified or defaulted: #IMPLIED attributes will not be included.</p> 030 * 031 * <p>There are two ways for the SAX application to obtain information 032 * from the AttributeList. First, it can iterate through the entire 033 * list:</p> 034 * 035 * <pre> 036 * public void startElement (String name, AttributeList atts) { 037 * for (int i = 0; i < atts.getLength(); i++) { 038 * String name = atts.getName(i); 039 * String type = atts.getType(i); 040 * String value = atts.getValue(i); 041 * [...] 042 * } 043 * } 044 * </pre> 045 * 046 * <p>(Note that the result of getLength() will be zero if there 047 * are no attributes.) 048 * 049 * <p>As an alternative, the application can request the value or 050 * type of specific attributes:</p> 051 * 052 * <pre> 053 * public void startElement (String name, AttributeList atts) { 054 * String identifier = atts.getValue("id"); 055 * String label = atts.getValue("label"); 056 * [...] 057 * } 058 * </pre> 059 * 060 * @deprecated This interface has been replaced by the SAX2 061 * {@link org.xml.sax.Attributes Attributes} 062 * interface, which includes Namespace support. 063 * @since SAX 1.0 064 * @author David Megginson, 065 * <a href="mailto:sax@megginson.com">sax@megginson.com</a> 066 * @version 2.0 067 * @see org.xml.sax.DocumentHandler#startElement startElement 068 * @see org.xml.sax.helpers.AttributeListImpl AttributeListImpl 069 */ 070public interface AttributeList { 071 072 073 //////////////////////////////////////////////////////////////////// 074 // Iteration methods. 075 //////////////////////////////////////////////////////////////////// 076 077 078 /** 079 * Return the number of attributes in this list. 080 * 081 * <p>The SAX parser may provide attributes in any 082 * arbitrary order, regardless of the order in which they were 083 * declared or specified. The number of attributes may be 084 * zero.</p> 085 * 086 * @return The number of attributes in the list. 087 */ 088 public abstract int getLength (); 089 090 091 /** 092 * Return the name of an attribute in this list (by position). 093 * 094 * <p>The names must be unique: the SAX parser shall not include the 095 * same attribute twice. Attributes without values (those declared 096 * #IMPLIED without a value specified in the start tag) will be 097 * omitted from the list.</p> 098 * 099 * <p>If the attribute name has a namespace prefix, the prefix 100 * will still be attached.</p> 101 * 102 * @param i The index of the attribute in the list (starting at 0). 103 * @return The name of the indexed attribute, or null 104 * if the index is out of range. 105 * @see #getLength 106 */ 107 public abstract String getName (int i); 108 109 110 /** 111 * Return the type of an attribute in the list (by position). 112 * 113 * <p>The attribute type is one of the strings "CDATA", "ID", 114 * "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES", 115 * or "NOTATION" (always in upper case).</p> 116 * 117 * <p>If the parser has not read a declaration for the attribute, 118 * or if the parser does not report attribute types, then it must 119 * return the value "CDATA" as stated in the XML 1.0 Recommentation 120 * (clause 3.3.3, "Attribute-Value Normalization").</p> 121 * 122 * <p>For an enumerated attribute that is not a notation, the 123 * parser will report the type as "NMTOKEN".</p> 124 * 125 * @param i The index of the attribute in the list (starting at 0). 126 * @return The attribute type as a string, or 127 * null if the index is out of range. 128 * @see #getLength 129 * @see #getType(java.lang.String) 130 */ 131 public abstract String getType (int i); 132 133 134 /** 135 * Return the value of an attribute in the list (by position). 136 * 137 * <p>If the attribute value is a list of tokens (IDREFS, 138 * ENTITIES, or NMTOKENS), the tokens will be concatenated 139 * into a single string separated by whitespace.</p> 140 * 141 * @param i The index of the attribute in the list (starting at 0). 142 * @return The attribute value as a string, or 143 * null if the index is out of range. 144 * @see #getLength 145 * @see #getValue(java.lang.String) 146 */ 147 public abstract String getValue (int i); 148 149 150 151 //////////////////////////////////////////////////////////////////// 152 // Lookup methods. 153 //////////////////////////////////////////////////////////////////// 154 155 156 /** 157 * Return the type of an attribute in the list (by name). 158 * 159 * <p>The return value is the same as the return value for 160 * getType(int).</p> 161 * 162 * <p>If the attribute name has a namespace prefix in the document, 163 * the application must include the prefix here.</p> 164 * 165 * @param name The name of the attribute. 166 * @return The attribute type as a string, or null if no 167 * such attribute exists. 168 * @see #getType(int) 169 */ 170 public abstract String getType (String name); 171 172 173 /** 174 * Return the value of an attribute in the list (by name). 175 * 176 * <p>The return value is the same as the return value for 177 * getValue(int).</p> 178 * 179 * <p>If the attribute name has a namespace prefix in the document, 180 * the application must include the prefix here.</p> 181 * 182 * @param i The index of the attribute in the list. 183 * @return The attribute value as a string, or null if 184 * no such attribute exists. 185 * @see #getValue(int) 186 */ 187 public abstract String getValue (String name); 188 189} 190 191// end of AttributeList.java