-- File: TDF_Attribute.cdl -- ----------------- -- Author: DAUTRY Philippe -- ---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 with as ID. FindAttribute (me; anID : GUID from Standard; anAttribute : in out Attribute from TDF) returns Boolean from Standard; ---Purpose: Finds an associated attribute of , according -- to . the returned 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 to the label of -- .Raises if there is already one of the same -- GUID fhan . ForgetAttribute (me; aguid : GUID from Standard) returns Boolean from Standard; ---Purpose: Forgets the Attribute of GUID associated -- to the label of . Be carefull that if is -- the attribute of , 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 . Does it on the sub-labels if -- is set to true. Of course, this -- method is compatible with Transaction & Delta -- mecanisms. Be carefull that if 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 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 . The -- returned status says if AfterUndo has been -- performed (true) or if this callback must be -- called once again further (false). If 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 . The -- returned status says if AfterUndo has been -- performed (true) or if this callback must be -- called once again further (false). If 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 -- into this one. It is used when aborting a -- transaction. ---Category: Delta generation -- ============================================================== DeltaOnAddition(me) returns DeltaOnAddition from TDF ---Purpose : Makes an AttributeDelta because -- 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 has been -- forgotten. is virtual; DeltaOnResume(me) returns DeltaOnResume from TDF ---Purpose : Makes an AttributeDelta because has been -- resumed. is virtual; DeltaOnModification(me; anOldAttribute : Attribute from TDF) returns DeltaOnModification from TDF ---Purpose : Makes a DeltaOnModification between and -- . DeltaOnRemoval(me) returns DeltaOnRemoval from TDF ---Purpose : Makes a DeltaOnRemoval on because 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 into -- . -- -- 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 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 . -- -- 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 on -- . -- ---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 , using -- 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 . -- ---C++: inline Forget(me: mutable; aTransaction : Integer from Standard); ---Purpose: Forgets the attribute. 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 . -- ---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;