// Created by: DAUTRY Philippe
// Copyright (c) 1997-1999 Matra Datavision
// Copyright (c) 1999-2014 OPEN CASCADE SAS
//
// This file is part of Open CASCADE Technology software library.
//
// This library is free software; you can redistribute it and/or modify it under
// the terms of the GNU Lesser General Public License version 2.1 as published
// by the Free Software Foundation, with special exception defined in the file
// OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
// distribution for complete text of the license and disclaimer of any warranty.
//
// Alternatively, this file may be used under the terms of Open CASCADE
// commercial license or contractual agreement.

#ifndef _TDF_Attribute_HeaderFile
#define _TDF_Attribute_HeaderFile

#include "Standard.hxx"
#include "Standard_Type.hxx"

#include "TDF_LabelNodePtr.hxx"
#include "Standard_Integer.hxx"
#include "Standard_Transient.hxx"
#include "Standard_OStream.hxx"
#include "NCollection_IndexedMap.hxx"
class TDF_Label;
class TDF_DeltaOnForget;
class Standard_GUID;
class TDF_AttributeDelta;
class TDF_DeltaOnAddition;
class TDF_DeltaOnResume;
class TDF_DeltaOnModification;
class TDF_DeltaOnRemoval;
class TDF_RelocationTable;
class TDF_DataSet;
class TDF_IDFilter;

//! A class each application has to implement. It is
//! used to contain the application data.
//! This abstract class, alongwith Label,
//! is one of the cornerstones of Model Editor.
//! The groundwork is to define the root of
//! information. This information is to be
//! attached to a Label, and could be of any of
//! the following types:
//! -   a feature
//! -   a constraint
//! -   a comment
//!
//! Contents:
//! ---------
//!
//! Each software component who'd like to attach its
//! own information to a label has to inherit from
//! this class and has to add its own information as
//! fields of this new class.
//!
//! Identification:
//! ---------------
//!
//! An attribute can be identified by its ID. Every
//! attributes used with the same meaning (for
//! example: Integer, String, Topology...) have the
//! same worldwide unique ID.
//!
//! Addition:
//! ---------
//!
//! An attribute can be added to a label only if there
//! is no attribute yet with the same ID. Call-back
//! methods are offered, called automatically before
//! and after the addition action.
//!
//! Removal:
//! --------
//!
//! An attribute can be removed from a label only if
//! there is an attribute yet with the same
//! ID. Call-back methods are offered, called
//! automatically before and after the removal
//! action. A removed attribute cannot be found
//! again. After a removal, only an addition of an
//! attribute with the sane ID is possible (no
//! backup...).
//!
//! Modification & Transaction:
//! ---------------------------
//!
//! An attribute can be backuped before a
//! modification. Only one backup attribute by
//! transaction is possible. The modification can be
//! forgotten (abort transaction) or validated (commit
//! transaction).
//!
//! BackupCopy and restore are methods used by the backup or
//! abort transaction actions. BackupCopy is called by
//! Backup to generate an attribute with the same
//! contents as the current one. Restore is called
//! when aborting a transaction to transfer the
//! backuped contents into the current
//! attribute. These methods must be implemented by
//! end use inheriting classes.
//!
//! A standard implementation of BackupCopy is provided, but
//! it is not necessary a good one for any use.
//!
//! Copy use methods:
//! -----------------
//!
//! Paste and NewEmpty methods are used by the copy
//! algorithms. The goal of "Paste" is to transfer an
//! attribute new contents into another attribute. The
//! goal of "NewEmpty" is to create an attribute
//! without contents, to be further filled with the
//! new contents of another one. These 2 methods must
//! be implemented by end use inheriting classes.
//!
//! AttributeDelta:
//! ---------------
//!
//! An AttributeDelta is the difference between to
//! attribute values states. These methods must be
//! implemented by end use inheriting classes, to
//! profit from the delta services.
class TDF_Attribute : public Standard_Transient
{

public:
  //! Returns the ID of the attribute.
  Standard_EXPORT virtual const Standard_GUID& ID() const = 0;

  //! Sets specific ID of the attribute (supports several attributes
  //! of one type at the same label feature).
  virtual void SetID(const Standard_GUID& /*theGuid*/) {}

  //! Sets default ID defined in nested class (to be used for attributes having User ID feature).
  virtual void SetID() {}

  //! Returns the label to which the attribute is
  //! attached. If the label is not included in a DF,
  //! the label is null. See Label.
  //! Warning:
  //! If the label is not included in a data
  //! framework, it is null.
  //! This function should not be redefined inline.
  Standard_EXPORT const TDF_Label Label() const;

  //! Returns the transaction index in which the
  //! attribute has been created or modified.
  int Transaction() const;

  //! Returns the upper transaction index until which
  //! the attribute is/was valid. This number may
  //! vary. A removed attribute validity range is
  //! reduced to its transaction index.
  Standard_EXPORT int UntilTransaction() const;

