0024157: Parallelization of assembly part of BO
[occt.git] / src / CDM / CDM_Document.cdl
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
21
22 deferred class Document from CDM
23
24 inherits 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
58 uses
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
66 raises NoSuchObject from Standard,Failure from Standard,DomainError from Standard
67 is
68
69     Initialize;
70      
71 ---Category: virtual methods
72     Destroy(me: mutable) is virtual protected;
73     ---C++: alias ~
74     
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
496 fields
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
532 friends 
533     class Reference from CDM,
534     class ReferenceIterator from CDM,
535     class Application from CDM
536     
537 end Document from CDM;