path: root/src/TDF/TDF_Attribute.cdl

-- File:	TDF_Attribute.cdl
--      	-----------------
-- Author:	DAUTRY Philippe
--		<fid@fox.paris1.matra-dtv.fr>
---Copyright:	 MATRA DATAVISION 1997

---Version:	0.0
---History:	Version	Date		Purpose
--		0.0	Feb  4 1997	Creation


deferred class Attribute from TDF
    inherits TShared from MMgt

	---Purpose: 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
	--          exemple: 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
	--          whithout 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.

uses

    GUID                from Standard,
    AttributeIndexedMap from TDF,
    DataSet             from TDF,
    AttributeDelta      from TDF,
    DeltaOnModification from TDF,
    DeltaOnRemoval      from TDF,
    DeltaOnResume       from TDF,
    DeltaOnAddition     from TDF,
    DeltaOnForget       from TDF,
    IDFilter            from TDF,
    Label               from TDF,
    LabelNode           from TDF,
    LabelNodePtr        from TDF,
    RelocationTable     from TDF

raises DomainError from Standard


is

    Initialize
    	returns mutable Attribute from TDF;
	---Purpose: Initializes fields.

    ---Category: Information access.
    --           ==============================================================

    -- Implement such a method and use it to implement ID(me).
    -- 
    -- GetID (myclass)   
    -- -C++: return const &  
    -- returns GUID from Standard;
    -- 
    -- const Standard_GUID& MyClass::GetID() const
    -- {
    --   static Standard_GUID myID("12345678-1234-1234-1234-1234567890ab");
    --   return myID;
    -- }

   
    ID(me)
    	returns GUID from Standard
	is deferred;
	---Purpose: Returns the ID of the attribute.
	--          
	---C++: return const &

    Label(me)
    	returns Label from TDF;
	---Purpose: 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.          
	---C++: return const

    Transaction(me)
    	returns Integer from Standard;
	---Purpose: Returns the transaction index in which the
	--          attribute has been created or modified.
	--          
	---C++: inline

    UntilTransaction(me)
    	returns Integer from Standard;
	---Purpose: 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.

    IsValid(me)
    	returns Boolean from Standard;
	---Purpose: Returns true if the attribute is valid; i.e. not a
	--          backuped or removed one.
	--          
	---C++: inline


    IsNew(me)
    	returns Boolean from Standard;
    	---Purpose: Returns true if the attribute has no backup
	--          
	---C++: inline


    IsForgotten(me)
    	returns Boolean from Standard;
	---Purpose: Returns true if the attribute forgotten status is
	--          set. 
	--          
	---C++: inline


    ---Purpose: ShortCut Methods concerning associated attributes
    --          =================================================

    IsAttribute (me; anID : GUID from Standard)
    	returns Boolean from Standard;
	---Purpose: Returns true if it  exists an associated attribute
	--          of <me> with <anID> as ID.  

    FindAttribute (me; anID         : GUID from Standard;
    	      anAttribute  : in out Attribute from TDF)
    	returns Boolean from Standard;
	---Purpose: 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.

    AddAttribute (me; other : Attribute from TDF)
    	raises DomainError from Standard;
	---Purpose: Adds   an   Attribute <other>  to  the   label  of
	--           <me>.Raises if there is  already  one of the same
	--          GUID fhan <other>.

    ForgetAttribute (me; aguid : GUID from Standard)
    returns Boolean from Standard;
	---Purpose: Forgets  the Attribute of  GUID <aguid> associated
	--          to the label of <me>. Be  carefull 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.

    ForgetAllAttributes (me; clearChildren : Boolean from Standard = Standard_True);
	---Purpose: 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
	--           mecanisms. Be carefull  that  if <me> will have a
	--          null label after this call

    ---Category: Immediate callbacks
    --           ==============================================================

    AfterAddition(me: mutable)
    	is virtual;
	---Purpose: Something to do after adding an Attribute to a label.

    BeforeRemoval(me: mutable)
    	is virtual;
	---Purpose: Something to do before removing an Attribute from
	--          a label.

    BeforeForget(me: mutable)
    	is virtual;
	---Purpose: Something to do before forgetting an Attribute to a
	--          label.

    AfterResume(me: mutable)
    	is virtual;
	---Purpose: Something to do after resuming an Attribute from
	--          a label.


    ---Category: Retrieval callbacks
    --           ==============================================================

    -- The following method is called after a whole
    -- Transient-Persistent translation.

    AfterRetrieval(me: mutable;
    	    	   forceIt : Boolean from Standard = Standard_False)
    	returns Boolean from Standard
    	is virtual;
	---Purpose: 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.


    ---Category: Undo callbacks
    --           ==============================================================

    -- The following methods are called before/after a whole Delta is
    -- applied. They are called for each concerned attribute.

    BeforeUndo(me: mutable;
    	       anAttDelta : AttributeDelta from TDF;
    	       forceIt : Boolean from Standard = Standard_False)
    	returns Boolean from Standard
    	is virtual;
	---Purpose: 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.

    AfterUndo(me: mutable;
    	       anAttDelta : AttributeDelta from TDF;
    	       forceIt : Boolean from Standard = Standard_False)
    	returns Boolean from Standard
    	is virtual;
	---Purpose: 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.


    ---Category: Modification & Transaction
    --           ==============================================================

    BeforeCommitTransaction(me : mutable)
    ---Purpose: A callback.
    --          By default does nothing.
    --          It is called by TDF_Data::CommitTransaction() method.
    is virtual;

    Backup(me : mutable);
	---Purpose: 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.

    IsBackuped(me)
    	returns Boolean from Standard;
	---Purpose: Returns true if the attribute backup status is
	--          set. This status is set/unset by the
	--          Backup() method.
	--          
	---C++: inline

    BackupCopy(me) returns mutable Attribute from TDF
    	is virtual;
	---Purpose: Copies  the attribute  contents into  a  new other
	--          attribute. It is used by Backup().

    Restore(me: mutable;
    	    anAttribute : Attribute from TDF)
    	is deferred;
	---Purpose: Restores the backuped contents from <anAttribute>
	--          into this one. It is used when aborting a
	--          transaction.


    ---Category: Delta generation
    --           ==============================================================

    DeltaOnAddition(me)
    	returns DeltaOnAddition from TDF
    	---Purpose : Makes an AttributeDelta because <me>
    	--         appeared. The only known use of a redefinition of
    	--         this method is to return a null handle (no delta).
    	is virtual;

    DeltaOnForget(me)
    	returns DeltaOnForget from TDF
    	---Purpose : Makes an AttributeDelta because <me> has been
    	--         forgotten.
    	is virtual;

    DeltaOnResume(me)
    	returns DeltaOnResume from TDF
    	---Purpose : Makes an AttributeDelta because <me> has been
    	--         resumed.
    	is virtual;

    DeltaOnModification(me; anOldAttribute : Attribute from TDF)
    	returns DeltaOnModification from TDF
    	---Purpose : Makes a DeltaOnModification between <me> and
    	--         <anOldAttribute.
    	is virtual;

    DeltaOnModification(me : mutable; aDelta : DeltaOnModification from TDF)
    	is virtual;
	---Purpose: Applies a DeltaOnModification to <me>.

    DeltaOnRemoval(me)
    	returns DeltaOnRemoval from TDF
    	---Purpose : Makes a DeltaOnRemoval on <me> because <me> has
    	--         disappeared from the DS.
    	is virtual;


    ---Category: Copy
    --           ==============================================================

    NewEmpty(me)
    	returns mutable Attribute from TDF
    	is deferred;
	---Purpose: Returns an new empty attribute from the good end
	--          type. It is used by the copy algorithm.

    Paste(me;
    	  intoAttribute    : mutable Attribute from TDF;
	  aRelocationTable : mutable RelocationTable from TDF)
	is deferred;
	---Purpose: 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.

    References(me; aDataSet : DataSet from TDF)
    	is virtual;
	---Purpose: 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.


    ---Category: Dump
    --           ==============================================================

    Dump(me; anOS : in out OStream from Standard)
    	returns OStream from Standard
    	is virtual;
	---Purpose: Dumps the minimum information about <me> on
	--          <aStream>.
	--          
	---C++: return &
    	---C++: alias operator<<


    ExtendedDump(me;
    	    	 anOS : in out OStream from Standard;
    	    	 aFilter : IDFilter from TDF;
    	    	 aMap    : in out AttributeIndexedMap from TDF)
    	is virtual;
	---Purpose: 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.


    ---Category: Miscelleaneous
    --           ==============================================================


    ---Category: Private area...
    --           ==============================================================

    Validate(me: mutable; aStatus : Boolean from Standard)
    	is private;
	---Purpose: Set the "Valid" status with <aStatus>.
	--          
	---C++: inline

    Forget(me: mutable; aTransaction : Integer from Standard);
	---Purpose: 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. Obvioulsy, 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.

    Resume(me: mutable)
    	is private;
	---Purpose: Resumes the attribute (undos Forget action).

    Backup(me: mutable; aStatus : Boolean from Standard)
    	is private;
	---Purpose: Set the "backuped" status with <aStatus>.
	--          
	---C++: inline

    RemoveBackup(me : mutable) is private;
	---Purpose: Removes the last backup attribute, if it exists.

fields

    myLabelNode        : LabelNodePtr  from TDF;
    myTransaction      : Integer       from Standard;
    mySavedTransaction : Integer       from Standard;
    myFlags            : Integer       from Standard;
    myNext             : Attribute     from TDF;
    myBackup           : Attribute     from TDF;

friends

    class Data               from TDF,
    class Label              from TDF,
    class LabelNode          from TDF,
    class AttributeIterator  from TDF,
    
    class DeltaOnForget from TDF

end Attribute;