1 -- Created by: Christian CAILLET <cky@phobox>
2 -- Copyright (c) 1992-1999 Matra Datavision
3 -- Copyright (c) 1999-2014 OPEN CASCADE SAS
5 -- This file is part of Open CASCADE Technology software library.
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.
13 -- Alternatively, this file may be used under the terms of Open CASCADE
14 -- commercial license or contractual agreement.
16 -- Modified : David Carbonel Mon 4 january 1999
17 -- Add of DENumber function. no. and of PrintToLog
20 deferred class InterfaceModel from Interface inherits TShared
22 ---Purpose : Defines an (Indexed) Set of data corresponding to a complete
23 -- Transfer by a File Interface, i.e. File Header and Transient
24 -- Entities (Objects) contained in a File. Contained Entities are
25 -- identified in the Model by unique and consecutive Numbers.
27 -- In addition, a Model can attach to each entity, a specific
28 -- Label according to the norm (e.g. Name for VDA, #ident for
29 -- Step ...), intended to be output on a string or a stream
30 -- (remark : labels are not obliged to be unique)
32 -- InterfaceModel itself is not Transient, it is intended to
33 -- work on a set of Transient Data. The services offered are
34 -- basic Listing and Identification operations on Transient
35 -- Entities, storage of Error Reports, Copying.
37 -- Moreovere, it is possible to define and use templates. These
38 -- are empty Models, from which copies can be obtained in order
39 -- to be filled with effective data. This allows to record
40 -- standard definitions for headers, avoiding to recreate them
41 -- for each sendings, and assuring customisation of produced
42 -- files for a given site.
43 -- A template is attached to a name. It is possible to define a
44 -- template from another one (get it, edit it then record it
45 -- under another name).
47 -- See also Graph, ShareTool, CheckTool for more
49 uses Transient, IndexedMapOfTransient,
50 DataMapOfIntegerTransient from TColStd,
51 HAsciiString from TCollection,
52 HSequenceOfHAsciiString from TColStd,
53 Messenger from Message,
54 ReportEntity, Check, CheckIterator,
55 EntityIterator, GeneralLib, Protocol, GTool,
58 raises OutOfRange, NoSuchObject, InterfaceMismatch
63 ---Purpose : Defines empty InterfaceModel, ready to be filled
65 Destroy (me : mutable);
66 ---Purpose : Clears the list of entities (service WhenDelete)
69 SetProtocol (me : mutable; proto : Protocol from Interface);
70 ---Purpose : Sets a Protocol for this Model
71 -- It is also set by a call to AddWithRefs with Protocol
72 -- It is used for : DumpHeader (as required), ClearEntities ...
74 Protocol (me) returns Protocol from Interface is virtual;
75 ---Purpose : Returns the Protocol which has been set by SetProtocol, or
76 -- AddWithRefs with Protocol
78 SetGTool (me : mutable; gtool : GTool from Interface);
79 ---Purpose : Sets a GTool for this model, which already defines a Protocol
81 GTool (me) returns GTool;
82 ---Purpose : Returns the GTool, set by SetProtocol or by SetGTool
84 DispatchStatus (me : mutable) returns Boolean;
85 ---Purpose : Returns the Dispatch Status, either for get or set
86 -- A Model which is produced from Dispatch may share entities
87 -- with the original (according to the Protocol), hence these
88 -- non-copied entities should not be deleted
91 Clear (me : mutable) is virtual;
92 ---Purpose : Erases contained data; used when a Model is copied to others :
93 -- the new copied ones begin from clear
94 -- Clear calls specific method ClearHeader (see below)
96 ClearEntities (me : mutable) is virtual;
97 ---Purpose : Clears the entities; uses the general service WhenDelete, in
98 -- addition to the standard Memory Manager; can be redefined
100 ClearLabels (me : mutable) is deferred;
101 ---Purpose : Erases informations about labels, if any : specific to each
104 ClearHeader (me : mutable) is deferred;
105 ---Purpose : Clears Model's header : specific to each norm
107 -- -- Unitary Accesses to Entities -- --
109 NbEntities (me) returns Integer;
110 ---Purpose : Returns count of contained Entities
112 Contains (me; anentity : Transient) returns Boolean;
113 ---Purpose : Returns True if a Model contains an Entity (for a ReportEntity,
114 -- looks for the ReportEntity itself AND its Concerned Entity)
116 Number (me; anentity : Transient) returns Integer;
117 ---Purpose : Returns the Number of an Entity in the Model if it contains it.
118 -- Else returns 0. For a ReportEntity, looks at Concerned Entity.
120 -- DENumber (me; anentity : Transient) returns Integer;
121 ---Purpose : Returns the Directory entry Number of an Entity in
122 -- the Model if it contains it. Else returns 0. For a
123 -- ReportEntity, looks at Concerned Entity.
125 Value (me; num : Integer) returns Transient raises OutOfRange;
126 ---Purpose : Returns an Entity identified by its number in the Model
127 -- Each sub-class of InterfaceModel can define its own method
128 -- Entity to return its specific class of Entity (e.g. for VDA,
129 -- VDAModel returns a VDAEntity), working by calling Value
130 -- Remark : For a Reported Entity, (Erroneous, Corrected, Unknown), this
131 -- method returns this Reported Entity.
132 -- See ReportEntity for other questions.
133 ---C++ : return const &
135 NbTypes (me; ent : Transient) returns Integer;
136 ---Purpose : Returns the count of DISTINCT types under which an entity may
137 -- be processed. Defined by the Protocol, which gives default as
140 Type (me; ent : Transient; num : Integer = 1) returns Type;
141 ---Purpose : Returns a type, given its rank : defined by the Protocol
142 -- (by default, the first one)
144 TypeName (me; ent : Transient; complete : Boolean = Standard_True)
146 ---Purpose : Returns the type name of an entity, from the list of types
148 -- <complete> True (D) gives the complete type, else packages are
150 -- WARNING : buffered, to be immediately copied or printed
152 ClassName (myclass; typnam : CString) returns CString;
153 ---Purpose : From a CDL Type Name, returns the Class part (package dropped)
154 -- WARNING : buffered, to be immediately copied or printed
156 -- -- Report Entities (for syntactic concerns) -- --
158 EntityState (me; num : Integer) returns DataState raises OutOfRange;
159 ---Purpose : Returns the State of an entity, given its number
161 IsReportEntity (me; num : Integer; semantic : Boolean = Standard_False)
162 returns Boolean raises OutOfRange;
163 ---Purpose : Returns True if <num> identifies a ReportEntity in the Model
164 -- Hence, ReportEntity can be called.
166 -- By default, queries main report, if <semantic> is True, it
167 -- queries report for semantic check
169 -- Remember that a Report Entity can be defined for an Unknown
170 -- Entity, or a Corrected or Erroneous (at read time) Entity.
171 -- The ReportEntity is defined before call to method AddEntity.
173 ReportEntity (me; num : Integer; semantic : Boolean = Standard_False)
175 ---Purpose : Returns a ReportEntity identified by its number in the Model,
176 -- or a Null Handle If <num> does not identify a ReportEntity.
178 -- By default, queries main report, if <semantic> is True, it
179 -- queries report for semantic check
181 -- Error if <num> is out of range
183 IsErrorEntity (me; num : Integer) returns Boolean raises OutOfRange;
184 ---Purpose : Returns True if <num> identifies an Error Entity : in this
185 -- case, a ReportEntity brings Fail Messages and possibly an
186 -- "undefined" Content, see IsRedefinedEntity
188 IsRedefinedContent (me; num : Integer) returns Boolean raises OutOfRange;
189 ---Purpose : Returns True if <num> identifies an Entity which content is
190 -- redefined through a ReportEntity (i.e. with literal data only)
191 -- This happens when an entity is syntactically erroneous in the
192 -- way that its basic content remains empty.
193 -- For more details (such as content itself), see ReportEntity
195 ClearReportEntity (me : mutable; num : Integer) returns Boolean
196 ---Purpose : Removes the ReportEntity attached to Entity <num>. Returns
197 -- True if done, False if no ReportEntity was attached to <num>.
198 -- Warning : the caller must assume that this clearing is meaningfull
200 -- Error if <num> is out of range
202 SetReportEntity (me : mutable; num : Integer; rep : ReportEntity)
204 ---Purpose : Sets or Replaces a ReportEntity for the Entity <num>. Returns
205 -- True if Report is replaced, False if it has been replaced
206 -- Warning : the caller must assume that this setting is meaningfull
207 raises OutOfRange, InterfaceMismatch;
208 -- Error if <num> is out of range, or if concerned Entity is
209 -- not equal to Value(num)
211 AddReportEntity (me : mutable; rep : ReportEntity;
212 semantic : Boolean = Standard_False) returns Boolean;
213 ---Purpose : Adds a ReportEntity as such. Returns False if the concerned
214 -- entity is not recorded in the Model
215 -- Else, adds it into, either the main report list or the
216 -- list for semantic checks, then returns True
218 IsUnknownEntity (me; num : Integer) returns Boolean raises OutOfRange;
219 ---Purpose : Returns True if <num> identifies an Unknown Entity : in this
220 -- case, a ReportEntity with no Check Messages designates it.
222 -- -- Checks (semantic & syntactic) -- --
224 FillSemanticChecks (me : mutable; checks : CheckIterator;
225 clear : Boolean = Standard_True);
226 ---Purpose : Fills the list of semantic checks.
227 -- This list is computed (by CheckTool). Hence, it can be stored
228 -- in the model for later queries
229 -- <clear> True (D) : new list replaces
230 -- <clear> False : new list is cumulated
232 HasSemanticChecks (me) returns Boolean;
233 ---Purpose : Returns True if semantic checks have been filled
235 Check (me; num : Integer; syntactic : Boolean) returns Check;
236 ---Purpose : Returns the check attached to an entity, designated by its
237 -- Number. 0 for global check
238 -- <semantic> True : recorded semantic check
239 -- <semantic> False : recorded syntactic check (see ReportEntity)
240 -- If no check is recorded for <num>, returns an empty Check
241 ---C++ : return const &
245 Reservate (me : mutable; nbent : Integer) is virtual;
246 ---Purpose : Does a reservation for the List of Entities (for optimized
247 -- storage management). If it is not called, storage management
248 -- can be less efficient. <nbent> is the expected count of
251 AddEntity (me : mutable; anentity : Transient)
252 ---Purpose : Internal method for adding an Entity. Used by file reading
253 -- (defined by each Interface) and Transfer tools. It adds the
254 -- entity required to be added, not its refs : see AddWithRefs.
255 -- If <anentity> is a ReportEntity, it is added to the list of
256 -- Reports, its Concerned Entity (Erroneous or Corrected, else
257 -- Unknown) is added to the list of Entities.
258 -- That is, the ReportEntity must be created before Adding
259 raises InterfaceMismatch is virtual;
260 -- Error if anentity already recorded
262 AddWithRefs (me : mutable; anent : Transient; proto : Protocol;
263 level : Integer = 0; listall : Boolean = Standard_False);
264 ---Purpose : Adds to the Model, an Entity with all its References, as they
265 -- are defined by General Services FillShared and ListImplied.
266 -- Process is recursive (any sub-levels) if <level> = 0 (Default)
267 -- Else, adds sub-entities until the required sub-level.
268 -- Especially, if <level> = 1, adds immediate subs and that's all
270 -- If <listall> is False (Default), an entity (<anentity> itself
271 -- or one of its subs at any level) which is already recorded in
272 -- the Model is not analysed, only the newly added ones are.
273 -- If <listall> is True, all items are analysed (this allows to
274 -- ensure the consistency of an adding made by steps)
276 AddWithRefs (me : mutable; anent : Transient;
277 level : Integer = 0; listall : Boolean = Standard_False)
278 ---Purpose : Same as above, but works with the Protocol of the Model
279 raises InterfaceMismatch;
280 -- Error if no Protocol is defined in the Model
282 AddWithRefs (me : mutable; anent : Transient; lib : GeneralLib;
283 level : Integer = 0; listall : Boolean = Standard_False);
284 ---Purpose : Same as above, but works with an already created GeneralLib
287 ReplaceEntity (me : mutable; nument : Integer; anent : Transient);
288 ---Purpose : Replace Entity with Number=nument on other entity - "anent"
290 ReverseOrders (me : mutable; after : Integer = 0);
291 ---Purpose : Reverses the Numbers of the Entities, between <after> and the
292 -- total count of Entities. Thus, the entities :
293 -- 1,2 ... after, after+1 ... nb-1, nb become numbered as :
294 -- 1,2 ... after, nb, nb-1 ... after+1
295 -- By default (after = 0) the whole list of Entities is reversed
297 ChangeOrder (me : mutable; oldnum, newnum : Integer; count : Integer = 1)
298 ---Purpose : Changes the Numbers of some Entities : <oldnum> is moved to
299 -- <newnum>, same for <count> entities. Thus :
300 -- 1,2 ... newnum-1 newnum ... oldnum .. oldnum+count oldnum+count+1 .. gives
301 -- 1,2 ... newnum-1 oldnum .. oldnum+count newnum ... oldnum+count+1
302 -- (can be seen as a circular permutation)
304 -- Error if one of <oldnum,newnum, and + count> is out of range,
305 -- or if <count> is greater than Abs(newnum-oldnum)
307 GetFromTransfer (me : mutable; aniter : EntityIterator)
308 ---Purpose : Gets contents from an EntityIterator, prepared by a
309 -- Transfer tool (e.g TransferCopy). Starts from clear
310 raises InterfaceMismatch;
311 -- Error if InterfaceEntities to get are not free
313 GetFromAnother (me : mutable; other : InterfaceModel) is deferred;
314 ---Purpose : Gets header (data specific of a defined Interface) from
315 -- another InterfaceModel; called from TransferCopy
317 NewEmptyModel (me) returns InterfaceModel is deferred;
318 ---Purpose : Returns a New Empty Model, same type as <me> (whatever its
319 -- Type); called to Copy parts a Model into other ones, then
320 -- followed by a call to GetFromAnother (Header) then filling
321 -- with specified Entities, themselves copied
323 -- -- Categories -- --
325 SetCategoryNumber (me : mutable; num : Integer; val : Integer)
327 ---Purpose : Records a category number for an entity number
328 -- Returns True when done, False if <num> is out of range
330 CategoryNumber (me; num : Integer) returns Integer;
331 ---Purpose : Returns the recorded category number for a given entity number
332 -- 0 if none was defined for this entity
334 -- -- Global Queries -- --
336 FillIterator (me; iter : in out EntityIterator);
337 ---Purpose : Allows an EntityIterator to get a list of Entities
340 Entities (me) returns EntityIterator;
341 ---Purpose : Returns the list of all Entities, as an Iterator on Entities
342 -- (the Entities themselves, not the Reports)
344 Reports (me; semantic : Boolean = Standard_False) returns EntityIterator;
345 ---Purpose : Returns the list of all ReportEntities, i.e. data about
346 -- Entities read with Error or Warning informations
347 -- (each item has to be casted to Report Entity then it can be
348 -- queried for Concerned Entity, Content, Check ...)
349 -- By default, returns the main reports, is <semantic> is True it
350 -- returns the list for sematic checks
351 ---See Also : classes ReportEntity (for contents) and CheckTool
353 Redefineds (me) returns EntityIterator;
354 ---Purpose : Returns the list of ReportEntities which redefine data
355 -- (generally, if concerned entity is "Error", a literal content
356 -- is added to it : this is a "redefined entity"
359 GlobalCheck (me; syntactic : Boolean = Standard_True) returns Check;
360 ---Purpose : Returns the GlobalCheck, which memorizes messages global to
361 -- the file (not specific to an Entity), especially Header
362 ---C++ : return const &
364 SetGlobalCheck (me : mutable; ach : Check);
365 ---Purpose : Allows to modify GlobalCheck, after getting then completing it
366 -- Remark : it is SYNTACTIC check. Semantics, see FillChecks
368 VerifyCheck (me; ach : in out Check) is virtual;
369 ---Purpose : Minimum Semantic Global Check on data in model (header)
370 -- Can only check basic Data. See also GlobalCheck from Protocol
371 -- for a check which takes the Graph into account
372 -- Default does nothing, can be redefined
374 DumpHeader (me; S : Messenger from Message; level : Integer = 0) is deferred;
375 ---Purpose : Dumps Header in a short, easy to read, form, onto a Stream
376 -- <level> allows to print more or less parts of the header,
377 -- if necessary. 0 for basic print
379 Print (me; ent : Transient; s : Messenger from Message; mode : Integer = 0);
380 ---Purpose : Prints identification of a given entity in <me>, in order to
381 -- be printed in a list or phrase
382 -- <mode> < 0 : prints only its number
383 -- <mode> = 1 : just calls PrintLabel
384 -- <mode> = 0 (D) : prints its number plus '/' plus PrintLabel
385 -- If <ent> == <me>, simply prints "Global"
386 -- If <ent> is unknown, prints "??/its type"
388 PrintLabel (me; ent : Transient; S : Messenger from Message) is deferred;
389 ---Purpose : Prints label specific to each norm, for a given entity.
390 -- Must only print label itself, in order to be included in a
391 -- phrase. Can call the result of StringLabel, but not obliged.
393 PrintToLog (me; ent : Transient; S : Messenger from Message) is virtual;
394 ---Purpose : Prints label specific to each norm in log format, for
396 -- By default, just calls PrintLabel, can be redefined
398 StringLabel (me; ent : Transient) returns HAsciiString from TCollection
400 ---Purpose : Returns a string with the label attached to a given entity.
401 -- Warning : While this string may be edited on the spot, if it is a read
402 -- field, the returned value must be copied before.
404 NextNumberForLabel (me; label : CString;
405 lastnum : Integer = 0; exact : Boolean = Standard_True)
406 returns Integer is virtual;
407 ---Purpose : Searches a label which matches with one entity.
408 -- Begins from <lastnum>+1 (default:1) and scans the entities
409 -- until <NbEntities>. For the first which matches <label>,
410 -- this method returns its Number. Returns 0 if nothing found
411 -- Can be called recursively (labels are not specified as unique)
412 -- <exact> : if True (default), exact match is required
413 -- else, checks the END of entity label
415 -- This method is virtual, hence it can be redefined for a more
416 -- efficient search (if exact is true).
418 -- -- Templates -- --
420 HasTemplate (myclass; name : CString) returns Boolean;
421 ---Purpose : Returns true if a template is attached to a given name
423 Template (myclass; name : CString) returns InterfaceModel;
424 ---Purpose : Returns the template model attached to a name, or a Null Handle
426 SetTemplate (myclass; name : CString; model : InterfaceModel)
428 ---Purpose : Records a new template model with a name. If the name was
429 -- already recorded, the corresponding template is replaced by
430 -- the new one. Then, WARNING : test HasTemplate to avoid
433 ListTemplates (myclass) returns HSequenceOfHAsciiString;
434 ---Purpose : Returns the complete list of names attached to template models
438 theentities : IndexedMapOfTransient;
439 thereports : DataMapOfIntegerTransient from TColStd; -- EntityNumber -> ReportEntity
440 therepch : DataMapOfIntegerTransient from TColStd; -- for semantic checks
441 thecheckstx : Check; -- it is GlobalCheck (Syntactic)
442 thechecksem : Check; -- it is GlobalCheck (Semantic)
443 haschecksem : Boolean; -- are semantic checks recorded
444 isdispatch : Boolean; -- is <me> produced for dispatch ?
445 thecategory : HAsciiString;
447 -- theprotocol : Protocol;