0024157: Parallelization of assembly part of BO
[occt.git] / src / CDM / CDM_Document.cdl
CommitLineData
b311480e 1-- Created on: 1997-07-30
2-- Created by: Jean-Louis Frenkel
3-- Copyright (c) 1997-1999 Matra Datavision
4-- Copyright (c) 1999-2012 OPEN CASCADE SAS
5--
6-- The content of this file is subject to the Open CASCADE Technology Public
7-- License Version 6.5 (the "License"). You may not use the content of this file
8-- except in compliance with the License. Please obtain a copy of the License
9-- at http://www.opencascade.org and read it completely before using this file.
10--
11-- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its
12-- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France.
13--
14-- The Original Code and all software distributed under the License is
15-- distributed on an "AS IS" basis, without warranty of any kind, and the
16-- Initial Developer hereby disclaims all such warranties, including without
17-- limitation, any warranties of merchantability, fitness for a particular
18-- purpose or non-infringement. Please see the License for the specific terms
19-- and conditions governing the rights and limitations under the License.
20
7fd59977 21
22deferred class Document from CDM
23
24inherits Transient from Standard
25
26---Purpose: An applicative document is an instance of a class inheriting CDM_Document.
27-- These documents have the following properties:
28-- - they can have references to other documents.
29-- - the modifications of a document are propagated to the referencing
30-- documents.
31-- - a document can be stored in different formats, with or
32-- without a persistent model.
33-- - the drivers for storing and retrieving documents are
34-- plugged in when necessary.
35-- - a document has a modification counter. This counter is
36-- incremented when the document is modified. When a document
37-- is stored, the current counter value is memorized as the
38-- last storage version of the document. A document is
39-- considered to be modified when the counter value is
40-- different from the storage version. Once the document is
41-- saved the storage version and the counter value are
42-- identical. The document is now not considered to be
43-- modified.
44-- - a reference is a link between two documents. A reference has two
45-- components: the "From Document" and the "To Document". When
46-- a reference is created, an identifier of the reference is generated.
47-- This identifier is unique in the scope of the From Document and
48-- is conserved during storage and retrieval. This means that the
49-- referenced document will be always accessible through this
50-- identifier.
51-- - a reference memorizes the counter value of the To Document when
52-- the reference is created. The From Document is considered to
53-- be up to date relative to the To Document when the
54-- reference counter value is equal to the To Document counter value.
55-- - retrieval of a document having references does not imply
56-- the retrieving of the referenced documents.
57
58uses
59 Reference from CDM,
60 ReferenceIterator from CDM,
61 ExtendedString from TCollection,MetaData from CDM, Application from CDM,
62 ListOfReferences from CDM, SequenceOfExtendedString from TColStd,
63 GUID from Standard,Manager from Resource,CanCloseStatus from CDM
64
65
66raises NoSuchObject from Standard,Failure from Standard,DomainError from Standard
67is
68
69 Initialize;
70
7fd59977 71---Category: virtual methods
24de79c3 72 Destroy(me: mutable) is virtual protected;
73 ---C++: alias ~
74
7fd59977 75
76 Update(me: mutable; aToDocument: Document from CDM; aReferenceIdentifier: Integer from Standard; aModifContext: Address from Standard)
77 ---Purpose: The Update method will be called once for each
78 -- reference, but it should not perform any computation,
79 -- to avoid multiple computation of a same document.
80 is virtual;
81
82
83 Update(me:mutable; ErrorString: out ExtendedString from TCollection)
84 returns Boolean from Standard
85 ---Purpose: This method Update will be called
86 -- to signal the end of the modified references list.
87 -- The document should be recomputed and
88 -- UpdateFromDocuments should be called. Update should
89 -- returns True in case of success, false otherwise. In
90 -- case of Failure, additional information can be given in
91 -- ErrorString.
92 is virtual;
93
94
95 StorageFormat(me)
96 returns ExtendedString from TCollection
97 ---Purpose: The Storage Format is the key which is used to determine in the
98 -- application resources the storage driver plugin, the file
99 -- extension and other data used to store the document.
100 is deferred;
101
102 Extensions(me; Extensions: out SequenceOfExtendedString from TColStd)
103 is virtual;
104 ---Purpose: by default empties the extensions.
105 --
106
107 GetAlternativeDocument(me: mutable; aFormat: ExtendedString from TCollection;
108 anAlternativeDocument: out Document from CDM)
109 returns Boolean from Standard
110 ---Purpose: This method can be redefined to extract another document in
111 -- a different format. For example, to extract a MDTV-Shape
112 -- from an applicative document.
113 is virtual;
114
115---Category: Reference management.
116--
117 CreateReference(me: mutable; anOtherDocument: Document from CDM)
118 returns Integer from Standard;
119 ---Purpose: Creates a reference from this document to {anOtherDocument}.
120 -- Returns a reference identifier. This reference identifier
121 -- is unique in the document and will not be used for the
122 -- next references, even after the storing of the document.
123 -- If there is already a reference between the two documents,
124 -- the reference is not created, but its reference identifier
125 -- is returned.
126
127
128 RemoveReference(me: mutable; aReferenceIdentifier: Integer from Standard);
129 ---Purpose: Removes the reference between the From Document and the
130 -- To Document identified by a reference identifier.
131
132
133 RemoveAllReferences(me: mutable);
134 ---Purpose: Removes all references having this document for From Document.
135
136 Document(me; aReferenceIdentifier: Integer from Standard)
137 returns Document from CDM
138 ---Purpose: Returns the To Document of the reference identified by
139 -- aReferenceIdentifier. If the ToDocument is stored and
140 -- has not yet been retrieved, this method will retrieve it.
141 raises NoSuchObject from Standard;
142
143 IsInSession(me; aReferenceIdentifier: Integer from Standard)
144 returns Boolean from Standard
145 ---Purpose: returns True if the To Document of the reference
146 -- identified by aReferenceIdentifier is in session, False
147 -- if it corresponds to a not yet retrieved document.
148 raises NoSuchObject from Standard;
149
150 IsStored(me; aReferenceIdentifier: Integer from Standard)
151 returns Boolean from Standard
152 ---Purpose: returns True if the To Document of the reference
153 -- identified by aReferenceIdentifier has already been stored,
154 -- False otherwise.
155 raises NoSuchObject from Standard;
156
157 Name(me; aReferenceIdentifier: Integer from Standard)
158 returns ExtendedString from TCollection
159 ---Purpose: returns the name of the metadata of the To Document of
160 -- the reference identified by aReferenceIdentifier.
161 raises DomainError from Standard;
162 ---Warning: if the corresponding document is not stored.
163
164 UpdateFromDocuments(me; aModifContext: Address from Standard);
165 ---Purpose: call virtual method Update on all referencing
166 -- documents. This method keeps the list of the --
167 -- documents to process.It may be the starting of an
168 -- update -- cycle. If not, the reentrant calls made by
169 -- Update method (without argument) will append the
170 -- referencing documents to the list and call the Update method
171 -- (with arguments). Only the first call to UpdateFromDocuments
172 -- generate call to Update().
173
174 ToReferencesNumber(me)
175 returns Integer from Standard;
176 ---Purpose: returns the number of references having this document as
177 -- From Document.
178
179
180 FromReferencesNumber(me)
181 returns Integer from Standard;
182 ---Purpose: returns the number of references having this document as
183 -- To Document.
184
185 ShallowReferences(me; aDocument: Document from CDM)
186 returns Boolean from Standard;
187 ---Purpose: returns True is this document references aDocument;
188 --
189 DeepReferences(me; aDocument: Document from CDM)
190 returns Boolean from Standard;
191 ---Purpose: returns True is this document references aDocument;
192 --
193 CopyReference(me: mutable; aFromDocument: Document from CDM; aReferenceIdentifier: Integer from Standard)
194 returns Integer from Standard;
195 ---Purpose: Copies a reference to this document. This method
196 -- avoid retrieval of referenced document. The arguments
197 -- are the original document and a valid reference
198 -- identifier Returns the local identifier.
199 --
200 ---Category: Modifications Counter management.
201
202 IsReadOnly(me) returns Boolean from Standard;
203 ---Purpose: indicates that this document cannot be modified.
204
205
206
207 IsReadOnly(me; aReferenceIdentifier: Integer from Standard)
208 returns Boolean from Standard;
209 ---Purpose: indicates that the referenced document cannot be modified,
210
211
212 SetIsReadOnly(me: mutable);
213
214 UnsetIsReadOnly(me: mutable);
215
216 Modify(me: mutable);
217 ---Purpose: Indicates that this document has been modified.
218 -- This method increments the modification counter.
219 --
220 Modifications(me) returns Integer from Standard;
221 ---Purpose: returns the current modification counter.
222
223 UnModify(me: mutable);
224
225 IsUpToDate(me; aReferenceIdentifier: Integer from Standard)
226 returns Boolean from Standard;
227 ---Purpose: returns true if the modification counter found in the given
228 -- reference is equal to the actual modification counter of
229 -- the To Document. This method is able to deal with a reference
230 -- to a not retrieved document.
231
232
233 SetIsUpToDate(me: mutable; aReferenceIdentifier: Integer from Standard);
234 ---Purpose: Resets the modification counter in the given reference
235 -- to the actual modification counter of its To Document.
236 -- This method should be called after the application has updated
237 -- this document.
238
239
240 SetComment(me: mutable; aComment: ExtendedString from TCollection);
241 ---Purpose: associates a comment with this document.
242
243 AddComment(me: mutable; aComment: ExtendedString from TCollection);
244 ---Purpose: appends a comment into comments of this document.
245
246 SetComments(me: mutable; aComments: SequenceOfExtendedString from TColStd);
247 ---Purpose: associates a comments with this document.
248
249 Comments(me; aComments: out SequenceOfExtendedString from TColStd);
250 ---Purpose: returns the associated comments through <aComments>.
251 -- Returns empty sequence if no comments are associated.
252
253 Comment(me) returns ExtString from Standard;
254 ---Purpose: returns the first of associated comments. By defaut
255 -- the comment is an empty string.
256
257---Category: presentation methods. The presentation is an alphanumeric string.
258-- In a given session a presentation cannot be given to two differents
259-- documents.
260
261 Presentation(me: mutable) returns ExtString from Standard;
262 ---Purpose: Returns an alphanumeric string identifying this document
263 -- in a unique manner in the current process. The presentation
264 -- may change when the document is stored.
265 -- Tries to get the 'FileFormat`.Presentation resource
266 -- This item is used to give a default presentation
267 -- to the document.
268 FindFromPresentation(myclass; aPresentation: ExtendedString from TCollection)
269 returns Document from CDM
270 ---Purpose: returns the document having the given alphanumeric presentation.
271 raises NoSuchObject from Standard;
272
273
274 FindPresentation(myclass; aPresentation: ExtendedString from TCollection)
275 returns Boolean from Standard;
276 ---Purpose: indicates whether a document having the given presentation
277 -- does exist.
278
279 ---Category: database related methods
280 IsStored(me) returns Boolean from Standard;
281
282 StorageVersion(me) returns Integer from Standard;
283 ---Purpose: returns the value of the modification counter at the
284 -- time of storage. By default returns 0.
285
286
287 SetMetaData(me: mutable; aMetaData: MetaData from CDM);
288 ---Purpose: associates database information to a document which
289 -- has been stored. The name of the document is now the
290 -- name which has beenused to store the data.
291
292
293 UnsetIsStored(me: mutable);
294
295 MetaData(me) returns MetaData from CDM
296 raises NoSuchObject from Standard;
297
298 Folder(me) returns ExtendedString from TCollection
299 raises NoSuchObject from Standard;
300 ---Warning: if the object is not stored;
301
302
303 ---Category: methods to define where to store the document, the name
304 -- under which it has to be stored and some other metadatas.
305
306
307
308 SetRequestedFolder(me: mutable; aFolder: ExtendedString from TCollection);
309 ---Purpose: defines the folder in which the object should be stored.
310
311 RequestedFolder(me) returns ExtendedString from TCollection
312 raises NoSuchObject from Standard;
313
314
315 HasRequestedFolder(me) returns Boolean from Standard;
316
317
318
319
320 SetRequestedName(me: mutable; aName: ExtendedString from TCollection);
321 ---Purpose: defines the name under which the object should be stored.
322 RequestedName(me:mutable) returns ExtendedString from TCollection;
323 ---Purpose: determines under which the document is going to be
324 -- store. By default the name of the document wil be --
325 -- used. If the document has no name its presentation
326 -- will be used.
327
328 SetRequestedPreviousVersion(me: mutable; aPreviousVersion: ExtendedString from TCollection);
329
330 UnsetRequestedPreviousVersion(me: mutable);
331
332 HasRequestedPreviousVersion(me) returns Boolean from Standard;
333 RequestedPreviousVersion(me) returns ExtendedString from TCollection
334 raises NoSuchObject from Standard;
335
336 SetRequestedComment(me: mutable; aComment: ExtendedString from TCollection);
337 ---Purpose: defines the Comment with which the object should be stored.
338
339 RequestedComment(me) returns ExtendedString from TCollection;
340
341
342---Category: resource reading methods
343--
344--
345--
346--
347-- Resources are read once at the creation of the document
348-- until LoadResources is called again.
349--
350--
351 LoadResources(me: mutable);
352 ---Purpose: read (or rereads) the following resource.
353
354 StorageResource(me: mutable) returns Manager from Resource
355 is private;
356 ---Purpose: the manager returned by this method will be
357 -- used to search for the following resource items.
358
359 FindFileExtension(me: mutable) returns Boolean from Standard;
360
361 FileExtension(me: mutable) returns ExtendedString from TCollection;
362 ---Purpose: gets the Desktop.Domain.Application.`FileFormat`.FileExtension resource.
363 FindDataType(me: mutable) returns Boolean from Standard;
364
365 DataType(me: mutable) returns ExtendedString from TCollection;
366 ---Purpose: this datatype will be used if the DBMS deals with this concept
367 ---Purpose: gets the `FileFormat`.DataType resource.
368 -- concept.
369
370 FindVersionDataType(me: mutable) returns Boolean from Standard;
371
372 VersionDataType(me: mutable) returns ExtendedString from TCollection;
373 ---Purpose: this datatype will be used if the DBMS deals with this concept
374 ---Purpose: gets the `FileFormat`.VersionDataType resource.
375 --
376 FindDescription(me: mutable) returns Boolean from Standard;
377
378 Description(me: mutable) returns ExtendedString from TCollection;
379 ---Purpose: gets the `FileFormat`.Description resource.
380
381 FindDomain(me: mutable) returns Boolean from Standard;
382
383 Domain(me: mutable) returns ExtendedString from TCollection;
384 ---Purpose: gets the `FileFormat`.Domain resource.
385
386
387 FindStoragePlugin(me: mutable) returns Boolean from Standard;
388
389 StoragePlugin(me: mutable) returns GUID from Standard;
390
391 ---Category: Miscellaneous methods
392
393 IsModified(me) returns Boolean from Standard;
394 ---Purpose: returns true if the version is greater than the
395 -- storage version
396
397 ---Category: print method
398 Print(me; anOStream: in out OStream from Standard)
399 returns OStream from Standard;
400 ---C++: return &
401 ---C++: alias "Standard_OStream& operator << (Standard_OStream& anOStream);"
402
403---Category: activation controll
404
405 IsOpened(me) returns Boolean from Standard;
406
407 Open(me: mutable; anApplication: Application from CDM);
408
409
410 CanClose(me) returns CanCloseStatus from CDM;
411 ---Purpose:
412 --Returns CDM_CCS_OK true if it is possible to close the document.
413 -- Otherwise, returns:
414 -- CDM_CSS_NotOpen if the document has not been opened
415 -- CDM_CCS_UnstoredReferenced if the document is not stored if it
416 -- is referenced.
417 -- CDM_CSS_ModifiedReferenced if the document has been modified,
418 -- if it is referenced, since it has been stored.
419 -- CDM_CCS_ReferenceRejection if one of the referencing documents
420 -- does not allow the closing of the document.
421 Close(me: mutable);
422
423 Application(me) returns Application from CDM
424 raises Failure from Standard;
425 ---C++: return const &
426 ---Warning: exception if the document is not open
427
428
429 CanCloseReference(me; aDocument: Document from CDM;
430 aReferenceIdentifier: Integer from Standard)
431 returns Boolean from Standard
432 is virtual;
433 ---Purpose: A referenced document may indicate through this
434 -- virtual method that it does not allow the closing of
435 -- aDocument which it references through the reference
436 -- aReferenceIdentifier. By default returns Standard_True;;
437
438 CloseReference(me: mutable; aDocument: Document from CDM;
439 aReferenceIdentifier: Integer from Standard)
440 is virtual;
441 ---Purpose: A referenced document may update its internal
442 -- data structure when {aDocument} which it references
443 -- through the reference {aReferenceIdentifier} is being closed.
444 -- By default this method does nothing.
445
446 IsOpened(me; aReferenceIdentifier: Integer from Standard)
447 returns Boolean from Standard;
448 ---Purpose: returns true if the document corresponding to the
449 -- given reference has been retrieved and opened.
450 -- Otherwise returns false. This method does not retrieve
451 -- the referenced document
452
453---Category: private methods;
454--
455 Reference(me; aReferenceIdentifier: Integer from Standard)
456 returns Reference from CDM
457 is private;
458
459 ComputePresentation(me: mutable)
460 is private;
461
462 UnvalidPresentation(me: mutable)
463 is private;
464
465 CreateReference(me: mutable; aMetaData: MetaData from CDM; aReferenceIdentifier: Integer from Standard; anApplication: Application from CDM; aToDocumentVersion: Integer from Standard; UseStorageConfiguration: Boolean from Standard);
466
467 CreateReference(me: mutable; aMetaData: MetaData from CDM; anApplication: Application from CDM; aDocumentVersion: Integer from Standard; UseStorageConfiguration: Boolean from Standard)
468 returns Integer from Standard;
469
470 AddToReference(me: mutable; aReference: Reference from CDM)
471 is private;
472
473 AddFromReference(me: mutable; aReference: Reference from CDM)
474 is private;
475
476 RemoveFromReference(me: mutable; aReferenceIdentifier: Integer from Standard)
477 is private;
478
479 SetModifications(me: mutable; Modifications: Integer from Standard)
480 is private;
481
482 ReferenceCounter(me) returns Integer from Standard;
483
484 SetReferenceCounter(me: mutable; aReferenceCounter: Integer from Standard)
485 is private;
486
487---Category: obsolete methods
488
489 Update(me: mutable)
490 is virtual;
491 ---Purpose: the following method should be used instead:
492 --
493 -- Update(me:mutable; ErrorString: out ExtendedString from TCollection)
494 -- returns Boolean from Standard
495
496fields
497
498
499 myComments: SequenceOfExtendedString from TColStd;
500
501 myPresentation: ExtendedString from TCollection;
502 myValidPresentation: Boolean from Standard;
503
504 myFromReferences: ListOfReferences from CDM;
505 myToReferences: ListOfReferences from CDM;
506 myVersion: Integer from Standard;
507
508 myActualReferenceIdentifier: Integer from Standard;
509
510 myStorageVersion: Integer from Standard;
511 myMetaData: MetaData from CDM;
512
513 myRequestedComment: ExtendedString from TCollection;
514
515 myRequestedFolder: ExtendedString from TCollection;
516 myRequestedFolderIsDefined: Boolean from Standard;
517
518 myRequestedName: ExtendedString from TCollection;
519 myRequestedNameIsDefined: Boolean from Standard;
520
521 myRequestedPreviousVersionIsDefined: Boolean from Standard;
522 myRequestedPreviousVersion: ExtendedString from TCollection;
523
524 ---Category: resources.
525 myFileExtension,myDataType,myVersionDataType,myDescription,myDomain,myDefaultPresentation: ExtendedString from TCollection;
526
527 myFileExtensionWasFound,myDataTypeWasFound,myVersionDataTypeWasFound,myDescriptionWasFound,myDomainWasFound,myStoragePluginWasFound,myDefaultPresentationWasFound: Boolean from Standard;
528 myResourcesAreLoaded: Boolean from Standard is protected;
529 myStoragePlugin: GUID from Standard;
530 myApplication: Application from CDM;
531
532friends
533 class Reference from CDM,
534 class ReferenceIterator from CDM,
535 class Application from CDM
536
537end Document from CDM;