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: DOM_Attr.hpp 568078 2007-08-21 11:43:25Z amassari $

    36  */

    37 

    38 #ifndef DOM_Attr_HEADER_GUARD_

    39 #define DOM_Attr_HEADER_GUARD_

    40 

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

    42 #include "DOM_Node.hpp"

    43 #include "DOM_Element.hpp"

    44 

    45 XERCES_CPP_NAMESPACE_BEGIN

    46 

    47 

    48 class AttrImpl;

    49 

    50 /**

    51 * The <code>DOM_Attr</code> class refers to an attribute of an XML element.

    52 *

    53 * Typically the allowable values for the

    54 * attribute are defined in a documenttype definition.

    55 * <p><code>DOM_Attr</code> objects inherit the <code>DOM_Node</code>  interface, but

    56 * since attributes are not actually child nodes of the elements they are associated with, the

    57 * DOM does not consider them part of the document  tree.  Thus, the

    58 * <code>DOM_Node</code> attributes <code>parentNode</code>,

    59 * <code>previousSibling</code>, and <code>nextSibling</code> have a  null

    60 * value for <code>DOM_Attr</code> objects. The DOM takes the  view that

    61 * attributes are properties of elements rather than having a  separate

    62 * identity from the elements they are associated with;  this should make it

    63 * more efficient to implement such features as default attributes associated

    64 * with all elements of a  given type.  Furthermore, attribute nodes

    65 * may not be immediate children of a <code>DocumentFragment</code>. However,

    66 * they can be associated with <code>Element</code> nodes contained within a

    67 * <code>DocumentFragment</code>. In short, users of the DOM

    68 * need to be aware that  <code>Attr</code> nodes have some things in  common

    69 * with other objects inheriting the <code>Node</code> interface, but they

    70 * also are quite distinct.

    71 *

    72 */

    73 class DEPRECATED_DOM_EXPORT DOM_Attr: public DOM_Node {

    74 

    75 public:

    76   /** @name Constructors and assignment operators */

    77   //@{

    78   /**

    79     * Default constructor for DOM_Attr.  The resulting object does not

    80     * refer to any Attribute; it will compare == to 0, and is similar

    81     * to a null object reference variable in Java.

    82     *

    83     */

    84     DOM_Attr();

    85 

    86 public:

    87 

    88   /**

    89     * Copy constructor.  Creates a new <code>DOM_Attr</code> that refers to the

    90     *   same underlying Attribute as the original.  See also DOM_Node::clone(),

    91     * which will copy an actual attribute, rather than just creating a new

    92     * reference to the original attribute.

    93     *

    94     * @param other The source attribute reference object

    95     */

    96     DOM_Attr(const DOM_Attr &other);

    97 

    98   /**

    99     * Assignment operator

   100     *

   101     * @param other The source attribute object

   102     */

   103     DOM_Attr & operator = (const DOM_Attr &other);

   104 

   105     /**

   106       * Assignment operator.  This overloaded variant is provided for

   107       *   the sole purpose of setting a DOM_Node reference variable to

   108       *   zero.  Nulling out a reference variable in this way will decrement

   109       *   the reference count on the underlying Node object that the variable

   110       *   formerly referenced.  This effect is normally obtained when reference

   111       *   variable goes out of scope, but zeroing them can be useful for

   112       *   global instances, or for local instances that will remain in scope

   113       *   for an extended time,  when the storage belonging to the underlying

   114       *   node needs to be reclaimed.

   115       *

   116       * @param val   Only a value of 0, or null, is allowed.

   117       */

   118     DOM_Attr & operator = (const DOM_NullPtr *val);

   119 

   120 

   121 

   122 	//@}

   123   /** @name Destructor */

   124   //@{

   125 	

   126   /**

   127     * Destructor.  The object being destroyed is a reference to the Attribute

   128     * "node", not the underlying attribute itself.

   129     *

   130     */

   131     ~DOM_Attr();

   132 	//@}

   133 

   134   /** @name Getter functions */

   135   //@{

   136     /**

   137     * Returns the name of this attribute.

   138     */

   139     DOMString       getName() const;

   140 

   141     /**

   142     *

   143     * Returns true if the attribute received its value explicitly in the

   144     * XML document, or if a value was assigned programatically with

   145     * the setValue function.  Returns false if the attribute value

   146     * came from the default value declared in the document's DTD.

   147     */

   148     bool            getSpecified() const;

   149 

   150     /**

   151 	* Returns the value of the attribute.

   152 	*

   153     * The value of the attribute is returned as a string.

   154     * Character and general entity references are replaced with their values.

   155     */

   156     DOMString       getValue() const;

   157 

   158 	//@}

   159   /** @name Setter functions */

   160   //@{

   161     /**

   162 	* Sets the value of the attribute.  A text node with the unparsed contents

   163     * of the string will be created.

   164 	*

   165     * @param value The value of the DOM attribute to be set

   166     */

   167     void            setValue(const DOMString &value);

   168 	//@}

   169 

   170     /** @name Functions introduced in DOM Level 2. */

   171     //@{

   172     /**

   173      * The <code>DOM_Element</code> node this attribute is attached to or

   174      * <code>null</code> if this attribute is not in use.

   175      *

   176      */

   177     DOM_Element     getOwnerElement() const;

   178     //@}

   179 

   180 protected:

   181     DOM_Attr(AttrImpl *attr);

   182 

   183     friend class DOM_Element;

   184     friend class DOM_Document;

   185 

   186 };

   187 

   188 XERCES_CPP_NAMESPACE_END

   189 

   190 #endif

   191 

   192