/////////////////////////////////////////////////////////////////////////////// 
// Copyright (C) 2002-2025, Open Design Alliance (the "Alliance"). 
// All rights reserved. 
// 
// This software and its documentation and related materials are owned by 
// the Alliance. The software may only be incorporated into application 
// programs owned by members of the Alliance, subject to a signed 
// Membership Agreement and Supplemental Software License Agreement with the
// Alliance. The structure and organization of this software are the valuable  
// trade secrets of the Alliance and its suppliers. The software is also 
// protected by copyright law and international treaty provisions. Application  
// programs incorporating this software must include the following statement 
// with their copyright notices:
//   
//   This application incorporates Open Design Alliance software pursuant to a license 
//   agreement with Open Design Alliance.
//   Open Design Alliance Copyright (C) 2002-2025 by Open Design Alliance. 
//   All rights reserved.
//
// By use of this software, its documentation or related materials, you 
// acknowledge and accept the above terms.
///////////////////////////////////////////////////////////////////////////////

#if !defined(ODA_ODMVDXMLCONCEPT_H_INCLUDED_)
#define ODA_ODMVDXMLCONCEPT_H_INCLUDED_

#if _MSC_VER > 1000
#pragma once
#endif // _MSC_VER > 1000

#include "MvdXmlIdentity.h"
#include "MvdXmlTemplateRule.h"
#include "MvdXmlTemplateRef.h"
#include "MvdXmlRequirement.h"
#include "MvdXmlTemplateRules.h"

/** \details 
Contains declarations related to Model View Definition (MVD) functionality.
*/
namespace OdMvdXml
{
  SMARTPTR(OdMvdXmlConcept);

  /** \details 
    A class that stores and handles data about a Concept element. 
    Concept element contains a usage definition for an appropriate entity within a related set of rules.
  */
  class MVDXML_EXPORT OdMvdXmlConcept : public OdMvdXmlIdentityDefinitions
  {
    ODRX_DECLARE_MEMBERS(OdMvdXmlConcept);

    /** \details 
      Creates a new Concept element with default parameters.
    */
    OdMvdXmlConcept();

    /** \details
      Retrieves the Template for the Concept object. 
      The Template element is represented with a reference to the <exref target="../tifc_api_cpp/OdMvdXml__OdMvdXmlConceptTemplate.html">Concept Template</exref> object by its unique identifier (UUID).
      \returns A smart pointer to the <exref target="../tifc_api_cpp/OdMvdXml__OdMvdXmlTemplateRef.html">OdMvdXmlTemplateRef</exref> object that represents the <exref target="../tifc_api_cpp/OdMvdXml__OdMvdXmlConceptTemplate.html">Concept Template</exref> for the Concept object.
    */
    const OdMvdXmlTemplateRefPtr& getTempateRef() const { return m_pTempateRef; };

    /** \details
      Retrieves the set of requirements which describe applicability of the Concept for particular exchanges for import, export or both.
      \returns An array of smart pointers to <exref target="../tifc_api_cpp/OdMvdXml__OdMvdXmlRequirement.html">OdMvdXmlRequirement</exref> objects.
    */
    const OdMvdXmlRequirementPtrArray& getRequirements() const { return m_requirements; };

    /** \details
      Retrieves the set of <exref target="../tifc_api_cpp/OdMvdXml__OdMvdXmlTemplateRules.html">template rules</exref> for the Concept object.
      \returns An array of smart pointers to <exref target="../tifc_api_cpp/OdMvdXml__OdMvdXmlTemplateRules.html">OdMvdXmlTemplateRules</exref> objects.
    */
    const OdMvdXmlTemplateRulesPtr& getRules() const { return m_rules; };
    
    /** \details
      Retrieves the template for the Concept object.
      \returns A raw pointer to the <exref target="../tifc_api_cpp/OdMvdXml__OdMvdXmlConceptTemplate.html">OdMvdXmlConceptTemplate</exref> object that represents the template the Concept object is based on.
    */
    const OdMvdXmlConceptTemplate* getConceptTemplate() const;

    /** \details
      Checks whether a specified <exref target="../tifc_api_cpp/OdDAI__ApplicationInstance.html">ApplicationInstance</exref> meets all constraints defined within the Concept object.
      \param pInstance [in] A raw pointer to the <exref target="../tifc_api_cpp/OdDAI__ApplicationInstance.html">application instance</exref> to check up.
      \param result    [out] A placeholder for the checkup result, represented with a boolean value.
      \returns eOk if the instance was successfully checked; otherwise, the method returns an appropriate error code.
      \remarks 
      If any of the required data is missing or violates any of the constraints, the checkup fails, and the output result parameter value equals false.
      If the checkup procedure fails itself, the value of the output parameter with the checkup result has an undefined value.
    */
    OdResult checkInstance(const OdDAI::ApplicationInstance* pInstance, bool& result) const;

  protected:
    /** \details
      Retrieves the name of the element. This name is used to write the element to a file.

      \returns The name of the element.
    */
    virtual OdAnsiString getElementName();

    /** \details
      Reads attributes from a xml element.

      \param pItem [in] Pointer to a xml element containing attributes.

      \returns eOk if the data was successfully read; otherwise, the method returns an appropriate error code.
    */
    virtual OdResult inAttributes(TiXmlElement* pItem) override;

    /** \details
      Reads child element from a xml element.

      \param nodeName [in] The node name of the xml element containing the child data.
      \param pChild [in] Pointer to a xml element containing child data.

      \returns eOk if the data was successfully read; otherwise, the method returns an appropriate error code.
    */
    virtual OdResult inChildNode(const char *nodeName, TiXmlElement* pChild) override;

    /** \details
      Writing attributes to the xml element.

      \param pItem [in] Pointer to the xml element to which you want to add attributes.

      \returns eOk if the data was written successfully; otherwise, the method returns an appropriate error code.
    */
    virtual OdResult outAttributes(TiXmlElement* pItem) override;

    /** \details
      Writing child elements to the xml element.

      \param pParent [in] Pointer to the xml element to which you want to add children.

      \returns eOk if the data was written successfully; otherwise, the method returns an appropriate error code.
    */
    virtual OdResult outChildNodes(TiXmlNode* pParent) override;

  private:
    /** \details
      Enables to select a concept definition that shall either be reused or redefined.
      This feature depends on the inheritance tree of the underlying schema. 
    */
    OdGUID m_baseConcept;
    /** \details
      This value must be defined if a BaseConcept is selected.  
      If Override = false then the Concept is reused without changes.  
      If true then the Concept from the super type is redefined by this Concept.
    */
    bool m_override;
    /** \details
      Mandatory reference to the ConceptTemplate by uuid, where such
      template may be defined within the same file(by @ref) or an external file
      (by @href).
    */
    OdMvdXmlTemplateRefPtr m_pTempateRef;
    /** \details
      Set of requirements which describe applicability of the concept to particular
      exchanges for import, export or both.
    */
    OdMvdXmlRequirementPtrArray m_requirements;
    /** \details
      Tree structure of rules indicating how template applies to particular entity.
      Each TemplateRules element consists of a set of other TemplateRules or
      TemplateRule element and a logical operator. Each TemplateRule element
      defines the @Parameter that refer to the RuleID of the referenced Template.
    */
    OdMvdXmlTemplateRulesPtr m_rules;
  };
}

#endif // !defined(ODA_ODMVDXMLCONCEPT_H_INCLUDED_)