  //! Returns true if the attribute is valid; i.e. not a
  //! backuped or removed one.
  bool IsValid() const;

  //! Returns true if the attribute has no backup
  bool IsNew() const;

  //! Returns true if the attribute forgotten status is
  //! set.
  //!
  //! ShortCut Methods concerning associated attributes
  //! =================================================
  bool IsForgotten() const;

  //! Returns true if it exists an associated attribute
  //! of <me> with <anID> as ID.
  Standard_EXPORT bool IsAttribute(const Standard_GUID& anID) const;

  //! Finds an associated attribute of <me>, according
  //! to <anID>. the returned <anAttribute> is a valid
  //! one. The method returns True if found, False
  //! otherwise. A removed attribute cannot be found using
  //! this method.
  Standard_EXPORT bool FindAttribute(const Standard_GUID&        anID,
                                     occ::handle<TDF_Attribute>& anAttribute) const;

  //! Safe variant for arbitrary type of argument
  template <class T>
  bool FindAttribute(const Standard_GUID& theID, occ::handle<T>& theAttr) const
  {
    occ::handle<TDF_Attribute> anAttr = theAttr;
    return FindAttribute(theID, anAttr) && !(theAttr = occ::down_cast<T>(anAttr)).IsNull();
  }

  //! Adds an Attribute <other> to the label of <me>.
  //! Raises if there is already one of the same GUID
  //! than <other>.
  Standard_EXPORT void AddAttribute(const occ::handle<TDF_Attribute>& other) const;

  //! Forgets the Attribute of GUID <aguid> associated
  //! to the label of <me>. Be careful that if <me> is
  //! the attribute of <guid>, <me> will have a null label
  //! after this call. If the attribute doesn't exist
  //! returns False. Otherwise returns True.
  Standard_EXPORT bool ForgetAttribute(const Standard_GUID& aguid) const;

  //! Forgets all the attributes attached to the label
  //! of <me>. Does it on the sub-labels if
  //! <clearChildren> is set to true. Of course, this
  //! method is compatible with Transaction & Delta
  //! mechanisms. Be careful that if <me> will have a
  //! null label after this call
  Standard_EXPORT void ForgetAllAttributes(const bool clearChildren = true) const;

  //! Something to do after adding an Attribute to a label.
  Standard_EXPORT virtual void AfterAddition();

  //! Something to do before removing an Attribute from
  //! a label.
  Standard_EXPORT virtual void BeforeRemoval();

  //! Something to do before forgetting an Attribute to a
  //! label.
  Standard_EXPORT virtual void BeforeForget();

  //! Something to do after resuming an Attribute from
  //! a label.
  Standard_EXPORT virtual void AfterResume();

  //! Something to do AFTER creation of an attribute by
  //! persistent-transient translation. The returned
  //! status says if AfterUndo has been performed (true)
  //! or if this callback must be called once again
  //! further (false). If <forceIt> is set to true, the
  //! method MUST perform and return true. Does nothing
  //! by default and returns true.
  Standard_EXPORT virtual bool AfterRetrieval(const bool forceIt = false);

  //! Something to do before applying <anAttDelta>. The
  //! returned status says if AfterUndo has been
  //! performed (true) or if this callback must be
  //! called once again further (false). If <forceIt> is
  //! set to true, the method MUST perform and return
  //! true. Does nothing by default and returns true.
  Standard_EXPORT virtual bool BeforeUndo(const occ::handle<TDF_AttributeDelta>& anAttDelta,
                                          const bool                             forceIt = false);

  //! Something to do after applying <anAttDelta>. The
  //! returned status says if AfterUndo has been
  //! performed (true) or if this callback must be
  //! called once again further (false). If <forceIt> is
  //! set to true, the method MUST perform and return
  //! true. Does nothing by default and returns true.
  Standard_EXPORT virtual bool AfterUndo(const occ::handle<TDF_AttributeDelta>& anAttDelta,
                                         const bool                             forceIt = false);

  //! A callback.
  //! By default does nothing.
  //! It is called by TDF_Data::CommitTransaction() method.
  Standard_EXPORT virtual void BeforeCommitTransaction();

  //! Backups the attribute. The backuped attribute is
  //! flagged "Backuped" and not "Valid".
  //!
  //! The method does nothing:
  //!
  //! 1) If the attribute transaction number is equal to
  //! the current transaction number (the attribute has
  //! already been backuped).
  //!
  //! 2) If the attribute is not attached to a label.
  Standard_EXPORT void Backup();

  //! Returns true if the attribute backup status is
  //! set. This status is set/unset by the
  //! Backup() method.
  bool IsBackuped() const;

  //! Copies the attribute contents into a new other
  //! attribute. It is used by Backup().
  Standard_EXPORT virtual occ::handle<TDF_Attribute> BackupCopy() const;

  //! Restores the backuped contents from <anAttribute>
  //! into this one. It is used when aborting a
  //! transaction.
  Standard_EXPORT virtual void Restore(const occ::handle<TDF_Attribute>& anAttribute) = 0;

