1. // Attributes.java - attribute list with Namespace support
  2. // Written by David Megginson, sax@megginson.com
  3. // NO WARRANTY! This class is in the public domain.
  4. // $Id: Attributes.java,v 1.1 2001/05/20 03:12:56 curcuru Exp $
  5. package org.xml.sax;
  6. /**
  7. * Interface for a list of XML attributes.
  8. *
  9. * <blockquote>
  10. * <em>This module, both source code and documentation, is in the
  11. * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
  12. * </blockquote>
  13. *
  14. * <p>This interface allows access to a list of attributes in
  15. * three different ways:</p>
  16. *
  17. * <ol>
  18. * <li>by attribute index;</li>
  19. * <li>by Namespace-qualified name; or</li>
  20. * <li>by qualified (prefixed) name.</li>
  21. * </ol>
  22. *
  23. * <p>The list will not contain attributes that were declared
  24. * #IMPLIED but not specified in the start tag. It will also not
  25. * contain attributes used as Namespace declarations (xmlns*) unless
  26. * the <code>http://xml.org/sax/features/namespace-prefixes</code>
  27. * feature is set to <var>true</var> (it is <var>false</var> by
  28. * default).</p>
  29. *
  30. * <p>If the namespace-prefixes feature (see above) is <var>false</var>,
  31. * access by qualified name may not be available; if the
  32. * <code>http://xml.org/sax/features/namespaces</code>
  33. * feature is <var>false</var>, access by Namespace-qualified names
  34. * may not be available.</p>
  35. *
  36. * <p>This interface replaces the now-deprecated SAX1 {@link
  37. * org.xml.sax.AttributeList AttributeList} interface, which does not
  38. * contain Namespace support. In addition to Namespace support, it
  39. * adds the <var>getIndex</var> methods (below).</p>
  40. *
  41. * <p>The order of attributes in the list is unspecified, and will
  42. * vary from implementation to implementation.</p>
  43. *
  44. * @since SAX 2.0
  45. * @author David Megginson,
  46. * <a href="mailto:sax@megginson.com">sax@megginson.com</a>
  47. * @version 2.0r2pre
  48. * @see org.xml.sax.helpers.AttributeListImpl
  49. */
  50. public interface Attributes
  51. {
  52. ////////////////////////////////////////////////////////////////////
  53. // Indexed access.
  54. ////////////////////////////////////////////////////////////////////
  55. /**
  56. * Return the number of attributes in the list.
  57. *
  58. * <p>Once you know the number of attributes, you can iterate
  59. * through the list.</p>
  60. *
  61. * @return The number of attributes in the list.
  62. * @see #getURI(int)
  63. * @see #getLocalName(int)
  64. * @see #getQName(int)
  65. * @see #getType(int)
  66. * @see #getValue(int)
  67. */
  68. public abstract int getLength ();
  69. /**
  70. * Look up an attribute's Namespace URI by index.
  71. *
  72. * @param index The attribute index (zero-based).
  73. * @return The Namespace URI, or the empty string if none
  74. * is available, or null if the index is out of
  75. * range.
  76. * @see #getLength
  77. */
  78. public abstract String getURI (int index);
  79. /**
  80. * Look up an attribute's local name by index.
  81. *
  82. * @param index The attribute index (zero-based).
  83. * @return The local name, or the empty string if Namespace
  84. * processing is not being performed, or null
  85. * if the index is out of range.
  86. * @see #getLength
  87. */
  88. public abstract String getLocalName (int index);
  89. /**
  90. * Look up an attribute's XML 1.0 qualified name by index.
  91. *
  92. * @param index The attribute index (zero-based).
  93. * @return The XML 1.0 qualified name, or the empty string
  94. * if none is available, or null if the index
  95. * is out of range.
  96. * @see #getLength
  97. */
  98. public abstract String getQName (int index);
  99. /**
  100. * Look up an attribute's type by index.
  101. *
  102. * <p>The attribute type is one of the strings "CDATA", "ID",
  103. * "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES",
  104. * or "NOTATION" (always in upper case).</p>
  105. *
  106. * <p>If the parser has not read a declaration for the attribute,
  107. * or if the parser does not report attribute types, then it must
  108. * return the value "CDATA" as stated in the XML 1.0 Recommentation
  109. * (clause 3.3.3, "Attribute-Value Normalization").</p>
  110. *
  111. * <p>For an enumerated attribute that is not a notation, the
  112. * parser will report the type as "NMTOKEN".</p>
  113. *
  114. * @param index The attribute index (zero-based).
  115. * @return The attribute's type as a string, or null if the
  116. * index is out of range.
  117. * @see #getLength
  118. */
  119. public abstract String getType (int index);
  120. /**
  121. * Look up an attribute's value by index.
  122. *
  123. * <p>If the attribute value is a list of tokens (IDREFS,
  124. * ENTITIES, or NMTOKENS), the tokens will be concatenated
  125. * into a single string with each token separated by a
  126. * single space.</p>
  127. *
  128. * @param index The attribute index (zero-based).
  129. * @return The attribute's value as a string, or null if the
  130. * index is out of range.
  131. * @see #getLength
  132. */
  133. public abstract String getValue (int index);
  134. ////////////////////////////////////////////////////////////////////
  135. // Name-based query.
  136. ////////////////////////////////////////////////////////////////////
  137. /**
  138. * Look up the index of an attribute by Namespace name.
  139. *
  140. * @param uri The Namespace URI, or the empty string if
  141. * the name has no Namespace URI.
  142. * @param localName The attribute's local name.
  143. * @return The index of the attribute, or -1 if it does not
  144. * appear in the list.
  145. */
  146. public int getIndex (String uri, String localName);
  147. /**
  148. * Look up the index of an attribute by XML 1.0 qualified name.
  149. *
  150. * @param qName The qualified (prefixed) name.
  151. * @return The index of the attribute, or -1 if it does not
  152. * appear in the list.
  153. */
  154. public int getIndex (String qName);
  155. /**
  156. * Look up an attribute's type by Namespace name.
  157. *
  158. * <p>See {@link #getType(int) getType(int)} for a description
  159. * of the possible types.</p>
  160. *
  161. * @param uri The Namespace URI, or the empty String if the
  162. * name has no Namespace URI.
  163. * @param localName The local name of the attribute.
  164. * @return The attribute type as a string, or null if the
  165. * attribute is not in the list or if Namespace
  166. * processing is not being performed.
  167. */
  168. public abstract String getType (String uri, String localName);
  169. /**
  170. * Look up an attribute's type by XML 1.0 qualified name.
  171. *
  172. * <p>See {@link #getType(int) getType(int)} for a description
  173. * of the possible types.</p>
  174. *
  175. * @param qName The XML 1.0 qualified name.
  176. * @return The attribute type as a string, or null if the
  177. * attribute is not in the list or if qualified names
  178. * are not available.
  179. */
  180. public abstract String getType (String qName);
  181. /**
  182. * Look up an attribute's value by Namespace name.
  183. *
  184. * <p>See {@link #getValue(int) getValue(int)} for a description
  185. * of the possible values.</p>
  186. *
  187. * @param uri The Namespace URI, or the empty String if the
  188. * name has no Namespace URI.
  189. * @param localName The local name of the attribute.
  190. * @return The attribute value as a string, or null if the
  191. * attribute is not in the list.
  192. */
  193. public abstract String getValue (String uri, String localName);
  194. /**
  195. * Look up an attribute's value by XML 1.0 qualified name.
  196. *
  197. * <p>See {@link #getValue(int) getValue(int)} for a description
  198. * of the possible values.</p>
  199. *
  200. * @param qName The XML 1.0 qualified name.
  201. * @return The attribute value as a string, or null if the
  202. * attribute is not in the list or if qualified names
  203. * are not available.
  204. */
  205. public abstract String getValue (String qName);
  206. }
  207. // end of Attributes.java