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 5 // 6 // This file is part of Open CASCADE Technology software library. 7 // 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. 13 // 14 // Alternatively, this file may be used under the terms of Open CASCADE 15 // commercial license or contractual agreement. 16 17 #ifndef _Transfer_ProcessForFinder_HeaderFile 18 #define _Transfer_ProcessForFinder_HeaderFile 19 20 #include <TColStd_IndexedMapOfInteger.hxx> 21 #include <Transfer_HSequenceOfFinder.hxx> 22 #include <Transfer_TransferMapOfProcessForFinder.hxx> 23 #include <Message_ProgressRange.hxx> 24 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; 33 class Message_Msg; 34 class Interface_Check; 35 class Standard_Transient; 36 class Interface_CheckIterator; 37 38 39 class Transfer_ProcessForFinder; 40 DEFINE_STANDARD_HANDLE(Transfer_ProcessForFinder, Standard_Transient) 41 42 43 class Transfer_ProcessForFinder : public Standard_Transient 44 { 45 46 public: 47 48 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); 54 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); 59 60 //! Resets a TransferProcess as ready for a completely new work. 61 //! Clears general data (roots) and the Map 62 Standard_EXPORT void Clear(); 63 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(); 69 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); 73 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); 78 79 //! Returns the defined Actor. Returns a Null Handle if 80 //! not set. 81 Standard_EXPORT Handle(Transfer_ActorOfProcessForFinder) Actor() const; 82 83 //! Returns the Binder which is linked with a starting Object 84 //! It can either bring a Result (Transfer done) or none (for a 85 //! pre-binding). 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; 89 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, 92 //! is linked with it 93 //! Considers a category number, by default 0 94 Standard_EXPORT Standard_Boolean IsBound (const Handle(Transfer_Finder)& start) const; 95 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; 100 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); 106 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); 113 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); 120 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); 125 126 //! Sets Messenger used for outputting messages. 127 Standard_EXPORT void SetMessenger (const Handle(Message_Messenger)& messenger); 128 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; 133 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); 142 143 //! Returns trace level used for outputting messages. 144 Standard_EXPORT Standard_Integer TraceLevel() const; 145 146 //! New name for AddFail (Msg) 147 Standard_EXPORT void SendFail (const Handle(Transfer_Finder)& start, const Message_Msg& amsg); 148 149 //! New name for AddWarning (Msg) 150 Standard_EXPORT void SendWarning (const Handle(Transfer_Finder)& start, const Message_Msg& amsg); 151 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); 155 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 = ""); 159 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 = ""); 162 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); 166 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 = ""); 170 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); 174 175 Standard_EXPORT void Mend (const Handle(Transfer_Finder)& start, const Standard_CString pref = ""); 176 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 187 //! 188 //! for (num = TP->NextItemWithAttribute(name,0); 189 //! num > 0; 190 //! num = TP->NextItemWithAttribute(name,num) { 191 //! .. process mapped item <num> 192 //! } 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; 205 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); 211 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; 218 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); 225 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); 229 230 //! Searches for a transient result attached to a starting object, 231 //! according to its type, by criterium IsKind(atype) 232 //! 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) 237 //! 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; 242 243 //! Safe variant for arbitrary type of argument 244 template <class T> FindTypedTransient(const Handle (Transfer_Finder)& start,const Handle (Standard_Type)& atype,Handle (T)& val) const245 Standard_Boolean FindTypedTransient (const Handle(Transfer_Finder)& start, const Handle(Standard_Type)& atype, Handle(T)& val) const 246 { 247 Handle(Standard_Transient) aVal = val; 248 return FindTypedTransient (start, atype, aVal) && ! (val = Handle(T)::DownCast(aVal)).IsNull(); 249 } 250 251 //! Searches for a transient result recorded in a Binder, whatever 252 //! this Binder is recorded or not in <me> 253 //! 254 //! This is strictly equivalent to the class method GetTypedResult 255 //! from class SimpleBinderOfTransient, but is just lighter to call 256 //! 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; 259 260 //! Safe variant for arbitrary type of argument 261 template <class T> GetTypedTransient(const Handle (Transfer_Binder)& start,const Handle (Standard_Type)& atype,Handle (T)& val) const262 Standard_Boolean GetTypedTransient (const Handle(Transfer_Binder)& start, const Handle(Standard_Type)& atype, Handle(T)& val) const 263 { 264 Handle(Standard_Transient) aVal = val; 265 return GetTypedTransient (start, atype, aVal) && ! (val = Handle(T)::DownCast(aVal)).IsNull(); 266 } 267 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; 271 272 //! Returns the Starting Object bound to an Index, 273 Standard_EXPORT const Handle(Transfer_Finder)& Mapped (const Standard_Integer num) const; 274 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; 277 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; 281 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); 286 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 292 //! object. 293 //! Default is set to True. 294 Standard_EXPORT void SetRootManagement (const Standard_Boolean stat); 295 296 //! Returns the count of recorded Roots 297 Standard_EXPORT Standard_Integer NbRoots() const; 298 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; 301 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; 305 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; 309 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; 314 315 //! Resets Nesting Level of Transfers to Zero (Root Level), 316 //! whatever its current value. 317 Standard_EXPORT void ResetNestingLevel(); 318 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; 322 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()); 329 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()); 334 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); 341 342 //! Returns error handling flag 343 Standard_EXPORT Standard_Boolean ErrorHandle() const; 344 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; 352 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; 356 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; 361 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; 366 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; 371 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; 376 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; 383 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; 390 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; 395 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; 400 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); 407 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; 412 413 414 415 416 DEFINE_STANDARD_RTTI_INLINE(Transfer_ProcessForFinder,Standard_Transient) 417 418 protected: 419 420 421 422 423 private: 424 425 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); 431 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()); 440 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; 453 454 455 }; 456 457 458 459 460 461 462 463 #endif // _Transfer_ProcessForFinder_HeaderFile 464