View Javadoc

1   // Attributes2.java - extended Attributes
2   // http://www.saxproject.org
3   // Public Domain: no warranty.
4   // $Id: Attributes2.java,v 1.4 2004/03/19 20:17:54 maartenc Exp $
5   
6   package org.xml.sax.ext;
7   
8   import org.xml.sax.Attributes;
9   
10  
11  /***
12   * SAX2 extension to augment the per-attribute information
13   * provided though {@link Attributes}.
14   * If an implementation supports this extension, the attributes
15   * provided in {@link org.xml.sax.ContentHandler#startElement
16   * ContentHandler.startElement() } will implement this interface,
17   * and the <em>http://xml.org/sax/features/use-attributes2</em>
18   * feature flag will have the value <em>true</em>.
19   *
20   * <blockquote>
21   * <em>This module, both source code and documentation, is in the
22   * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
23   * </blockquote>
24   *
25   * <p> XMLReader implementations are not required to support this
26   * information, and it is not part of core-only SAX2 distributions.</p>
27   *
28   * <p>Note that if an attribute was defaulted (<em>!isSpecified()</em>)
29   * it will of necessity also have been declared (<em>isDeclared()</em>)
30   * in the DTD.
31   * Similarly if an attribute's type is anything except CDATA, then it
32   * must have been declared.
33   * </p>
34   *
35   * @since SAX 2.0 (extensions 1.1 alpha)
36   * @author David Brownell
37   * @version TBS
38   */
39  public interface Attributes2 extends Attributes
40  {
41      /***
42       * Returns false unless the attribute was declared in the DTD.
43       * This helps distinguish two kinds of attributes that SAX reports
44       * as CDATA:  ones that were declared (and hence are usually valid),
45       * and those that were not (and which are never valid).
46       *
47       * @param index The attribute index (zero-based).
48       * @return true if the attribute was declared in the DTD,
49       *		false otherwise.
50       * @exception java.lang.ArrayIndexOutOfBoundsException When the
51       *            supplied index does not identify an attribute.
52       */
53      public boolean isDeclared (int index);
54  
55      /***
56       * Returns false unless the attribute was declared in the DTD.
57       * This helps distinguish two kinds of attributes that SAX reports
58       * as CDATA:  ones that were declared (and hence are usually valid),
59       * and those that were not (and which are never valid).
60       *
61       * @param qName The XML qualified (prefixed) name.
62       * @return true if the attribute was declared in the DTD,
63       *		false otherwise.
64       * @exception java.lang.IllegalArgumentException When the
65       *            supplied name does not identify an attribute.
66       */
67      public boolean isDeclared (String qName);
68  
69      /***
70       * Returns false unless the attribute was declared in the DTD.
71       * This helps distinguish two kinds of attributes that SAX reports
72       * as CDATA:  ones that were declared (and hence are usually valid),
73       * and those that were not (and which are never valid).
74       *
75       * <p>Remember that since DTDs do not "understand" namespaces, the
76       * namespace URI associated with an attribute may not have come from
77       * the DTD.  The declaration will have applied to the attribute's
78       * <em>qName</em>.
79       *
80       * @param uri The Namespace URI, or the empty string if
81       *        the name has no Namespace URI.
82       * @param localName The attribute's local name.
83       * @return true if the attribute was declared in the DTD,
84       *		false otherwise.
85       * @exception java.lang.IllegalArgumentException When the
86       *            supplied names do not identify an attribute.
87       */
88      public boolean isDeclared (String uri, String localName);
89  
90      /***
91       * Returns true unless the attribute value was provided
92       * by DTD defaulting.
93       *
94       * @param index The attribute index (zero-based).
95       * @return true if the value was found in the XML text,
96       *		false if the value was provided by DTD defaulting.
97       * @exception java.lang.ArrayIndexOutOfBoundsException When the
98       *            supplied index does not identify an attribute.
99       */
100     public boolean isSpecified (int index);
101 
102     /***
103      * Returns true unless the attribute value was provided
104      * by DTD defaulting.
105      *
106      * <p>Remember that since DTDs do not "understand" namespaces, the
107      * namespace URI associated with an attribute may not have come from
108      * the DTD.  The declaration will have applied to the attribute's
109      * <em>qName</em>.
110      *
111      * @param uri The Namespace URI, or the empty string if
112      *        the name has no Namespace URI.
113      * @param localName The attribute's local name.
114      * @return true if the value was found in the XML text,
115      *		false if the value was provided by DTD defaulting.
116      * @exception java.lang.IllegalArgumentException When the
117      *            supplied names do not identify an attribute.
118      */
119     public boolean isSpecified (String uri, String localName);
120 
121     /***
122      * Returns true unless the attribute value was provided
123      * by DTD defaulting.
124      *
125      * @param qName The XML qualified (prefixed) name.
126      * @return true if the value was found in the XML text,
127      *		false if the value was provided by DTD defaulting.
128      * @exception java.lang.IllegalArgumentException When the
129      *            supplied name does not identify an attribute.
130      */
131     public boolean isSpecified (String qName);
132 }