001: /*
002: * Javolution - Java(TM) Solution for Real-Time and Embedded Systems
003: * Copyright (C) 2006 - Javolution (http://javolution.org/)
004: * All rights reserved.
005: *
006: * Permission to use, copy, modify, and distribute this software is
007: * freely granted, provided that this notice is preserved.
008: */
009: package javolution.xml.sax;
010:
011: import javolution.text.CharArray;
012: import j2me.lang.CharSequence;
013:
014: /**
015: * <p> This interface represents a list of XML attributes.</p>
016: *
017: * <p> It is a more efficient version of <code>org.xml.sax.Attributes</code>
018: * with {@link CharArray CharArray}/{@link CharSequence CharSequence}
019: * instead of the <code>String</code> to avoid forcing dynamic object
020: * allocations.</p>
021: *
022: * @author <a href="mailto:sax@megginson.com">David Megginson</a>
023: * @author <a href="mailto:jean-marie@dautelle.com">Jean-Marie Dautelle</a>
024: * @version 4.0, June 16, 2006
025: */
026: public interface Attributes {
027:
028: /**
029: * Returns the number of attributes in this list of attributes.
030: *
031: * @return the number of attributes.
032: */
033: int getLength();
034:
035: /**
036: * Looks up an attribute's Namespace URI by index.
037: *
038: * @param index the attribute index (zero-based).
039: * @return the Namespace URI, or an empty character sequence if none is
040: * available, or <code>null</code> if the index is out of range.
041: * @see #getLength
042: */
043: CharArray getURI(int index);
044:
045: /**
046: * Looks up an attribute's local name by index.
047: *
048: * @param index the attribute index (zero-based).
049: * @return the local name, or an empty character sequence if Namespace
050: * processing is not being performed, or <code>null</code> if
051: * the index is out of range.
052: * @see #getLength
053: */
054: CharArray getLocalName(int index);
055:
056: /**
057: * Looks up an attribute's XML 1.0 qualified name by index.
058: *
059: * @param index the attribute index (zero-based).
060: * @return the XML 1.0 qualified name, or an empty character sequence if
061: * none is available, or <code>null</code> if the index is out
062: * of range.
063: * @see #getLength
064: */
065: CharArray getQName(int index);
066:
067: /**
068: * Looks up an attribute's type by index.
069: *
070: * <p> The attribute type is one of the strings "CDATA", "ID",
071: * "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES",
072: * or "NOTATION" (always in upper case).</p>
073: *
074: * <p> If the parser has not read a declaration for the attribute,
075: * or if the parser does not report attribute types, then it must
076: * return the value "CDATA" as stated in the XML 1.0 Recommentation
077: * (clause 3.3.3, "Attribute-TextBuilder Normalization").</p>
078: *
079: * <p> For an enumerated attribute that is not a notation, the
080: * parser will report the type as "NMTOKEN".</p>
081: *
082: * @param index the attribute index (zero-based).
083: * @return the attribute's type as a string, or null if the
084: * index is out of range.
085: * @see #getLength
086: */
087: CharArray getType(int index);
088:
089: /**
090: * Looks up an attribute's value by index.
091: *
092: * <p> If the attribute value is a list of tokens (IDREFS,
093: * ENTITIES, or NMTOKENS), the tokens will be concatenated
094: * into a single string with each token separated by a
095: * single space.</p>
096: *
097: * @param index the attribute index (zero-based).
098: * @return the attribute's value as a character sequence,
099: * <code>null</code> if the index is out of range.
100: * @see #getLength
101: */
102: CharArray getValue(int index);
103:
104: /**
105: * Looks up the index of an attribute by namespace name (convenience
106: * method).
107: * This method returns the index of the attribute whose uri/localName
108: * have the same character content as the specified uri/localName.
109: *
110: * @param uri the Namespace URI, or an empty character sequence if
111: * the name has no Namespace URI.
112: * @param localName the attribute's local name.
113: * @return the index of the attribute, or <code>-1</code> if it does not
114: * appear in the list.
115: */
116: int getIndex(CharSequence uri, CharSequence localName);
117:
118: /**
119: * Looks up the index of an attribute by XML 1.0 qualified name
120: * (convenience method). This method returns the index of the attribute
121: * whose name has the same character content as the specified qName.
122: *
123: * @param qName the qualified (prefixed) name.
124: * @return the index of the attribute, or <code>-1</code> if it does not
125: * appear in the list.
126: */
127: int getIndex(CharSequence qName);
128:
129: /**
130: * Looks up an attribute's type by Namespace name (convenience method).
131: * This method returns the type of the attribute whose uri/localName
132: * have the same character content as the specified uri/localName.
133: *
134: * @param uri the Namespace URI, or an empty string if the
135: * name has no Namespace URI.
136: * @param localName the local name of the attribute.
137: * @return the attribute type as a string, or null if the attribute is not
138: * in the list or if Namespace processing is not being performed.
139: */
140: CharArray getType(CharSequence uri, CharSequence localName);
141:
142: /**
143: * Looks up an attribute's type by XML 1.0 qualified name.
144: * This method returns the type of the attribute whose qName
145: * has the same character content as the specified qName.
146: *
147: * @param qName The XML 1.0 qualified name.
148: * @return the attribute type as a string, or null if the attribute is not
149: * in the list or if qualified names are not available.
150: */
151: CharArray getType(CharSequence qName);
152:
153: /**
154: * Looks up an attribute's value by Namespace name (convenience method).
155: * This method returns the value of the attribute whose uri/localName
156: * have the same character content as the specified uri/localName.
157: *
158: * @param uri the Namespace URI, or the empty string if the name has no
159: * Namespace URI.
160: * @param localName the local name of the attribute.
161: * @return the attribute value as a character sequence, or <code>null</code>
162: * if the attribute is not in the list.
163: */
164: CharArray getValue(CharSequence uri, CharSequence localName);
165:
166: /**
167: * Looks up an attribute's value by XML 1.0 qualified name (convenience
168: * method). This method returns the value of the attribute whose qName
169: * has the same character content as the specified qName.
170: *
171: * @param qName The XML 1.0 qualified name.
172: * @return the attribute value as a character sequence, or <code>null</code>
173: * if the attribute is not in the list or if qualified names
174: * are not available.
175: */
176: CharArray getValue(CharSequence qName);
177: }
|