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