1 /*

     2 * Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: 

    15 *

    16 */

    17 /*

    18  * Licensed to the Apache Software Foundation (ASF) under one or more

    19  * contributor license agreements.  See the NOTICE file distributed with

    20  * this work for additional information regarding copyright ownership.

    21  * The ASF licenses this file to You under the Apache License, Version 2.0

    22  * (the "License"); you may not use this file except in compliance with

    23  * the License.  You may obtain a copy of the License at

    24  * 

    25  *      http://www.apache.org/licenses/LICENSE-2.0

    26  * 

    27  * Unless required by applicable law or agreed to in writing, software

    28  * distributed under the License is distributed on an "AS IS" BASIS,

    29  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

    30  * See the License for the specific language governing permissions and

    31  * limitations under the License.

    32  */

    33 

    34 /*

    35  * $Id: AttributeList.hpp 568078 2007-08-21 11:43:25Z amassari $

    36  */

    37 

    38 #ifndef ATTRIBUTELIST_HPP

    39 #define ATTRIBUTELIST_HPP

    40 

    41 #include <xercesc/util/XercesDefs.hpp>

    42 

    43 XERCES_CPP_NAMESPACE_BEGIN

    44 

    45 /**

    46   * Interface for an element's attribute specifications.

    47   *

    48   * The SAX parser implements this interface and passes an instance

    49   * to the SAX application as the second argument of each startElement

    50   * event.

    51   *

    52   * The instance provided will return valid results only during the

    53   * scope of the startElement invocation (to save it for future

    54   * use, the application must make a copy: the AttributeListImpl

    55   * helper class provides a convenient constructor for doing so).

    56   *

    57   * An AttributeList includes only attributes that have been

    58   * specified or defaulted: #IMPLIED attributes will not be included.

    59   *

    60   * There are two ways for the SAX application to obtain information

    61   * from the AttributeList.  First, it can iterate through the entire

    62   * list:

    63   *

    64   * <code>

    65   * public void startElement (String name, AttributeList atts) {<br>

    66   * &nbsp;for (int i = 0; i < atts.getLength(); i++) {<br>

    67   * &nbsp;&nbsp;String name = atts.getName(i);<br>

    68   * &nbsp;&nbsp;String type = atts.getType(i);<br>

    69   * &nbsp;&nbsp;String value = atts.getValue(i);<br>

    70   * &nbsp;&nbsp;[...]<br>

    71   * &nbsp;}<br>

    72   * }

    73   * </code>

    74   *

    75   * (Note that the result of getLength() will be zero if there

    76   * are no attributes.)

    77   *

    78   * As an alternative, the application can request the value or

    79   * type of specific attributes:

    80   *

    81   * <code>

    82   * public void startElement (String name, AttributeList atts) {<br>

    83   * &nbsp;String identifier = atts.getValue("id");<br>

    84   * &nbsp;String label = atts.getValue("label");<br>

    85   * &nbsp;[...]<br>

    86   * }

    87   * </code>

    88   *

    89   * The AttributeListImpl helper class provides a convenience

    90   * implementation for use by parser or application writers.

    91   *

    92   * @see DocumentHandler#startElement

    93   * @see AttributeListImpl#AttributeListImpl

    94   */

    95 

    96 class SAX_EXPORT AttributeList

    97 {

    98 public:

    99     // -----------------------------------------------------------------------

   100     //  Constructors and Destructor

   101     // -----------------------------------------------------------------------

   102     /** @name Constructors and Destructor */

   103     //@{

   104     /** Default constructor */

   105     AttributeList()

   106     {

   107     }

   108 

   109     /** Destructor */

   110     virtual ~AttributeList()

   111     {

   112     }

   113     //@}

   114 

   115     /** @name The virtual attribute list interface */

   116     //@{

   117   /**

   118     * Return the number of attributes in this list.

   119     *

   120     * The SAX parser may provide attributes in any

   121     * arbitrary order, regardless of the order in which they were

   122     * declared or specified.  The number of attributes may be

   123     * zero.

   124     *

   125     * @return The number of attributes in the list.

   126     */

   127     virtual unsigned int getLength() const = 0;

   128 

   129   /**

   130     * Return the name of an attribute in this list (by position).

   131     *

   132     * The names must be unique: the SAX parser shall not include the

   133     * same attribute twice.  Attributes without values (those declared

   134     * #IMPLIED without a value specified in the start tag) will be

   135     * omitted from the list.

   136     *

   137     * If the attribute name has a namespace prefix, the prefix

   138     * will still be attached.

   139     *

   140     * @param index The index of the attribute in the list (starting at 0).

   141     * @return The name of the indexed attribute, or null

   142     *         if the index is out of range.

   143     * @see #getLength

   144     */

   145     virtual const XMLCh* getName(const unsigned int index) const = 0;

   146 

   147   /**

   148     * Return the type of an attribute in the list (by position).

   149     *

   150     * The attribute type is one of the strings "CDATA", "ID",

   151     * "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES",

   152     * or "NOTATION" (always in upper case).

   153     *

   154     * If the parser has not read a declaration for the attribute,

   155     * or if the parser does not report attribute types, then it must

   156     * return the value "CDATA" as stated in the XML 1.0 Recommentation

   157     * (clause 3.3.3, "Attribute-Value Normalization").

   158     *

   159     * For an enumerated attribute that is not a notation, the

   160     * parser will report the type as "NMTOKEN".

   161     *

   162     * @param index The index of the attribute in the list (starting at 0).

   163     * @return The attribute type as a string, or

   164     *         null if the index is out of range.

   165     * @see #getLength

   166     * @see #getType(String)

   167     */

   168     virtual const XMLCh* getType(const unsigned int index) const = 0;

   169 

   170   /**

   171     * Return the value of an attribute in the list (by position).

   172     *

   173     * If the attribute value is a list of tokens (IDREFS,

   174     * ENTITIES, or NMTOKENS), the tokens will be concatenated

   175     * into a single string separated by whitespace.

   176     *

   177     * @param index The index of the attribute in the list (starting at 0).

   178     * @return The attribute value as a string, or

   179     *         null if the index is out of range.

   180     * @see #getLength

   181     * @see #getValue(XMLCh*)

   182     * @see #getValue(char *)

   183     */

   184     virtual const XMLCh* getValue(const unsigned int index) const = 0;

   185 

   186   /**

   187     * Return the type of an attribute in the list (by name).

   188     *

   189     * The return value is the same as the return value for

   190     * getType(int).

   191     *

   192     * If the attribute name has a namespace prefix in the document,

   193     * the application must include the prefix here.

   194     *

   195     * @param name The name of the attribute.

   196     * @return The attribute type as a string, or null if no

   197     *         such attribute exists.

   198     * @see #getType(int)

   199     */

   200     virtual const XMLCh* getType(const XMLCh* const name) const = 0;

   201 

   202   /**

   203     * Return the value of an attribute in the list (by name).

   204     *

   205     * The return value is the same as the return value for

   206     * getValue(int).

   207     *

   208     * If the attribute name has a namespace prefix in the document,

   209     * the application must include the prefix here.

   210     *

   211     * @param name The name of the attribute in the list.

   212     * @return The attribute value as a string, or null if

   213     *         no such attribute exists.

   214     * @see #getValue(int)

   215     * @see #getValue(char *)

   216     */

   217     virtual const XMLCh* getValue(const XMLCh* const name) const = 0;

   218 

   219   /**

   220     * Return the value of an attribute in the list (by name).

   221     *

   222     * The return value is the same as the return value for

   223     * getValue(int).

   224     *

   225     * If the attribute name has a namespace prefix in the document,

   226     * the application must include the prefix here.

   227     *

   228     * @param name The name of the attribute in the list.

   229     * @return The attribute value as a string, or null if

   230     *         no such attribute exists.

   231     * @see #getValue(int)

   232     * @see #getValue(XMLCh*)

   233     */

   234     virtual const XMLCh* getValue(const char* const name) const = 0;

   235     //@}

   236 

   237 private :

   238     /* Constructors and operators */

   239     /* Copy constructor */

   240     AttributeList(const AttributeList&);

   241     /* Assignment operator */

   242     AttributeList& operator=(const AttributeList&);

   243 

   244 };

   245 

   246 XERCES_CPP_NAMESPACE_END

   247 

   248 #endif