0031501: Foundation Classes, Message_Printer - remove theToPutEndl argument -- prepar...
[occt.git] / src / Interface / Interface_InterfaceModel.hxx
1 // Created by: Christian CAILLET <cky@phobox> 
2 // Copyright (c) 1992-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 #ifndef _Interface_InterfaceModel_HeaderFile
17 #define _Interface_InterfaceModel_HeaderFile
18
19 #include <Standard.hxx>
20 #include <Standard_Type.hxx>
21
22 #include <TColStd_IndexedMapOfTransient.hxx>
23 #include <TColStd_DataMapOfIntegerTransient.hxx>
24 #include <Standard_Boolean.hxx>
25 #include <Standard_Transient.hxx>
26 #include <Standard_Integer.hxx>
27 #include <Standard_Type.hxx>
28 #include <Standard_CString.hxx>
29 #include <Interface_DataState.hxx>
30 #include <TColStd_HSequenceOfHAsciiString.hxx>
31 class Interface_Check;
32 class TCollection_HAsciiString;
33 class Interface_GTool;
34 class Standard_OutOfRange;
35 class Standard_NoSuchObject;
36 class Interface_InterfaceMismatch;
37 class Interface_Protocol;
38 class Standard_Transient;
39 class Interface_ReportEntity;
40 class Interface_CheckIterator;
41 class Interface_GeneralLib;
42 class Interface_EntityIterator;
43
44
45 class Interface_InterfaceModel;
46 DEFINE_STANDARD_HANDLE(Interface_InterfaceModel, Standard_Transient)
47
48 //! Defines an (Indexed) Set of data corresponding to a complete
49 //! Transfer by a File Interface, i.e. File Header and Transient
50 //! Entities (Objects) contained in a File. Contained Entities are
51 //! identified in the Model by unique and consecutive Numbers.
52 //!
53 //! In addition, a Model can attach to each entity, a specific
54 //! Label according to the norm (e.g. Name for VDA, #ident for
55 //! Step ...), intended to be output on a string or a stream
56 //! (remark : labels are not obliged to be unique)
57 //!
58 //! InterfaceModel itself is not Transient, it is intended to
59 //! work on a set of Transient Data. The services offered are
60 //! basic Listing and Identification operations on Transient
61 //! Entities, storage of Error Reports, Copying.
62 //!
63 //! Moreovere, it is possible to define and use templates. These
64 //! are empty Models, from which copies can be obtained in order
65 //! to be filled with effective data. This allows to record
66 //! standard definitions for headers, avoiding to recreate them
67 //! for each sendings, and assuring customisation of produced
68 //! files for a given site.
69 //! A template is attached to a name. It is possible to define a
70 //! template from another one (get it, edit it then record it
71 //! under another name).
72 //!
73 //! See also Graph, ShareTool, CheckTool for more
74 class Interface_InterfaceModel : public Standard_Transient
75 {
76
77 public:
78
79   
80   //! Clears the list of entities (service WhenDelete)
81   Standard_EXPORT void Destroy();
82 ~Interface_InterfaceModel()
83 {
84   Destroy();
85 }
86   
87   //! Sets a Protocol for this Model
88   //! It is also set by a call to AddWithRefs with Protocol
89   //! It is used for : DumpHeader (as required), ClearEntities ...
90   Standard_EXPORT void SetProtocol (const Handle(Interface_Protocol)& proto);
91   
92   //! Returns the Protocol which has been set by SetProtocol, or
93   //! AddWithRefs with Protocol
94   Standard_EXPORT virtual Handle(Interface_Protocol) Protocol() const;
95   
96   //! Sets a GTool for this model, which already defines a Protocol
97   Standard_EXPORT void SetGTool (const Handle(Interface_GTool)& gtool);
98   
99   //! Returns the GTool, set by SetProtocol or by SetGTool
100   Standard_EXPORT Handle(Interface_GTool) GTool() const;
101   
102   //! Returns the Dispatch Status, either for get or set
103   //! A Model which is produced from Dispatch may share entities
104   //! with the original (according to the Protocol), hence these
105   //! non-copied entities should not be deleted
106   Standard_EXPORT Standard_Boolean& DispatchStatus();
107   
108   //! Erases contained data; used when a Model is copied to others :
109   //! the new copied ones begin from clear
110   //! Clear calls specific method ClearHeader (see below)
111   Standard_EXPORT virtual void Clear();
112   
113   //! Clears the entities; uses the general service WhenDelete, in
114   //! addition to the standard Memory Manager; can be redefined
115   Standard_EXPORT virtual void ClearEntities();
116   
117   //! Erases informations about labels, if any : specific to each
118   //! norm
119   Standard_EXPORT virtual void ClearLabels() = 0;
120   
121   //! Clears Model's header : specific to each norm
122   Standard_EXPORT virtual void ClearHeader() = 0;
123   
124   //! Returns count of contained Entities
125   Standard_EXPORT Standard_Integer NbEntities() const;
126   
127   //! Returns True if a Model contains an Entity (for a ReportEntity,
128   //! looks for the ReportEntity itself AND its Concerned Entity)
129   Standard_EXPORT Standard_Boolean Contains (const Handle(Standard_Transient)& anentity) const;
130   
131   //! Returns the Number of an Entity in the Model if it contains it.
132   //! Else returns 0. For a ReportEntity, looks at Concerned Entity.
133   //! Returns the Directory entry   Number of  an Entity in
134   //! the  Model if it contains it.   Else returns  0.  For a
135   //! ReportEntity, looks at Concerned Entity.
136   Standard_EXPORT Standard_Integer Number (const Handle(Standard_Transient)& anentity) const;
137   
138   //! Returns an Entity identified by its number in the Model
139   //! Each sub-class of InterfaceModel can define its own method
140   //! Entity to return its specific class of Entity (e.g. for VDA,
141   //! VDAModel returns a VDAEntity), working by calling Value
142   //! Remark : For a Reported Entity, (Erroneous, Corrected, Unknown), this
143   //! method returns this Reported Entity.
144   //! See ReportEntity for other questions.
145   Standard_EXPORT const Handle(Standard_Transient)& Value (const Standard_Integer num) const;
146   
147   //! Returns the count of DISTINCT types under which an entity may
148   //! be processed. Defined by the Protocol, which gives default as
149   //! 1 (dynamic Type).
150   Standard_EXPORT Standard_Integer NbTypes (const Handle(Standard_Transient)& ent) const;
151   
152   //! Returns a type, given its rank : defined by the Protocol
153   //! (by default, the first one)
154   Standard_EXPORT Handle(Standard_Type) Type (const Handle(Standard_Transient)& ent, const Standard_Integer num = 1) const;
155   
156   //! Returns the type name of an entity, from the list of types
157   //! (one or more ...)
158   //! <complete> True (D) gives the complete type, else packages are
159   //! removed
160   //! WARNING : buffered, to be immediately copied or printed
161   Standard_EXPORT Standard_CString TypeName (const Handle(Standard_Transient)& ent, const Standard_Boolean complete = Standard_True) const;
162   
163   //! From a CDL Type Name, returns the Class part (package dropped)
164   //! WARNING : buffered, to be immediately copied or printed
165   Standard_EXPORT static Standard_CString ClassName (const Standard_CString typnam);
166   
167   //! Returns the State of an entity, given its number
168   Standard_EXPORT Interface_DataState EntityState (const Standard_Integer num) const;
169   
170   //! Returns True if <num> identifies a ReportEntity in the Model
171   //! Hence, ReportEntity can be called.
172   //!
173   //! By default, queries main report, if <semantic> is True, it
174   //! queries report for semantic check
175   //!
176   //! Remember that a Report Entity can be defined for an Unknown
177   //! Entity, or a Corrected or Erroneous (at read time) Entity.
178   //! The ReportEntity is defined before call to method AddEntity.
179   Standard_EXPORT Standard_Boolean IsReportEntity (const Standard_Integer num, const Standard_Boolean semantic = Standard_False) const;
180   
181   //! Returns a ReportEntity identified by its number in the Model,
182   //! or a Null Handle If <num> does not identify a ReportEntity.
183   //!
184   //! By default, queries main report, if <semantic> is True, it
185   //! queries report for semantic check
186   Standard_EXPORT Handle(Interface_ReportEntity) ReportEntity (const Standard_Integer num, const Standard_Boolean semantic = Standard_False) const;
187   
188   //! Returns True if <num> identifies an Error Entity : in this
189   //! case, a ReportEntity brings Fail Messages and possibly an
190   //! "undefined" Content, see IsRedefinedEntity
191   Standard_EXPORT Standard_Boolean IsErrorEntity (const Standard_Integer num) const;
192   
193   //! Returns True if <num> identifies an Entity which content is
194   //! redefined through a ReportEntity (i.e. with literal data only)
195   //! This happens when an entity is syntactically erroneous in the
196   //! way that its basic content remains empty.
197   //! For more details (such as content itself), see ReportEntity
198   Standard_EXPORT Standard_Boolean IsRedefinedContent (const Standard_Integer num) const;
199   
200   //! Removes the ReportEntity attached to Entity <num>. Returns
201   //! True if done, False if no ReportEntity was attached to <num>.
202   //! Warning : the caller must assume that this clearing is meaningfull
203   Standard_EXPORT Standard_Boolean ClearReportEntity (const Standard_Integer num);
204   
205   //! Sets or Replaces a ReportEntity for the Entity <num>. Returns
206   //! True if Report is replaced, False if it has been replaced
207   //! Warning : the caller must assume that this setting is meaningfull
208   Standard_EXPORT Standard_Boolean SetReportEntity (const Standard_Integer num, const Handle(Interface_ReportEntity)& rep);
209   
210   //! Adds a ReportEntity as such. Returns False if the concerned
211   //! entity is not recorded in the Model
212   //! Else, adds it into, either the main report list or the
213   //! list for semantic checks, then returns True
214   Standard_EXPORT Standard_Boolean AddReportEntity (const Handle(Interface_ReportEntity)& rep, const Standard_Boolean semantic = Standard_False);
215   
216   //! Returns True if <num> identifies an Unknown Entity : in this
217   //! case, a ReportEntity with no Check Messages designates it.
218   Standard_EXPORT Standard_Boolean IsUnknownEntity (const Standard_Integer num) const;
219   
220   //! Fills the list of semantic checks.
221   //! This list is computed (by CheckTool). Hence, it can be stored
222   //! in the model for later queries
223   //! <clear> True (D) : new list replaces
224   //! <clear> False    : new list is cumulated
225   Standard_EXPORT void FillSemanticChecks (const Interface_CheckIterator& checks, const Standard_Boolean clear = Standard_True);
226   
227   //! Returns True if semantic checks have been filled
228   Standard_EXPORT Standard_Boolean HasSemanticChecks() const;
229   
230   //! Returns the check attached to an entity, designated by its
231   //! Number. 0 for global check
232   //! <semantic> True  : recorded semantic check
233   //! <semantic> False : recorded syntactic check (see ReportEntity)
234   //! If no check is recorded for <num>, returns an empty Check
235   Standard_EXPORT const Handle(Interface_Check)& Check (const Standard_Integer num, const Standard_Boolean syntactic) const;
236   
237   //! Does a reservation for the List of Entities (for optimized
238   //! storage management). If it is not called, storage management
239   //! can be less efficient. <nbent> is the expected count of
240   //! Entities to store
241   Standard_EXPORT virtual void Reservate (const Standard_Integer nbent);
242   
243   //! Internal method for adding an Entity. Used by file reading
244   //! (defined by each Interface) and Transfer tools. It adds the
245   //! entity required to be added, not its refs : see AddWithRefs.
246   //! If <anentity> is a ReportEntity, it is added to the list of
247   //! Reports, its Concerned Entity (Erroneous or Corrected, else
248   //! Unknown) is added to the list of Entities.
249   //! That is, the ReportEntity must be created before Adding
250   Standard_EXPORT virtual void AddEntity (const Handle(Standard_Transient)& anentity);
251   
252   //! Adds to the Model, an Entity with all its References, as they
253   //! are defined by General Services FillShared and ListImplied.
254   //! Process is recursive (any sub-levels) if <level> = 0 (Default)
255   //! Else, adds sub-entities until the required sub-level.
256   //! Especially, if <level> = 1, adds immediate subs and that's all
257   //!
258   //! If <listall> is False (Default), an entity (<anentity> itself
259   //! or one of its subs at any level) which is already recorded in
260   //! the Model is not analysed, only the newly added ones are.
261   //! If <listall> is True, all items are analysed (this allows to
262   //! ensure the consistency of an adding made by steps)
263   Standard_EXPORT void AddWithRefs (const Handle(Standard_Transient)& anent, const Handle(Interface_Protocol)& proto, const Standard_Integer level = 0, const Standard_Boolean listall = Standard_False);
264   
265   //! Same as above, but works with the Protocol of the Model
266   Standard_EXPORT void AddWithRefs (const Handle(Standard_Transient)& anent, const Standard_Integer level = 0, const Standard_Boolean listall = Standard_False);
267   
268   //! Same as above, but works with an already created GeneralLib
269   Standard_EXPORT void AddWithRefs (const Handle(Standard_Transient)& anent, const Interface_GeneralLib& lib, const Standard_Integer level = 0, const Standard_Boolean listall = Standard_False);
270   
271   //! Replace Entity with Number=nument on other entity - "anent"
272   Standard_EXPORT void ReplaceEntity (const Standard_Integer nument, const Handle(Standard_Transient)& anent);
273   
274   //! Reverses the Numbers of the Entities, between <after> and the
275   //! total count of Entities. Thus, the entities :
276   //! 1,2 ... after, after+1 ... nb-1, nb  become numbered as :
277   //! 1,2 ... after, nb, nb-1 ... after+1
278   //! By default (after = 0) the whole list of Entities is reversed
279   Standard_EXPORT void ReverseOrders (const Standard_Integer after = 0);
280   
281   //! Changes the Numbers of some Entities : <oldnum> is moved to
282   //! <newnum>, same for <count> entities. Thus :
283   //! 1,2 ... newnum-1 newnum ... oldnum .. oldnum+count oldnum+count+1 .. gives
284   //! 1,2 ... newnum-1 oldnum .. oldnum+count newnum ... oldnum+count+1
285   //! (can be seen as a circular permutation)
286   Standard_EXPORT void ChangeOrder (const Standard_Integer oldnum, const Standard_Integer newnum, const Standard_Integer count = 1);
287   
288   //! Gets contents from an EntityIterator, prepared by a
289   //! Transfer tool (e.g TransferCopy). Starts from clear
290   Standard_EXPORT void GetFromTransfer (const Interface_EntityIterator& aniter);
291   
292   //! Gets header (data specific of a defined Interface) from
293   //! another InterfaceModel; called from TransferCopy
294   Standard_EXPORT virtual void GetFromAnother (const Handle(Interface_InterfaceModel)& other) = 0;
295   
296   //! Returns a New Empty Model, same type as <me> (whatever its
297   //! Type); called to Copy parts a Model into other ones, then
298   //! followed by a call to GetFromAnother (Header) then filling
299   //! with specified Entities, themselves copied
300   Standard_EXPORT virtual Handle(Interface_InterfaceModel) NewEmptyModel() const = 0;
301   
302   //! Records a category number for an entity number
303   //! Returns True when done, False if <num> is out of range
304   Standard_EXPORT Standard_Boolean SetCategoryNumber (const Standard_Integer num, const Standard_Integer val);
305   
306   //! Returns the recorded category number for a given entity number
307   //! 0 if none was defined for this entity
308   Standard_EXPORT Standard_Integer CategoryNumber (const Standard_Integer num) const;
309   
310   //! Allows an EntityIterator to get a list of Entities
311   Standard_EXPORT void FillIterator (Interface_EntityIterator& iter) const;
312   
313   //! Returns the list of all Entities, as an Iterator on Entities
314   //! (the Entities themselves, not the Reports)
315   Standard_EXPORT Interface_EntityIterator Entities() const;
316   
317   //! Returns the list of all ReportEntities, i.e. data about
318   //! Entities read with Error or Warning informations
319   //! (each item has to be casted to Report Entity then it can be
320   //! queried for Concerned Entity, Content, Check ...)
321   //! By default, returns the main reports, is <semantic> is True it
322   //! returns the list for sematic checks
323   Standard_EXPORT Interface_EntityIterator Reports (const Standard_Boolean semantic = Standard_False) const;
324   
325   //! Returns the list of ReportEntities which redefine data
326   //! (generally, if concerned entity is "Error", a literal content
327   //! is added to it : this is a "redefined entity"
328   Standard_EXPORT Interface_EntityIterator Redefineds() const;
329   
330   //! Returns the GlobalCheck, which memorizes messages global to
331   //! the file (not specific to an Entity), especially Header
332   Standard_EXPORT const Handle(Interface_Check)& GlobalCheck (const Standard_Boolean syntactic = Standard_True) const;
333   
334   //! Allows to modify GlobalCheck, after getting then completing it
335   //! Remark : it is SYNTACTIC check. Semantics, see FillChecks
336   Standard_EXPORT void SetGlobalCheck (const Handle(Interface_Check)& ach);
337   
338   //! Minimum Semantic Global Check on data in model (header)
339   //! Can only check basic Data. See also GlobalCheck from Protocol
340   //! for a check which takes the Graph into account
341   //! Default does nothing, can be redefined
342   Standard_EXPORT virtual void VerifyCheck (Handle(Interface_Check)& ach) const;
343   
344   //! Dumps Header in a short, easy to read, form, onto a Stream
345   //! <level> allows to print more or less parts of the header,
346   //! if necessary. 0 for basic print
347   Standard_EXPORT virtual void DumpHeader (Standard_OStream& S, const Standard_Integer level = 0) const = 0;
348   
349   //! Prints identification of a given entity in <me>, in order to
350   //! be printed in a list or phrase
351   //! <mode> < 0 : prints only its number
352   //! <mode> = 1 : just calls PrintLabel
353   //! <mode> = 0 (D) : prints its number plus '/' plus PrintLabel
354   //! If <ent> == <me>, simply prints "Global"
355   //! If <ent> is unknown, prints "??/its type"
356   Standard_EXPORT void Print (const Handle(Standard_Transient)& ent, Standard_OStream& s, const Standard_Integer mode = 0) const;
357   
358   //! Prints label specific to each norm, for a given entity.
359   //! Must only print label itself, in order to be included in a
360   //! phrase. Can call the result of StringLabel, but not obliged.
361   Standard_EXPORT virtual void PrintLabel (const Handle(Standard_Transient)& ent, Standard_OStream& S) const = 0;
362   
363   //! Prints label specific to each norm in log format, for
364   //! a given entity.
365   //! By default, just calls PrintLabel, can be redefined
366   Standard_EXPORT virtual void PrintToLog (const Handle(Standard_Transient)& ent, Standard_OStream& S) const;
367   
368   //! Returns a string with the label attached to a given entity.
369   //! Warning : While this string may be edited on the spot, if it is a read
370   //! field, the returned value must be copied before.
371   Standard_EXPORT virtual Handle(TCollection_HAsciiString) StringLabel (const Handle(Standard_Transient)& ent) const = 0;
372   
373   //! Searches a label which matches with one entity.
374   //! Begins from <lastnum>+1 (default:1) and scans the entities
375   //! until <NbEntities>. For the first which matches <label>,
376   //! this method returns its Number. Returns 0 if nothing found
377   //! Can be called recursively (labels are not specified as unique)
378   //! <exact> : if True (default), exact match is required
379   //! else, checks the END of entity label
380   //!
381   //! This method is virtual, hence it can be redefined for a more
382   //! efficient search (if exact is true).
383   Standard_EXPORT virtual Standard_Integer NextNumberForLabel (const Standard_CString label, const Standard_Integer lastnum = 0, const Standard_Boolean exact = Standard_True) const;
384   
385   //! Returns true if a template is attached to a given name
386   Standard_EXPORT static Standard_Boolean HasTemplate (const Standard_CString name);
387   
388   //! Returns the template model attached to a name, or a Null Handle
389   Standard_EXPORT static Handle(Interface_InterfaceModel) Template (const Standard_CString name);
390   
391   //! Records a new template model with a name. If the name was
392   //! already recorded, the corresponding template is replaced by
393   //! the new one. Then, WARNING : test HasTemplate to avoid
394   //! surprises
395   Standard_EXPORT static Standard_Boolean SetTemplate (const Standard_CString name, const Handle(Interface_InterfaceModel)& model);
396   
397   //! Returns the complete list of names attached to template models
398   Standard_EXPORT static Handle(TColStd_HSequenceOfHAsciiString) ListTemplates();
399
400
401
402   DEFINE_STANDARD_RTTIEXT(Interface_InterfaceModel,Standard_Transient)
403
404 protected:
405
406   
407   //! Defines empty InterfaceModel, ready to be filled
408   Standard_EXPORT Interface_InterfaceModel();
409
410
411
412 private:
413
414
415   TColStd_IndexedMapOfTransient theentities;
416   TColStd_DataMapOfIntegerTransient thereports;
417   TColStd_DataMapOfIntegerTransient therepch;
418   Handle(Interface_Check) thecheckstx;
419   Handle(Interface_Check) thechecksem;
420   Standard_Boolean haschecksem;
421   Standard_Boolean isdispatch;
422   Handle(TCollection_HAsciiString) thecategory;
423   Handle(Interface_GTool) thegtool;
424
425
426 };
427
428
429
430
431
432
433
434 #endif // _Interface_InterfaceModel_HeaderFile