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 } // namespace utility
     47 
     48 class PARAMETER_EXPORT CElement : public IXmlSink, public IXmlSource
     49 {
     50 public:
     51     CElement(const std::string &strName = "");
     52     ~CElement() override;
     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     bool fromXml(const CXmlElement &xmlElement,
    110                  CXmlSerializingContext &serializingContext) override;
    111 
    112     // From IXmlSource
    113     void toXml(CXmlElement &xmlElement, CXmlSerializingContext &serializingContext) const override;
    114 
    115     /**
    116      * Serialize the children to XML
    117      *
    118      * This method is virtual, to be derived in case a special treatment is
    119      * needed before doing so.
    120      *
    121      * @param[in,out] xmlElement the XML Element below which the children must
    122      *                be serialized (which may or may not be the CElement
    123      *                object upon which this method is called)
    124      * @param[in,out] serializingContext information about the serialization
    125      */
    126     virtual void childrenToXml(CXmlElement &xmlElement,
    127                                CXmlSerializingContext &serializingContext) const;
    128 
    129     // Content structure dump
    130     std::string dumpContent(utility::ErrorContext &errorContext, const size_t depth = 0) const;
    131 
    132     // Element properties
    133     virtual void showProperties(std::string &strResult) const;
    134 
    135     // Class kind
    136     virtual std::string getKind() const = 0;
    137 
    138     /**
    139      * Fill the Description field of the Xml Element during XML composing.
    140      *
    141      * @param[in,out] xmlElement to fill with the description
    142      */
    143     void setXmlDescriptionAttribute(CXmlElement &xmlElement) const;
    144 
    145     /**
    146      * Appends if found human readable description property.
    147      *
    148      * @param[out] strResult in which the description is wished to be appended.
    149      */
    150     void showDescriptionProperty(std::string &strResult) const;
    151 
    152     /**
    153      * Returns Xml element name used for element XML importing/exporting functionalities
    154      */
    155     virtual std::string getXmlElementName() const;
    156 
    157 protected:
    158     // Content dumping
    159     virtual std::string logValue(utility::ErrorContext &errorContext) const;
    160 
    161     // Hierarchy
    162     CElement *getParent();
    163 
    164     /**
    165      * Creates a child CElement from a child XML Element
    166      *
    167      * @param[in] childElement the XML element to create CElement from
    168      * @param[in] elementSerializingContext the serializing context
    169      *
    170      * @return child a pointer on the CElement object that has been added to the tree
    171      */
    172     CElement *createChild(const CXmlElement &childElement,
    173                           CXmlSerializingContext &elementSerializingContext);
    174 
    175     static const std::string gDescriptionPropertyName;
    176 
    177 private:
    178     // Returns Name or Kind if no Name
    179     std::string getPathName() const;
    180     // Returns true if children dynamic creation is to be dealt with
    181     virtual bool childrenAreDynamic() const;
    182     // House keeping
    183     void removeChildren();
    184     // Fill XmlElement during XML composing
    185     void setXmlNameAttribute(CXmlElement &xmlElement) const;
    186 
    187     // Name
    188     std::string _strName;
    189 
    190     // Description
    191     std::string _strDescription;
    192 
    193     // Child iterators
    194     typedef std::vector<CElement *>::iterator ChildArrayIterator;
    195     typedef std::vector<CElement *>::reverse_iterator ChildArrayReverseIterator;
    196     // Children
    197     std::vector<CElement *> _childArray;
    198     // Parent
    199     CElement *_pParent{nullptr};
    200 };
    201