1 // Created on: 1992-02-03
2 // Created by: Christian CAILLET
3 // Copyright (c) 1992-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 #ifndef _Transfer_ProcessForFinder_HeaderFile
18 #define _Transfer_ProcessForFinder_HeaderFile
20 #include <TColStd_IndexedMapOfInteger.hxx>
21 #include <Transfer_HSequenceOfFinder.hxx>
22 #include <Transfer_TransferMapOfProcessForFinder.hxx>
23 #include <Message_ProgressRange.hxx>
25 class Message_Messenger;
26 class Transfer_Finder;
27 class Transfer_Binder;
28 class Transfer_ActorOfProcessForFinder;
29 class Interface_InterfaceError;
30 class Transfer_TransferFailure;
31 class Transfer_FindHasher;
32 class Transfer_IteratorOfProcessForFinder;
34 class Interface_Check;
35 class Standard_Transient;
36 class Interface_CheckIterator;
39 class Transfer_ProcessForFinder;
40 DEFINE_STANDARD_HANDLE(Transfer_ProcessForFinder, Standard_Transient)
43 class Transfer_ProcessForFinder : public Standard_Transient
49 //! Sets TransferProcess at initial state. Gives an Initial size
50 //! (indicative) for the Map when known (default is 10000).
51 //! Sets default trace file as a printer and default trace level
52 //! (see Message_TraceFile).
53 Standard_EXPORT Transfer_ProcessForFinder(const Standard_Integer nb = 10000);
55 //! Sets TransferProcess at initial state. Gives an Initial size
56 //! (indicative) for the Map when known (default is 10000).
57 //! Sets a specified printer.
58 Standard_EXPORT Transfer_ProcessForFinder(const Handle(Message_Messenger)& printer, const Standard_Integer nb = 10000);
60 //! Resets a TransferProcess as ready for a completely new work.
61 //! Clears general data (roots) and the Map
62 Standard_EXPORT void Clear();
64 //! Rebuilds the Map and the roots to really remove Unbound items
65 //! Because Unbind keeps the entity in place, even if not bound
66 //! Hence, working by checking new items is meaningless if a
67 //! formerly unbound item is rebound
68 Standard_EXPORT void Clean();
70 //! Resizes the Map as required (if a new reliable value has been
71 //! determined). Acts only if <nb> is greater than actual NbMapped
72 Standard_EXPORT void Resize (const Standard_Integer nb);
74 //! Defines an Actor, which is used for automatic Transfer
75 //! If already defined, the new Actor is cumulated
76 //! (see SetNext from Actor)
77 Standard_EXPORT void SetActor (const Handle(Transfer_ActorOfProcessForFinder)& actor);
79 //! Returns the defined Actor. Returns a Null Handle if
81 Standard_EXPORT Handle(Transfer_ActorOfProcessForFinder) Actor() const;
83 //! Returns the Binder which is linked with a starting Object
84 //! It can either bring a Result (Transfer done) or none (for a
86 //! If no Binder is linked with <start>, returns a Null Handle
87 //! Considers a category number, by default 0
88 Standard_EXPORT Handle(Transfer_Binder) Find (const Handle(Transfer_Finder)& start) const;
90 //! Returns True if a Result (whatever its form) is Bound with
91 //! a starting Object. I.e., if a Binder with a Result set,
93 //! Considers a category number, by default 0
94 Standard_EXPORT Standard_Boolean IsBound (const Handle(Transfer_Finder)& start) const;
96 //! Returns True if the result of the transfer of an object is
97 //! already used in other ones. If it is, Rebind cannot change it.
98 //! Considers a category number, by default 0
99 Standard_EXPORT Standard_Boolean IsAlreadyUsed (const Handle(Transfer_Finder)& start) const;
101 //! Creates a Link a starting Object with a Binder. This Binder
102 //! can either bring a Result (effective Binding) or none (it can
103 //! be set later : pre-binding).
104 //! Considers a category number, by default 0
105 Standard_EXPORT void Bind (const Handle(Transfer_Finder)& start, const Handle(Transfer_Binder)& binder);
107 //! Changes the Binder linked with a starting Object for its
108 //! unitary transfer. This it can be useful when the exact form
109 //! of the result is known once the transfer is widely engaged.
110 //! This can be done only on first transfer.
111 //! Considers a category number, by default 0
112 Standard_EXPORT void Rebind (const Handle(Transfer_Finder)& start, const Handle(Transfer_Binder)& binder);
114 //! Removes the Binder linked with a starting object
115 //! If this Binder brings a non-empty Check, it is replaced by
116 //! a VoidBinder. Also removes from the list of Roots as required.
117 //! Returns True if done, False if <start> was not bound
118 //! Considers a category number, by default 0
119 Standard_EXPORT Standard_Boolean Unbind (const Handle(Transfer_Finder)& start);
121 //! Returns a Binder for a starting entity, as follows :
122 //! Tries to Find the already bound one
123 //! If none found, creates a VoidBinder and Binds it
124 Standard_EXPORT Handle(Transfer_Binder) FindElseBind (const Handle(Transfer_Finder)& start);
126 //! Sets Messenger used for outputting messages.
127 Standard_EXPORT void SetMessenger (const Handle(Message_Messenger)& messenger);
129 //! Returns Messenger used for outputting messages.
130 //! The returned object is guaranteed to be non-null;
131 //! default is Message::Messenger().
132 Standard_EXPORT Handle(Message_Messenger) Messenger() const;
134 //! Sets trace level used for outputting messages:
135 //! <trace> = 0 : no trace at all
136 //! <trace> = 1 : handled exceptions and calls to AddError
137 //! <trace> = 2 : also calls to AddWarning
138 //! <trace> = 3 : also traces new Roots
139 //! (uses method ErrorTrace).
140 //! Default is 1 : Errors traced
141 Standard_EXPORT void SetTraceLevel (const Standard_Integer tracelev);
143 //! Returns trace level used for outputting messages.
144 Standard_EXPORT Standard_Integer TraceLevel() const;
146 //! New name for AddFail (Msg)
147 Standard_EXPORT void SendFail (const Handle(Transfer_Finder)& start, const Message_Msg& amsg);
149 //! New name for AddWarning (Msg)
150 Standard_EXPORT void SendWarning (const Handle(Transfer_Finder)& start, const Message_Msg& amsg);
152 //! Adds an information message
153 //! Trace is filled if trace level is at least 3
154 Standard_EXPORT void SendMsg (const Handle(Transfer_Finder)& start, const Message_Msg& amsg);
156 //! Adds an Error message to a starting entity (to the check of
157 //! its Binder of category 0, as a Fail)
158 Standard_EXPORT void AddFail (const Handle(Transfer_Finder)& start, const Standard_CString mess, const Standard_CString orig = "");
160 //! (other name of AddFail, maintained for compatibility)
161 Standard_EXPORT void AddError (const Handle(Transfer_Finder)& start, const Standard_CString mess, const Standard_CString orig = "");
163 //! Adds an Error Message to a starting entity from the definition
164 //! of a Msg (Original+Value)
165 Standard_EXPORT void AddFail (const Handle(Transfer_Finder)& start, const Message_Msg& amsg);
167 //! Adds a Warning message to a starting entity (to the check of
168 //! its Binder of category 0)
169 Standard_EXPORT void AddWarning (const Handle(Transfer_Finder)& start, const Standard_CString mess, const Standard_CString orig = "");
171 //! Adds a Warning Message to a starting entity from the definition
172 //! of a Msg (Original+Value)
173 Standard_EXPORT void AddWarning (const Handle(Transfer_Finder)& start, const Message_Msg& amsg);
175 Standard_EXPORT void Mend (const Handle(Transfer_Finder)& start, const Standard_CString pref = "");
177 //! Returns the Check attached to a starting entity. If <start>
178 //! is unknown, returns an empty Check
179 //! Adds a case name to a starting entity
180 //! Adds a case value to a starting entity
181 //! Returns the complete case list for an entity. Null Handle if empty
182 //! In the list of mapped items (between 1 and NbMapped),
183 //! searches for the first item which follows <num0>(not included)
184 //! and which has an attribute named <name>
185 //! Attributes are brought by Binders
186 //! Hence, allows such an iteration
188 //! for (num = TP->NextItemWithAttribute(name,0);
190 //! num = TP->NextItemWithAttribute(name,num) {
191 //! .. process mapped item <num>
193 //! Returns the type of an Attribute attached to binders
194 //! If this name gives no Attribute, returns ParamVoid
195 //! If this name gives several different types, returns ParamMisc
196 //! Else, returns the effective type (ParamInteger, ParamReal,
197 //! ParamIdent, or ParamText)
198 //! Returns the list of recorded Attribute Names, as a Dictionary
199 //! of Integer : each value gives the count of items which bring
200 //! this attribute name
201 //! By default, considers all the attribute names
202 //! If <rootname> is given, considers only the attribute names
203 //! which begin by <rootname>
204 Standard_EXPORT Handle(Interface_Check) Check (const Handle(Transfer_Finder)& start) const;
206 //! Binds a starting object with a Transient Result.
207 //! Uses a SimpleBinderOfTransient to work. If there is already
208 //! one but with no Result set, sets its Result.
209 //! Considers a category number, by default 0
210 Standard_EXPORT void BindTransient (const Handle(Transfer_Finder)& start, const Handle(Standard_Transient)& res);
212 //! Returns the Result of the Transfer of an object <start> as a
213 //! Transient Result.
214 //! Returns a Null Handle if there is no Transient Result
215 //! Considers a category number, by default 0
216 //! Warning : Supposes that Binding is done with a SimpleBinderOfTransient
217 Standard_EXPORT const Handle(Standard_Transient)& FindTransient (const Handle(Transfer_Finder)& start) const;
219 //! Prepares an object <start> to be bound with several results.
220 //! If no Binder is yet attached to <obj>, a MultipleBinder
221 //! is created, empty. If a Binder is already set, it must
222 //! accept Multiple Binding.
223 //! Considers a category number, by default 0
224 Standard_EXPORT void BindMultiple (const Handle(Transfer_Finder)& start);
226 //! Adds an item to a list of results bound to a starting object.
227 //! Considers a category number, by default 0, for all results
228 Standard_EXPORT void AddMultiple (const Handle(Transfer_Finder)& start, const Handle(Standard_Transient)& res);
230 //! Searches for a transient result attached to a starting object,
231 //! according to its type, by criterium IsKind(atype)
233 //! In case of multiple result, explores the list and gives in
234 //! <val> the first transient result IsKind(atype)
235 //! Returns True and fills <val> if found
236 //! Else, returns False (<val> is not touched, not even nullified)
238 //! This syntactic form avoids to do DownCast : if a result is
239 //! found with the good type, it is loaded in <val> and can be
240 //! immediately used, well initialised
241 Standard_EXPORT Standard_Boolean FindTypedTransient (const Handle(Transfer_Finder)& start, const Handle(Standard_Type)& atype, Handle(Standard_Transient)& val) const;
243 //! Safe variant for arbitrary type of argument
245 Standard_Boolean FindTypedTransient (const Handle(Transfer_Finder)& start, const Handle(Standard_Type)& atype, Handle(T)& val) const
247 Handle(Standard_Transient) aVal = val;
248 return FindTypedTransient (start, atype, aVal) && ! (val = Handle(T)::DownCast(aVal)).IsNull();
251 //! Searches for a transient result recorded in a Binder, whatever
252 //! this Binder is recorded or not in <me>
254 //! This is strictly equivalent to the class method GetTypedResult
255 //! from class SimpleBinderOfTransient, but is just lighter to call
257 //! Apart from this, works as FindTypedTransient
258 Standard_EXPORT Standard_Boolean GetTypedTransient (const Handle(Transfer_Binder)& binder, const Handle(Standard_Type)& atype, Handle(Standard_Transient)& val) const;
260 //! Safe variant for arbitrary type of argument
262 Standard_Boolean GetTypedTransient (const Handle(Transfer_Binder)& start, const Handle(Standard_Type)& atype, Handle(T)& val) const
264 Handle(Standard_Transient) aVal = val;
265 return GetTypedTransient (start, atype, aVal) && ! (val = Handle(T)::DownCast(aVal)).IsNull();
268 //! Returns the maximum possible value for Map Index
269 //! (no result can be bound with a value greater than it)
270 Standard_EXPORT Standard_Integer NbMapped() const;
272 //! Returns the Starting Object bound to an Index,
273 Standard_EXPORT const Handle(Transfer_Finder)& Mapped (const Standard_Integer num) const;
275 //! Returns the Index value bound to a Starting Object, 0 if none
276 Standard_EXPORT Standard_Integer MapIndex (const Handle(Transfer_Finder)& start) const;
278 //! Returns the Binder bound to an Index
279 //! Considers a category number, by default 0
280 Standard_EXPORT Handle(Transfer_Binder) MapItem (const Standard_Integer num) const;
282 //! Declares <obj> (and its Result) as Root. This status will be
283 //! later exploited by RootResult, see below (Result can be
284 //! produced at any time)
285 Standard_EXPORT void SetRoot (const Handle(Transfer_Finder)& start);
287 //! Enable (if <stat> True) or Disables (if <stat> False) Root
288 //! Management. If it is set, Transfers are considered as stacked
289 //! (a first Transfer commands other Transfers, and so on) and
290 //! the Transfers commanded by an external caller are "Root".
291 //! Remark : SetRoot can be called whatever this status, on every
293 //! Default is set to True.
294 Standard_EXPORT void SetRootManagement (const Standard_Boolean stat);
296 //! Returns the count of recorded Roots
297 Standard_EXPORT Standard_Integer NbRoots() const;
299 //! Returns a Root Entity given its number in the list (1-NbRoots)
300 Standard_EXPORT const Handle(Transfer_Finder)& Root (const Standard_Integer num) const;
302 //! Returns the Binder bound with a Root Entity given its number
303 //! Considers a category number, by default 0
304 Standard_EXPORT Handle(Transfer_Binder) RootItem (const Standard_Integer num) const;
306 //! Returns the index in the list of roots for a starting item,
307 //! or 0 if it is not recorded as a root
308 Standard_EXPORT Standard_Integer RootIndex (const Handle(Transfer_Finder)& start) const;
310 //! Returns Nesting Level of Transfers (managed by methods
311 //! TranscriptWith & Co). Starts to zero. If no automatic Transfer
312 //! is used, it remains to zero. Zero means Root Level.
313 Standard_EXPORT Standard_Integer NestingLevel() const;
315 //! Resets Nesting Level of Transfers to Zero (Root Level),
316 //! whatever its current value.
317 Standard_EXPORT void ResetNestingLevel();
319 //! Tells if <start> has been recognized as good candidate for
320 //! Transfer. i.e. queries the Actor and its Nexts
321 Standard_EXPORT Standard_Boolean Recognize (const Handle(Transfer_Finder)& start) const;
323 //! Performs the Transfer of a Starting Object, by calling
324 //! the method TransferProduct (see below).
325 //! Mapping and Roots are managed : nothing is done if a Result is
326 //! already Bound, an exception is raised in case of error.
327 Standard_EXPORT Handle(Transfer_Binder) Transferring (const Handle(Transfer_Finder)& start,
328 const Message_ProgressRange& theProgress = Message_ProgressRange());
330 //! Same as Transferring but does not return the Binder.
331 //! Simply returns True in case of success (for user call)
332 Standard_EXPORT Standard_Boolean Transfer (const Handle(Transfer_Finder)& start,
333 const Message_ProgressRange& theProgress = Message_ProgressRange());
335 //! Allows controls if exceptions will be handled
336 //! Transfer Operations
337 //! <err> False : they are not handled with try {} catch {}
338 //! <err> True : they are
339 //! Default is False: no handling performed
340 Standard_EXPORT void SetErrorHandle (const Standard_Boolean err);
342 //! Returns error handling flag
343 Standard_EXPORT Standard_Boolean ErrorHandle() const;
345 //! Method called when trace is asked
346 //! Calls PrintTrace to display information relevant for starting
347 //! objects (which can be redefined)
348 //! <level> is Nesting Level of Transfer (0 = root)
349 //! <mode> controls the way the trace is done :
350 //! 0 neutral, 1 for Error, 2 for Warning message, 3 for new Root
351 Standard_EXPORT void StartTrace (const Handle(Transfer_Binder)& binder, const Handle(Transfer_Finder)& start, const Standard_Integer level, const Standard_Integer mode) const;
353 //! Prints a short information on a starting object. By default
354 //! prints its Dynamic Type. Can be redefined
355 Standard_EXPORT virtual void PrintTrace (const Handle(Transfer_Finder)& start, Standard_OStream& S) const;
357 //! Returns True if we are surely in a DeadLoop. Evaluation is not
358 //! exact, it is a "majorant" which must be computed fast.
359 //! This "majorant" is : <alevel> greater than NbMapped.
360 Standard_EXPORT Standard_Boolean IsLooping (const Standard_Integer alevel) const;
362 //! Returns, as an iterator, the log of root transfer, i.e. the
363 //! created objects and Binders bound to starting roots
364 //! If withstart is given True, Starting Objects are also returned
365 Standard_EXPORT Transfer_IteratorOfProcessForFinder RootResult (const Standard_Boolean withstart = Standard_False) const;
367 //! Returns, as an Iterator, the entire log of transfer (list of
368 //! created objects and Binders which can bring errors)
369 //! If withstart is given True, Starting Objects are also returned
370 Standard_EXPORT Transfer_IteratorOfProcessForFinder CompleteResult (const Standard_Boolean withstart = Standard_False) const;
372 //! Returns Binders which are neither "Done" nor "Initial",
373 //! that is Error,Loop or Run (abnormal states at end of Transfer)
374 //! Starting Objects are given in correspondence in the iterator
375 Standard_EXPORT Transfer_IteratorOfProcessForFinder AbnormalResult() const;
377 //! Returns a CheckList as a list of Check : each one is for a
378 //! starting entity which have either check (warning or fail)
379 //! messages are attached, or are in abnormal state : that case
380 //! gives a specific message
381 //! If <erronly> is True, checks with Warnings only are ignored
382 Standard_EXPORT Interface_CheckIterator CheckList (const Standard_Boolean erronly) const;
384 //! Returns, as an Iterator, the log of transfer for one object
385 //! <level> = 0 : this object only
386 //! and if <start> is a scope owner (else, <level> is ignored) :
387 //! <level> = 1 : object plus its immediate scoped ones
388 //! <level> = 2 : object plus all its scoped ones
389 Standard_EXPORT Transfer_IteratorOfProcessForFinder ResultOne (const Handle(Transfer_Finder)& start, const Standard_Integer level, const Standard_Boolean withstart = Standard_False) const;
391 //! Returns a CheckList for one starting object
392 //! <level> interpreted as by ResultOne
393 //! If <erronly> is True, checks with Warnings only are ignored
394 Standard_EXPORT Interface_CheckIterator CheckListOne (const Handle(Transfer_Finder)& start, const Standard_Integer level, const Standard_Boolean erronly) const;
396 //! Returns True if no check message is attached to a starting
397 //! object. <level> interpreted as by ResultOne
398 //! If <erronly> is True, checks with Warnings only are ignored
399 Standard_EXPORT Standard_Boolean IsCheckListEmpty (const Handle(Transfer_Finder)& start, const Standard_Integer level, const Standard_Boolean erronly) const;
401 //! Removes Results attached to (== Unbinds) a given object and,
402 //! according <level> :
403 //! <level> = 0 : only it
404 //! <level> = 1 : it plus its immediately owned sub-results(scope)
405 //! <level> = 2 : it plus all its owned sub-results(scope)
406 Standard_EXPORT void RemoveResult (const Handle(Transfer_Finder)& start, const Standard_Integer level, const Standard_Boolean compute = Standard_True);
408 //! Computes a number to be associated to a starting object in
409 //! a check or a check-list
410 //! By default, returns 0; can be redefined
411 Standard_EXPORT virtual Standard_Integer CheckNum (const Handle(Transfer_Finder)& start) const;
416 DEFINE_STANDARD_RTTI_INLINE(Transfer_ProcessForFinder,Standard_Transient)
426 //! Same as Find but stores the last access to the map, for a
427 //! faster access on next calls (as Bind does too)
428 //! Considers a category number, by default 0
429 //! C++ : return const &
430 Standard_EXPORT Handle(Transfer_Binder) FindAndMask (const Handle(Transfer_Finder)& start);
432 //! Internal action of Transfer, called by Transferring, with or
433 //! without ErrorHandle. It invokes the Actor to work (set by
434 //! SetActor), and tries its Nexts if no result is produced,
435 //! until a Non Null Binder is produced.
436 //! But keep in mind that a Null Binder can always be returned
437 //! if a Starting Entity has not been recognized at all.
438 Standard_EXPORT Handle(Transfer_Binder) TransferProduct (const Handle(Transfer_Finder)& start,
439 const Message_ProgressRange& theProgress = Message_ProgressRange());
441 Standard_Boolean theerrh;
442 Standard_Integer thetrace;
443 Handle(Message_Messenger) themessenger;
444 Standard_Integer thelevel;
445 Standard_Integer therootl;
446 Standard_Boolean therootm;
447 TColStd_IndexedMapOfInteger theroots;
448 Handle(Transfer_Finder) thelastobj;
449 Handle(Transfer_Binder) thelastbnd;
450 Standard_Integer theindex;
451 Handle(Transfer_ActorOfProcessForFinder) theactor;
452 Transfer_TransferMapOfProcessForFinder themap;
463 #endif // _Transfer_ProcessForFinder_HeaderFile