xercesc/sax2/Attributes.hpp

0001 /*
0002  * Licensed to the Apache Software Foundation (ASF) under one or more
0003  * contributor license agreements.  See the NOTICE file distributed with
0004  * this work for additional information regarding copyright ownership.
0005  * The ASF licenses this file to You under the Apache License, Version 2.0
0006  * (the "License"); you may not use this file except in compliance with
0007  * the License.  You may obtain a copy of the License at
0008  *
0009  *      http://www.apache.org/licenses/LICENSE-2.0
0010  *
0011  * Unless required by applicable law or agreed to in writing, software
0012  * distributed under the License is distributed on an "AS IS" BASIS,
0013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0014  * See the License for the specific language governing permissions and
0015  * limitations under the License.
0016  */
0017
0018 /*
0019  * $Id$
0020  */
0021
0022 #if !defined(XERCESC_INCLUDE_GUARD_ATTRIBUTES_HPP)
0023 #define XERCESC_INCLUDE_GUARD_ATTRIBUTES_HPP
0024
0025 #include <xercesc/util/XercesDefs.hpp>
0026
0027 XERCES_CPP_NAMESPACE_BEGIN
0028
0029 /**
0030   * Interface for an element's attribute specifications.
0031   *
0032   * The SAX2 parser implements this interface and passes an instance
0033   * to the SAX2 application as the last argument of each startElement
0034   * event.
0035   *
0036   * The instance provided will return valid results only during the
0037   * scope of the startElement invocation (to save it for future
0038   * use, the application must make a copy: the AttributesImpl
0039   * helper class provides a convenient constructor for doing so).
0040   *
0041   * An Attributes includes only attributes that have been
0042   * specified or defaulted: \#IMPLIED attributes will not be included.
0043   *
0044   * There are two ways for the SAX application to obtain information
0045   * from the Attributes.  First, it can iterate through the entire
0046   * list:
0047   *
0048   * <code>
0049   * public void startElement (String uri, String localpart, String qName, Attributes atts) {<br>
0050   * &nbsp;for (XMLSize_t i = 0; i < atts.getLength(); i++) {<br>
0051   * &nbsp;&nbsp;String Qname = atts.getQName(i);<br>
0052   * &nbsp;&nbsp;String URI   = atts.getURI(i)<br>
0053   * &nbsp;&nbsp;String local = atts.GetLocalName(i)<br>
0054   * &nbsp;&nbsp;String type  = atts.getType(i);<br>
0055   * &nbsp;&nbsp;String value = atts.getValue(i);<br>
0056   * &nbsp;&nbsp;[...]<br>
0057   * &nbsp;}<br>
0058   * }
0059   * </code>
0060   *
0061   * (Note that the result of getLength() will be zero if there
0062   * are no attributes.)
0063   *
0064   * As an alternative, the application can request the value or
0065   * type of specific attributes:
0066   *
0067   * <code>
0068   * public void startElement (String uri, String localpart, String qName, Attributes atts) {<br>
0069   * &nbsp;String identifier = atts.getValue("id");<br>
0070   * &nbsp;String label = atts.getValue("label");<br>
0071   * &nbsp;[...]<br>
0072   * }
0073   * </code>
0074   *
0075   * The AttributesImpl helper class provides a convenience
0076   * implementation for use by parser or application writers.
0077   *
0078   * @see Sax2DocumentHandler#startElement
0079   * @see AttributesImpl#AttributesImpl
0080   */
0081
0082 class SAX2_EXPORT Attributes
0083 {
0084 public:
0085     // -----------------------------------------------------------------------
0086     //  Constructors and Destructor
0087     // -----------------------------------------------------------------------
0088     /** @name Constructors and Destructor */
0089     //@{
0090     /** Default constructor */
0091     Attributes()
0092     {
0093     }
0094
0095     /** Destructor */
0096     virtual ~Attributes()
0097     {
0098     }
0099     //@}
0100
0101     /** @name The virtual attribute list interface */
0102     //@{
0103   /**
0104     * Return the number of attributes in this list.
0105     *
0106     * The SAX parser may provide attributes in any
0107     * arbitrary order, regardless of the order in which they were
0108     * declared or specified.  The number of attributes may be
0109     * zero.
0110     *
0111     * @return The number of attributes in the list.
0112     */
0113     virtual XMLSize_t getLength() const = 0;
0114
0115   /**
0116     * Return the namespace URI of an attribute in this list (by position).
0117     *
0118     * The QNames must be unique: the SAX parser shall not include the
0119     * same attribute twice.  Attributes without values (those declared
0120     * \#IMPLIED without a value specified in the start tag) will be
0121     * omitted from the list.
0122     *
0123     * @param index The index of the attribute in the list (starting at 0).
0124     * @return The URI of the indexed attribute, or null
0125     *         if the index is out of range.
0126     * @see #getLength
0127     */
0128     virtual const XMLCh* getURI(const XMLSize_t index) const = 0;
0129
0130   /**
0131     * Return the local name of an attribute in this list (by position).
0132     *
0133     * The QNames must be unique: the SAX parser shall not include the
0134     * same attribute twice.  Attributes without values (those declared
0135     * \#IMPLIED without a value specified in the start tag) will be
0136     * omitted from the list.
0137     *
0138     * @param index The index of the attribute in the list (starting at 0).
0139     * @return The local name of the indexed attribute, or null
0140     *         if the index is out of range.
0141     * @see #getLength
0142     */
0143     virtual const XMLCh* getLocalName(const XMLSize_t index) const = 0;
0144
0145   /**
0146     * Return the qName of an attribute in this list (by position).
0147     *
0148     * The QNames must be unique: the SAX parser shall not include the
0149     * same attribute twice.  Attributes without values (those declared
0150     * \#IMPLIED without a value specified in the start tag) will be
0151     * omitted from the list.
0152     *
0153     * @param index The index of the attribute in the list (starting at 0).
0154     * @return The qName of the indexed attribute, or null
0155     *         if the index is out of range.
0156     * @see #getLength
0157     */
0158     virtual const XMLCh* getQName(const XMLSize_t index) const = 0;
0159
0160   /**
0161     * Return the type of an attribute in the list (by position).
0162     *
0163     * The attribute type is one of the strings "CDATA", "ID",
0164     * "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES",
0165     * or "NOTATION" (always in upper case).
0166     *
0167     * If the parser has not read a declaration for the attribute,
0168     * or if the parser does not report attribute types, then it must
0169     * return the value "CDATA" as stated in the XML 1.0 Recommendation
0170     * (clause 3.3.3, "Attribute-Value Normalization").
0171     *
0172     * For an enumerated attribute that is not a notation, the
0173     * parser will report the type as "NMTOKEN".
0174     *
0175     * @param index The index of the attribute in the list (starting at 0).
0176     * @return The attribute type as a string, or
0177     *         null if the index is out of range.
0178     * @see #getLength
0179     * @see #getType
0180     */
0181     virtual const XMLCh* getType(const XMLSize_t index) const = 0;
0182
0183   /**
0184     * Return the value of an attribute in the list (by position).
0185     *
0186     * If the attribute value is a list of tokens (IDREFS,
0187     * ENTITIES, or NMTOKENS), the tokens will be concatenated
0188     * into a single string separated by whitespace.
0189     *
0190     * @param index The index of the attribute in the list (starting at 0).
0191     * @return The attribute value as a string, or
0192     *         null if the index is out of range.
0193     * @see #getLength
0194     * @see #getValue
0195     */
0196     virtual const XMLCh* getValue(const XMLSize_t index) const = 0;
0197
0198     ////////////////////////////////////////////////////////////////////
0199     // Name-based query.
0200     ////////////////////////////////////////////////////////////////////
0201
0202    /**
0203      * Look up the index of an attribute by Namespace name. Non-standard
0204      * extension.
0205      *
0206      * @param uri The Namespace URI, or the empty string if
0207      *        the name has no Namespace URI.
0208      * @param localPart The attribute's local name.
0209      * @param index Reference to the variable where the index will be stored.
0210      * @return true if the attribute is found and false otherwise.
0211      */
0212     virtual bool getIndex(const XMLCh* const uri,
0213                           const XMLCh* const localPart,
0214                           XMLSize_t& index) const = 0 ;
0215
0216    /**
0217      * Look up the index of an attribute by Namespace name.
0218      *
0219      * @param uri The Namespace URI, or the empty string if
0220      *        the name has no Namespace URI.
0221      * @param localPart The attribute's local name.
0222      * @return The index of the attribute, or -1 if it does not
0223      *         appear in the list.
0224      */
0225     virtual int getIndex(const XMLCh* const uri,
0226                          const XMLCh* const localPart ) const = 0 ;
0227
0228     /**
0229      * Look up the index of an attribute by XML 1.0 qualified name.
0230      * Non-standard extension.
0231      *
0232      * @param qName The qualified (prefixed) name.
0233      * @param index Reference to the variable where the index will be stored.
0234      * @return true if the attribute is found and false otherwise.
0235      */
0236     virtual bool getIndex(const XMLCh* const qName,
0237                           XMLSize_t& index) const = 0 ;
0238
0239    /**
0240      * Look up the index of an attribute by XML 1.0 qualified name.
0241      *
0242      * @param qName The qualified (prefixed) name.
0243      * @return The index of the attribute, or -1 if it does not
0244      *         appear in the list.
0245      */
0246     virtual int getIndex(const XMLCh* const qName ) const = 0 ;
0247
0248    /**
0249      * Look up an attribute's type by Namespace name.
0250      *
0251      * <p>See #getType for a description of the possible types.</p>
0252      *
0253      * @param uri The Namespace URI, or the empty String if the
0254      *        name has no Namespace URI.
0255      * @param localPart The local name of the attribute.
0256      * @return The attribute type as a string, or null if the
0257      *         attribute is not in the list or if Namespace
0258      *         processing is not being performed.
0259      */
0260     virtual const XMLCh* getType(const XMLCh* const uri,
0261                                  const XMLCh* const localPart ) const = 0 ;
0262
0263    /**
0264      * Look up an attribute's type by XML 1.0 qualified name.
0265      *
0266      * <p>See #getType for a description of the possible types.</p>
0267      *
0268      * @param qName The XML 1.0 qualified name.
0269      * @return The attribute type as a string, or null if the
0270      *         attribute is not in the list or if qualified names
0271      *         are not available.
0272      */
0273     virtual const XMLCh* getType(const XMLCh* const qName) const = 0;
0274
0275    /**
0276      * Look up an attribute's value by Namespace name.
0277      *
0278      * <p>See #getValue for a description of the possible values.</p>
0279      *
0280      * @param uri The Namespace URI, or the empty String if the
0281      *        name has no Namespace URI.
0282      * @param localPart The local name of the attribute.
0283      * @return The attribute value as a string, or null if the
0284      *         attribute is not in the list.
0285      */
0286     virtual const XMLCh* getValue(const XMLCh* const uri, const XMLCh* const localPart ) const = 0 ;
0287
0288    /**
0289      * Look up an attribute's value by XML 1.0 qualified name.
0290      *
0291      * <p>See #getValue for a description of the possible values.</p>
0292      *
0293      * @param qName The XML 1.0 qualified name.
0294      * @return The attribute value as a string, or null if the
0295      *         attribute is not in the list or if qualified names
0296      *         are not available.
0297      */
0298     virtual const XMLCh* getValue(const XMLCh* const qName) const = 0;
0299
0300     //@}
0301
0302 private :
0303     /* Constructors and operators */
0304     /* Copy constructor */
0305     Attributes(const Attributes&);
0306     /* Assignment operator */
0307     Attributes& operator=(const Attributes&);
0308
0309 };
0310
0311 XERCES_CPP_NAMESPACE_END
0312
0313 #endif