Home | History | Annotate | Download | only in parameter 
      1 /*
      2  * Copyright (c) 2011-2015, Intel Corporation
      3  * All rights reserved.
      4  *
      5  * Redistribution and use in source and binary forms, with or without modification,
      6  * are permitted provided that the following conditions are met:
      7  *
      8  * 1. Redistributions of source code must retain the above copyright notice, this
      9  * list of conditions and the following disclaimer.
     10  *
     11  * 2. Redistributions in binary form must reproduce the above copyright notice,
     12  * this list of conditions and the following disclaimer in the documentation and/or
     13  * other materials provided with the distribution.
     14  *
     15  * 3. Neither the name of the copyright holder nor the names of its contributors
     16  * may be used to endorse or promote products derived from this software without
     17  * specific prior written permission.
     18  *
     19  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
     20  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
     21  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
     22  * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
     23  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
     24  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
     25  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
     26  * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
     27  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
     28  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
     29  */
     30 #pragma once
     31 
     32 #include "parameter_export.h"
     33 
     34 #include <string>
     35 #include <vector>
     36 #include <stdint.h>
     37 #include "XmlSink.h"
     38 #include "XmlSource.h"
     39 
     40 #include "PathNavigator.h"
     41 
     42 class CXmlElementSerializingContext;
     43 namespace utility
     44 {
     45 class ErrorContext;
     46 }
     47 
     48 class PARAMETER_EXPORT CElement : public IXmlSink, public IXmlSource
     49 {
     50 public:
     51     CElement(const std::string &strName = "");
     52     virtual ~CElement();
     53 
     54     // Description
     55     void setDescription(const std::string &strDescription);
     56     const std::string &getDescription() const;
     57 
     58     // Name / Path
     59     const std::string &getName() const;
     60     void setName(const std::string &strName);
     61     bool rename(const std::string &strName, std::string &strError);
     62     std::string getPath() const;
     63     std::string getQualifiedPath() const;
     64 
     65     // Creation / build
     66     virtual bool init(std::string &strError);
     67     virtual void clean();
     68 
     69     // Children management
     70     void addChild(CElement *pChild);
     71     bool removeChild(CElement *pChild);
     72     void listChildren(std::string &strChildList) const;
     73     std::string listQualifiedPaths(bool bDive, size_t level = 0) const;
     74     void listChildrenPaths(std::string &strChildPathList) const;
     75 
     76     // Hierarchy query
     77     size_t getNbChildren() const;
     78     CElement *findChildOfKind(const std::string &strKind);
     79     const CElement *findChildOfKind(const std::string &strKind) const;
     80     const CElement *getParent() const;
     81 
     82     /**
     83      * Get a child element (const)
     84      *
     85      * Note: this method will assert if given a wrong child index (>= number of children)
     86      *
     87      * @param[in] index the index of the child element from 0 to number of children - 1
     88      * @return the child element
     89      */
     90     const CElement *getChild(size_t index) const;
     91 
     92     /**
     93      * Get a child element
     94      *
     95      * Note: this method will assert if given a wrong child index (>= number of children)
     96      *
     97      * @param[in] index the index of the child element from 0 to number of children - 1
     98      * @return the child element
     99      */
    100     CElement *getChild(size_t index);
    101 
    102     const CElement *findChild(const std::string &strName) const;
    103     CElement *findChild(const std::string &strName);
    104     const CElement *findDescendant(CPathNavigator &pathNavigator) const;
    105     CElement *findDescendant(CPathNavigator &pathNavigator);
    106     bool isDescendantOf(const CElement *pCandidateAscendant) const;
    107 
    108     // From IXmlSink
    109     virtual bool fromXml(const CXmlElement &xmlElement, CXmlSerializingContext &serializingContext);
    110 
    111     // From IXmlSource
    112     virtual void toXml(CXmlElement &xmlElement, CXmlSerializingContext &serializingContext) const;
    113 
    114     /**
    115      * Serialize the children to XML
    116      *
    117      * This method is virtual, to be derived in case a special treatment is
    118      * needed before doing so.
    119      *
    120      * @param[in,out] xmlElement the XML Element below which the children must
    121      *                be serialized (which may or may not be the CElement
    122      *                object upon which this method is called)
    123      * @param[in,out] serializingContext information about the serialization
    124      */
    125     virtual void childrenToXml(CXmlElement &xmlElement,
    126                                CXmlSerializingContext &serializingContext) const;
    127 
    128     // Content structure dump
    129     std::string dumpContent(utility::ErrorContext &errorContext, const size_t depth = 0) const;
    130 
    131     // Element properties
    132     virtual void showProperties(std::string &strResult) const;
    133 
    134     // Class kind
    135     virtual std::string getKind() const = 0;
    136 
    137     /**
    138      * Fill the Description field of the Xml Element during XML composing.
    139      *
    140      * @param[in,out] xmlElement to fill with the description
    141      */
    142     void setXmlDescriptionAttribute(CXmlElement &xmlElement) const;
    143 
    144     /**
    145      * Appends if found human readable description property.
    146      *
    147      * @param[out] strResult in which the description is wished to be appended.
    148      */
    149     void showDescriptionProperty(std::string &strResult) const;
    150 
    151     /**
    152      * Returns Xml element name used for element XML importing/exporting functionalities
    153      */
    154     virtual std::string getXmlElementName() const;
    155 
    156 protected:
    157     // Content dumping
    158     virtual std::string logValue(utility::ErrorContext &errorContext) const;
    159 
    160     // Hierarchy
    161     CElement *getParent();
    162 
    163     /**
    164      * Creates a child CElement from a child XML Element
    165      *
    166      * @param[in] childElement the XML element to create CElement from
    167      * @param[in] elementSerializingContext the serializing context
    168      *
    169      * @return child a pointer on the CElement object that has been added to the tree
    170      */
    171     CElement *createChild(const CXmlElement &childElement,
    172                           CXmlSerializingContext &elementSerializingContext);
    173 
    174     static const std::string gDescriptionPropertyName;
    175 
    176 private:
    177     // Returns Name or Kind if no Name
    178     std::string getPathName() const;
    179     // Returns true if children dynamic creation is to be dealt with
    180     virtual bool childrenAreDynamic() const;
    181     // House keeping
    182     void removeChildren();
    183     // Fill XmlElement during XML composing
    184     void setXmlNameAttribute(CXmlElement &xmlElement) const;
    185 
    186     // Name
    187     std::string _strName;
    188 
    189     // Description
    190     std::string _strDescription;
    191 
    192     // Child iterators
    193     typedef std::vector<CElement *>::iterator ChildArrayIterator;
    194     typedef std::vector<CElement *>::reverse_iterator ChildArrayReverseIterator;
    195     // Children
    196     std::vector<CElement *> _childArray;
    197     // Parent
    198     CElement *_pParent{nullptr};
    199 };
    200