KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > xml > sax > AttributeList


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