source: NonGTP/Xerces/xerces/include/xercesc/sax2/Attributes.hpp @ 358

Revision 358, 11.7 KB checked in by bittner, 19 years ago (diff)

xerces added

Line 
1/*
2 * Copyright 1999-2001,2004 The Apache Software Foundation.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17/*
18 * $Log: Attributes.hpp,v $
19 * Revision 1.6  2004/09/26 01:06:31  cargilld
20 * Fix documentation generation problem.  Replace <pre> with <code>.  Patch from James Littlejohn.
21 *
22 * Revision 1.5  2004/09/08 13:56:20  peiyongz
23 * Apache License Version 2.0
24 *
25 * Revision 1.4  2003/03/07 18:10:30  tng
26 * Return a reference instead of void for operator=
27 *
28 * Revision 1.3  2002/11/04 14:55:45  tng
29 * C++ Namespace Support.
30 *
31 * Revision 1.2  2002/02/20 18:17:02  tng
32 * [Bug 5977] Warnings on generating apiDocs.
33 *
34 * Revision 1.1.1.1  2002/02/01 22:22:08  peiyongz
35 * sane_include
36 *
37 * Revision 1.5  2001/05/11 13:26:25  tng
38 * Copyright update.
39 *
40 * Revision 1.4  2001/02/26 19:44:19  tng
41 * Schema: add utility class QName, by Pei Yong Zhang.
42 *
43 * Revision 1.3  2000/08/09 22:19:28  jpolast
44 * many conformance & stability changes:
45 *   - ContentHandler::resetDocument() removed
46 *   - attrs param of ContentHandler::startDocument() made const
47 *   - SAXExceptions thrown now have msgs
48 *   - removed duplicate function signatures that had 'const'
49 *       [ eg: getContentHander() ]
50 *   - changed getFeature and getProperty to apply to const objs
51 *   - setProperty now takes a void* instead of const void*
52 *   - SAX2XMLReaderImpl does not inherit from SAXParser anymore
53 *   - Reuse Validator (http://apache.org/xml/features/reuse-validator) implemented
54 *   - Features & Properties now read-only during parse
55 *
56 * Revision 1.2  2000/08/07 18:21:26  jpolast
57 * change SAX_EXPORT module to SAX2_EXPORT
58 *
59 * Revision 1.1  2000/08/02 18:02:34  jpolast
60 * initial checkin of sax2 implementation
61 * submitted by Simon Fell (simon@fell.com)
62 * and Joe Polastre (jpolast@apache.org)
63 *
64 *
65 */
66
67#ifndef ATTRIBUTES_HPP
68#define ATTRIBUTES_HPP
69
70#include <xercesc/util/XercesDefs.hpp>
71
72XERCES_CPP_NAMESPACE_BEGIN
73
74/**
75  * Interface for an element's attribute specifications.
76  *
77  * The SAX2 parser implements this interface and passes an instance
78  * to the SAX2 application as the last argument of each startElement
79  * event.
80  *
81  * The instance provided will return valid results only during the
82  * scope of the startElement invocation (to save it for future
83  * use, the application must make a copy: the AttributesImpl
84  * helper class provides a convenient constructor for doing so).
85  *
86  * An Attributes includes only attributes that have been
87  * specified or defaulted: #IMPLIED attributes will not be included.
88  *
89  * There are two ways for the SAX application to obtain information
90  * from the Attributes.  First, it can iterate through the entire
91  * list:
92  *
93  * <code>
94  * public void startElement (String uri, String localpart, String qName, Attributes atts) {<br>
95  * &nbsp;for (int i = 0; i < atts.getLength(); i++) {<br>
96  * &nbsp;&nbsp;String Qname = atts.getQName(i);<br>
97  * &nbsp;&nbsp;String URI   = atts.getURI(i)<br>
98  * &nbsp;&nbsp;String local = atts.GetLocalName(i)<br>
99  * &nbsp;&nbsp;String type  = atts.getType(i);<br>
100  * &nbsp;&nbsp;String value = atts.getValue(i);<br>
101  * &nbsp;&nbsp;[...]<br>
102  * &nbsp;}<br>
103  * }
104  * </code>
105  *
106  * (Note that the result of getLength() will be zero if there
107  * are no attributes.)
108  *
109  * As an alternative, the application can request the value or
110  * type of specific attributes:
111  *
112  * <code>
113  * public void startElement (String uri, String localpart, String qName, Attributes atts) {<br>
114  * &nbsp;String identifier = atts.getValue("id");<br>
115  * &nbsp;String label = atts.getValue("label");<br>
116  * &nbsp;[...]<br>
117  * }
118  * </code>
119  *
120  * The AttributesImpl helper class provides a convenience
121  * implementation for use by parser or application writers.
122  *
123  * @see Sax2DocumentHandler#startElement
124  * @see AttributesImpl#AttributesImpl
125  */
126
127class SAX2_EXPORT Attributes
128{
129public:
130    // -----------------------------------------------------------------------
131    //  Constructors and Destructor
132    // -----------------------------------------------------------------------
133    /** @name Constructors and Destructor */
134    //@{
135    /** Default constructor */
136    Attributes()
137    {
138    }
139
140    /** Destructor */
141    virtual ~Attributes()
142    {
143    }
144    //@}
145
146    /** @name The virtual attribute list interface */
147    //@{
148  /**
149    * Return the number of attributes in this list.
150    *
151    * The SAX parser may provide attributes in any
152    * arbitrary order, regardless of the order in which they were
153    * declared or specified.  The number of attributes may be
154    * zero.
155    *
156    * @return The number of attributes in the list.
157    */
158    virtual unsigned int getLength() const = 0;
159
160  /**
161    * Return the namespace URI of an attribute in this list (by position).
162    *
163    * The QNames must be unique: the SAX parser shall not include the
164    * same attribute twice.  Attributes without values (those declared
165    * #IMPLIED without a value specified in the start tag) will be
166    * omitted from the list.
167    *
168    * @param index The index of the attribute in the list (starting at 0).
169    * @return The URI of the indexed attribute, or null
170    *         if the index is out of range.
171    * @see #getLength
172    */
173        virtual const XMLCh* getURI(const unsigned int index) const = 0;
174
175  /**
176    * Return the local name of an attribute in this list (by position).
177    *
178    * The QNames must be unique: the SAX parser shall not include the
179    * same attribute twice.  Attributes without values (those declared
180    * #IMPLIED without a value specified in the start tag) will be
181    * omitted from the list.
182    *
183    * @param index The index of the attribute in the list (starting at 0).
184    * @return The local name of the indexed attribute, or null
185    *         if the index is out of range.
186    * @see #getLength
187    */
188    virtual const XMLCh* getLocalName(const unsigned int index) const = 0;
189
190  /**
191    * Return the qName of an attribute in this list (by position).
192    *
193    * The QNames must be unique: the SAX parser shall not include the
194    * same attribute twice.  Attributes without values (those declared
195    * #IMPLIED without a value specified in the start tag) will be
196    * omitted from the list.
197    *
198    * @param index The index of the attribute in the list (starting at 0).
199    * @return The qName of the indexed attribute, or null
200    *         if the index is out of range.
201    * @see #getLength
202    */
203    virtual const XMLCh* getQName(const unsigned int index) const = 0;
204
205  /**
206    * Return the type of an attribute in the list (by position).
207    *
208    * The attribute type is one of the strings "CDATA", "ID",
209    * "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES",
210    * or "NOTATION" (always in upper case).
211    *
212    * If the parser has not read a declaration for the attribute,
213    * or if the parser does not report attribute types, then it must
214    * return the value "CDATA" as stated in the XML 1.0 Recommentation
215    * (clause 3.3.3, "Attribute-Value Normalization").
216    *
217    * For an enumerated attribute that is not a notation, the
218    * parser will report the type as "NMTOKEN".
219    *
220    * @param index The index of the attribute in the list (starting at 0).
221    * @return The attribute type as a string, or
222    *         null if the index is out of range.
223    * @see #getLength
224    * @see #getType(String)
225    */
226    virtual const XMLCh* getType(const unsigned int index) const = 0;
227
228  /**
229    * Return the value of an attribute in the list (by position).
230    *
231    * If the attribute value is a list of tokens (IDREFS,
232    * ENTITIES, or NMTOKENS), the tokens will be concatenated
233    * into a single string separated by whitespace.
234    *
235    * @param index The index of the attribute in the list (starting at 0).
236    * @return The attribute value as a string, or
237    *         null if the index is out of range.
238    * @see #getLength
239    * @see #getValue(XMLCh*)
240    */
241    virtual const XMLCh* getValue(const unsigned int index) const = 0;
242
243    ////////////////////////////////////////////////////////////////////
244    // Name-based query.
245    ////////////////////////////////////////////////////////////////////
246
247   /**
248     * Look up the index of an attribute by Namespace name.
249     *
250     * @param uri The Namespace URI, or the empty string if
251     *        the name has no Namespace URI.
252     * @param localPart The attribute's local name.
253     * @return The index of the attribute, or -1 if it does not
254     *         appear in the list.
255     */
256        virtual int getIndex(const XMLCh* const uri, const XMLCh* const localPart ) const = 0 ;
257
258   /**
259     * Look up the index of an attribute by XML 1.0 qualified name.
260     *
261     * @param qName The qualified (prefixed) name.
262     * @return The index of the attribute, or -1 if it does not
263     *         appear in the list.
264     */
265        virtual int getIndex(const XMLCh* const qName ) const = 0 ;
266
267   /**
268     * Look up an attribute's type by Namespace name.
269     *
270     * <p>See #getType for a description of the possible types.</p>
271     *
272     * @param uri The Namespace URI, or the empty String if the
273     *        name has no Namespace URI.
274     * @param localPart The local name of the attribute.
275     * @return The attribute type as a string, or null if the
276     *         attribute is not in the list or if Namespace
277     *         processing is not being performed.
278     */
279        virtual const XMLCh* getType(const XMLCh* const uri, const XMLCh* const localPart ) const = 0 ;
280
281   /**
282     * Look up an attribute's type by XML 1.0 qualified name.
283     *
284     * <p>See #getType for a description of the possible types.</p>
285     *
286     * @param qName The XML 1.0 qualified name.
287     * @return The attribute type as a string, or null if the
288     *         attribute is not in the list or if qualified names
289     *         are not available.
290     */
291    virtual const XMLCh* getType(const XMLCh* const qName) const = 0;
292
293   /**
294     * Look up an attribute's value by Namespace name.
295     *
296     * <p>See #getValue for a description of the possible values.</p>
297     *
298     * @param uri The Namespace URI, or the empty String if the
299     *        name has no Namespace URI.
300     * @param localPart The local name of the attribute.
301     * @return The attribute value as a string, or null if the
302     *         attribute is not in the list.
303     */
304        virtual const XMLCh* getValue(const XMLCh* const uri, const XMLCh* const localPart ) const = 0 ;
305
306   /**
307     * Look up an attribute's value by XML 1.0 qualified name.
308     *
309     * <p>See #getValue for a description of the possible values.</p>
310     *
311     * @param qName The XML 1.0 qualified name.
312     * @return The attribute value as a string, or null if the
313     *         attribute is not in the list or if qualified names
314     *         are not available.
315     */
316    virtual const XMLCh* getValue(const XMLCh* const qName) const = 0;
317
318    //@}
319
320private :
321    /* Constructors and operators */
322    /* Copy constructor */
323    Attributes(const Attributes&);
324    /* Assignment operator */
325    Attributes& operator=(const Attributes&);
326
327};
328
329XERCES_CPP_NAMESPACE_END
330
331#endif
Note: See TracBrowser for help on using the repository browser.