001: /* Copyright 2000 - 2001 Quadcap Software. All rights reserved.
002: *
003: * This software is distributed under the Quadcap Free Software License.
004: * This software may be used or modified for any purpose, personal or
005: * commercial. Open Source redistributions are permitted. Commercial
006: * redistribution of larger works derived from, or works which bundle
007: * this software requires a "Commercial Redistribution License"; see
008: * http://www.quadcap.com/purchase.
009: *
010: * Redistributions qualify as "Open Source" under one of the following terms:
011: *
012: * Redistributions are made at no charge beyond the reasonable cost of
013: * materials and delivery.
014: *
015: * Redistributions are accompanied by a copy of the Source Code or by an
016: * irrevocable offer to provide a copy of the Source Code for up to three
017: * years at the cost of materials and delivery. Such redistributions
018: * must allow further use, modification, and redistribution of the Source
019: * Code under substantially the same terms as this license.
020: *
021: * Redistributions of source code must retain the copyright notices as they
022: * appear in each source code file, these license terms, and the
023: * disclaimer/limitation of liability set forth as paragraph 6 below.
024: *
025: * Redistributions in binary form must reproduce this Copyright Notice,
026: * these license terms, and the disclaimer/limitation of liability set
027: * forth as paragraph 6 below, in the documentation and/or other materials
028: * provided with the distribution.
029: *
030: * The Software is provided on an "AS IS" basis. No warranty is
031: * provided that the Software is free of defects, or fit for a
032: * particular purpose.
033: *
034: * Limitation of Liability. Quadcap Software shall not be liable
035: * for any damages suffered by the Licensee or any third party resulting
036: * from use of the Software.
037: */
038:
039: // SAX Attribute List Interface.
040: // No warranty; no copyright -- use this as you will.
041: // $Id: AttributeList.java,v 1.3 2001/01/06 06:11:01 stan Exp $
042: package org.xml.sax;
043:
044: /**
045: * Interface for an element's attribute specifications.
046: *
047: * <p>The SAX parser implements this interface and passes an instance
048: * to the SAX application as the second argument of each startElement
049: * event.</p>
050: *
051: * <p>The instance provided will return valid results only during the
052: * scope of the startElement invocation (to save it for future
053: * use, the application must make a copy: the AttributeListImpl
054: * helper class provides a convenient constructor for doing so).</p>
055: *
056: * <p>An AttributeList includes only attributes that have been
057: * specified or defaulted: #IMPLIED attributes will not be included.</p>
058: *
059: * <p>There are two ways for the SAX application to obtain information
060: * from the AttributeList. First, it can iterate through the entire
061: * list:</p>
062: *
063: * <pre>
064: * public void startElement (String name, AttributeList atts) {
065: * for (int i = 0; i < atts.getLength(); i++) {
066: * String name = atts.getName(i);
067: * String type = atts.getType(i);
068: * String value = atts.getValue(i);
069: * [...]
070: * }
071: * }
072: * </pre>
073: *
074: * <p>(Note that the result of getLength() will be zero if there
075: * are no attributes.)
076: *
077: * <p>As an alternative, the application can request the value or
078: * type of specific attributes:</p>
079: *
080: * <pre>
081: * public void startElement (String name, AttributeList atts) {
082: * String identifier = atts.getValue("id");
083: * String label = atts.getValue("label");
084: * [...]
085: * }
086: * </pre>
087: *
088: * <p>The AttributeListImpl helper class provides a convenience
089: * implementation for use by parser or application writers.</p>
090: *
091: * @author David Megginson (ak117@freenet.carleton.ca)
092: * @version 1.0
093: * @see org.xml.sax.DocumentHandler#startElement
094: * @see org.xml.sax.helpers.AttributeListImpl
095: */
096: public interface AttributeList {
097:
098: /**
099: * Return the number of attributes in this list.
100: *
101: * <p>The SAX parser may provide attributes in any
102: * arbitrary order, regardless of the order in which they were
103: * declared or specified. The number of attributes may be
104: * zero.</p>
105: *
106: * @return The number of attributes in the list.
107: */
108: public abstract int getLength();
109:
110: /**
111: * Return the name of an attribute in this list (by position).
112: *
113: * <p>The names must be unique: the SAX parser shall not include the
114: * same attribute twice. Attributes without values (those declared
115: * #IMPLIED without a value specified in the start tag) will be
116: * omitted from the list.</p>
117: *
118: * <p>If the attribute name has a namespace prefix, the prefix
119: * will still be attached.</p>
120: *
121: * @param i The index of the attribute in the list (starting at 0).
122: * @return The name of the indexed attribute, or null
123: * if the index is out of range.
124: * @see #getLength
125: */
126: public abstract String getName(int i);
127:
128: /**
129: * Return the type of an attribute in the list (by position).
130: *
131: * <p>The attribute type is one of the strings "CDATA", "ID",
132: * "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES",
133: * or "NOTATION" (always in upper case).</p>
134: *
135: * <p>If the parser has not read a declaration for the attribute,
136: * or if the parser does not report attribute types, then it must
137: * return the value "CDATA" as stated in the XML 1.0 Recommentation
138: * (clause 3.3.3, "Attribute-Value Normalization").</p>
139: *
140: * <p>For an enumerated attribute that is not a notation, the
141: * parser will report the type as "NMTOKEN".</p>
142: *
143: * @param i The index of the attribute in the list (starting at 0).
144: * @return The attribute type as a string, or
145: * null if the index is out of range.
146: * @see #getLength
147: * @see #getType(java.lang.String)
148: */
149: public abstract String getType(int i);
150:
151: /**
152: * Return the value of an attribute in the list (by position).
153: *
154: * <p>If the attribute value is a list of tokens (IDREFS,
155: * ENTITIES, or NMTOKENS), the tokens will be concatenated
156: * into a single string separated by whitespace.</p>
157: *
158: * @param i The index of the attribute in the list (starting at 0).
159: * @return The attribute value as a string, or
160: * null if the index is out of range.
161: * @see #getLength
162: * @see #getValue(java.lang.String)
163: */
164: public abstract String getValue(int i);
165:
166: /**
167: * Return the type of an attribute in the list (by name).
168: *
169: * <p>The return value is the same as the return value for
170: * getType(int).</p>
171: *
172: * <p>If the attribute name has a namespace prefix in the document,
173: * the application must include the prefix here.</p>
174: *
175: * @param name The name of the attribute.
176: * @return The attribute type as a string, or null if no
177: * such attribute exists.
178: * @see #getType(int)
179: */
180: public abstract String getType(String name);
181:
182: /**
183: * Return the value of an attribute in the list (by name).
184: *
185: * <p>The return value is the same as the return value for
186: * getValue(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 i The index of the attribute in the list.
192: * @return The attribute value as a string, or null if
193: * no such attribute exists.
194: * @see #getValue(int)
195: */
196: public abstract String getValue(String name);
197:
198: }
|