src/TDF/TDF_Data.cdl

   1 -- Created by: DAUTRY Philippe
   2 -- Copyright (c) 1997-1999 Matra Datavision
   3 -- Copyright (c) 1999-2014 OPEN CASCADE SAS
   4 --
   5 -- This file is part of Open CASCADE Technology software library.
   6 --
   7 -- This library is free software; you can redistribute it and/or modify it under
   8 -- the terms of the GNU Lesser General Public License version 2.1 as published
   9 -- by the Free Software Foundation, with special exception defined in the file
  10 -- OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
  11 -- distribution for complete text of the license and disclaimer of any warranty.
  12 --
  13 -- Alternatively, this file may be used under the terms of Open CASCADE
  14 -- commercial license or contractual agreement.
  15
  16 --              ------------
  17
  18 ---Version:     0.0
  19 --Version Date            Purpose
  20 --              0.0     Feb  4 1997     Creation
  21
  22 class Data from TDF inherits TShared from MMgt
  23
  24         ---Purpose: This class is used to manipulate a complete
  25         --          independant, self sufficient data structure and
  26         --          its services:
  27         --
  28         --          Access to the root label;
  29         --
  30         --          Opens, aborts, commits a transaction;
  31         --
  32         --          Generation and use of Delta, depending on the time.
  33 -- This class uses a special allocator
  34 -- (see LabelNodeAllocator() method)
  35 --  for more efficient allocation of
  36 --  objects in memory.
  37 uses
  38
  39     Attribute              from TDF,
  40     Label                  from TDF,
  41     LabelNodePtr           from TDF,
  42     Delta                  from TDF,
  43     IDFilter               from TDF,
  44     ListOfInteger         from TColStd,
  45     HAllocator             from TDF
  46
  47 raises
  48
  49     NoMoreObject from Standard
  50
  51 is
  52
  53     Create returns mutable Data from TDF;
  54         ---Purpose: A new and empty Data structure.
  55
  56     -- -----------------------------------------------------------------------
  57
  58     Root(me) returns Label from TDF;
  59         ---Purpose: Returns the root label of the Data structure.
  60         --
  61         ---C++: inline
  62         ---C++: return const
  63
  64     -- -----------------------------------------------------------------------
  65
  66     -- Important notice: For a more secure use of Open/Commit/Abort
  67     -- transactions, see class Transaction from TDF.
  68
  69     Transaction(me) returns Integer;
  70         ---Purpose: Returns the current transaction number.
  71
  72     OpenTransaction(me : mutable) returns Integer
  73         is private;
  74         ---Purpose: Increments the transaction number and returns it.
  75
  76     CommitTransaction(me : mutable;
  77                       withDelta : Boolean from Standard = Standard_False)
  78         returns Delta from TDF
  79         raises NoMoreObject from Standard
  80         is private;
  81         ---Purpose: Decrements the transaction number and commits the
  82         --          modifications.
  83         --
  84         --          Raises if there is no current transaction.
  85         --
  86         --          Optionnal <withDelta> set to True indiquates a
  87         --          Delta must be generated.
  88
  89     CommitUntilTransaction(me : mutable;
  90                            untilTransaction : Integer from Standard;
  91                            withDelta : Boolean from Standard = Standard_False)
  92         returns Delta from TDF
  93         is private;
  94         ---Purpose: Decrements the transaction number and commits the
  95         --          modifications until AND including the transaction
  96         --          <untilTransaction>.
  97
  98     AbortTransaction(me : mutable)
  99         raises NoMoreObject from Standard
 100         is private;
 101         ---Purpose: Decrements the transaction number and forgets the
 102         --          modifications.
 103         --
 104         --          Raises if there is no current transaction.
 105
 106     AbortUntilTransaction(me : mutable;
 107                           untilTransaction : Integer from Standard)
 108         is private;
 109         ---Purpose: Decrements the transaction number and forgets the
 110         --          modifications until AND including the transaction
 111         --          <untilTransaction>.
 112
 113     -- -----------------------------------------------------------------------
 114
 115     Time(me) returns Integer from Standard;
 116         ---Purpose: Returns the current tick. It is incremented each Commit.
 117         --
 118         ---C++: inline
 119
 120     IsApplicable (me;
 121                   aDelta : Delta from TDF)
 122         returns Boolean from Standard;
 123         ---Purpose: Returns true if <aDelta> is applicable HERE and NOW.
 124
 125
 126     Undo(me : mutable;
 127          aDelta : Delta from TDF;
 128          withDelta : Boolean from Standard = Standard_False)
 129         returns Delta from TDF;
 130         ---Purpose: Apply <aDelta> to undo a set of attribute
 131         --          modifications.
 132         --
 133         --          Optionnal <withDelta> set to True indiquates a
 134         --          Delta Set must be generated. (See above)
 135
 136     -- -----------------------------------------------------------------------
 137
 138     Destroy(me : mutable);
 139         ---C++: alias ~
 140
 141
 142     -- Private internal use methods ------------------------------------------
 143
 144     CommitTransaction(me : mutable;
 145                       aLabel : Label from TDF;
 146                       aDelta : Delta from TDF;
 147                       withDelta : Boolean from Standard)
 148         returns Integer from Standard
 149         is private;
 150         ---Purpose: Decrements the transaction number and commits the
 151         --          modifications. Used to implement the recursif
 152         --          commit process. The returned boolean says how many
 153         --          attributes (new, modified or deleted) has been
 154         --          committed from the previous transaction into the
 155         --          current one.
 156
 157
 158     -- Miscelleaneous
 159     -- --------------
 160
 161     NotUndoMode(me) returns Boolean from Standard;
 162         ---Purpose: Returns the undo mode status.
 163         --
 164         ---C++: inline
 165
 166
 167     Dump(me; anOS : in out OStream from Standard)
 168         returns OStream from Standard;
 169         ---Purpose: Dumps the Data on <aStream>.
 170         --
 171         ---C++: return &
 172         ---C++: alias operator<<
 173
 174     --  methods for check modifications outside the transaction -----------
 175
 176     AllowModification(me: mutable; isAllowed : Boolean from Standard );
 177         ---Purpose: Sets modification mode.
 178         --
 179         ---C++: inline
 180
 181     IsModificationAllowed(me) returns Boolean from Standard;
 182         ---Purpose: returns modification mode.
 183         --
 184         ---C++: inline
 185
 186     LabelNodeAllocator(me) returns HAllocator from TDF;
 187         ---Purpose: Returns TDF_HAllocator, which is an
 188 -- incremental allocator used by
 189 -- TDF_LabelNode.
 190 --      This allocator is used to
 191 --      manage TDF_LabelNode objects,
 192 --      but it can also be used for
 193 --      allocating memory to
 194 --      application-specific data (be
 195 --      careful because this
 196 --      allocator does not release
 197 --      the memory).
 198 --      The benefits of this
 199 --      allocation scheme are
 200 --      noticeable when dealing with
 201 --      large OCAF documents, due to:
 202 -- 1.    Very quick allocation of
 203 --   objects (memory heap is not
 204 --   used, the algorithm that
 205 --   replaces it is very simple).
 206 -- 2.    Very quick destruction of
 207 --   objects (memory is released not
 208 --   by destructors of TDF_LabelNode,
 209 --   but rather by the destructor of
 210 --   TDF_Data).
 211 -- 3.  TDF_LabelNode objects do not
 212 --   fragmentize the memory; they are
 213 --   kept compactly in a number of
 214 --   arrays of 16K each.
 215 -- 4.    Swapping is reduced on large
 216 --   data, because each document now
 217 --   occupies a smaller number of
 218 --   memory pages.
 219         ---C++:  inline
 220         ---C++:  return const &
 221
 222 fields
 223
 224     myRoot              : LabelNodePtr          from TDF;
 225     myTransaction       : Integer               from Standard;
 226     myNbTouchedAtt      : Integer               from Standard;
 227     myNotUndoMode       : Boolean               from Standard;
 228     myTime              : Integer               from Standard;
 229     myTimes             : ListOfInteger         from TColStd;
 230     myLabelNodeAllocator: HAllocator            from TDF;
 231     myAllowModification : Boolean               from Standard;
 232
 233 friends
 234
 235     class Transaction from TDF,
 236     class LabelNode   from TDF
 237
 238
 239 end Data;