  //! Makes an AttributeDelta because <me>
  //! appeared. The only known use of a redefinition of
  //! this method is to return a null handle (no delta).
  Standard_EXPORT virtual occ::handle<TDF_DeltaOnAddition> DeltaOnAddition() const;

  //! Makes an AttributeDelta because <me> has been
  //! forgotten.
  Standard_EXPORT virtual occ::handle<TDF_DeltaOnForget> DeltaOnForget() const;

  //! Makes an AttributeDelta because <me> has been
  //! resumed.
  Standard_EXPORT virtual occ::handle<TDF_DeltaOnResume> DeltaOnResume() const;

  //! Makes a DeltaOnModification between <me> and
  //! <anOldAttribute.
  Standard_EXPORT virtual occ::handle<TDF_DeltaOnModification> DeltaOnModification(
    const occ::handle<TDF_Attribute>& anOldAttribute) const;

  //! Applies a DeltaOnModification to <me>.
  Standard_EXPORT virtual void DeltaOnModification(
    const occ::handle<TDF_DeltaOnModification>& aDelta);

  //! Makes a DeltaOnRemoval on <me> because <me> has
  //! disappeared from the DS.
  Standard_EXPORT virtual occ::handle<TDF_DeltaOnRemoval> DeltaOnRemoval() const;

  //! Returns an new empty attribute from the good end
  //! type. It is used by the copy algorithm.
  Standard_EXPORT virtual occ::handle<TDF_Attribute> NewEmpty() const = 0;

  //! This method is different from the "Copy" one,
  //! because it is used when copying an attribute from
  //! a source structure into a target structure. This
  //! method may paste the contents of <me> into
  //! <intoAttribute>.
  //!
  //! The given pasted attribute can be full or empty of
  //! its contents. But don't make a NEW! Just set the
  //! contents!
  //!
  //! It is possible to use <aRelocationTable> to
  //! get/set the relocation value of a source
  //! attribute.
  Standard_EXPORT virtual void Paste(
    const occ::handle<TDF_Attribute>&       intoAttribute,
    const occ::handle<TDF_RelocationTable>& aRelocationTable) const = 0;

  //! Adds the first level referenced attributes and labels
  //! to <aDataSet>.
  //!
  //! For this, use the AddLabel or AddAttribute of
  //! DataSet.
  //!
  //! If there is none, do not implement the method.
  Standard_EXPORT virtual void References(const occ::handle<TDF_DataSet>& aDataSet) const;

  //! Dumps the minimum information about <me> on
  //! <aStream>.
  Standard_EXPORT virtual Standard_OStream& Dump(Standard_OStream& anOS) const;

  Standard_OStream& operator<<(Standard_OStream& anOS) const { return Dump(anOS); }

  //! Dumps the attribute content on <aStream>, using
  //! <aMap> like this: if an attribute is not in the
  //! map, first put add it to the map and then dump it.
  //! Use the map rank instead of dumping each attribute
  //! field.
  Standard_EXPORT virtual void ExtendedDump(
    Standard_OStream&                                   anOS,
    const TDF_IDFilter&                                 aFilter,
    NCollection_IndexedMap<occ::handle<TDF_Attribute>>& aMap) const;

  //! Forgets the attribute. <aTransaction> is the
  //! current transaction in which the forget is done. A
  //! forgotten attribute is also flagged not "Valid".
  //!
  //! A forgotten attribute is invisible. Set also the
  //! "Valid" status to False. Obviously, DF cannot
  //! empty an attribute (this has a semantic
  //! signification), but can remove it from the
  //! structure. So, a forgotten attribute is NOT an empty
  //! one, but a soon DEAD one.
  //!
  //! Should be private.
  Standard_EXPORT void Forget(const int aTransaction);

  //! Dumps the content of me into the stream
  Standard_EXPORT virtual void DumpJson(Standard_OStream& theOStream, int theDepth = -1) const;

  friend class TDF_Data;
  friend class TDF_Label;
  friend class TDF_LabelNode;
  friend class TDF_AttributeIterator;
  friend class TDF_DeltaOnForget;

  DEFINE_STANDARD_RTTIEXT(TDF_Attribute, Standard_Transient)

protected:
  //! Initializes fields.
  Standard_EXPORT TDF_Attribute();

private:
  //! Set the "Valid" status with <aStatus>.
  void Validate(const bool aStatus);

  //! Resumes the attribute (undos Forget action).
  Standard_EXPORT void Resume();

  //! Set the "backuped" status with <aStatus>.
  void Backup(const bool aStatus);

  //! Removes the last backup attribute, if it exists.
  Standard_EXPORT void RemoveBackup();

  TDF_LabelNodePtr           myLabelNode;
  int                        myTransaction;
  int                        mySavedTransaction;
  int                        myFlags;
  occ::handle<TDF_Attribute> myNext;
  occ::handle<TDF_Attribute> myBackup;
};

#include "TDF_Attribute.lxx"

#endif // _TDF_Attribute_HeaderFile