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