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