1 -- Created on: 1993-02-02
2 -- Created by: Christian CAILLET
3 -- Copyright (c) 1993-1999 Matra Datavision
4 -- Copyright (c) 1999-2014 OPEN CASCADE SAS
6 -- This file is part of Open CASCADE Technology software library.
8 -- This library is free software; you can redistribute it and/or modify it under
9 -- the terms of the GNU Lesser General Public License version 2.1 as published
10 -- by the Free Software Foundation, with special exception defined in the file
11 -- OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
12 -- distribution for complete text of the license and disclaimer of any warranty.
14 -- Alternatively, this file may be used under the terms of Open CASCADE
15 -- commercial license or contractual agreement.
17 class CopyTool from Interface
19 ---Purpose : Performs Deep Copies of sets of Entities
20 -- Allows to perform Copy of Interface Entities from a Model to
21 -- another one. Works by calling general services GetFromAnother
23 -- Uses a CopyMap to bind a unique Result to each Copied Entity
25 -- It is possible to command Copies of Entities (and those they
26 -- reference) by call to the General Service Library, or to
27 -- enforce results for transfer of some Entities (calling Bind)
29 -- A Same CopyTool can be used for several successive Copies from
30 -- the same Model : either by restarting from scratch (e.g. to
31 -- copy different parts of a starting Model to several Targets),
32 -- or incremental : in that case, it is possible to know what is
33 -- the content of the last increment (defined by last call to
34 -- ClearLastFlags and queried by call to LastCopiedAfter)
36 -- Works in two times : first, create the list of copied Entities
37 -- second, pushes them to a target Model (manages also Model's
38 -- Header) or returns the Result as an Iterator, as desired
40 -- The core action (Copy) works by using ShallowCopy (method
41 -- attached to each class) and Copy from GeneralLib (itself using
42 -- dedicated tools). It can be redefined for specific actions.
44 uses Transient, SequenceOfInteger from TColStd, BitMap,
45 InterfaceModel, EntityIterator, CopyControl, CopyMap,
46 GeneralModule, GeneralLib, Protocol from Interface
52 Create (amodel : InterfaceModel; lib : GeneralLib) returns CopyTool;
53 ---Purpose : Creates a CopyTool adapted to work from a Model. Works
54 -- with a General Service Library, given as an argument
56 Create (amodel : InterfaceModel; protocol : Protocol from Interface)
58 ---Purpose : Same as above, but Library is defined through a Protocol
60 Create (amodel : InterfaceModel) returns CopyTool
61 ---Purpose : Same as above, but works with the Active Protocol
62 raises InterfaceError;
63 -- Error if no Active Protocol is defined
65 Model (me) returns InterfaceModel;
66 ---Purpose : Returns the Model on which the CopyTool works
68 SetControl (me : in out; othermap : CopyControl);
69 ---Purpose : Changes the Map of Result for another one. This allows to work
70 -- with a more sophisticated Mapping Control than the Standard
71 -- one which is CopyMap (e.g. TransferProcess from Transfer)
73 Control (me) returns CopyControl;
74 ---Purpose : Returns the object used for Control
76 -- -- Basic Operations -- --
78 Clear (me : in out) is virtual;
79 ---Purpose : Clears Transfer List. Gets Ready to begin another Transfer
81 NewVoid (me : in out; entfrom : Transient; entto : out Transient)
82 returns Boolean is virtual protected;
83 ---Purpose : Creates a new void instance (just created) of the same class
84 -- as <entfrom>. Uses the general service GeneralModule:NewVoid
85 -- Returns True if OK (Recognize has succeeded), False else
86 -- (in such a case, the standard method ShallowCopy is called
87 -- to produce <ento> from <entfrom> : hence it is not void)
89 -- No mapping is managed by this method
91 Copy (me : in out; entfrom : Transient; entto : out Transient;
92 mapped : Boolean; errstat : Boolean)
93 returns Boolean is virtual;
94 ---Purpose : Creates the CounterPart of an Entity (by ShallowCopy), Binds
95 -- it, then Copies the content of the former Entity to the other
96 -- one (same Type), by call to the General Service Library
97 -- It may command the Copy of Referenced Entities
98 -- Then, its returns True.
100 -- If <mapped> is True, the Map is used to store the Result
101 -- Else, the Result is simply produced : it can be used to Copy
102 -- internal sub-parts of Entities, which are not intended to be
103 -- shared (Strings, Arrays, etc...)
104 -- If <errstat> is True, this means that the Entity is recorded
105 -- in the Model as Erroneous : in this case, the General Service
106 -- for Deep Copy is not called (this could be dangerous) : hence
107 -- the Counter-Part is produced but empty, it can be referenced.
109 -- This method does nothing and returns False if the Protocol
110 -- does not recognize <ent>.
111 -- It basically makes a Deep Copy without changing the Types.
112 -- It can be redefined for special uses.
114 Implied (me : in out; entfrom : Transient; entto : Transient)
116 ---Purpose : Renews the Implied References of one already Copied Entity
118 Transferred (me : in out; ent : Transient) returns Transient
119 ---Purpose : Transfers one Entity, if not yet bound to a result
120 -- Remark : For an Entity which is reported in the Starting Model,
121 -- the ReportEntity will also be copied with its Content if it
122 -- has one (at least ShallowCopy; Complete Copy if the Protocol
123 -- recognizes the Content : see method Copy)
124 raises InterfaceError;
125 -- This method can raise any kind of Interface exception.
126 -- Especially if <ent> is not contained in Starting Model.
128 Bind (me : in out; ent : Transient; res : Transient)
129 ---Purpose : Defines a Result for the Transfer of a Starting object.
130 -- Used by method Transferred (which performs a normal Copy),
131 -- but can also be called to enforce a result : in the latter
132 -- case, the enforced result must be compatible with the other
133 -- Transfers which are performed
134 raises InterfaceError;
135 -- Error if a Result is already bound with this Starting Object
137 Search (me; ent : Transient; res : out Transient)
139 ---Purpose : Search for the result of a Starting Object (i.e. an Entity)
140 -- Returns True if a Result is Bound (and fills "result")
141 -- Returns False if no result is Bound
143 ClearLastFlags (me : in out);
144 ---Purpose : Clears LastFlags only. This allows to know what Entities are
145 -- copied after its call (see method LastCopiedAfter). It can be
146 -- used when copies are done by increments, which must be
147 -- distinghished. ClearLastFlags is also called by Clear.
149 LastCopiedAfter (me; numfrom : Integer;
150 ent : out Transient; res : out Transient) returns Integer;
151 ---Purpose : Returns an copied Entity and its Result which were operated
152 -- after last call to ClearLastFlags. It returns the first
153 -- "Last Copied Entity" which Number follows <numfrom>, Zero if
154 -- none. It is used in a loop as follow :
156 -- while ( (num = CopyTool.LastCopiedAfter(num,ent,res)) ) {
157 -- .. Process Starting <ent> and its Result <res>
160 -- -- General Operations -- --
162 TransferEntity (me : in out; ent : Transient)
163 ---Purpose : Transfers one Entity and records result into the Transfer List
164 -- Calls method Transferred
165 raises InterfaceError;
166 -- This method can raise any kind of Interface exception
168 RenewImpliedRefs (me : in out) raises InterfaceError;
169 ---Purpose : Renews the Implied References. These References do not involve
170 -- Copying of referenced Entities. For such a Reference, if the
171 -- Entity which defines it AND the referenced Entity are both
172 -- copied, then this Reference is renewed. Else it is deleted in
173 -- the copied Entities.
174 -- Remark : this concerns only some specific references, such as
177 FillModel (me : in out; bmodel : InterfaceModel)
178 raises InterfaceError;
179 ---Purpose : Fills a Model with the result of the transfer (TransferList)
180 -- Commands copy of Header too, and calls RenewImpliedRefs
182 CompleteResult (me; withreports : Boolean = Standard_False)
183 returns EntityIterator;
184 ---Purpose : Returns the complete list of copied Entities
185 -- If <withreports> is given True, the entities which were
186 -- reported in the Starting Model are replaced in the list
187 -- by the copied ReportEntities
189 RootResult (me; withreports : Boolean = Standard_False)
190 returns EntityIterator;
191 ---Purpose : Returns the list of Root copied Entities (those which were
192 -- asked for copy by the user of CopyTool, not by copying
195 Destroy (me: in out) is virtual;
196 ---C++: alias "Standard_EXPORT virtual ~Interface_CopyTool() { Destroy(); }"
200 themod : InterfaceModel; -- Starting Model & Entities
201 themap : CopyControl; -- Basic Copy Results
202 therep : CopyMap; -- Report Results (if any)
204 thelib : GeneralLib is protected; -- (heirs can use it)
205 thelev : Integer; -- Current recursive Call Level (Root = 0)
206 therts : SequenceOfInteger from TColStd; -- "Root" Entities (thelev = 0)
207 theimp : Boolean; -- are Implied Refs renewed
209 theent : Transient; -- Last processed
210 themdu : GeneralModule;